From f5daab0d44f1e14725755d9e01488e56f5d3f37d Mon Sep 17 00:00:00 2001
From: zlwu <704541015@qq.com>
Date: Tue, 13 Oct 2026 19:37:15 +0800
Subject: [PATCH] docs: define complete mobile market parity scope and
 boundaries

---
 ...market-five-module-mobile-parity-design.md | 165 ++++++++++++++++++
 1 file changed, 165 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-10-13-market-five-module-mobile-parity-design.md

diff --git a/docs/superpowers/specs/2026-10-13-market-five-module-mobile-parity-design.md b/docs/superpowers/specs/2026-10-13-market-five-module-mobile-parity-design.md
new file mode 100644
index 00000000..91e1005c
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-13-market-five-module-mobile-parity-design.md
@@ -0,0 +1,165 @@
+# 市场五模块小程序与 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 页面、样本独立模块或科研捐赠业务。