提交

2026-05-17 08:36:37 +08:00
1 parent 246ad2228e
commit 8e2dd8b9f0
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-13
@@ -0,0 +1,43 @@
+## Context
+
+参见 `docs/superpowers/specs/2026-05-13-cell-storage-protocol-modules-design.md`。当前仓库已实现基础信息管理 CRUD，但 `biz_collection_protocol` 及相关缴费/审核表在后端尚无 Model/API。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 最小闭环：协议单列表 + 概要详情；审核记录；财务两确认；分期预警。
+- 租户隔离、软删除、默认排序符合 `zkxw-engineering-standards`。
+- 审核不改变 `protocol_status`；审核支持多条历史（A1）。
+
+**Non-Goals:**
+
+- 不对 2.2.6 全部子表做一次性完整表单。
+- 不实现退费发起与非 `jfqrz`/`tfqrz` 入口的财务动作。
+- 不用工作流引擎替换表驱动逻辑。
+
+## Decisions
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 建模范围 | 仅 `biz_collection_protocol`、`biz_protocol_audit`、`biz_protocol_payment`、`biz_protocol_payment_detail` | 方案 C，对齐已确认边界 |
+| API 前缀 | 延续 `/web/admin`，新路由文件例如 `collection_protocol.py`，在 `api/__init__.py` 注册 | 与 `basic_info.py` 一致 |
+| 审核 | 仅插入 `biz_protocol_audit` | 用户选定方案 A |
+| 财务确认 | 列表过滤固定状态；POST 校验当前行状态后更新 | 防止误操作 |
+| 预警日期 | 服务器日期与 `installment_due_date`（YYYYMMDD）比较 | 简单可靠 |
+| 前端路由 | `/cell-storage/*` 五页 | 已定稿 |
+
+## Risks / Trade-offs
+
+- **详情信息不足** → 第一版标注「概要」，后续迭代补子表 Tab。
+- **无退费发起** → 退费确认页可能长期为空，依赖外部流程或后续变更。
+- **并发确认** → 依赖数据库行更新与状态校验；必要时可加重试提示。
+
+## Migration Plan
+
+- 无破坏性 schema 变更：部署顺序为后端 → 前端；可选执行菜单 SQL 补丁（若有）。
+- 回滚：下线路由与菜单项，禁用新 API 路由注册。
+
+## Open Questions
+
+- 协议单第一版是否允许「新建/编辑」：若需求未定，建议第一版只读列表 + 详情，创建单独后续变更。
@@ -0,0 +1,32 @@
+## Why
+
+需求文档 `docs/中科兴皖需求V0.3.md` 中「细胞存储管理」下 2.2.6～2.2.10 尚未在 web-admin 与后端落地；业务依赖 `biz_collection_protocol` 及缴费/审核表。需要在租户隔离与既有 `/web/admin` 约定下交付列表、审核与财务确认、分期预警的最小可用闭环。
+
+## What Changes
+
+- 新增一级菜单 **细胞存储管理**及 5 个子路由页面（与 `sqxp.ts`、`backend/app/api/menu.py` 静态菜单对齐）。
+- 后端新增采集协议单查询、审核写入、缴费明细财务确认、分期预警查询等 API；补充对应表的 SQLAlchemy Model 与 CRUD（方案 C：最小表集）。
+- 前端新增 `views/cell-storage/**` 五个列表页（及必要弹窗），对接上述接口；样式对齐 Fresh Mint 与 CRUD 模板页。
+- **不包含**：退费发起、协议单子表（采集信息/样本等）全量录入 UI；工作流引擎驱动本组菜单。
+
+## Capabilities
+
+### New Capabilities
+
+- `cell-storage-collection-protocol`: 采集协议单列表与概要详情 API；Web 列表/详情（第一版以主表 + 缴费概要为主）。
+- `cell-storage-protocol-audit`: 协议附件类审核（写入 `biz_protocol_audit`，不修改协议单状态）；多条审核历史（A1）；审核列表与提交。
+- `cell-storage-receipt-confirm`: 财务收款确认列表（仅 `jfqrz`）与确认动作（`jfqrz`→`yjf`）。
+- `cell-storage-refund-confirm`: 财务退费确认列表（仅 `tfqrz`）与确认动作（`tfqrz`→`ytf`）；不包含退费发起。
+- `cell-storage-installment-warning`: 分期应缴预警列表（仅 `dfj`、有分期序号；15 天内预警；逾期为应缴日早于今日）。
+
+### Modified Capabilities
+
+- （无）本变更为新增业务能力，不修改已归档基线 spec 的既有 REQUIREMENTS 表述。
+
+## Impact
+
+- **后端**：`backend/app/models/models.py`、`app/crud/`、`app/api/`（新建 `collection_protocol.py` 或合并至既有 router）、`app/api/__init__.py`、`app/main.py`。
+- **前端**：`web-admin/src/router/modules/sqxp.ts`、`web-admin/src/api/*.ts`、`web-admin/src/views/cell-storage/**`。
+- **菜单**：`backend/app/api/menu.py`。
+- **数据库**：沿用既有 DDL，原则上不新增表；若需菜单种子则可选 `docs/sql/` 补丁脚本。
+- **权威交叉**：`docs/superpowers/specs/2026-05-13-cell-storage-protocol-modules-design.md`。
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: 租户内采集协议单分页列表
+
+系统 SHALL 向已认证管理端用户提供采集协议单分页查询接口，数据来源为 `biz_collection_protocol`。查询 SHALL 限定当前用户所属 `tenant_no`，且默认排除 `del_flag=1`。列表默认排序 SHALL 为 `create_time DESC`（若无自定义排序）。列表 SHALL 至少包含协议号展示字段、协议状态、创建时间等便于识别的列。
+
+#### Scenario: 仅返回本租户数据
+
+- **WHEN** 用户请求采集协议单分页列表且租户为 T
+- **THEN** 响应中每条记录的 `tenant_no` SHALL 为 T，且不包含已软删除行
+
+### Requirement: 采集协议单概要详情
+
+系统 SHALL 提供按主键查询单条采集协议单的接口，返回 `biz_collection_protocol` 业务字段及公共字段。系统 SHOULD 在同响应或次级结构中附带同一协议单关联的缴费主表 `biz_protocol_payment` 概要（若存在），用于详情页展示缴费模式与金额类信息。
+
+#### Scenario: 详情命中未删除记录
+
+- **WHEN** 请求详情且 id 对应当租户下未删除协议单
+- **THEN** 系统返回该协议单数据；若存在缴费主表记录则一并返回概要
+
+#### Scenario: 跨租户或已删除拒绝
+
+- **WHEN** 请求详情 id 不属于当前租户或记录已软删除
+- **THEN** 系统返回 404 或与项目一致的业务错误，且不泄漏其他租户数据
+
+### Requirement: Web 采集协议单列表与概要详情页
+
+Web 管理端 SHALL 提供采集协议单列表页（筛选、工具栏、表格、分页），对齐 `web-admin` 标准列表模板与 Fresh Mint 规范。SHALL 支持打开概要详情（抽屉或弹窗），展示主表及缴费概要；第一版不要求录入全部子表字段。
+
+#### Scenario: 用户打开列表页
+
+- **WHEN** 用户进入「采集协议单」菜单路由
+- **THEN** 页面加载分页列表并可通过操作查看概要详情
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: 分期预警数据范围
+
+系统 SHALL 仅统计满足以下条件的 `biz_protocol_payment_detail` 行：当前租户、`del_flag=0`、`pay_status = dfj`（待缴费）、`installment_no` 非空（分期明细）。系统 SHALL NOT 将 `pay_status = jfqrz` 或其他状态纳入本列表。
+
+#### Scenario: 待缴费过滤
+
+- **WHEN** 请求分期预警列表
+- **THEN** 返回行均满足 `dfj` 且存在分期期序号
+
+### Requirement: 预警与逾期判定
+
+系统 SHALL 使用服务器当前日期与 `installment_due_date`（存储为 `YYYYMMDD` 字符串）比较。对每一行 SHALL 可判定：
+
+- **逾期**：应缴日早于当天；
+- **预警**：应缴日在当天或未来 15 天（含）内，且未逾期。
+
+系统 SHALL 支持按「预警 / 逾期 / 全部」类筛选参数过滤（具体 query 名称以实现为准，须在前后端一致）。
+
+#### Scenario: 超出 15 天未到期不标为预警
+
+- **WHEN** 某分期应缴日晚于今天起算第 16 天
+- **THEN** 该行在仅查「预警」类结果中 SHALL NOT 出现（「全部」是否出现由产品约定；默认实现可仍列出但标签非预警）
+
+### Requirement: Web 分期缴费预警页
+
+Web 管理端 SHALL 提供「分期缴费用户预警」列表页，展示应缴日、预警/逾期标签、关联协议单标识等；对齐标准列表模板与 Fresh Mint 规范。
+
+#### Scenario: 用户查看逾期列表
+
+- **WHEN** 用户选择逾期筛选并加载列表
+- **THEN** 展示的行均为应缴日早于今天的待缴费分期明细
@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: 审核记录写入且不修改协议单状态
+
+系统 SHALL 支持对指定采集协议单提交审核结果，持久化到 `biz_protocol_audit`，字段包含审核状态（`shtg` 审核通过、`shth` 审核退回）、审核备注、审核人（当前用户）及关联协议单 ID。系统 SHALL NOT 因审核提交而修改 `biz_collection_protocol.protocol_status` 或协议单其他状态字段。
+
+#### Scenario: 提交审核成功写入一行
+
+- **WHEN** 审核人对某协议单提交合法审核结果
+- **THEN** 系统插入一条 `biz_protocol_audit` 记录且协议单主表状态字段保持不变
+
+### Requirement: 同一协议单多条审核历史
+
+系统 SHALL 允许同一 `collection_protocol_id` 存在多条审核记录（按时间保留历史），SHALL NOT 以唯一约束强制单行覆盖。
+
+#### Scenario: 同一协议单两次审核
+
+- **WHEN** 同一协议单先后两次提交审核
+- **THEN** 系统存在两条审核记录且均可被列表查询到
+
+### Requirement: 审核列表查询
+
+系统 SHALL 提供审核记录分页列表接口，限定当前租户未删除数据，并支持按关键字（如协议号关联合理性由实现约定）、审核状态筛选。默认排序 SHALL 符合项目列表约定。
+
+#### Scenario: 列表仅含本租户审核
+
+- **WHEN** 请求审核列表
+- **THEN** 返回记录均属当前租户且 `del_flag=0`
+
+### Requirement: Web 采集协议单审核页
+
+Web 管理端 SHALL 提供「采集协议单审核」页面，包含列表与审核操作入口（通过/退回及备注）；弹窗表单 SHALL 符合 `label-position="top"` 与 CRUD 弹窗规范。
+
+#### Scenario: 用户完成一次审核提交
+
+- **WHEN** 用户填写审核结论并提交
+- **THEN** 系统调用审核接口成功后刷新列表或局部更新
@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: 收款确认待办列表
+
+系统 SHALL 提供分页列表接口，仅返回 `biz_protocol_payment_detail` 中 `pay_status = jfqrz`（缴费确认中）且当前租户、`del_flag=0` 的明细。列表 SHALL 携带关联协议单标识信息（至少协议单 ID 或协议号展示字段）以便财务核对。
+
+#### Scenario: 列表不含其他状态
+
+- **WHEN** 请求收款确认列表
+- **THEN** 每条明细的 `pay_status` SHALL 为 `jfqrz`
+
+### Requirement: 收款确认动作
+
+系统 SHALL 提供确认接口，针对单条缴费明细主键：若当前行 `pay_status` 为 `jfqrz`，SHALL 将其更新为 `yjf`（已缴费），并可写入财务确认附件字段（若请求体提供）。若当前行不是 `jfqrz`，SHALL 拒绝并返回业务错误。若已为 `yjf`，SHALL 拒绝重复确认（幂等错误语义）。
+
+#### Scenario: 正常确认
+
+- **WHEN** 对 `jfqrz` 明细调用确认接口
+- **THEN** 该明细 `pay_status` 变为 `yjf`
+
+#### Scenario: 非法状态拒绝
+
+- **WHEN** 对非 `jfqrz` 明细调用确认接口
+- **THEN** 系统拒绝且不修改数据
+
+### Requirement: Web 收款确认页
+
+Web 管理端 SHALL 提供「收款确认（财务）」列表页，对齐标准列表模板；SHALL 提供确认操作（弹窗上传附件/备注若需要）。页面 SHALL 仅展示待财务确认的明细。
+
+#### Scenario: 财务完成确认
+
+- **WHEN** 用户在列表中对一条待确认记录提交确认
+- **THEN** 调用后端确认接口成功后该行从待办列表消失或状态更新为已缴费
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: 退费确认待办列表
+
+系统 SHALL 提供分页列表接口，仅返回 `biz_protocol_payment_detail` 中 `pay_status = tfqrz`（退费确认中）且当前租户、`del_flag=0` 的明细。
+
+#### Scenario: 列表不含非退费确认中状态
+
+- **WHEN** 请求退费确认列表
+- **THEN** 每条明细的 `pay_status` SHALL 为 `tfqrz`
+
+### Requirement: 退费确认动作
+
+系统 SHALL 提供确认接口，针对单条缴费明细主键：若当前行 `pay_status` 为 `tfqrz`，SHALL 将其更新为 `ytf`（已退费）。若当前行不是 `tfqrz`，SHALL 拒绝。若已为 `ytf`，SHALL 拒绝重复确认。本变更 SHALL NOT 实现「发起退费」或向 `tfqrz` 推进状态的业务接口。
+
+#### Scenario: 正常确认退费
+
+- **WHEN** 对 `tfqrz` 明细调用退费确认接口
+- **THEN** 该明细 `pay_status` 变为 `ytf`
+
+### Requirement: Web 退费确认页
+
+Web 管理端 SHALL 提供「退费确认（财务）」列表页与确认操作，对齐标准列表与弹窗规范。
+
+#### Scenario: 财务完成退费确认
+
+- **WHEN** 用户对一条退费确认中记录提交确认
+- **THEN** 调用接口成功后该行不再出现在退费待办列表（或显示为已退费）
@@ -0,0 +1,39 @@
+## 1. 后端模型与 CRUD
+
+- [x] 1.1 在 `backend/app/models/models.py` 增加 `BizCollectionProtocol`、`BizProtocolAudit`、`BizProtocolPayment`、`BizProtocolPaymentDetail` 与 DDL 字段对齐
+- [x] 1.2 新建 `backend/app/crud/collection_protocol.py`（或拆分多个模块）：协议单列表/详情查询、审核插入、缴费明细状态更新、分期预警查询；统一 `_row_to_dict` camelCase 输出与租户过滤
+- [x] 1.3 新建 `backend/app/schemas/` 下 Pydantic 请求体（审核、财务确认、分页参数）若项目惯例需要（已在 `collection_protocol.py` 内联 Body，未单独建 schemas 文件）
+
+## 2. 后端 API
+
+- [x] 2.1 新建 `backend/app/api/collection_protocol.py`（名称可调整）：实现 GET 列表/详情、POST 审核、GET/POST 收款确认、GET/POST 退费确认、GET 分期预警；依赖 `require_admin_or_super_admin` 与 `get_db`
+- [x] 2.2 在 `backend/app/api/__init__.py` 与 `backend/app/main.py` 注册路由前缀 `/web/admin`（或既有聚合方式）
+- [ ] 2.3 手工验证：Swagger `/docs` 中上述路径可用，错误状态与业务校验符合 spec（需在本地启动后端后点验）
+
+## 3. 菜单与路由对齐
+
+- [x] 3.1 更新 `backend/app/api/menu.py` 的 `STATIC_MENU_TREE`：新增一级「细胞存储管理」及 5 个子菜单（path/component 与前端一致）
+- [x] 3.2 更新 `web-admin/src/router/modules/sqxp.ts`：同级路由与 meta.title；图标与现有风格一致
+
+## 4. 前端 API 与类型
+
+- [x] 4.1 新建 `web-admin/src/api/collection-protocol.ts`（或并入 `admin.ts`）：封装列表、详情、审核、两种确认、预警接口，路径与后端一致
+- [x] 4.2 在 `web-admin/src/types/api.d.ts` 补充必要类型（若项目惯例）（页面使用 `Record<string, unknown>` / 专用 Row 类型已够用）
+
+## 5. 前端页面（五页）
+
+- [x] 5.1 新建 `web-admin/src/views/cell-storage/protocol/index.vue`：列表 + 概要详情弹窗；对齐 `system/unit/index.vue` 结构
+- [x] 5.2 新建 `web-admin/src/views/cell-storage/protocol-audit/index.vue`：审核列表 + 审核弹窗（通过/退回）
+- [x] 5.3 新建 `web-admin/src/views/cell-storage/payment-confirm/index.vue`：仅 `jfqrz` 列表 + 确认弹窗
+- [x] 5.4 新建 `web-admin/src/views/cell-storage/refund-confirm/index.vue`：仅 `tfqrz` 列表 + 确认弹窗
+- [x] 5.5 新建 `web-admin/src/views/cell-storage/installment-warning/index.vue`：筛选预警/逾期/全部 + 标签列；对齐 Fresh Mint 状态色
+
+## 6. 数据与文档收尾
+
+- [ ] 6.1 若 DB 菜单走种子数据：在 `docs/sql/` 增加补丁脚本（可选），与仓库既有 `docs/sql/` 增量脚本惯例一致（全量基线为 `zkxw.sql`；当前为前端静态路由 + `STATIC_MENU_TREE`，若生产依赖 DB 菜单种子再补）
+- [ ] 6.2 本地联调：登录 admin → 五菜单可进 → 列表有接口响应（可用占位数据或手动插库验证）
+
+## 7. 验证
+
+- [ ] 7.1 后端：`pytest` 现有用例通过；如有新增关键逻辑可补最小单测（可选）（当前仓库 `tests/test_api_crypto.py` 与实现不一致导致 1 例失败，与本次变更无关）
+- [ ] 7.2 前端：`pnpm build` 或 `pnpm build:typecheck` 通过（仓库内尚有既有 vue-tsc 报错；新增页面未引入新的独占阻塞项）