zkxw/docs/superpowers/specs/2026-10-03-per-sample-payment-presign-design.md

按样本缴费 + 预签约订单 + 意向金 — 设计说明（方案 2）

日期：2026-10-03
状态：已实现（P0）· 实现计划见 docs/superpowers/plans/2026-10-03-per-sample-payment-presign.md
方案：方案 2 — 三层缴费（样本方案 → 应缴批次 → 转账笔）+ 预签约独立模块

关联现状分析：docs/superpowers/specs/2026-10-03-cell-storage-protocol-sample-payment-analysis.md

关联既有设计（将被本设计部分取代或调整）：

• 2026-06-04-protocol-pay-mode-switch-design.md（模式切换下沉到样本级）
• 2026-06-17-protocol-invoice-request-design.md（开票对象改为转账笔）
• 采集协议单财务退费确认流程（本期取消，改为协议级登记 + 工作流审批）

---

1. 背景与目标

1.1 问题

现状：1 协议 → 1 套缴费主表 → N 条明细（期次与转账揉在一行）；多样本时按金额之和做趸交/分期。
实际业务：每个样本各自趸交/分期；一期/趸交计划下可有多笔转账；财务按笔确认；退费走工作流，协议侧只需登记。

1.2 目标

1. 正式协议：每样本一套缴费方案（合同金额、缴费方式、分期参数）。
2. 缴费分层：应缴批次 + 转账笔；财务确认最小单位 = 转账笔。
3. 协议级保留可手填总金额；与样本合同金额合计不一致时仅提示。
4. 新增预签约订单：录入意向金；按笔财务确认；转正式协议时仅提示意向金金额。
5. 退费：协议级登记（金额/备注/时间/附件），审批在工作流；下线协议模块内退费财务确认。

1.3 非目标（本期不做）

• 转正式单时自动冲抵/拆分意向金到样本。
• 强制协议总金额 = 样本合同金额之和。
• 开票驳回、冲红。
• 历史协议自动拆分迁移（见 §10；默认新单新模型，旧单兼容策略另定）。
• 新建独立「退费工作流」菜单（假设使用既有 OA；本模块只登记）。

---

2. 已确认产品决策

#	议题	决策
D1	财务确认粒度	每一笔转账（转 3 次确认 3 次）
D2	意向金入口	预签约订单；字段含到账金额、刷卡时间等
D3	预签约样本	多样本类型多选
D4	预签约金额/方式	整单一套合同总额 + 缴费方式
D5	意向金财务	与正式缴费相同：登记 → 提交财务 → 按笔确认
D6	转正式协议	缴费区上方提示意向金数量；正式金额全手填，不自动冲抵
D7	协议总金额	可手填；与样本合计不一致仅提示
D8	退费	不走采集协议单财务退费确认；工作流审批；协议侧协议级登记（可多条历史）
D9	菜单	新增 1 个「预签约订单」；改造「采集协议单」「缴退费财务确认及开票」

---

3. 菜单与模块范围

3.1 新增菜单（1）

菜单	建议 path	归属
预签约订单	/#/cell-storage/presign-order	细胞存储，与采集协议单同级

3.2 改造菜单（2）

菜单	改造要点
采集协议单	按样本缴费 UI；协议总金额；退费登记；转单意向金提示；缴费 Tab 适配
缴退费财务确认及开票	按转账笔待办（正式 + 预签约意向金）；移除/隐藏退费确认 Tab；开票挂转账笔；菜单文案建议改为「缴费财务确认及开票」

3.3 隐藏/废弃

项	处理
缴费信息（已隐藏）	随新模型改造，仍可隐藏
退费确认（财务）（已隐藏）	废弃，不再使用
支付明细上的 tfqrz/ytf 退费状态机	新模型不再使用；旧数据只读兼容

3.4 连带

模块	说明
样本信息管理	查看协议弹窗缴费展示适配
OA 工作流	退费审批配置（若已有则对接登记；本设计不规定流程节点）
质检/生产费用摘要	paymentSummary 改为按样本/转账笔汇总

---

4. 领域模型

4.1 总览

biz_presign_order（预签约订单）
  ├── 样本类型多选（子表或逗号/JSON）
  └── biz_presign_transfer（意向金转账笔）→ 财务按笔确认
        │
        │ 转正式协议（复制客户/样本类型等；缴费手填）
        ▼
biz_collection_protocol
  ├── protocol_total_amount（手填总金额）
  ├── source_presign_order_id（可空）
  ├── biz_protocol_sample (N)
  │     └── biz_protocol_sample_payment（每样本 1 套方案）
  │           ├── pay_mode / contract_amount / 分期参数
  │           └── biz_protocol_payment_schedule（应缴批次）
  │                 └── biz_protocol_payment_transfer（转账笔）→ 财务按笔确认
  ├── biz_protocol_refund_record（协议级退费登记，N）
  └── biz_protocol_invoice_request
        └── item → transfer_id（改挂转账笔）

4.2 与旧模型关系

旧表	新模型
biz_protocol_payment（1/协议）	改为 每样本 biz_protocol_sample_payment（或扩展旧表加 sample_code 且 1 协议 N 行）
biz_protocol_payment_detail（期+转账合一）	拆为 schedule（批次） + transfer（转账笔）
detail 上退费字段/状态	废弃；改 biz_protocol_refund_record

实现选型（推荐）：

• 新建 biz_protocol_sample_payment / biz_protocol_payment_schedule / biz_protocol_payment_transfer / biz_presign_order / biz_presign_transfer / biz_protocol_refund_record。
• 旧 biz_protocol_payment + detail：保留只读服务历史协议（payment_model_version=1）；新协议 payment_model_version=2。

（若产品要求「旧单也改成按样本」，另开迁移专项；见 §10。）

4.3 样本关联键

缴费方案、批次、转账笔关联样本时：

• 持久化：同时存 protocol_sample_id（创建时）+ sample_code（业务关联主键）。
• 列表/财务/开票 JOIN：优先 tenant_no + sample_code（与 OpenSpec 一致）。
• 协议编辑重建样本行 id 后，按 sample_code 回绑，避免断链。

---

5. 表结构设计

5.1 预签约主表 biz_presign_order

字段	类型	说明
id	VARCHAR(64)	PK
order_date	CHAR(8)	业务日期 YYYYMMDD（对应年/月/日）
protocol_no	VARCHAR(64)	协议编号（预占或转单后回写，规则实现时定）
mother_name	VARCHAR(64)	母亲姓名
expected_delivery_date	CHAR(8)	预产期
region_id / hospital_id	VARCHAR(64)	采集地区/医院
sample_collect_time	DATETIME	采集时间
pay_mode	VARCHAR(8)	整单初步缴费方式 dj/fq/…
contract_amount	DECIMAL(18,2)	整单合同金额
sales_user_id	VARCHAR(64)	市场专员
region_manager_user_id	VARCHAR(64)	地区经理
remark	VARCHAR(512)	备注
order_status	VARCHAR(16)	如 draft/active/converted/void（最终码表实现定）
converted_protocol_id	VARCHAR(64)	转成的正式协议 id，可空
公共字段		tenantno, create, update_, del_flag, …

列表「到账金额」= Σ 已财务确认的意向金转账笔；「刷卡时间」可取最近一笔确认时间或业务填写的代表时间（实现时定展示规则）。

5.2 预签约样本类型 biz_presign_order_sample_type

字段	说明
id	PK
presign_order_id	预签约 id
sample_type_id	样本类型
order_num	排序

（多选几个类型就几行。）

5.3 预签约转账笔 biz_presign_transfer

字段	说明
id	PK
presign_order_id
transfer_amount	缴费金额
transfer_time	刷卡/转账时间
transfer_type	缴费方式（微信/银行等字典）
transfer_attachments	附件
remark
pay_status	同正式转账笔：dfj/jfqrz/yjf（无退费态）
finance_confirm_attachments / finance_remark	财务确认
公共字段

5.4 协议主表增量 biz_collection_protocol

字段	说明
protocol_total_amount	手填协议总金额
source_presign_order_id	来源预签约，可空
payment_model_version	1 旧 / 2 新；默认新单 = 2

5.5 样本缴费方案 biz_protocol_sample_payment

字段	说明
id	PK
collection_protocol_id
protocol_sample_id	可空兜底
sample_code	业务关联键
pay_mode	dj 趸交 / fq 分期 /（分改趸为操作结果，不必新枚举或增加 fgd 仅作标记）
contract_amount	该样本合同金额
installment_count / interval / start_date / advance_days / ratios 或 amounts	分期参数
lump_sum_deadline	趸交截止
公共字段

约束：同一协议下同一 sample_code 至多 1 条有效方案（del_flag=0）。

5.6 应缴批次 biz_protocol_payment_schedule

字段	说明
id	PK
sample_payment_id	方案 id
collection_protocol_id	冗余便于列表
sample_code	冗余
schedule_no	期次：趸交可为 1 或 null；分期 1..N
due_amount	应缴金额
due_date	应缴日期 YYYYMMDD
schedule_status	可选：open/cleared/void（或纯计算）
remark
公共字段

已缴金额 = Σ 下属转账笔中 pay_status=yjf 的 transfer_amount
欠缴金额 = due_amount − 已缴（展示用，可不落库）

5.7 转账笔 biz_protocol_payment_transfer

字段	说明
id	PK
schedule_id	所属批次
sample_payment_id / collection_protocol_id / sample_code	冗余
transfer_amount
transfer_time
transfer_type
transfer_attachments
remark
pay_status	dfj → jfqrz → yjf
finance_confirm_attachments / finance_remark
公共字段

说明：退费相关字段不放本表。

5.8 协议退费登记 biz_protocol_refund_record

字段	说明
id	PK
collection_protocol_id
refund_amount
refund_time
refund_remark
refund_attachments
workflow_instance_id	可选，关联 OA 实例
公共字段

不绑样本、不绑转账笔；一协议可多条。

5.9 开票子表调整

biz_protocol_invoice_request_item：

• 新字段 payment_transfer_id（正式转账笔）。
• 可开票条件：转账笔 pay_status=yjf 且未被有效开票占用。
• 金额快照 = 转账笔 transfer_amount。
• 旧 payment_detail_id：仅服务 payment_model_version=1 历史单。

---

6. 状态机

6.1 转账笔（正式 + 预签约意向金）

dfj（待缴费/待提交）
  │ 业务提交财务确认
  ▼
jfqrz（缴费确认中）
  │ 财务确认 → yjf
  │ 财务退回 → dfj
  ▼
yjf（已缴费）

• 无 tfqrz / ytf（新模型）。
• 仅 dfj 可编辑转账草稿；仅 dfj 可提交；仅 jfqrz 可确认/退回。

6.2 缴费方式（样本级）

模式	批次	转账
趸交 dj	通常 1 个应缴批次（应缴=样本合同额）	批次下可多笔
分期 fq	N 个批次（常 6 期）	每批次可多笔
分改趸	操作：保留已产生 yjf 的批次；作废未清批次；新建 1 个剩余应缴批次	同趸交

规则对齐旧「模式切换」设计，但作用域改为单样本方案。存在 jfqrz 时禁止切换。

6.3 预签约订单状态（建议）

状态	含义
draft/active	可编辑、可录意向金
converted	已转正式协议
void	作废

转正式：生成/关联 biz_collection_protocol，写入 source_presign_order_id；不自动生成样本缴费金额与转账。

6.4 退费

• 工作流：系统外/OA 完成审批。
  
• 协议：CRUD biz_protocol_refund_record 登记结果。
  
• 不改变转账笔 pay_status。

---

7. 前端页面设计

7.1 预签约订单（新）

• 模式：标准列表（对照 unit / 复杂列表按需）+ 新增/编辑弹窗。
  
• 列表列：对齐用户提供表头（序号、年/月/日、协议编号、母亲姓名、样本类型汇总、地区医院、缴费方式、采集时间、合同金额、到账金额、刷卡时间、预产期、市场专员、地区经理、备注）。
  
• 表单：样本类型多选；整单合同额/缴费方式；意向金转账笔可编辑列表（多笔）。
  
• 操作：提交财务确认、查看财务状态、转正式协议。

7.2 采集协议单 — 缴费区（改造）

[提示条] 来源预签约意向金已确认合计：¥xxx（若有）
[协议总金额] 手填    [样本合同合计] 只读汇总    不一致时 warning

Tab 或折叠：样本 A | 样本 B | …
  - 缴费方式、合同金额、分期参数
  - 应缴批次表（应缴、应缴日、已缴、欠缴）
  - 展开批次 → 转账笔列表（提交财务）

• 分改趸：样本方案工具按钮，确认后重建未清批次。
  
• 退费登记：独立区块/弹窗，列表展示历史登记；新增金额/时间/备注/附件。

7.3 缴费财务确认及开票（改造）

Tab	内容
缴费确认	待办 = 所有 jfqrz 转账笔（正式 + 预签约）；已办 = yjf
退费确认	删除或隐藏
开票申请	可选 yjf 转账笔；逻辑同前，对象改 transfer

卡片需展示：协议号、母亲、样本编码（正式）、来源（正式/预签约）、金额、时间。

7.4 UI 规范

• 遵循 Fresh Mint / docs/web-admin-ui-spec-fresh-mint.md。
  
• 弹窗 dialog-form-layout、label-position=top。
  
• 按钮带图标；状态用 el-tag。
  
• 模式索引：预签约列表偏 P01；协议缴费改造对照既有 protocol 页。

---

8. 后端 API 草案

前缀：/web/admin；租户隔离 + 数据权限。

8.1 预签约

方法	路径	说明
GET/POST	/presign-orders	列表/创建
GET/PUT/DELETE	/presign-orders/{id}	详情/更新/软删
POST	/presign-orders/{id}/convert	转正式协议
POST	/presign-transfers/{id}/submit-receipt-finance	提交确认
POST	/presign-transfers/{id}/receipt-confirm / receipt-reject	财务确认/退回

8.2 正式样本缴费

方法	路径	说明
PUT	/collection-protocols/{id}/sample-payments	批量保存各样本方案+批次（或分资源）
POST	/payment-transfers/{id}/submit-receipt-finance
GET	/payment-transfers/receipt-confirm 等	财务列表（可与预签约合并查询层）
POST	/payment-transfers/{id}/receipt-confirm / reject

8.3 退费登记

方法	路径	说明
GET/POST	/collection-protocols/{id}/refund-records
PUT/DELETE	/protocol-refund-records/{id}

8.4 开票

• eligible 改为返回可开票 transfer 列表。
  
• create item 写 payment_transfer_id。

8.5 废弃 API（新单不再调用）

• submit-refund-finance / refund-confirm / refund-reject（可保留供旧版协议 payment_model_version=1）。

---

9. 定价与校验

9.1 默认定价

• 废弃「1/2 样本共享一套 djfq 总价」作为唯一方案。
  
• 改为：单样本类型价目（或沿用原单样本价）写入该样本 contract_amount；双样本 = 两套方案。
  
• 协议 protocol_total_amount 默认可带出样本合计，允许用户改。

9.2 保存校验

规则	级别
样本方案存在 jfqrz 时禁止改模式/重生成批次	阻断
分期批次数 = 期数	阻断
批次应缴合计与样本合同金额	建议提示，是否强制实现时定（默认提示）
协议总金额 ≠ Σ 样本合同金额	仅提示（D7）
转账提交：金额>0、方式必填	阻断

---

10. 历史数据策略

推荐默认（P0）：

• 新创建协议 / 预签约转正：payment_model_version=2。
  
• 旧协议 version=1：继续走旧表与旧财务接口；前端按版本切换 UI。
  
• 不做自动「总账拆到样本」。

可选 P1：人工/脚本迁移工具（按规则挂到第一样本或均分）— 需单独评审，不阻塞 P0。

---

11. 实施分期建议

阶段	内容
P0-a	表结构 + 样本缴费方案/批次/转账笔 CRUD + 协议总金额 + 按笔财务确认（正式）
P0-b	采集协议单缴费 UI 改造；财务确认页改造；下线退费确认 Tab；退费登记
P0-c	预签约订单模块 + 意向金按笔确认 + 转正式 + 意向金提示
P1	开票改挂 transfer；旧单迁移工具；菜单文案「缴费财务确认及开票」
P2	费用摘要/查看弹窗等全量适配；文档与 OpenSpec 归档

---

12. 风险与依赖

1. 协议编辑重建样本 id：必须靠 sample_code 回绑缴费方案。
   
2. 财务待办量增加：按笔后卡片变多，需分页与筛选（协议号/母亲/样本编码/来源）。
   
3. 开票：与旧 detail 开票并存一期，注意双写/双读分支。
   
4. OA 退费：本模块只登记；若工作流未就绪，登记仍可先做。
   
5. 权限：预签约、转账确认、退费登记需独立或复用 menuCode。

---

13. 验收要点（摘要）

1. 两样本协议可分别设趸交/分期，互不影响。
   
2. 同一批次下登记 3 笔转账 → 财务出现 3 条待确认 → 确认后批次已缴累加正确。
   
3. 协议总金额与样本合计不符时能保存且有提示。
   
4. 预签约多选样本类型；意向金多笔确认；转正式后缴费区显示意向金提示且金额不自动写入样本。
   
5. 协议可登记多条退费；财务页无退费确认待办（新单）。
   
6. 旧版协议（若保留）仍可按旧流程处理收款。

---

14. 文档自检

• 无「TBD」占位关键决策（实施码表细节已标明「实现时定」）
  
• 与 D1–D9 无矛盾
  
• 退费与按笔收款边界清晰
  
• 菜单范围与先前确认一致（+1 预签约，改 2 个既有）
  
• 未纳入自动冲抵意向金、强制总金额相等
  

---

请审阅本文。确认后可进入 writing-plans 拆实现任务；若需修改决策，直接标注章节号即可。