diff --git a/docs/superpowers/specs/2026-10-11-market-presign-mobile-parity-design.md b/docs/superpowers/specs/2026-10-11-market-presign-mobile-parity-design.md new file mode 100644 index 00000000..3741fa20 --- /dev/null +++ b/docs/superpowers/specs/2026-10-11-market-presign-mobile-parity-design.md @@ -0,0 +1,272 @@ +# 市场专员 / 地区经理:预签约订单移动端对齐 Web 设计 + +**日期:** 2026-10-11 +**状态:** 视觉方向已通过 HTML Demo 确认,待设计文档确认 +**范围:** `mobile-oa-h5` 预签约订单列表、表单及其配套移动 API;市场专员和地区经理使用同一套展示组件、不同角色路由与服务端数据范围 + +## 1. 背景与目标 + +现有移动市场模块使用通用配置驱动页面,已具备基础列表、详情、表单和移动 API,但预签约订单与 Web 管理端仍存在明显差距: + +- 列表顶部使用了额外的绿色渐变头部,和小程序工作流页面不一致。 +- 新增按钮占据列表顶部工具栏,状态下拉筛选与本期需求不符。 +- 列表卡片只展示通用摘要,缺少 Web 端完整字段及编辑、转正式、删除操作。 +- 表单仍使用原生 HTML 控件,采集地区、医院、缴费方式等未使用 Vant 移动选择器。 +- 医院选项未随采集地区即时重新加载;缴费方式仍是普通文本输入。 +- 意向金转账只支持新增时的通用重复块,未覆盖 Web 端编辑、提交财务确认、撤回和附件卡片能力。 +- 列表仍使用“加载更多”按钮,不符合滚动触底动态分页要求。 + +本次目标是以 Web 管理端预签约订单为功能权威,以现有 OA 工作流移动页面为视觉与交互权威,把预签约订单完整复刻为移动端形式,并将其沉淀为后续其他市场模块改造的参考实现。 + +## 2. 权威参考 + +### 2.1 功能与字段权威 + +- 列表:`web-admin/src/views/cell-storage/presign-order/index.vue` +- 新增 / 编辑:`web-admin/src/views/cell-storage/presign-order/PresignOrderFormDialog.vue` +- Web API:`web-admin/src/api/presign-order.ts` + +### 2.2 移动视觉与交互权威 + +- 工作流卡片列表:`mobile-h5/pages/oa/pending/index.vue`、`mobile-h5/pages/oa/done/index.vue`、`mobile-oa-h5/src/views/OaHistory.vue` +- 工作流表单与固定底栏:`mobile-oa-h5/src/views/OaStart.vue` +- 工作流移动组件:`mobile-oa-h5/src/oa/components/*` +- UI 框架:Vant 4;`mobile-oa-h5/src/main.js` 已全局注册 Vant +- 小程序品牌主色:`#0a9f6d`,本模块不得使用 Web 管理端主色 `#10b981` + +### 2.3 已确认 HTML Demo + +视觉确认稿由本次 brainstorming 会话生成: + +- 列表保留白色顶部导航栏,移除绿色背景区域。 +- 白色顶部栏显示返回按钮与“预签约订单”标题。 +- 搜索框位于顶部栏下方。 +- 右下角使用圆形悬浮新增按钮。 +- 卡片显示 Web 列表全部业务字段与操作。 +- 表单采用移动 Cell、底部选择器、分区卡片和固定底栏。 + +## 3. 方案比较与选择 + +### 方案 A:继续扩充通用配置驱动页面 + +在 `presign.js` 中增加更多字段配置,并不断增强 `MarketFormField`、`MarketListCard`。 + +优点是改动文件少;缺点是预签约订单的级联查询、人员远程搜索、意向金多状态操作和附件卡片会迫使通用配置层加入大量业务特例,后续其他模块更难维护。 + +### 方案 B:预签约订单专用页面 + 复用市场基础设施(采用) + +为预签约订单提供专用列表卡片、专用新增 / 编辑表单及必要的业务组件;继续复用现有路由上下文、鉴权、HTTP、错误处理、请求状态和品牌 Token。 + +优点是能准确对齐 Web 功能,同时把成熟的移动交互组件沉淀为后续市场模块模板;缺点是会增加少量专用组件。 + +### 方案 C:逐段复制 Web 组件逻辑 + +把 Web 表格、弹窗与 Element Plus 交互直接翻译到移动端。 + +该方案功能映射直接,但会把桌面布局思路带入移动端,难以复用 OA 工作流组件,也不符合用户已确认的移动 Demo,因此不采用。 + +## 4. 列表页设计 + +### 4.1 页面结构 + +从上至下固定为: + +1. 白色顶部导航栏:返回按钮 + 居中标题“预签约订单”。 +2. 白色搜索区域:只保留一个关键词输入框,占位文案“搜索母亲姓名 / 协议编号”。 +3. 可滚动卡片列表。 +4. 右下角圆形悬浮新增按钮,按钮尺寸不小于 56×56px,`+` 水平、垂直居中。 + +明确移除: + +- 原 `MarketPageShell` 的绿色渐变标题区域。 +- 列表顶部“新增预签约订单”长按钮。 +- “全部状态”下拉筛选。 +- 手工“加载更多”按钮。 + +### 4.2 卡片字段 + +每张卡片必须与 Web 表格展示字段一致: + +| 顺序 | 字段 | 移动端展示 | +|------|------|------------| +| 1 | 序号 | 左上角品牌绿圆形编号,跨分页连续编号 | +| 2 | 业务日期 | `YYYY-MM-DD` | +| 3 | 协议编号 | 无值显示 `-` | +| 4 | 母亲姓名 | 卡片主标题 | +| 5 | 预产期 | `YYYY-MM-DD` | +| 6 | 合同金额 | `¥` + 两位小数,无值显示 `-` | +| 7 | 到账金额 | `¥` + 两位小数,无值显示 `-` | +| 8 | 状态 | Vant Tag,文案与 Web 状态注册表一致 | +| 9 | 创建时间 | 移动端紧凑时间格式,但信息不得丢失 | + +卡片底部操作与 Web 一致: + +- `编辑`:草稿、进行中等后端允许状态显示。 +- `转正式`:非已转正式、非已作废且后端返回 `convert` 时显示。 +- `删除`:非已转正式且后端返回 `delete` 时显示。 + +前端不得只根据状态自行推导权限;最终可见操作取“前端动作白名单 ∩ 后端 `allowedActions`”。 + +### 4.3 搜索与动态分页 + +- 输入关键词后,点击键盘搜索触发第一页加载;清空输入框立即重载第一页。 +- 列表使用 Vant `List` 的滚动触底加载语义,分页大小保持 10。 +- 首次加载、追加加载、空态、首屏失败和追加失败分别展示对应状态。 +- 新搜索、保存返回、删除成功或转正式成功后重置到第一页,禁止与旧请求结果串页。 +- `finished` 依据当前已加载条数与服务端 `total` 计算。 +- 默认排序继续由后端保证 `create_time DESC`。 + +## 5. 新增 / 编辑页设计 + +### 5.1 页面与底栏 + +- 顶部使用白色导航栏,标题为“新增预签约订单”或“编辑预签约订单”。 +- 表单正文独立滚动,底部固定“取消 / 确定”操作栏,对齐 `OaStart`。 +- 主操作按钮使用 `#0a9f6d`,所有点击目标不小于 44×44px。 +- 表单按“预签信息”“意向金转账”分区,采用白色卡片 + 品牌绿标题竖条。 + +### 5.2 预签信息字段 + +字段、顺序、默认值、必填性和禁用规则与 Web 表单一致: + +1. 业务日期:日期选择器,新增默认当天。 +2. 协议编号:文本,可选。 +3. 母亲姓名:文本,必填。 +4. 预产期:日期选择器。 +5. 采集地区:数据库选项,Vant 弹出选择器。 +6. 医院:数据库选项,Vant 弹出选择器;未选地区时禁用。 +7. 采集专员:远程检索用户;新增默认当前用户;已转正式禁用。 +8. 采集经理:选择地区后默认该地区负责人,允许重新远程选择;已转正式禁用。 +9. 采集时间:日期时间选择器。 +10. 缴费方式:下拉选择,`趸交(dj)` / `分期(fq)`,新增默认趸交。 +11. 整单合同金额(元):金额输入,最小值 0。 +12. 订单状态:`草稿 / 进行中 / 已转正式 / 已作废`;已转正式禁用。 +13. 样本类型:数据库选项、多选、必填。 +14. 备注:最多 500 字。 + +### 5.3 地区、医院与负责人级联 + +- 首次打开表单时加载地区、样本类型、转账方式等公共选项。 +- 选择采集地区后立即清空原医院,并以 `regionId` 重新请求医院选项。 +- 同时加载地区工作人员,优先选择 `isLeader=1` 的负责人作为采集经理默认值。 +- 编辑页先回填地区,再加载该地区医院,最后回填医院,避免跨地区脏选项。 +- 服务端继续校验地区、医院、样本类型均属于当前租户,且医院确实属于所选地区。 +- 选择器中显示节点名称;表单回显使用业务名称,不显示数据库 ID。 + +### 5.4 移动选择器组件 + +- 单选字段使用 `van-field` 只读入口 + `van-popup` / `van-picker`。 +- 日期使用 `van-popup` / `van-date-picker`。 +- 日期时间使用日期、时间两步选择或可复用的 OA 日期时间组件。 +- 多选样本类型使用底部弹层 + `van-checkbox-group`,确认后以 Tag 列表回显。 +- 人员远程搜索使用底部弹层中的 `van-search` + 可滚动结果列表。 +- 金额输入优先复用 OA Money Field 的格式和校验方式。 + +## 6. 意向金转账设计 + +### 6.1 转账卡片字段 + +每笔转账在移动端表现为独立卡片,字段与 Web 一致: + +- 转账方式:数据库字典选项。 +- 转账金额(元):金额输入。 +- 转账时间:日期时间选择器。 +- 转账凭证:上传卡片 + 已上传附件卡片。 +- 备注。 +- 财务备注:只读。 +- 状态:Vant Tag。 + +### 6.2 附件上传 + +- 使用 Vant `Uploader` 的移动交互,上传按钮作为附件列表中的第一张卡片。 +- 选择文件后立即上传;附件值仍以逗号分隔 URL 传输,后端继续验证附件登记与业务绑定。 +- 图片按 1:1 `aspectFill` 展示;非图片展示文件类型图标。 +- 支持预览、下载和删除;单文件上限与 Web 一致为 20MB。 +- 上传中、上传失败必须有明确状态,提交时不得携带仍在上传或失败的附件。 + +### 6.3 转账操作 + +与 Web 端一致: + +- 添加转账笔。 +- 待付款(`dfj`):允许修改、删除;已保存记录允许“提交财务确认”。 +- 待财务确认(`jfqrz`):字段锁定,允许“撤回”。 +- 已确认(`yjf`)及其他锁定状态:字段只读,不允许删除。 +- 已转正式订单:全部转账字段与主表单只读。 + +新增订单保存时可连同新转账笔一次创建;编辑订单时分别创建或更新未锁定的转账记录。 + +## 7. 确认操作与反馈 + +- 转正式、删除订单、撤回转账、删除转账笔均使用 Vant Confirm Dialog。 +- 转正式确认文案与 Web 保持同一业务含义,明确人员和意向金会带入正式协议。 +- 成功反馈使用 Vant Success Toast,失败使用统一 `marketErrorMessage`。 +- 操作进行中禁用重复点击,并在按钮内展示 loading。 + +## 8. 前后端改造边界 + +### 8.1 `mobile-oa-h5` + +- 预签约订单列表与表单切换为专用页面/组件,不再受通用 `MarketListCard` 三字段摘要限制。 +- 复用现有市场路由上下文、请求状态、鉴权 token、错误映射和 `action-policy`。 +- `presign.js` 继续保留模块元数据,但不再承担复杂表单渲染。 +- 新增删除订单、转账创建/更新/提交/撤回等移动 API 调用。 + +### 8.2 `backend` + +在现有两套固定 scope 路由下补齐与 Web 对齐的能力: + +- `DELETE /api/mini/market/{scope}/presign-orders/{id}`:软删除订单;已转正式不可删除。 +- 预签转账创建、更新、删除、提交财务确认和撤回端点。 +- `form-options` 支持按 `regionId` 返回医院和地区负责人,并返回缴费方式、转账方式、状态等规范选项。 +- 列表和详情 DTO 返回 Web 所需全部字段与准确 `allowedActions`。 +- 所有读写继续执行租户隔离、角色数据权限和当前页面现场 scope;客户端不得覆盖 `tenant_no`、`sales_user_id` 或 scope。 + +### 8.3 不改动范围 + +- 不改变 Web 管理端既有行为。 +- 不改变市场专员 / 地区经理两套路由和 scope 设计。 +- 不在 `mobile-h5` 小程序壳中实现业务表单。 +- 不顺带改造协议、缴费、样本、运费等其他市场模块;它们在本模块验收后逐个参照改造。 + +## 9. 测试策略 + +### 9.1 前端 + +- 列表请求状态:首次、追加、搜索重置、重复触底、过期响应、追加失败重试。 +- 卡片字段格式与动作可见性。 +- 地区变更清空医院并重新加载;编辑回填顺序正确。 +- 缴费方式、样本类型、人员选择器值映射。 +- 转账锁定状态、上传状态和动作策略。 +- 删除、转正式成功后列表重载。 +- `pnpm build` 通过。 + +### 9.2 后端 + +- 专员与经理 scope 的列表、详情、更新、删除和转账操作隔离。 +- 跨租户主数据、跨地区医院、越权人员和伪造附件拒绝。 +- 已转正式 / 已作废订单不能编辑、删除或再次转正式。 +- 转账状态机:待付款可改删可提交;待财务确认可撤回;已确认不可改删。 +- 默认排序与分页稳定。 +- 运行相关测试后再运行后端全量测试。 + +### 9.3 知识图谱 + +完成代码修改后按仓库规则执行: + +- `./scripts/update-graph.sh backend` +- 涉及 `mobile-oa-h5`,当前图谱脚本无该目标;若本次同时修改 `web-admin` 才执行 `./scripts/update-graph.sh frontend`。 + +## 10. 验收标准 + +1. 列表保留白色顶部栏,完全移除绿色标题背景区域。 +2. 列表只提供关键词搜索;没有状态筛选和顶部新增长按钮。 +3. 右下角显示品牌绿圆形 `+` 悬浮按钮,点击进入新增页。 +4. 卡片显示 Web 列表全部字段,并提供同等的编辑、转正式、删除能力。 +5. 上滑触底自动加载下一页,直到服务端数据加载完毕。 +6. 新增 / 编辑字段、默认值、校验、禁用规则与 Web 一致。 +7. 地区、医院、人员、缴费方式、样本类型和转账方式均使用数据库或规范枚举选项;地区与医院正确级联。 +8. 意向金转账、附件上传、提交财务确认与撤回行为与 Web 一致。 +9. 市场专员与地区经理只看到和操作各自 scope 内的数据。 +10. 页面使用 Vant 4 与工作流移动风格,品牌主色为 `#0a9f6d`,不混用 Web 主色。 +