diff --git a/docs/superpowers/specs/2026-10-10-transfer-remark-and-withdraw-design.md b/docs/superpowers/specs/2026-10-10-transfer-remark-and-withdraw-design.md new file mode 100644 index 00000000..6d7fdf48 --- /dev/null +++ b/docs/superpowers/specs/2026-10-10-transfer-remark-and-withdraw-design.md @@ -0,0 +1,146 @@ +# 转账业务备注 + 缴费确认中撤回 + +> 状态:待用户审阅 +> 日期:2026-10-10 +> 范围:存储服务 · 细胞存储转账(意向金 / 趸交 / 分期每期) +> 界面模式:协议/预签表单内嵌转账表;缴费财务确认列表 +> 关联:`docs/superpowers/specs/2026-10-03-per-sample-payment-presign-design.md` + +## 1. 背景与目标 + +### 1.1 现状 + +转账行 UI 仅有:转账方式、转账金额、转账时间、转账凭证、状态。 + +库表已具备: + +| 表 | 业务备注 | 财务确认备注 | +|----|----------|--------------| +| `biz_presign_transfer` | `remark` | `finance_remark` | +| `biz_protocol_payment_transfer` | `remark` | `finance_remark` | + +缺口主要在前端:业务侧无法录入/展示 `remark`;查看与财务列表未系统展示双备注。 + +状态机:`dfj`(待缴费)→ `jfqrz`(缴费确认中)→ `yjf`(已缴费)。提交后业务侧锁定,**无撤回**,无法改完再提。 + +### 1.2 目标 + +1. 每笔转账可填写**业务备注**(`remark`),并在列表/查看展示。 +2. **财务备注**(`finance_remark`)仍由财务确认写入,业务侧只读展示。 +3. **缴费确认中**支持业务**撤回**为待缴费,修改后保存并再次提交。 +4. **已缴费**一律不可撤回、不可改业务字段。 + +### 1.3 非目标 + +- 不新增备注表或新列(复用现有 `remark` / `finance_remark`)。 +- 不改财务确认主流程(确认/驳回语义保持)。 +- 不做备注历史版本。 +- 样本信息 / 运费 / 催缴无转账登记表本轮不改。 +- 不自动冲抵意向金。 + +## 2. 字段语义与编辑规则 + +| 字段 | 文案 | 谁写 | 何时可写 | +|------|------|------|----------| +| `remark` | 备注 | 业务 | 仅 `pay_status = dfj`;与金额/凭证同锁定 | +| `finance_remark` | 财务备注 | 财务 | 确认收款时;业务侧只读 | + +- 锁定:`jfqrz` / `yjf` 下业务不可改金额、时间、方式、凭证、**备注**。 +- 撤回**不清除** `finance_remark`(保留历史财务批注)。 +- 公共字段 `remark` 即业务备注,不另建 `biz_remark`。 + +## 3. 撤回状态机 + +``` +dfj ──提交财务确认──► jfqrz ──财务确认──► yjf + ▲ │ + └──── 业务撤回 ──────┘ +``` + +| 动作 | 前置状态 | 结果状态 | 谁可操作 | 副作用 | +|------|----------|----------|----------|--------| +| 提交财务确认 | `dfj` | `jfqrz` | 业务(既有) | 无 | +| 撤回 | `jfqrz` | `dfj` | 业务 | **保留** `finance_remark` 与财务确认附件 | +| 财务确认收款 | `jfqrz` | `yjf` | 财务(既有) | 可写 `finance_remark` | +| 财务驳回(若已有) | `jfqrz` | 既有规则 | 财务 | 本设计不改驳回语义 | + +约束: + +- `can_withdraw_receipt(pay_status)` 当且仅当 `pay_status == "jfqrz"`。 +- `yjf` 不可撤回。 +- 撤回后流程:编辑(`dfj`)→ 保存 → 再次「提交财务确认」。 + +共享规则放在 `app/services/protocol_transfer_status.py`(与 `can_submit_receipt` / `can_confirm_receipt` 并列)。 + +## 4. API + +### 4.1 正式协议转账 + +- 既有 create/update 草稿:确保接收并持久化 `remark`;仅 `dfj` 可改业务字段(含备注)。 +- **新增** `POST /web/admin/.../payment-transfers/{id}/withdraw`(路径与现有 transfer 路由模块对齐) + - 租户隔离;校验转账存在且 `del_flag=0`。 + - `jfqrz` → `dfj`;不改 `finance_remark` / `finance_confirm_attachments`。 + - 非 `jfqrz` → 业务错误提示(如「仅缴费确认中可撤回」)。 + +### 4.2 预签意向金转账 + +- 既有 draft update:已支持 `remark`;保持仅 `dfj` 可改。 +- **新增** 对等 withdraw 接口(挂在 `presign-orders` 转账路由下)。 +- 列表/详情 `_transfer_to_dict` 已含 `remark` / `financeRemark`,保持不变。 + +### 4.3 财务确认 + +- 继续只写 `finance_remark`;确认列表/详情展示业务「备注」+「财务备注」。 + +## 5. 前端 + +### 5.1 转账表列顺序 + +方式 → 金额 → 时间 → 凭证 → **备注** → **财务备注** → 状态 → 操作 + +- **备注**:`dfj` 可编辑 `el-input`(建议 maxlength 与库一致 512);锁定后只读文本。 +- **财务备注**:始终只读(业务表单/查看);财务确认弹窗继续可写。 + +### 5.2 操作列 + +| 状态 | 操作 | +|------|------| +| `dfj` | 保存(若需)+ 提交财务确认 + 删除(既有) | +| `jfqrz` | **撤回**(`ElMessageBox.confirm`) | +| `yjf` | 无撤回;业务字段只读 | + +### 5.3 页面清单 + +| 页面 | 改动 | +|------|------| +| `PresignOrderFormDialog.vue` | 意向金表加备注/财务备注列;`jfqrz` 撤回 | +| `SamplePaymentPanel.vue` | 各期转账表同上;保存透传 `remark`;撤回调正式 API | +| `ProtocolFormDialog.vue` | 关联意向金子表展示备注/财务备注(只读,数据来自预签) | +| `ProtocolViewDialog.vue` | 意向金 + 样本转账只读表补两列 | +| 缴费财务确认页 | 待办/已办列表或详情补业务「备注」列(财务备注已有则对齐) | +| 缴费信息(转账明细弹窗/表) | 有转账列则补展示 | + +不改:催缴信息、样本信息、运费信息(无本类转账登记)。 + +## 6. 测试要点 + +1. 单测:`can_withdraw_receipt`:`jfqrz` 真,其余假。 +2. 单测/集成:withdraw 后状态为 `dfj`,`finance_remark` 不变。 +3. 单测:`yjf` / `dfj` 调用 withdraw 失败。 +4. 手工:预签与正式各走一遍「提交 → 撤回 → 改备注/金额 → 保存 → 再提交 → 财务确认」。 +5. 手工:查看弹窗与财务页可见双备注。 + +## 7. SQL + +**无需执行建表/加列迁移。** +(若环境缺少历史 `remark`/`finance_remark`,以 `docs/sql/biz_per_sample_payment_presign.sql` 为准核对,本需求不新增脚本。) + +## 8. 决策记录 + +| 项 | 结论 | +|----|------| +| 备注形态 | C:业务 `remark` + 财务 `finance_remark`,列表/查看都展示 | +| 业务备注锁定 | A:与金额/凭证一致,锁定后不可改 | +| 撤回权限 | 仅业务;`jfqrz → dfj` | +| 撤回与财务备注 | B:撤回不删除 `finance_remark` | +| 已缴费 | 一律不可撤回 |