缴费信息独立菜单 + 按样本维度设计

状态：已实现
日期：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 目标

将【缴费信息】从采集协议单拆成独立侧栏菜单，放在【预签约订单】下面、【样本信息管理】上面。
独立页按两个维度展示：
- 流程看板：沿用现有已缴费 / 确认中 / 成功。
- 按样本：一行 = 一个样本；展示协议号、客户、样本编码、缴费方式、合同额、已缴/待缴、整体进度；点开看各期与转账，并可上传凭证、提交财务确认。
采集协议单页去掉缴费 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）。

2026-10-05-payment-info-standalone-menu-design.md 11 KB История Исходник