cykj/shanxia2.0
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
246ad2228e2e0af7f4eb3dfe581a50ea3e7f9559
shanxia2.0/docs/superpowers/specs/2026-05-13-cell-storage-protocol-modules-design.md
T

8.0 KiB
Raw Blame History

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

依据：docs/中科兴皖需求V0.3.md 菜单 2.2.6～2.2.10；数据模型 docs/sql/zkxw-requirements-v0.3-schema.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 列表默认排序

  • 无自定义排序时：order_num ASC, 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 变更落地。

Reference in new issue View Git Blame Copy Permalink