271 lines
14 KiB
Markdown
271 lines
14 KiB
Markdown
# 山峡小程序 · 四模块开发清单
|
||
|
||
> **用途**：明确移动端开发范围、分期节奏与进度。阶段性完成后请把对应项从 `[ ]` 改为 `[x]`，并更新文首「进度总览」。
|
||
> **权威 UI**：`mobile-ui/shanxia-mp-*.html` + `docs/miniprogram-ui-spec-sanqiang.md` + Pattern 四页。
|
||
> **附件基线**：仅拍照凭证 → OpenSpec `zkxw-engineering-standards`（ui/api/architecture「小程序拍照凭证上传」）。
|
||
> **更新日期**：2026-07-16
|
||
|
||
---
|
||
|
||
## 进度总览
|
||
|
||
| 阶段 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| P0 基础设施 | 登录、Tab 壳、工作台、我的、上传工具、`/api/mini` 约定 | **基本完成**（见 §2；Pattern 组件随 P1 抽取） |
|
||
| P1 CRM | 线索 / 商机 / 客户 / 公海 / 报价 / 合同 | **基本完成**（列表/详情已接 `/web/crm/*`；联调冒烟待做） |
|
||
| P2 报销 | 待办、报销/借款申请与审批、我的单据 | **基本完成**（已接 `/reimburses` `/advances`；联调冒烟待做） |
|
||
| P3 地磅 | 仪表盘、计划、地磅单、出入库 | **基本完成**（已接 `/dashboard` `/plans` `/weighing` `/inventory`；联调冒烟待做） |
|
||
| P4 运输 | 计划、归档、购买证、运费结算/审批 | **基本完成**（已接 `/transport/*`；联调冒烟待做） |
|
||
| P5 收尾 | 联调、合法域名、发版检查、文档回写 | **接口冒烟完成**；真机 UI / 域名待做 |
|
||
|
||
**图例**：`[ ]` 未开始 · `[~]` 进行中 · `[x]` 已完成 · `[-]` 本期不做（灰卡/明确排除）
|
||
|
||
---
|
||
|
||
## 1. 范围边界
|
||
|
||
### 1.1 本期要做（Web 一级菜单 → 小程序）
|
||
|
||
| 模块 | Web 路径 | 小程序入口 | Demo |
|
||
|------|----------|------------|------|
|
||
| CRM 管理 | `/crm` | 工作台 → CRM 区块 | `shanxia-mp-crm-demo.html` |
|
||
| 报销管理 | `/bx` | 工作台 → 报销区块 | `shanxia-mp-bx-demo.html` |
|
||
| 地磅管理 | `/db` | 工作台 → 地磅区块 | `shanxia-mp-db-demo.html` |
|
||
| 运输管理 | `/pl` | 工作台 → 运输区块 | `shanxia-mp-pl-demo.html` |
|
||
|
||
### 1.2 明确不做
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 工作流管理 `/workflow` | 不单独做一级模块；报销审批走 BX 业务接口 |
|
||
| 系统管理 `/system` | 租户/菜单/角色等仅 Web |
|
||
| Tab「首页」「待办」业务内容 | Demo 标 Phase 2：壳可占位，本期不开发实质功能 |
|
||
| Web 专属配置页 | 如 BX 费用项目/工作流配置、CRM 产品主数据维护等（见各模块灰卡） |
|
||
| 小程序文档类附件 | PDF/Word 等；仅拍照凭证（见 OpenSpec） |
|
||
|
||
### 1.3 信息架构（与 Demo 一致）
|
||
|
||
```
|
||
登录 → 默认「工作台」Tab
|
||
Tab：首页(占位) | 待办(占位) | 工作台★ | 我的
|
||
工作台：四大模块菜单卡片 → 业务列表/详情/表单（无 TabBar，返回工作台）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. P0 基础设施
|
||
|
||
> 目标：四模块可挂载的统一壳 + 鉴权 + 上传 + 列表/详情模式对齐 Pattern。
|
||
|
||
### 2.1 工程与壳
|
||
|
||
- [x] uni-app 工程存在（`miniprogram/`，自 sqxp 精简）
|
||
- [x] 登录页 + 协议/隐私 + RSA 登录对接 Web 公共鉴权
|
||
- [x] 占位首页 `pages/home`
|
||
- [x] TabBar：首页 / 待办 / 工作台 / 我的（登录默认进工作台）
|
||
- [x] 工作台页：四模块 + 菜单卡片（对齐 `shanxia-mp-workbench-demo.html`；灰卡禁用）
|
||
- [x] 「我的」：展示用户信息、退出登录（对齐 `shanxia-mp-mine-demo.html`）
|
||
- [x] 首页 / 待办：占位页即可（本期不做业务）
|
||
- [x] 全局样式 Token 对齐 `shanxia-mp-base.css` / UI 规范（`styles/mp-shell.scss`）
|
||
- [~] Pattern 落地：列表 / 查看 / 表单 / 反馈 — Demo 已有；可复用组件随 **P1** 首业务页抽取（见 `pages/common/patterns-readme.md`）
|
||
|
||
### 2.2 网络与上传
|
||
|
||
- [x] `config/api.js`：区分环境基址；真机局域网说明（注释）
|
||
- [x] 业务 API 路径约定：P0 认证复用 `/web/auth/*`；上传复用 `/web/admin/attachment/upload`；业务 `/api/mini/*` 随模块补充
|
||
- [x] `utils/upload.js`：`chooseImage` + `uploadFile` + URL 收集（OpenSpec 基线）
|
||
- [x] 上传路径已在服务端 `API_ENCRYPT_EXCLUDE_PATHS`（`/api/web/admin/attachment/upload`）
|
||
- [ ] 微信合法域名（request / uploadFile）清单与发版脚本核对（发版前 / P5）
|
||
|
||
### 2.3 菜单与权限
|
||
|
||
- [x] 工作台菜单前端写死四模块（`config/workbench-menus.js`，与 Demo 灰卡一致）
|
||
- [ ] 按角色权限过滤/置灰（有菜单权限接口后再接；P0 全量展示启用卡）
|
||
|
||
---
|
||
|
||
## 3. P1 CRM 管理
|
||
|
||
> Demo 启用菜单 = 本期范围；灰卡 = 本期不做。
|
||
|
||
| 菜单 | 本期 | 建议能力 | 进度 |
|
||
|------|------|----------|------|
|
||
| 线索管理 | 要做 | 列表/筛选 Tab、详情、新增/跟进、分配、转商机 | [x] 列表/详情/新增/跟进/转客户/无效；分配待 Web |
|
||
| 商机管理 | 要做 | 列表、详情、跟进/阶段（看板可二期） | [x] 列表/详情/跟进；阶段变更二期 |
|
||
| 客户管理 | 要做 | 列表、详情、跟进入口 | [x] |
|
||
| 公海池 | 要做 | 列表、领取/分配 | [x] 列表+领取；分配待 Web 选人 |
|
||
| 报价管理 | 要做 | 列表、详情、关键状态操作 | [x] 列表/详情（审批在 Web） |
|
||
| 合同管理 | 要做 | 列表、详情、关键状态（无审批流复杂页可简化） | [x] 列表/详情（审批在 Web） |
|
||
| 产品分类 | 不做 | Web 主数据 | [-] |
|
||
| 产品管理 | 不做 | Web 主数据 | [-] |
|
||
| 合同审批 | 不做 | Demo 灰卡 | [-] |
|
||
| 线索/商机统计、看板、漏斗 | 不做 | Web 分析页，除非产品加开 | [-] |
|
||
|
||
### P1 任务拆解
|
||
|
||
- [x] 工作台 CRM 菜单卡片接线（`WORKBENCH_ROUTE_MAP`）
|
||
- [x] 线索：列表 + 详情 + 表单/跟进（`mobile-ui` Pattern：Header/Tabs/Card/Tag/BottomBar）
|
||
- [x] 商机：列表 + 详情 + 跟进
|
||
- [x] 客户：列表 + 详情 + 跟进
|
||
- [x] 公海池：列表 + 领取（分配需选人，留 Web）
|
||
- [x] 报价：列表 + 详情
|
||
- [x] 合同：列表 + 详情
|
||
- [ ] 接口联调与租户/数据权限冒烟（需 admin 账号 + 后端）
|
||
- [ ] 阶段验收：销售角色可完成「线索→商机→客户」主路径
|
||
|
||
---
|
||
|
||
## 4. P2 报销管理
|
||
|
||
| 菜单 | 本期 | 建议能力 | 进度 |
|
||
|------|------|----------|------|
|
||
| 待办任务 | 要做 | 待审批/我的申请/已办 Tab；通过/驳回 | [x] |
|
||
| 报销申请 | 要做 | 新建/编辑、明细、提交（票据以拍照凭证为主） | [x] 新建+拍照+草稿/提交 |
|
||
| 报销审批 | 要做 | 列表 + 审批动作（可与待办合并入口） | [x] |
|
||
| 借款申请 | 要做 | 备用金申请 | [x] |
|
||
| 借款审批 | 要做 | 备用金审批 | [x] |
|
||
| 我的单据 | 要做 | 我的申请单列表/详情 | [x] |
|
||
| 借款发放 | 不做 | Demo 灰卡（偏财务后台） | [-] |
|
||
| 全部单据 | 不做 | Demo 灰卡（总经理 Web） | [-] |
|
||
| 付款记录 | 不做 | Demo 灰卡 | [-] |
|
||
| 费用项目/工作流配置 | 不做 | Web 基础配置 | [-] |
|
||
| 支付发放冲抵 | 不做 | 本期不进工作台 | [-] |
|
||
|
||
### P2 任务拆解
|
||
|
||
- [x] 工作台报销菜单卡片接线
|
||
- [x] 待办任务列表（对齐 bx-demo：大麦黄 Header + Tabs + 卡片审批）
|
||
- [x] 报销申请（表单 + 拍照凭证 `/attachments/upload` + bind）
|
||
- [x] 报销审批动作
|
||
- [x] 借款（备用金）申请 / 审批
|
||
- [x] 我的单据
|
||
- [ ] 接口联调与审批状态机冒烟
|
||
- [ ] 阶段验收：申请人提交 → 审批人通过/驳回闭环
|
||
|
||
---
|
||
|
||
## 5. P3 地磅管理
|
||
|
||
| 菜单 | 本期 | 建议能力 | 进度 |
|
||
|------|------|----------|------|
|
||
| 仪表盘 | 要做 | 关键统计卡片（只读） | [x] |
|
||
| 地磅计划 | 要做 | 列表、详情、必要办理动作 | [x] 列表/详情/生成出入库关联 |
|
||
| 地磅单管理 | 要做 | 列表、详情、二次过磅等现场动作 | [x] 二次过磅 + 当天作废 |
|
||
| 地磅出入库 | 要做 | 列表、详情 | [x] |
|
||
|
||
### P3 任务拆解
|
||
|
||
- [x] 工作台地磅菜单卡片接线
|
||
- [x] 仪表盘（对齐 db-demo 青绿 Header + 统计卡）
|
||
- [x] 地磅计划列表/详情
|
||
- [x] 地磅单列表/详情/二次过磅/作废
|
||
- [x] 出入库列表/详情
|
||
- [ ] 接口联调（注意与地磅系统边界，见 ecosystem-landscape）
|
||
- [ ] 阶段验收：查计划 → 看待过磅单 → 完成一次现场办理路径
|
||
|
||
---
|
||
|
||
## 6. P4 运输管理
|
||
|
||
| 菜单 | 本期 | 建议能力 | 进度 |
|
||
|------|------|----------|------|
|
||
| 运输计划 | 要做 | 列表 Tab、详情、安排运输等 | [x] 待发运/在途/已完成 + 安排运输 |
|
||
| 计划归档 | 要做 | 只读列表/详情 | [x] |
|
||
| 购买证上传 | 要做 | 列表 + **拍照凭证**上传（OpenSpec） | [x] 拍照 + 证书齐备 |
|
||
| 运费结算 | 要做 | 列表、详情、提交 | [x] 结算单/待结算生成 + 提交审批 |
|
||
| 运费审批 | 要做 | 列表、审批 | [x] |
|
||
| 财务发放 | 不做 | Demo 灰卡 | [-] |
|
||
| 车辆充值 | 不做 | Demo 灰卡（ETC 等） | [-] |
|
||
| 车辆维修 | 不做 | Demo 灰卡 | [-] |
|
||
| 运输地址库 | 不做 | Demo 灰卡（主数据） | [-] |
|
||
| 基础信息库其余页 | 不做 | 车辆/承运商/驾押等主数据偏 Web | [-] |
|
||
| 证件提醒 / 尿素等 | 不做 | 未进工作台启用卡 | [-] |
|
||
|
||
### P4 任务拆解
|
||
|
||
- [x] 工作台运输菜单卡片接线
|
||
- [x] 运输计划列表/详情/办理（对齐 pl-demo）
|
||
- [x] 计划归档
|
||
- [x] 购买证上传（拍照凭证）
|
||
- [x] 运费结算 + 运费审批（含选人提交审批）
|
||
- [ ] 接口联调
|
||
- [ ] 阶段验收：计划办理 → 购买证上传 → 运费提交/审批主路径
|
||
|
||
---
|
||
|
||
## 7. P5 收尾与发版
|
||
|
||
- [x] 四模块冒烟清单（角色 × 主路径）— 接口级已跑通，见 §7.1
|
||
- [ ] 真机：登录、列表、上传、审批/办理
|
||
- [ ] `npm run release:check-api`（或等价）通过
|
||
- [ ] 微信后台域名与上传域名配置完成
|
||
- [x] README / 本清单进度回写（接口冒烟结论已写入）
|
||
- [ ] 可选：OpenSpec 归档或增补「小程序四模块」变更说明
|
||
|
||
### 7.1 四模块冒烟清单（联调时勾选）
|
||
|
||
> 账号：具备对应模块权限的 admin / 业务角色；基址见 `miniprogram/config/api.js`。
|
||
> **接口冒烟执行**：2026-07-17，`admin` / 本机 `http://127.0.0.1:8000/api`，脚本 `miniprogram/scripts/mp_api_smoke.py`（结果见 `mp_api_smoke_last.json`）。
|
||
> 图例：`[x]` 接口可达且读通；写操作因缺样本/字段校验未闭环的在备注中说明。
|
||
|
||
| # | 模块 | 路径 | 预期 | 结果 |
|
||
|---|------|------|------|------|
|
||
| S1 | 公共 | 登录 → current-user | Token 可用 | [x] 登录+current-user ok |
|
||
| S2 | CRM | 线索列表 → 详情 → 跟进 | 列表/详情正常 | [x] 列表+详情 ok；跟进 body 422（字段待对齐） |
|
||
| S3 | CRM | 公海列表/领取 | 列表正常 | [x] 列表空态 ok（无领取样本） |
|
||
| S4 | 报销 | 我的报销 / 新建 | 列表可读 | [x] my 列表 ok；新建缺 `details` 字段 422（小程序 payload 待对齐） |
|
||
| S5 | 报销 | 待审批列表 | 列表正常 | [x] 空态 ok（无待审样本） |
|
||
| S6 | 地磅 | 仪表盘 + 地磅单列表 | 数字/列表可读 | [x] stats+列表 ok；无二次过磅样本 |
|
||
| S7 | 运输 | 计划列表 / 安排 | 列表正常 | [x] 列表 ok；安排因证书未齐备业务拒绝（接口可达） |
|
||
| S8 | 运输 | 购买证相关计划列表 | 列表正常 | [x] 列表空态 ok |
|
||
| S9 | 运输 | 运费结算 + 用户选项 | 列表/选人接口正常 | [x] freight 列表 + users/options ok；无待结算 |
|
||
| S10 | 运输 | 运费待审批列表 | 列表正常 | [x] 列表空态 ok |
|
||
|
||
**接口冒烟结论**：S1–S10 **读路径全部通**（0 FAIL）。写路径有 3 处需跟进：① 线索跟进字段；② 报销创建体应用 `details` 而非 `items`；③ 安排运输依赖证书齐备业务数据。
|
||
|
||
### 7.2 H5 UI 冒烟（Playwright，不改 uni-app 工程）
|
||
|
||
> **执行**：2026-07-17，H5 `http://localhost:5173/`，账号 `admin` / `admin123`，后端 `127.0.0.1:8000`。
|
||
> 脚本：独立目录 `miniprogram-e2e/smoke.mjs`（`cd miniprogram-e2e && node smoke.mjs`）；截图与 JSON 在 `miniprogram-e2e/artifacts/`。
|
||
|
||
| # | 路径 | 结果 |
|
||
|---|------|------|
|
||
| E1 | 登录 → 工作台四模块可见 | [x] PASS |
|
||
| E2 | 线索管理 | [x] PASS |
|
||
| E3 | 报销申请 | [x] PASS |
|
||
| E4 | 地磅仪表盘 | [x] PASS |
|
||
| E5 | 运输计划 | [x] PASS |
|
||
|
||
**UI 冒烟结论**：E1–E5 **全通**（0 FAIL）。微信开发者工具 / 真机验收仍见 §7 未勾项。
|
||
|
||
---
|
||
|
||
## 8. 推荐开发顺序
|
||
|
||
1. **P0** 壳与工作台（否则业务页无处挂）
|
||
2. **P2 报销** 或 **P1 CRM**（审批/跟进闭环短，易验证上传与列表模式）
|
||
3. **P3 地磅**（现场办理，偏读+少量动作）
|
||
4. **P4 运输**（计划+运费+购买证，依赖上传基线）
|
||
5. **P5** 联调发版
|
||
|
||
> 顺序可按业务优先级调整；调整时只改本节与文首总览，子清单保持勾选状态。
|
||
|
||
---
|
||
|
||
## 9. 进度记录（追加）
|
||
|
||
| 日期 | 阶段 | 说明 |
|
||
|------|------|------|
|
||
| 2026-07-16 | 范围 | 确认仅 CRM / 地磅 / 运输 / 报销四模块；本清单建立 |
|
||
| 2026-07-16 | 规范 | 拍照凭证上传写入 OpenSpec engineering-standards |
|
||
| 2026-07-16 | P0 | TabBar + 工作台/我的/占位页 + upload.js + mp-shell；清单回写 |
|
||
| 2026-07-16 | P1–P4 | CRM / 报销 / 地磅 / 运输业务页落地并接线工作台 |
|
||
| 2026-07-16 | P4+ | 运费提交审批改为用户选项选人 Sheet；P5 冒烟表写入 §7.1 |
|
||
| 2026-07-17 | P5 | 接口冒烟 S1–S10 读路径全通（脚本 `mp_api_smoke.py`）；写路径 3 处待对齐见 §7.1 |
|
||
| 2026-07-17 | P5 | H5 Playwright E1–E5 冒烟全通（`miniprogram-e2e/smoke.mjs`，见 §7.2） |
|
||
| 2026-07-17 | P5 | 按 QA 节奏启动：先全量文字用例（`miniprogram-e2e/cases/`），脚本验证待用例评审后逐步开展 |
|
||
|
||
<!-- 每完成一批任务追加一行，例如：
|
||
| 2026-0x-xx | P0 | TabBar + 工作台落地 |
|
||
-->
|