zkxw/openspec/changes/cell-storage-protocol-modules/design.md

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

• 协议单第一版是否允许「新建/编辑」：若需求未定，建议第一版只读列表 + 详情，创建单独后续变更。