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