# 细胞存储管理（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 变更落地。