From 33004fe9b96c5ea7be653209511174c05ccf3441 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Mon, 5 Oct 2026 12:50:01 +0800 Subject: [PATCH] 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 --- ...-05-payment-info-standalone-menu-design.md | 234 ++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-05-payment-info-standalone-menu-design.md diff --git a/docs/superpowers/specs/2026-10-05-payment-info-standalone-menu-design.md b/docs/superpowers/specs/2026-10-05-payment-info-standalone-menu-design.md new file mode 100644 index 00000000..1d4eb4f4 --- /dev/null +++ b/docs/superpowers/specs/2026-10-05-payment-info-standalone-menu-design.md @@ -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`）。