docs: record standalone payment-info menu and per-sample view design.

Capture the agreed split from protocol-audit tabs, dual flow/sample views, and read-only aggregation APIs before implementation. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-05 12:50:01 +08:00
1 parent f73428dcfd
commit 33004fe9b9
@@ -0,0 +1,234 @@
+# 缴费信息独立菜单 + 按样本维度设计
+
+> 状态：待实现  
+> 日期：2026-10-05  
+> 界面模式：P02 复杂业务列表（按样本）+ 现有看板迁入；确认弹窗复用 P13 能力  
+> 参考页：`web-admin/src/views/cell-storage/sample-info/index.vue`、`protocol-audit/PaymentInfoTab.vue`、`/#/demo/order`
+
+## 1. 背景与目标
+
+### 1.1 现状
+
+【采集协议单】`/#/cell-storage/protocol-audit` 含四个 Pill Tab：协议单管理、缴费信息、储存证管理、满月待办管理。
+
+缴费信息 Tab（`PaymentInfoTab.vue`）按**流程**展示收款三列看板：已缴费（`dfj`）/ 缴费确认中（`jfqrz`）/ 缴费成功（`yjf`）。卡片粒度为转账笔或旧版缴费明细。
+
+仓库已有隐藏路由 `CellStoragePaymentInfo`（`/#/cell-storage/payment-info`，`menuCode: cellStorage:paymentInfo:list`），当前页面仅重定向回协议单 `?tab=payment-info`。
+
+数据层已按样本建模（`docs/sql/biz_per_sample_payment_presign.sql`）：
+
+```
+协议单 1 ──N 样本缴费方案 (biz_protocol_sample_payment)
+            └──N 应缴批次 (biz_protocol_payment_schedule)
+                └──N 转账笔 (biz_protocol_payment_transfer, pay_status)
+```
+
+协议表单内 `SamplePaymentPanel` 已按样本配置方案；缺的是跨协议的「一行一样本」运营列表。
+
+### 1.2 目标
+
+1. 将【缴费信息】从采集协议单拆成独立侧栏菜单，放在【预签约订单】下面、【样本信息管理】上面。
+2. 独立页按两个维度展示：
+   - **流程看板**：沿用现有已缴费 / 确认中 / 成功。
+   - **按样本**：一行 = 一个样本；展示协议号、客户、样本编码、缴费方式、合同额、已缴/待缴、整体进度；点开看各期与转账，并可上传凭证、提交财务确认。
+3. 采集协议单页去掉缴费 Tab，仅保留协议单管理 / 储存证 / 满月待办。
+
+### 1.3 已确认决策
+
+| 项 | 选择 |
+|----|------|
+| 样本列表粒度 | 一行 = 一个样本缴费方案 |
+| 样本维操作 | 可操作，与看板对齐（上传凭证、仅保存、提交财务确认） |
+| 协议单缴费 Tab | 完全移除 |
+| 页内形态 | 双 Pill Tab（对齐样本信息管理），不用两个侧栏菜单 |
+| 权限码 | 沿用 `cellStorage:paymentInfo:list` |
+| 写接口 | 不新增；复用 `payment-transfers` |
+
+## 2. 菜单与路由
+
+### 2.1 侧栏顺序
+
+```
+… → 采集协议单 → 预签约订单 → 【缴费信息】→ 样本信息管理 → …
+```
+
+### 2.2 前端路由
+
+| 项 | 约定 |
+|----|------|
+| Hash | `/#/cell-storage/payment-info` |
+| name | `CellStoragePaymentInfo` |
+| 组件 | `web-admin/src/views/cell-storage/payment-info/index.vue`（由重定向壳改为独立页） |
+| `isHide` | `false` |
+| menuCode | `cellStorage:paymentInfo:list` |
+
+`web-admin/src/router/modules/sqxp.ts`：取消隐藏，路由声明顺序与侧栏一致（预签约之后、样本信息之前）。
+
+### 2.3 页内 Tab
+
+| `?tab=` | 标题 | 实现 |
+|---------|------|------|
+| `flow`（默认） | 流程看板 | 迁入现有 `PaymentInfoTab.vue` |
+| `by-sample` | 按样本 | 新建 `PaymentBySampleTab.vue`（建议仍放在 `payment-info/` 或 `protocol-audit/` 旁，由独立页引用） |
+
+深链：`?tab=flow` / `?tab=by-sample`。
+
+### 2.4 采集协议单
+
+- `protocol-audit/index.vue`：从 `VALID_TABS` / `entityTabs` 移除 `payment-info`。
+- `protocol-audit?tab=payment-info`：重定向到 `CellStoragePaymentInfo`（可带 `tab=flow`），对齐样本 Tab 迁出时的兼容写法。
+
+### 2.5 菜单 SQL
+
+在 `docs/sql/` 增加增量脚本：将 `cellStorage:paymentInfo:list` 对应菜单取消隐藏，并把 `order_num` 调整到预签约订单与样本信息管理之间。前端静态路由与库内菜单需一并改。
+
+## 3. 按样本列表与详情
+
+### 3.1 列表（P02）
+
+主数据：`biz_protocol_sample_payment`（`del_flag=0`）。未配置按样本缴费方案的样本不进入本表。
+
+| 列 | 说明 |
+|----|------|
+| 协议号 | 关联采集协议单 |
+| 客户 | 母亲姓名；电话可同列次要展示 |
+| 样本编码 | `sample_code`（跨表业务键） |
+| 缴费方式 | Tag：趸交 `dj` / 分期 `fq` |
+| 合同额 | 该样本 `contract_amount` |
+| 已缴 / 待缴 | 已缴 = `pay_status=yjf` 的转账合计；待缴 = 未作废批次应缴合计 − 已缴（不为负） |
+| 整体进度 | 文案如 `已缴清 2/6 期`；进度按「已缴清期数 / 有效期数」 |
+| 缴费进度状态 | Tag，见 3.2 |
+
+筛选：关键词（协议号 / 客户姓名 / 样本编码 / 母亲电话）、缴费方式、缴费进度状态、应缴日期区间（命中该样本任一未作废批次的应缴日）。
+
+操作列 `fixed="right"`，min-width ≥ 260：
+
+- **查看**：打开详情。
+- **缴费确认**：仅当 `canConfirm=true` 时显示；打开详情并定位到最早一期待缴，再打开确认弹窗。
+- **协议单**：打开现有 `ProtocolViewDialog`。
+
+双击行等同查看。
+
+### 3.2 进度状态（互斥，优先级从上到下）
+
+| 码 | 标签 | Tag type | 条件 |
+|----|------|----------|------|
+| `jfqrz` | 缴费确认中 | warning | 存在任一转账 `pay_status=jfqrz` |
+| `yjq` | 已缴清 | success | 有效期（`schedule_status != void`）全部 `cleared` |
+| `bfyj` | 部分已缴 | primary | 已缴 > 0 且未全部缴清 |
+| `dfj` | 待缴费 | info | 其余 |
+
+有效期排除 `schedule_status=void`。已缴金额只计财务确认成功（`yjf`）的转账。
+
+状态、结论、类型字段用 `el-tag` + `status-tag-registry.ts`，不新增自定义色块。
+
+### 3.3 详情弹窗（可操作）
+
+- 上半：只读摘要（列表同行字段 + 协议状态）。
+- 下半：按期列出应缴额、应缴日、已缴、欠缴、批次状态；期下转账笔含金额、方式、时间、凭证、缴费状态。
+- **缴费确认**挂在有欠缴的期上，不挂在样本整行上。
+- 弹窗字段与看板完全一致：转账方式、金额、时间、备注、上传凭证；按钮「仅保存」「提交缴费确认」。
+- `jfqrz` / `yjf` 转账只读。
+- 本页不改缴费方案（趸交/分期参数仍在协议单表单 `SamplePaymentPanel`）。
+
+### 3.4 与流程看板
+
+| | 流程看板 | 按样本 |
+|--|----------|--------|
+| 粒度 | 一笔转账 / 一条待缴 | 一个样本 |
+| 操作 | 现有确认弹窗 | 同一套弹窗与写 API |
+| 旧模型 v1 明细 | 看板继续拼接展示 | **不进入**按样本列表 |
+
+建议将确认弹窗抽成双方共用组件（若改动面可控）；否则按样本 Tab 直接复用同一套表单逻辑与 API，禁止复制第二套字段规则。
+
+## 4. 后端 API
+
+原则：只加读接口，不改写库规则与 `pay_status` 枚举。
+
+### 4.1 新增
+
+`GET /web/admin/sample-payments`
+
+分页列表。主表 `biz_protocol_sample_payment`，JOIN 协议 + 当事人。
+
+查询参数：`page`、`pageSize`、`keyword`、`payMode`、`progressStatus`、`installmentDueDateStart`、`installmentDueDateEnd`。
+
+默认排序：`create_time DESC`。
+
+列表行不含完整转账树，只返回摘要：
+
+- 身份：`id`、`collectionProtocolId`、`protocolNo`、`protocolStatus`、`voidType`、`motherName`、`motherPhone`、`sampleCode`
+- 方案：`payMode`、`contractAmount`
+- 汇总：`paidAmount`、`dueRemainAmount`、`clearedScheduleCount`、`activeScheduleCount`、`progressStatus`、`canConfirm`
+
+`progressStatus` 过滤必须在查询层完成（SQL 聚合 / 子查询），禁止先分页再内存筛选。
+
+`GET /web/admin/sample-payments/{id}`
+
+单样本详情：复用 `_sample_payment_to_dict`（方案 + schedules + transfers），并补协议号、客户、协议状态。所属协议不在数据范围内 → 403。
+
+建议落在现有 `backend/app/api/protocol_sample_payment.py` 与 `backend/app/crud/protocol_sample_payment.py`。
+
+### 4.2 复用（不改语义）
+
+- `GET/POST /web/admin/payment-transfers`
+- `PUT /web/admin/payment-transfers/{id}`
+- `POST /web/admin/payment-transfers/{id}/submit-receipt-finance`
+- `GET /web/admin/collection-protocols/{id}/sample-payments`（协议表单）
+- 看板仍用现有 `payment-transfers` + 旧 `payment-details` 拼接
+
+### 4.3 租户与数据权限
+
+- 所有查询带当前用户 `tenant_no`，不信任客户端租户覆盖。
+- 列表与详情的数据范围按 **采集协议单** `apply_data_scope`（与能否看见该协议一致）。
+- 写操作维持现有 `_protocol_accessible` 校验。
+
+## 5. 权限
+
+| 项 | 约定 |
+|----|------|
+| 新页菜单码 | `cellStorage:paymentInfo:list`（已有角色自动可见） |
+| 协议单 | 去掉 Tab 不改 `biz:cellStorageProtocolAudit:list` 语义 |
+| 财务确认页 | 不改 `biz:cellStoragePaymentConfirm:list` |
+
+## 6. 兼容
+
+| 场景 | 处理 |
+|------|------|
+| 旧书签 `/#/cell-storage/payment-info` | 同一路由名，默认进入流程看板 |
+| `protocol-audit?tab=payment-info` | 重定向到独立页 |
+| 储存证 / 满月待办 / 协议单管理 | 不变 |
+| 财务缴退费确认及开票 | 不变 |
+| 协议表单按样本缴费配置 | 不变 |
+| `payment_model_version=1` | 仅看板兼容；按样本只展示新模型行 |
+
+## 7. 测试
+
+- 后端：分页；关键词 / 缴费方式 / 进度状态 / 应缴日；四种 `progressStatus`；数据范围外 403；租户隔离。
+- 前端：协议单仅 3 Tab；菜单位置；`?tab=` 深链；样本详情走「仅保存 / 提交缴费确认」；提交后看板与按样本数据一致。
+- 回归：财务确认列表、协议保存按样本缴费。
+
+## 8. 范围边界（本期不做）
+
+- 不改缴费状态机，不新增退费入口。
+- 不在本页改合同额 / 分期参数。
+- 不把预签约意向金并进按样本列表。
+- 不做导出，不做看板与按样本的合并视图。
+- 不重做财务确认页。
+- 不新建缴费状态表。
+
+## 9. 实现落点（建议）
+
+| 层 | 路径 |
+|----|------|
+| 独立页 | `web-admin/src/views/cell-storage/payment-info/index.vue` |
+| 按样本 Tab | `web-admin/src/views/cell-storage/payment-info/PaymentBySampleTab.vue` |
+| 看板 | 继续 `protocol-audit/PaymentInfoTab.vue`（或迁入 `payment-info/` 后由独立页引用） |
+| API 模块 | `web-admin/src/api/protocol-sample-payment.ts` |
+| 后端 | `backend/app/api/protocol_sample_payment.py`、`backend/app/crud/protocol_sample_payment.py` |
+| 路由 | `web-admin/src/router/modules/sqxp.ts` |
+| 协议单 Tab | `web-admin/src/views/cell-storage/protocol-audit/index.vue` |
+| 菜单 SQL | `docs/sql/` 增量脚本 |
+| 测试 | `backend/tests/` 增补 sample-payments 列表/详情 |
+
+实现完成后按仓库约定增量更新 `web-admin` / `backend` 代码知识图谱（`./scripts/update-graph.sh`）。