zkxw/docs/superpowers/specs/2026-10-13-market-five-module-mobile-parity-design.md

市场五模块小程序与 Web 功能对齐设计

日期： 2026-10-13
状态： 已确认
范围： 市场专员、地区经理的预签约订单、协议单、缴费信息、催缴信息、运费信息 10 个小程序入口

1. 目标与基准

小程序市场功能由 mobile-oa-h5 承载，后端使用 /api/mini/market/{specialist|manager}/... 路由。五个模块分别以以下 Web 页面为业务事实来源：

小程序模块	Web 权威页面
预签约订单	web-admin/src/views/cell-storage/presign-order/index.vue、PresignOrderFormDialog.vue
协议单	web-admin/src/views/cell-storage/protocol/index.vue、ProtocolFormDialog.vue、ProtocolViewDialog.vue
缴费信息	web-admin/src/views/cell-storage/payment-info/PaymentExcelList.vue
催缴信息	web-admin/src/views/cell-storage/payment-chase/index.vue
运费信息	web-admin/src/views/cell-storage/sample-freight/index.vue、FreightConfigDialog.vue、FreightEditDialog.vue

“对齐”包括：筛选条件、列表信息、详情信息、表单字段、业务校验、状态展示及本设计明确开放的动作。桌面表格和弹窗不原样移植，移动端继续使用 Vant、卡片、分区、底部弹层和固定操作栏。

2. 权限边界

2.1 两个角色的数据范围

• 市场专员：沿用已实现的本人现场单据范围。
• 地区经理：沿用已实现的负责地区或单据指定经理范围。
• 所有列表、详情、选项和写接口继续叠加租户隔离、软删除过滤、角色数据权限并集和现场范围；客户端不得传入身份或租户扩大权限。
• 两个角色复用同一套页面组件，通过固定角色路由和后端 allowedActions 决定数据及动作，不复制十套页面。

2.2 暂不开放的管理能力

以下能力保持 Web-only，小程序不展示入口，后端市场路由也不开放对应写动作：

• 协议审核；
• 协议生效、过期、作废、转科研等状态变更；
• 退费登记；
• 开票；
• 储存证与保险办理；
• 财务确认、财务拒绝。

小程序可以只读展示已产生的审核记录、状态变更记录、储存证和保险信息。市场人员可以“提交财务确认”和在确认中状态撤回，但不能代替财务执行确认或拒绝。

3. 技术方案

采用“共享移动壳 + 模块契约 + 专用复杂组件”的增量方案：

1. MarketModuleList.vue、MarketModuleDetail.vue、MarketModuleForm.vue 继续承担通用列表、详情、表单和动作编排。
2. src/market/modules/*.js 定义每个模块的筛选参数、卡片信息、详情分区、表单字段和静态动作白名单。
3. 协议单及预签约订单的复杂交互使用专用组件，不将多行样本、缴费期次、转账和附件硬塞进通用字段渲染器。
4. 后端 market_mobile.py 路由保持薄层，数据范围与业务校验放在现有 market_* service / CRUD 中；优先复用 Web 使用的核心 CRUD，移动接口只做 DTO 和权限适配。
5. 每个模块建立可执行的字段/动作契约测试，避免以后 Web 字段变化后移动端静默落后。

不采用十套角色页面，也不在小程序 WebView 中直接嵌入桌面管理页面。

4. 通用移动端交互

• 品牌主色使用小程序三墙色 #0a9f6d，不得引入 Web 的 #10b981 主色。
• 列表以单列业务卡片展示；状态、结论、类型使用语义化标签。
• 筛选条件与 Web 信息等价：关键词保留在页面顶部，其他条件使用筛选弹层或紧凑选择器，不因移动布局而删除条件。
• 列表继续使用滚动分页；搜索、重置后回到第一页并清空旧列表。
• 详情为全屏分区页面；复杂明细使用卡片嵌套，附件复用移动附件卡片。
• 新增/编辑为全屏表单；日期、字典、地区、医院、人员均使用移动选择器；地区变更后重置并重载医院。
• 底部操作栏只展示前端白名单与后端 allowedActions 的交集；所有触控目标至少 44×44px。
• 加载、空态、错误、重复提交、二次确认和保存成功后的刷新行为在五模块保持一致。

5. 五模块能力

5.1 预签约订单

对齐 Web 的关键词、订单状态筛选，列表与详情完整展示业务日期、协议编号、母亲姓名、预产期、地区、医院、采集专员、采集经理、采集时间、缴费模式、合同金额、到账金额、订单状态、备注及创建时间。

开放动作：新增、编辑、删除、转正式协议；意向金转账新增、编辑、删除、提交财务确认、撤回。已转正式、已作废及已锁定转账遵循 Web 状态限制。表单包含 Web 全部字段、样本类型多选和转账附件。

5.2 协议单

本轮对齐目标为 Web【存储服务】采集协议单。现有科研捐赠入口保留，避免回归，但不以科研捐赠页面作为本轮字段验收基准。

列表补齐 Web 的关键词、协议状态、创建时间、样本采集时间筛选及全部业务信息。新增、编辑和详情覆盖：

• 协议信息；
• 采集信息；
• 母亲、父亲和新生儿客户信息；
• 样本及运输信息；
• 按样本缴费方案与应缴期次；
• 预签约意向金只读关联；
• 协议内转账登记、编辑、提交财务确认和撤回；
• 协议、知情同意书、健康调查表等附件；
• 审核、状态变更、储存证、保险等只读信息。

开放动作：新增、编辑、查看、单条删除和移动端适配的批量删除。不得开放 §2.2 管理动作。

5.3 缴费信息

筛选补齐关键词、缴费方式、缴费进度、应缴费时间范围。列表卡片完整承载 Web Excel 宽表信息：协议号、客户、手机号、样本编码、签署日期、存储年限、存储项目、合同总额、缴费方式、优惠金额、应收总额、各期应缴金额/日期/已缴金额/已缴时间/欠缴金额、累计实缴、待缴金额和备注。

详情展示缴费概览、全部期次和全部转账信息。开放动作：查看协议、查看期次明细、登记/编辑转账、提交财务确认、确认中撤回。不得开放财务确认、拒绝、退费、开票或修改应缴计划。

5.4 催缴信息

筛选补齐关键词、催缴类型、缴费方式。列表完整展示协议号、客户、联系电话、样本编码、市场专员、缴费方式、期次、应缴日、应缴金额、已缴金额、欠缴金额、催缴状态和协议状态。

催缴为只读派生视图，不新增“催缴记录”实体。开放动作：查看该期转账明细、查看关联协议单；若从催缴进入缴费详情，仍按缴费模块的 allowedActions 决定是否可登记转账。

5.5 运费信息

筛选补齐关键词、运输方式、来源。列表与详情完整展示批次号、运输方式、运费金额、当前范围内关联数、来源、协议号、母亲姓名、子女姓名、样本编码、样本类型、创建人、创建时间、更新时间和备注。

开放动作：新增运费批次、编辑批次、关联样本、取消关联。关联与取消关联使用移动卡片多选。共享批次继续执行既有脱敏和写权限规则，不泄露范围外明细或数量。

6. 数据和 API 约束

• 不建立与 Web 重复的业务表；移动端和 Web 读写相同业务数据。
• 新增 DTO 字段时保持 camelCase 契约、Pydantic extra='forbid' 和明确类型。
• 跨表样本匹配使用 tenant_no + sample_code，不以协议 ID 作为稳定业务键。
• 所有写操作在后端重新验证租户、现场范围、状态和目标资源，不以按钮隐藏替代授权。
• 列表无自定义排序时保持 create_time DESC；派生列表按 Web 的业务排序规则执行。
• 附件继续使用 MinIO、受控上传目录与移动市场附件绑定校验。
• 当前目标不需要新增数据库表；若实现中发现必须变更字段或索引，须同步更新 docs/sql/ 并单独验证 MySQL 5.7 兼容性。

7. 错误处理与一致性

• 401/403、越权详情和越权写入由后端统一拒绝；前端显示明确提示并不缓存敏感响应。
• 校验错误保留后端业务消息；网络失败不清空用户正在编辑的表单。
• 删除、转正式、提交财务确认、撤回、关联和取消关联均二次确认并防重复提交。
• 保存后重新获取详情或列表，避免客户端局部状态与后端状态机不一致。
• 并发写入沿用已有锁定和锁后权限复核，不能通过旧详情页覆盖新状态。

8. 测试与验收

8.1 自动化测试

• mobile-oa-h5：模块契约、列表卡片字段、详情分区、筛选参数、动作策略、表单 payload、复杂组件状态机和附件行为测试。
• backend：两个角色对五模块的列表/详情/写操作、租户隔离、现场范围、状态限制、DTO 完整性与越权拒绝测试。
• 回归：现有市场测试、前端构建、后端相关测试、字段一致性检查、git diff --check。
• 修改函数签名、import 或新建文件后执行 ./scripts/update-graph.sh backend；若仅修改 mobile-oa-h5，现有图谱脚本无对应项目，不伪造 Web 图谱更新。

8.2 手工验收矩阵

至少使用市场专员和地区经理各一个真实测试账号，在 375px、390px、430px 视口逐页验证：

1. 五个入口均能加载、筛选、分页、查看详情。
2. 同一业务数据的信息元素与 Web 对照一致，移动端无横向压缩桌面表格。
3. 每个开放动作成功后状态和列表即时刷新。
4. §2.2 管理动作无入口，直调市场接口也不能执行。
5. 专员与经理看到的数据范围符合既有规则，兼岗用户进入不同入口时不发生范围串用。
6. 附件预览、上传、删除和错误恢复符合现有移动端规范。

9. 实施顺序

1. 建立五模块 Web ↔ 移动字段/动作契约，形成可失败的自动化测试。
2. 收敛并完成当前协议单在制改动，先恢复干净、可验证的基线。
3. 补齐预签约订单差异。
4. 补齐缴费信息和催缴信息，两者共享期次/转账展示。
5. 补齐运费信息。
6. 执行后端权限与前端构建回归，更新后端知识图谱。
7. 输出逐项完成矩阵及测试环境手工验收清单。

10. 非目标

• 不开放 §2.2 的管理动作。
• 不删除或重构 Web 页面。
• 不改变既有市场专员、地区经理数据范围算法。
• 不新增催缴记录实体，不引入消息发送能力。
• 不把桌面管理页直接嵌入小程序。
• 不以本轮任务重构无关 OA 页面、样本独立模块或科研捐赠业务。