From 06a30ff65834ac6aef09692cf3669258642e0709 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Mon, 12 Oct 2026 17:47:48 +0800 Subject: [PATCH] docs: specify payment status labels and paid-amount semantics MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify transfer statuses (已付款/付款确认中/付款完成) vs period money (应缴费/已缴费/欠缴费), with 已缴费 counting only yjf, and rename the finance confirm menu. Co-authored-by: Cursor --- ...status-and-paid-amount-semantics-design.md | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-12-payment-status-and-paid-amount-semantics-design.md diff --git a/docs/superpowers/specs/2026-10-12-payment-status-and-paid-amount-semantics-design.md b/docs/superpowers/specs/2026-10-12-payment-status-and-paid-amount-semantics-design.md new file mode 100644 index 00000000..c2d65e11 --- /dev/null +++ b/docs/superpowers/specs/2026-10-12-payment-status-and-paid-amount-semantics-design.md @@ -0,0 +1,192 @@ +# 转账「付款」状态文案 + 期次「已缴费」仅计付款完成 + +> 状态：待用户审阅 +> 日期：2026-10-12 +> 界面模式：细胞存储缴费相关列表/表单（P02 / P13）；市场小程序缴费/催缴卡片 +> 关联： +> - `docs/superpowers/specs/2026-10-09-payment-period-columns-and-schedule-edit-design.md`（期次列口径，本设计**覆盖**其中「已缴费含 dfj+jfqrz+yjf」） +> - `docs/superpowers/specs/2026-10-09-payment-info-excel-list-and-chase-design.md`（催缴纳入依赖欠缴） +> - `docs/superpowers/specs/2026-10-10-transfer-remark-and-withdraw-design.md`（状态机不变，仅文案） + +## 1. 背景与目标 + +### 1.1 问题 + +1. 转账笔状态文案与期次金额维度都用「缴费」，易混淆：`dfj` 在 Web 显示「已缴费」，与期次列「已缴费金额」同词不同义。 +2. 期次「已缴费」现网合计 `dfj + jfqrz + yjf`，与业务约定不符：业务要求**只有财务确认（付款完成）才算已缴费**。 +3. 菜单「缴费财务确认及开票」开票能力已下线，名称过时。 +4. 小程序与 Web 对同码文案不一致（小程序 `dfj=待缴费`、`yjf=已确认`）。 + +### 1.2 目标 + +1. **转账笔状态**统一为：「已付款 / 付款确认中 / 付款完成」。 +2. **期次金额维度**保持：「应缴费 / 已缴费 / 欠缴费」；**已缴费仅含 `yjf`**；欠缴费 = 应缴费 − 已缴费。 +3. 菜单改为「缴费财务确认」，并更新 `sys_menu`。 +4. Web 管理端与市场小程序（`mobile-oa-h5`）文案与金额口径一致。 + +### 1.3 非目标 + +- 不改状态码（仍为 `dfj` / `jfqrz` / `yjf` / `tfqrz` / `ytf`）。 +- 不改状态机流转与权限。 +- 不恢复开票 Tab。 +- 不改合同金额、应缴批次生成规则。 +- 不做无关 UI 重构。 + +## 2. 术语分层（权威） + +### 2.1 转账笔状态（`pay_status`） + +| 码值 | 新文案 | 含义 | +|------|--------|------| +| `dfj` | **已付款** | 业务已录转账；财务未确认；可编辑（规则不变） | +| `jfqrz` | **付款确认中** | 已提交财务；可撤回（规则不变） | +| `yjf` | **付款完成** | 财务已确认收款 | +| `tfqrz` | 退费确认中 | 本轮不改 | +| `ytf` | 已退费 | 本轮不改 | + +### 2.2 期次金额维度（展示字段，非状态码） + +| 字段 | 口径 | +|------|------| +| 应缴费 | 该期 `dueAmount` | +| 已缴费 | 该期转账中 **仅 `pay_status = yjf`** 的 `transfer_amount` 合计 | +| 欠缴费 | `max(应缴费 − 已缴费, 0)` | + +示例：应缴 10000，仅有「已付款」或「付款确认中」共 6000 → **已缴费 = 0，欠缴费 = 10000**。 + +### 2.3 勿混用 + +| 概念 | 正确词 | 错误混用 | +|------|--------|----------| +| 转账流程态 | 已付款 / 付款确认中 / 付款完成 | 已缴费 / 缴费确认中 / 缴费成功 | +| 期次统计金额 | 应缴费 / 已缴费 / 欠缴费 | 已付款金额（不要改列名） | +| 样本整体进度 `samplePaymentProgress` | 待缴费 / **付款确认中** / 部分已缴 / 已缴清 | 与转账 `payStatus` 仍分离；仅 `jfqrz` 文案与转账态对齐（见 §4.3） | + +## 3. 菜单改名 + +| 项 | 值 | +|----|-----| +| 旧 | 缴费财务确认及开票 | +| 新 | **缴费财务确认** | +| 菜单 id | `50000000000000000000000000000004` | +| perms / menuCode | `biz:cellStoragePaymentConfirm:list` | + +必须同步： + +1. `web-admin/src/router/modules/sqxp.ts`（前端固定菜单，当前主路径） +2. `backend/app/api/menu.py` +3. 新增 `docs/sql/migrations/2026-10-12-rename-payment-confirm-menu.sql`：`UPDATE sys_menu SET menu_name = '缴费财务确认' WHERE ...`（幂等） +4. 页面顶部注释等产品可见文案（如 `payment-confirm/index.vue` 文件头注释） + +## 4. 文案改造范围 + +### 4.1 单一事实源（Web） + +`web-admin/src/utils/status-tag-registry.ts` → `payStatus`： + +```ts +dfj: { label: '已付款', tagType: 'primary' }, +jfqrz: { label: '付款确认中', tagType: 'warning' }, +yjf: { label: '付款完成', tagType: 'success' }, +``` + +注释中「`payStatus.dfj=已缴费`」改为「`payStatus.dfj=已付款`」。 + +凡通过 `payStatusLabel` 渲染的 Tag 自动跟上。硬编码字符串须逐处替换（确认框、空状态、列头说明等）。 + +### 4.2 后端用户可见错误文案 + +将面向用户的「仅已缴费…」「仅缴费确认中…」「状态将变为「已缴费」」等改为「已付款 / 付款确认中 / 付款完成」对应语义。 +注意：历史错误信息里「仅已缴费状态可编辑」实际校验的是 `dfj`，应改为「仅已付款状态可编辑」，避免与期次「已缴费」混淆。 + +主要触及：`protocol_sample_payment.py`、`collection_protocol.py`、`presign_order.py`、`market_payment.py`、`protocol_transfer_status.py` 及相关测试断言。 + +### 4.3 样本进度 / 期次财务审核 + +- `samplePaymentProgress.jfqrz`：现为「缴费确认中」。为与转账态一致，改为 **「付款确认中」**。其余（待缴费 / 部分已缴 / 已缴清）保持。 +- `periodFinanceAudit`：`确认中` / `已通过` 等可保留（财务审核摘要，非转账主状态）；若产品希望完全统一，可改为「付款确认中」——**默认保留短文案「确认中」，避免宽表拥挤**。 + +### 4.4 质检/生产费用摘要等旁路文案 + +`qc_work_order_fee_summary.py` 等映射表中的 `jfqrz`/`yjf` 中文须改为「付款确认中」/「付款完成」。 + +### 4.5 临床 / 试点服务 + +与细胞存储共用 `payStatus` 注册表时，**文案一并变更**（方案 A）。状态机与业务规则不变。硬编码「已缴费」Tag 的临床页同步替换。 + +### 4.6 市场小程序（`mobile-oa-h5`） + +| 文件/模块 | 动作 | +|-----------|------| +| `src/market/modules/payment.js` `PAY_STATUS` | `dfj→已付款`，`jfqrz→付款确认中`，`yjf→付款完成` | +| `PAYMENT_PROGRESS.jfqrz` | → 付款确认中 | +| `src/market/modules/presign.js`、`PresignTransferCard.vue` | 对齐同上 | +| 列表展示 | 列名「应缴费/已缴费/欠缴费」**保留**；数值依赖后端新口径 | +| 相关 `*.test.js` | 更新期望文案 | + +`mobile-h5` 壳菜单无「缴费财务确认」入口，无需改菜单名。 + +## 5. 金额口径改造（核心） + +### 5.1 权威实现 + +后端 `backend/app/services/sample_payment_period_summary.py`： + +- `_DISPLAY_PAID_STATUSES` 从 `("dfj", "jfqrz", "yjf")` 改为 **`("yjf",)`** +- `displayPaidAmount` 语义 = 期次「已缴费金额」= 仅付款完成 +- `arrearsAmount` = `max(due - displayPaidAmount, 0)`（公式不变，输入变严） + +前端对齐： + +- `web-admin/src/utils/protocol-sample-payment.ts` 中 `schedulePaidArrears` / `DISPLAY_PAID_STATUSES` 改为仅 `yjf` +- 已有 `scheduleFinanceConfirmedPaidArrears` 与新口径一致，可复用或让 `schedulePaidArrears` 委托之，避免双份逻辑漂移 + +### 5.2 级联消费者（必须同口径） + +| 能力 | 说明 | +|------|------| +| 缴费信息宽表期次列 | `displayPaidAmount` / 欠缴列 | +| 催缴列表 | `payment_chase.chase_period_money` 依赖 `summarize_period`；欠缴变大 → 更多期可能进入催缴 | +| 市场小程序缴费/催缴 | `market_payment` 组装的 `paidAmount` / `arrearsAmount` / `displayPaidAmount` | +| 协议查看/表单期次摘要 | 若走同一摘要函数则自动正确 | + +### 5.3 已缴费时间 + +保持现规则：该期转账列表**首笔**（`create_time ASC`）的日期部分。 +说明：可能首笔仍是「已付款」而未付款完成；时间表示「首次发生付款动作的日期」，金额「已缴费」仍只计付款完成。若后续产品要求「已缴费时间 = 首笔付款完成时间」，另开变更——**本设计不改时间规则**。 + +### 5.4 与样本进度 `paidAmount` 对齐 + +`compute_sample_payment_progress` 的 `paidAmount` **本来就只计 `yjf`**。本改动使期次展示口径与进度实收口径一致，消除历史分裂。 + +## 6. 测试与验收 + +### 6.1 单测（必改期望） + +- `backend/tests/test_sample_payment_period_summary.py`：`dfj`/`jfqrz` 不再计入 `displayPaidAmount`；仅 `yjf` 计入；欠缴随之变化 +- `backend/tests/test_payment_chase.py`、`test_market_payment_api.py`：催缴已缴/欠缴断言 +- `web-admin`：`protocol-sample-payment.test.ts` +- `mobile-oa-h5`：payment / list-presenter / parity 相关文案与金额断言 + +### 6.2 手工验收 + +1. 侧栏「存储服务」菜单显示「缴费财务确认」；DB 模式环境执行迁移后 `menu_name` 一致。 +2. 新建转账：Tag 为「已付款」→ 提交后「付款确认中」→ 财务确认后「付款完成」。 +3. 宽表：仅付款完成的金额进入「已缴费」；未确认笔全进「欠缴费」。 +4. 催缴：仅「已付款/付款确认中」未完成财务确认的期，在欠缴>0 且日期规则满足时仍可进催缴。 +5. 小程序缴费详情：状态文案与 Web 一致；期次金额与 Web 同单一致。 + +## 7. 实现顺序建议 + +1. 后端 `summarize_period` + 测试（口径先锁死） +2. 前端 `schedulePaidArrears` + 注册表文案 + 硬编码替换 +3. 小程序状态映射 + 测试 +4. 菜单三处 + SQL 迁移 +5. 后端错误文案与旁路映射扫尾 +6. 回归催缴 / 市场 API 测试 + +## 8. 风险与说明 + +- **催缴变严**：原先把未确认金额算进「已缴」会缩小欠缴；改后欠缴增大，催缴列表可能变长——符合业务确认。 +- **历史文档**：旧 design/plan 中「已缴 = dfj+jfqrz+yjf」以本文件为准覆盖；不必批量改历史文档，实现计划中引用本 spec。 +- **码值不改**：报表/SQL 若按码过滤无需迁移数据。