zkxw/docs/superpowers/specs/2026-05-13-cell-storage-protocol-modules-design.md

细胞存储管理（2.2.6～2.2.10）— 实现设计（方案 C）

依据：docs/中科兴皖需求V0.3.md 菜单 2.2.6～2.2.10；数据模型 docs/sql/zkxw.sql（biz_collection_protocol 及其子表）。

范围：Web 管理端 web-admin + FastAPI backend；租户隔离与既有 /web/admin 响应风格保持一致。

---

1. 目标与非目标

1.1 目标

• 新增一级菜单 细胞存储管理，下挂 5 个页面，路由与目录命名已定稿。
• 最小闭环：协议单列表/概要详情；审核（仅写审核表）；财务收款确认与退费确认（限定状态流转）；分期缴费预警（固定规则）。
• 审核（2.2.7）：采用用户确认的 方案 A——审核仅写入 biz_protocol_audit，不修改 biz_collection_protocol.protocol_status。
• 审核记录策略：采用 A1——同一协议单允许多条审核记录，保留历史。
• 收款确认（2.2.8）：仅处理 pay_status = jfqrz → yjf。
• 退费确认（2.2.9）：仅处理 pay_status = tfqrz → ytf；不包含退费发起（不把状态推到 tfqrz）。
• 分期预警（2.2.10）：预警窗口 未来 15 天；列表仅包含 pay_status = dfj 的分期明细（不包含 jfqrz）；逾期定义为应缴日早于当天。

1.2 非目标（本阶段不做）

• 不实现科研捐赠、临床应用等非本菜单范围模块。
• 不把 2.2.6 下所有子表（采集信息、样本、运输、当事人等）一次性做全量录入与维护 UI；第一版协议单详情以主表 + 缴费相关信息为主，子表可后续迭代。
• 不引入工作流引擎驱动上述 5 个菜单（除非后续产品明确要求）；审核与财务确认以表字段 + 接口为准。
• 退费发起、待缴费→提交财务确认等业务动作若未在本阶段定义接口，不实现。

---

2. 前端：菜单与路由

2.1 一级菜单

• 标题：细胞存储管理
  
• 路径前缀：/cell-storage
  
• 组件容器：与现有模块一致，使用布局父级 /index/index。

2.2 子菜单与文件路径

需求编号	菜单名称	path	组件路径
2.2.6	采集协议单	protocol	views/cell-storage/protocol/index.vue
2.2.7	采集协议单审核	protocol-audit	views/cell-storage/protocol-audit/index.vue
2.2.8	收款确认（财务）	payment-confirm	views/cell-storage/payment-confirm/index.vue
2.2.9	退费确认（财务）	refund-confirm	views/cell-storage/refund-confirm/index.vue
2.2.10	分期缴费用户预警	installment-warning	views/cell-storage/installment-warning/index.vue

2.3 与后端菜单对齐

• 同步更新 web-admin/src/router/modules/sqxp.ts 与 backend/app/api/menu.py 中的静态菜单树，保证 前端路由与后端菜单接口一致（与仓库现有约定相同）。

2.4 UI 约定

• 列表页对齐模板：web-admin/src/views/system/unit/index.vue（筛选、工具栏、表格、分页）。
• 弹窗表单：label-position="top"，.dialog-form-layout，无 backdrop blur；色板遵循 docs/web-admin-ui-spec-fresh-mint.md。

---

3. 数据与后端建模范围（方案 C）

3.1 本阶段必须落地的表（SQLAlchemy Model + CRUD）

表名	用途
biz_collection_protocol	协议单主表：列表、概要详情
biz_protocol_audit	审核记录：列表、提交审核
biz_protocol_payment	缴费主表：展示缴费模式、合同金额、分期参数（与协议单 1:1）
biz_protocol_payment_detail	缴费明细：财务确认列表、状态变更、分期预警

可选后续迭代再补：biz_protocol_collection_info、biz_protocol_sample、biz_protocol_party_customer 等。

3.2 租户与软删除

• 所有查询默认 tenant_no = 当前用户租户、del_flag = 0。
• 写入时设置 tenant_no、create_by / update_by 等公共字段（与现有 CRUD 一致）。

3.3 列表默认排序

• 无自定义排序时：create_time DESC（与工程规范一致）；预警列表可按 installment_due_date ASC 等业务需求单独约定。

---

4. API 设计（前缀 /api，路由挂载与现有 basic_info、admin 一致）

以下路径均在 /web/admin 下（与现有基础信息管理相同前缀），具体以路由注册为准。

4.1 采集协议单（2.2.6）

• GET .../collection-protocols
  
  • Query：page, pageSize, keyword（协议号等）, protocolStatus（可选）
• GET .../collection-protocols/{id}
  
  • 返回：协议单主表字段 + 缴费主表概要（若存在）+ 缴费明细分页或摘要（实现时可先返回主表 + payment 一行）

创建/编辑协议单若产品未在本次冻结字段，可：第一版仅只读列表 + 详情，或最小字段新增——以 OpenSpec tasks 为准。

4.2 采集协议单审核（2.2.7）

• GET .../collection-protocol-audits
  
  • 列表：关联协议单展示协议号、审核状态、审核时间等；支持按 auditStatus、keyword 筛选
    
• POST .../collection-protocols/{id}/audit
  
  • Body：auditStatus（shtg | shth）, auditRemark（可选）
    
  • 行为：插入一条 biz_protocol_audit（A1：允许多条）；不更新 biz_collection_protocol.protocol_status
    
  • auditor_user_id / create_by 使用当前登录用户

4.3 收款确认（2.2.8）

• GET .../protocol-payment-details/receipt-confirm
  
  • 仅 pay_status = jfqrz
    
• POST .../protocol-payment-details/{detailId}/receipt-confirm
  
  • 校验当前行必须为 jfqrz
    
  • 更新为 yjf，写入 finance_confirm_attachments（若前端上传）、备注等
    
  • 幂等：已为 yjf 则返回业务错误提示

4.4 退费确认（2.2.9）

• GET .../protocol-payment-details/refund-confirm
  
  • 仅 pay_status = tfqrz
    
• POST .../protocol-payment-details/{detailId}/refund-confirm
  
  • 校验当前行必须为 tfqrz
    
  • 更新为 ytf
    
  • 幂等：已为 ytf 则返回业务错误提示
    

4.5 分期缴费预警（2.2.10）

• GET .../protocol-payment-details/installment-warning
  
  • 条件：installment_no IS NOT NULL、pay_status = dfj
    
  • 计算字段（可由后端计算返回）：
    
  • warningType = warn：today <= due <= today+15天
    
  • warningType = overdue：due < today
    
  • Query：warningType（warn | overdue | all）、page、pageSize
    
  • 排序建议：installment_due_date ASC

日期计算使用服务器本地日期（YYYYMMDD 字符串与当天对比）。

---

5. 权限（建议）

• 五个菜单默认 admin / super_admin 可见（与 Demo 体系一致）；若需细分「财务」角色，在 OpenSpec 任务中增加 perms 与角色菜单种子 SQL，不阻塞第一版。

---

6. 风险与后续迭代

• 协议单详情不完整：第一版可能无法满足采集专员全量录入，需在后续变更中按子表拆分页面或 Tab。
• 退费链路不完整：仅确认 tfqrz→ytf，需业务侧在其他模块或后续任务中补齐「发起退费」。
• 附件字段：finance_confirm_attachments 等与 MinIO 上传组件对齐现有项目用法。

---

7. OpenSpec 后续步骤

1. 使用 openspec new change 创建变更（例如 cell-storage-protocol-modules）。
2. 按 openspec-propose 生成 proposal.md、design.md、tasks.md 及 capabilities 下各 spec.md，与本设计对齐。
3. openspec-apply-change 按 tasks 实现后端 Model、CRUD、路由注册、sqxp.ts + menu.py、五个 Vue 页面及 web-admin/src/api 封装。

---

文档状态：已定稿上述边界（含 A、A1、财务状态、预警 C+1、菜单与路径）。审阅通过后进入 implementation plan（writing-plans）与 OpenSpec 变更落地。