docs: specify payment status labels and paid-amount semantics

Clarify transfer statuses (已付款/付款确认中/付款完成) vs period money (应缴费/已缴费/欠缴费), with 已缴费 counting only yjf, and rename the finance confirm menu. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-12 17:47:48 +08:00
1 parent 97bf67c962
commit 06a30ff658
@@ -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 若按码过滤无需迁移数据。