213 lines
8.8 KiB
Markdown
213 lines
8.8 KiB
Markdown
# H5 材料浏览端 设计文档
|
||
|
||
- 日期：2026-04-24
|
||
- 作者：caoqianming
|
||
- 状态：草案
|
||
|
||
## 1 · 背景与目标
|
||
|
||
在现有 mat3 项目（PC 端材料管理 + Django 后端）基础上，新增面向手机浏览器的 **H5 材料查看端**。
|
||
核心诉求：**只读浏览**——登录后按 "大类 → 种类 → 子类 → 材料 → 详情" 的层级快速找到材料并查看详细信息。
|
||
不包含新增 / 编辑 / 导入 / 审批等写操作。
|
||
|
||
## 2 · 项目结构与技术栈
|
||
|
||
### 2.1 组织方式
|
||
新建独立项目 `frontend-h5/`，与现有 `frontend/` 平级；独立 Vite、独立依赖、独立打包。
|
||
|
||
```
|
||
frontend-h5/
|
||
├── index.html
|
||
├── vite.config.js # base: '/m/'，dev proxy → 后端
|
||
├── package.json
|
||
├── tailwind.config.js
|
||
├── postcss.config.js
|
||
└── src/
|
||
├── main.js
|
||
├── App.vue
|
||
├── router/ # vue-router 4，history 模式
|
||
├── store/ # pinia
|
||
├── api/ # 参照 frontend/src/api 复制同名文件，保持一致
|
||
├── composables/ # useAuth / useInfiniteScroll / useToast ...
|
||
├── styles/ # tailwind.css、全局变量
|
||
├── components/ # MaterialCard / CategoryCard / StarLevel / Chip / NavBar / Toast ...
|
||
└── views/
|
||
├── Login.vue
|
||
├── Home.vue
|
||
├── CategoryDetail.vue
|
||
└── MaterialDetail.vue
|
||
```
|
||
|
||
### 2.2 技术栈
|
||
- Vue 3 + vue-router 4 + Pinia
|
||
- Axios（同 PC 端一致的拦截器：附 token、统一错误处理、401 跳登录）
|
||
- **Tailwind CSS**（自定义设计令牌），不使用 Vant/NutUI
|
||
- 少量自研组件（Toast、NavBar、Tab、InfiniteList、StarLevel、Chip、Skeleton）
|
||
|
||
### 2.3 部署
|
||
- 构建产物部署到 Nginx 子路径 `/m/`（与 PC 端同域名）
|
||
- `vite.config.js` 设 `base: '/m/'`
|
||
- 开发期 `vite` devServer 走本地端口（如 5174），通过 `server.proxy` 把 `/api` 转发到后端
|
||
|
||
### 2.4 登录态
|
||
- `localStorage` 存 token，key 为 `h5_token`（与 PC 端 `token` 隔离，避免互相污染）
|
||
- Pinia `authStore` 暴露 `token` / `user` / `login()` / `logout()`
|
||
- Axios request 拦截器：存在 `h5_token` 则附 `Authorization`
|
||
- Axios response 拦截器：401 清 token 并跳 `/login?redirect=<current>`
|
||
|
||
## 3 · 路由与页面流
|
||
|
||
| 路径 | 页面 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/login` | Login | 账号密码登录 |
|
||
| `/` | Home | 大类卡片 + 选中后展开种类区 |
|
||
| `/category/:major/:category` | CategoryDetail | 子类 Tab + 材料列表 |
|
||
| `/material/:id` | MaterialDetail | 材料详情（三块） |
|
||
|
||
**路由守卫**：非 `/login` 页进入前校验 token；无 token → 跳 `/login?redirect=<原路径>`；登录成功后回跳。
|
||
|
||
**过渡**：页面切换用右推左 slide + fade CSS 过渡。
|
||
|
||
**状态保留**：
|
||
- Pinia `uiStore` 记录 Home 选中的大类、CategoryDetail 选中的子类 Tab、列表滚动位置
|
||
- 从详情返回时恢复选中态和滚动位置
|
||
- 使用 `<keep-alive>` 缓存 Home 与 CategoryDetail
|
||
|
||
## 4 · 数据接口
|
||
|
||
### 4.1 复用现有接口
|
||
|
||
| 用途 | 接口 |
|
||
| --- | --- |
|
||
| 登录 | `POST /auth/login/` |
|
||
| 当前用户 | `GET /auth/user/` |
|
||
| 材料列表 | `GET /material/?major_category=&material_category=&material_subcategory=&search=&page=&page_size=` |
|
||
| 材料详情 | `GET /material/{id}/` |
|
||
| 选项字典 | `GET /material/choices/` |
|
||
|
||
### 4.2 新增接口
|
||
|
||
由于 `MaterialCategory` 与 `Material.major_category` 没有 FK 关系，"大类下的种类""种类下的子类" 需要从 `Material` 表按大类 distinct 计算。两个新接口都作为 `MaterialViewSet` 的 `@action` 提供。
|
||
|
||
**接口 1**：`GET /material/categories-by-major/?major_category=architecture`
|
||
|
||
- 从 `Material` 表取 `major_category=X` 的记录，按 `material_category` 分组 count
|
||
- 响应：
|
||
```json
|
||
[
|
||
{ "value": "地砖", "count": 12 },
|
||
{ "value": "涂料", "count": 8 }
|
||
]
|
||
```
|
||
|
||
**接口 2**：`GET /material/subcategories-by-category/?major_category=&material_category=`
|
||
|
||
- 同上，按 `material_subcategory` 分组 count，过滤空值
|
||
- 响应：
|
||
```json
|
||
[
|
||
{ "value": "釉面砖", "count": 5 },
|
||
{ "value": "通体砖", "count": 3 }
|
||
]
|
||
```
|
||
|
||
"全部"分类不从后端返回，由前端在 Tab 第一项注入，点击时不传 `material_subcategory` 参数。
|
||
|
||
### 4.3 列表卡片使用字段
|
||
|
||
- `name`（材料名称）
|
||
- `cost_compare`（成本对比，百分数，负数表示更便宜）
|
||
- `advantage_display`（竞争优势，取前 2 个 chip 显示）
|
||
- `importance_level`（重要等级 chip）
|
||
- `score_level`（综合评分，1-3 星）
|
||
- `factory_short_name`（供应商简称）
|
||
|
||
### 4.4 分页与加载
|
||
|
||
- `page_size = 20`
|
||
- 列表支持下拉刷新 + 上拉无限加载（基于 IntersectionObserver 的 `useInfiniteScroll`）
|
||
|
||
## 5 · 视觉与交互设计
|
||
|
||
### 5.1 设计语言
|
||
**克制的卡片式 · 暖中性色** + **墨绿品牌色**
|
||
|
||
- 背景：白 `#FFFFFF` + 极浅灰分层 `#FAFAFA` / `#F5F4F2`
|
||
- 主色：`#2F4F3F`（墨绿），用于按钮、重点数值、选中态
|
||
- 辅助色：红 `#D2584A`（核心）、蓝 `#5A7FB8`（优先）、灰 `#8A8A8A`（一般）
|
||
- 卡片圆角 `16-20px`；阴影 `0 1px 2px rgba(0,0,0,.04)`；不用重描边
|
||
- 字体：系统栈 (`-apple-system, "PingFang SC", ...`)；数值字段启用 `font-feature-settings: "tnum"` 等宽
|
||
- 点按反馈：`active:scale-[0.98]` + 背景变深
|
||
|
||
以上颜色 / 圆角 / 间距在 `tailwind.config.js` 定义为 theme tokens，后续组件直接用工具类。
|
||
|
||
### 5.2 关键页面
|
||
|
||
**Login**
|
||
- 上 60% 留白 + 品牌标识
|
||
- 下 40% 表单：用户名、密码、提交按钮
|
||
- 失败信息由 Toast 从顶部下滑显示，2s 自动消失
|
||
|
||
**Home**
|
||
- 顶部栏：欢迎语 + 用户名 + 退出图标
|
||
- 主体：2×2 大类卡片网格（建筑/景观/设备/装修），每卡显示大类名 + 材料总数
|
||
- 选中大类后在下方 slide-down + fade 出现种类卡片区（2 列网格，卡带材料数角标）
|
||
- 未选中时下方显示引导文案
|
||
- 选中的大类 ID 写入 `uiStore`，从详情返回恢复展开状态
|
||
|
||
**CategoryDetail**
|
||
- 顶部 NavBar：返回按钮 + 种类名标题
|
||
- 吸顶的子类 Tab 栏（横向滚动，"全部" 为第一项，选中下划线 + 文字加重）
|
||
- 材料卡列表：通栏，左信息区（名称 / 供应商 / 优势 chip）+ 右数值区（成本 / 评分 / 重要等级）
|
||
- 下拉刷新、上拉无限加载
|
||
- 空态：图标 + "暂无材料"
|
||
|
||
**MaterialDetail**
|
||
- 顶部 NavBar
|
||
- 可选顶部 banner：`brochure` 宣传图（16:9，懒加载，点击可全屏预览）
|
||
- 三个 section，每个 section 是一张圆角卡：
|
||
|
||
1. **材料信息**：基础 / 应用 / 优势 / 成本 / 评分，`grid-cols-[auto_1fr]` 标签值布局；竞争优势、应用场景、重要等级、替代类型用 chip；4 项等级用星级可视化。长文本（优势说明、成本说明、应用说明）独立成段。
|
||
2. **品牌与供应商**：品牌、供应商简称/全称、合作模式、省-市、对接人、对接人联系方式。电话字段带 `tel:` 链接可一键拨打。
|
||
3. **案例信息**：落地项目、案例（保留换行）、经办人、备注。
|
||
|
||
### 5.3 通用交互
|
||
- Loading：顶部 NProgress 细线进度条；列表用骨架屏
|
||
- 错误：非 401 错误 Toast 提示；页面级错误态带"重试"按钮
|
||
- 401：清 token + 跳登录
|
||
|
||
## 6 · 后端改动清单
|
||
|
||
`apps/material/views.py`
|
||
- `MaterialViewSet` 新增两个 `@action(detail=False, methods=['get'])`：
|
||
- `categories_by_major`
|
||
- `subcategories_by_category`
|
||
- 两者权限与现有列表一致（登录用户可访问）
|
||
- 考虑给 `material_category` / `material_subcategory` 字段的"查询计数"加缓存（低优，后续再说）
|
||
|
||
无 model migration。
|
||
|
||
## 7 · 验收标准
|
||
|
||
- [ ] 手机浏览器（iOS Safari / 微信内置 / Android Chrome）访问 `/m/`，可完成 登录 → 大类 → 种类 → 子类 → 材料详情 的完整浏览
|
||
- [ ] 详情页三块布局、字段映射与本文档 §5.2 一致
|
||
- [ ] 从详情返回上级页面，滚动位置与选中 Tab 保持
|
||
- [ ] 401 时自动跳登录且登录后回跳原路径
|
||
- [ ] 包体积：首屏 gzip 后 < 150 KB（不含首图）
|
||
- [ ] 单手可达性：关键按钮在屏幕下半区
|
||
- [ ] PC 端 `/` 功能不受影响
|
||
|
||
## 8 · 非目标
|
||
|
||
- 新增、编辑、导入、导出、审批
|
||
- 离线缓存 / PWA
|
||
- 多语言
|
||
- 手机号验证码登录（后续视需要再开 Spec）
|
||
|
||
## 9 · 风险与开放项
|
||
|
||
- **微信内置浏览器差异**：目前未要求适配微信分享/JSSDK，仅确保页面能正常打开
|
||
- **H5 与 PC 登录态隔离**：使用不同 localStorage key，后端 token 为同一份 JWT，无服务端改动成本
|
||
- **种类 distinct 性能**：当前数据量小可直接 SQL `GROUP BY`；后续若过万条可再加索引或 Redis 缓存
|
||
- **视觉最终稿**：本文档只定方向，具体 mockup 由后续 `frontend-design` 技能产出
|