docs: define mobile presign parity design for consistent market workflows.

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 主色。
+