307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
# 采集协议单 · 分期缴费可配置化设计
|
||
|
||
**日期**：2026-06-10
|
||
**范围**：`web-admin` 采集协议单新增/编辑弹窗（`ProtocolFormDialog.vue`）、查看弹窗、后端缴费主表/明细保存与计算
|
||
**前置 spec**：[2026-06-04-protocol-pay-mode-switch-design.md](./2026-06-04-protocol-pay-mode-switch-design.md)
|
||
**状态**：已实现（2026-06-10）
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
分期模式（`pay_mode=fq`）下，当前应缴费时间与应缴费金额均为**硬编码规则**：
|
||
|
||
| 维度 | 现状 | 目标 |
|
||
|------|------|------|
|
||
| 应缴费提前天数 | 第 2 期起固定提前 **10** 天 | 可配置，默认 **30** 天 |
|
||
| 每期缴费比例 | 各期**均分**合同金额 | 每期比例可配置，默认 `50/10/10/10/10/10` |
|
||
| 比例合计 | — | **必须 = 100%**；最后一期自动补齐 |
|
||
| 期数变化 | 明细条数联动 | 比例输入框数量同步；保留已有比例，新增框默认 0 |
|
||
|
||
本设计在既有「缴费模式切换 / 分期参数变更 / 已缴锁定」规则之上扩展，**不改动**趸交逻辑与明细状态机。
|
||
|
||
---
|
||
|
||
## 2. 决策记录
|
||
|
||
| 议题 | 决定 |
|
||
|------|------|
|
||
| 提前天数默认值 | **30** 天（替代原 10 天；更新 2026-06-04 spec 对应条目） |
|
||
| 提前天数适用范围 | 仅第 **2** 期起；第 1 期 = 分期开始时间 |
|
||
| 比例默认值（6 期） | `50 / 10 / 10 / 10 / 10 / 10` |
|
||
| 比例合计 | **必须 = 100%** |
|
||
| 最后一期比例 | **只读**，自动 = `100 − Σ(前 N−1 期)` |
|
||
| 期数减少（如 6→3） | **保留前 N 个**比例，最后一期自动补齐 |
|
||
| 期数增加（如 3→6） | **保留已有**比例，新增框默认 **0**，最后一期自动补齐 |
|
||
| 首次切分期 / 新增 | 期数 6、间隔 6 月、提前 30 天、比例默认 50/10/10/10/10/10 |
|
||
| 小数月间隔换算 | 仍 30 天/月（不变） |
|
||
| 已缴行（`yjf`） | 保留原 `dueAmount`，不参与比例/日期重算 |
|
||
| 部分已缴后重建未缴 | 剩余金额按**未缴期次比例归一化**分配 |
|
||
|
||
---
|
||
|
||
## 3. 数据模型
|
||
|
||
### 3.1 缴费主表新增字段
|
||
|
||
表 `biz_protocol_payment`：
|
||
|
||
| 字段 | 类型 | 默认 | 说明 |
|
||
|------|------|------|------|
|
||
| `installment_advance_days` | INT | 30 | 第 2 期起应缴费提前天数 |
|
||
| `installment_ratios` | VARCHAR(256) | NULL | 各期缴费比例，JSON 数组，如 `[50,10,10,10,10,10]`，长度 = `installment_count` |
|
||
|
||
迁移脚本：`docs/sql/migrations/2026-06-10-protocol-installment-config.sql`
|
||
同步更新 `docs/sql/zkxw.sql`。
|
||
|
||
### 3.2 前后端字段映射
|
||
|
||
| 后端 snake | 前端 camel |
|
||
|------------|------------|
|
||
| `installment_advance_days` | `installmentAdvanceDays` |
|
||
| `installment_ratios` | `installmentRatios` |
|
||
|
||
`installmentRatios` 在前端为 `number[]`，长度始终等于 `installmentCount`。
|
||
|
||
### 3.3 历史数据兼容
|
||
|
||
- 旧记录无新字段：`installmentAdvanceDays` 读默认 **30**；`installmentRatios` 为空时按**均分**反推或保存时按均分写入（编辑打开时若为空则 `Array(count).fill(100/count)` 末位补尾差到 100）。
|
||
- 只读查看：无比例快照时展示「均分（历史）」或按明细反算比例（可选，P1）。
|
||
|
||
---
|
||
|
||
## 4. 计算规则
|
||
|
||
### 4.1 应缴费时间
|
||
|
||
```typescript
|
||
function calcFqInstallmentDueDate(
|
||
startDate: string,
|
||
index: number, // 0-based 期次索引
|
||
intervalMonths: number,
|
||
advanceDays: number // 新增参数，默认 30
|
||
): string
|
||
```
|
||
|
||
- `index === 0`：返回 `startDate`
|
||
- `index >= 1`：`addIntervalMonthsYmd(startDate, index * intervalMonths)` 再 **`− advanceDays` 天**
|
||
|
||
前后端共用同一规则；后端 `protocol_payment_installment.py` 删除常量 `FQ_ADVANCE_DAYS = 10`，改为读主表字段。
|
||
|
||
### 4.2 应缴费金额（全额、无已缴）
|
||
|
||
设合同金额 `C`，比例数组 `R[0..N−1]`，ΣR = 100：
|
||
|
||
```
|
||
amount[i] = floor(C × R[i] / 100 × 100) / 100 // 前 N−1 期，分向下取整
|
||
amount[N−1] = C − Σ amount[0..N−2] // 最后一期补尾差
|
||
```
|
||
|
||
### 4.3 应缴费金额（部分已缴）
|
||
|
||
已有 `yjf` 行时，修改比例/期数/合同金额触发未缴重建：
|
||
|
||
```
|
||
remaining = contractAmount − Σ(dueAmount WHERE pay_status = 'yjf')
|
||
unpaidIndices = 未缴期次索引集合
|
||
unpaidRatioSum = Σ R[i] for i in unpaidIndices
|
||
amount[i] = remaining × R[i] / unpaidRatioSum // 前若干未缴期向下取整
|
||
最后一期未缴 = remaining − Σ(其他未缴期 amount)
|
||
```
|
||
|
||
已缴行 `dueAmount`、`installmentNo`、转账信息**不变**。
|
||
|
||
### 4.4 比例数组维护（期数联动 · 策略 1）
|
||
|
||
```typescript
|
||
function resizeInstallmentRatios(
|
||
oldRatios: number[],
|
||
newCount: number
|
||
): number[]
|
||
```
|
||
|
||
| 操作 | 行为 |
|
||
|------|------|
|
||
| `newCount > old.length` | 保留原数组，末尾补 `(newCount - old.length)` 个 **0** |
|
||
| `newCount < old.length` | 截取前 `newCount` 个 |
|
||
| `newCount === old.length` | 不变 |
|
||
| 最后一项 | 始终重算为 `100 − sum(前 N−1)`，**不可编辑** |
|
||
|
||
**示例**
|
||
|
||
- 6→3：`[50,10,10,10,10,10]` → `[50,10,40]`（末位自动）
|
||
- 3→6：`[50,10,40]` → `[50,10,0,0,0,40]`（末位自动）
|
||
|
||
校验：`sum(前 N−1) <= 100`；若 `> 100` 表单报错，禁止保存。
|
||
|
||
---
|
||
|
||
## 5. UI 设计
|
||
|
||
### 5.1 布局位置
|
||
|
||
`ProtocolFormDialog.vue` → 缴费信息 → 缴费主表 → `payMode === 'fq'` 区块。
|
||
|
||
在现有「分期期数 / 每期间隔(月) / 分期开始时间」下方新增一行（或两行）：
|
||
|
||
```
|
||
应缴费提前(天) [ 30 ] （整数，≥ 0，建议 min=0 max=365）
|
||
|
||
缴费比例(%) [50] [10] [10] [10] [10] [10]
|
||
第1期 … 第5期 第6期(自动)
|
||
合计：100% （前 N−1 可编辑，最后一期 disabled + 自动值）
|
||
```
|
||
|
||
- 每个比例框：`el-input type="number"`，宽度紧凑（约 64–72px），带期次序号 label（第 1 期…第 N 期）。
|
||
- 最后一期 label 加 `form-label-tip`：「自动补齐」。
|
||
- 比例变更 → 防抖或 `@change` 后调用 `syncPaymentDueAmounts()`（跳过锁定行）。
|
||
- 提前天数变更 → 纳入分期参数变更流程（见 §6）。
|
||
|
||
### 5.2 查看弹窗
|
||
|
||
`ProtocolViewDialog.vue` 分期区块只读展示：
|
||
|
||
- 应缴费提前(天)
|
||
- 缴费比例：「50% / 10% / … / 10%」
|
||
|
||
### 5.3 默认值
|
||
|
||
| 场景 | installmentAdvanceDays | installmentRatios |
|
||
|------|------------------------|-------------------|
|
||
| 新增协议，首次选分期 | 30 | `[50,10,10,10,10,10]` |
|
||
| 编辑旧数据，字段为空 | 30 | 均分生成并末位补齐 |
|
||
| dj→fq 切换 | 30 | 默认 6 期比例（若 resetCountInterval） |
|
||
|
||
---
|
||
|
||
## 6. 交互与联动
|
||
|
||
### 6.1 纳入「分期参数变更」的参数
|
||
|
||
扩展 `FqParams`：
|
||
|
||
```typescript
|
||
interface FqParams {
|
||
installmentCount: number | null
|
||
installmentIntervalMonths: number | null
|
||
installmentStartDate: string
|
||
installmentAdvanceDays: number | null // 新增
|
||
installmentRatios: number[] // 新增
|
||
}
|
||
```
|
||
|
||
以下变更走现有 `handleFqParamsChange` 流程（校验 → 确认 → 重建）：
|
||
|
||
- 分期期数
|
||
- 每期间隔
|
||
- 分期开始时间
|
||
- **应缴费提前天数**
|
||
- **缴费比例**（前 N−1 期）
|
||
|
||
`isSameFqParams` 同步比较新字段。
|
||
|
||
### 6.2 期数变更
|
||
|
||
1. `resizeInstallmentRatios` 调整数组（策略 1）
|
||
2. 重算最后一期比例
|
||
3. 触发 `handleFqParamsChange`（与改期数同一链路）
|
||
|
||
### 6.3 合同金额变更
|
||
|
||
`syncContractAmount` → `syncPaymentDueAmounts`：按当前比例重算**未锁定**明细金额（逻辑 §4.2 / §4.3）。
|
||
|
||
### 6.4 缴费模式切换
|
||
|
||
- **dj → fq**：生成 N 条明细时使用当前 `installmentRatios` + `installmentAdvanceDays`
|
||
- **fq → dj**：比例/提前天数字段保留主表快照（与现有分期参数一致，只读历史）
|
||
|
||
### 6.5 已缴 / 锁定规则
|
||
|
||
与 [2026-06-04 spec](./2026-06-04-protocol-pay-mode-switch-design.md) 一致：
|
||
|
||
- `yjf` / `jfqrz` / `tfqrz` / `ytf` 行锁定
|
||
- 含 `jfqrz` 等时禁止修改分期参数（含比例、提前天数）
|
||
- 期数不得小于已缴最大期次
|
||
|
||
---
|
||
|
||
## 7. 后端改造
|
||
|
||
### 7.1 CRUD / Schema
|
||
|
||
- `_row_to_dict` 增加两字段
|
||
- Create/Update body 可写（分期模式下必填校验见下）
|
||
- 读取 bundle 时返回数组
|
||
|
||
### 7.2 保存校验（`pay_mode=fq`）
|
||
|
||
1. `installment_advance_days` ≥ 0（建议整数）
|
||
2. `len(installment_ratios) === installment_count`
|
||
3. `sum(installment_ratios) === 100`（允许 ±0.01 浮点误差）
|
||
4. 各期 `due_amount` 之和 = `contract_amount`（±0.015，已有）
|
||
5. 明细条数 = 期数（已有）
|
||
|
||
### 7.3 计算服务
|
||
|
||
- `calc_fq_installment_due_date(..., advance_days)` 参数化
|
||
- 可选：抽取 `calc_installment_due_amounts_by_ratios(contract, ratios)` 与前端 mirror
|
||
|
||
---
|
||
|
||
## 8. 影响文件
|
||
|
||
| 层级 | 路径 |
|
||
|------|------|
|
||
| SQL | `docs/sql/migrations/2026-06-10-protocol-installment-config.sql`、`docs/sql/zkxw.sql` |
|
||
| Model | `backend/app/models/models.py` |
|
||
| CRUD/Schema/API | `backend/app/crud/collection_protocol.py`、相关 schema |
|
||
| 计算 | `backend/app/services/protocol_payment_installment.py` |
|
||
| 校验 | `backend/app/services/protocol_pay_mode_switch.py` |
|
||
| 前端工具 | `protocol-payment-installment.ts` |
|
||
| 前端工具 | `protocol-fq-params-change.ts` |
|
||
| 前端工具 | `protocol-pay-mode-switch.ts` |
|
||
| 表单 | `ProtocolFormDialog.vue` |
|
||
| 查看 | `ProtocolViewDialog.vue` |
|
||
| 文档 | 更新 `2026-06-04-protocol-pay-mode-switch-design.md` §2 决策表 |
|
||
|
||
---
|
||
|
||
## 9. 测试用例
|
||
|
||
| # | 场景 | 期望 |
|
||
|---|------|------|
|
||
| T1 | 新增 fq，默认 6 期 | 提前 30 天；比例 50/10/10/10/10/10；金额按比分配 |
|
||
| T2 | 改第 1 期比例为 60 | 末位自动变 0；前 5 期 10 各；金额重算 |
|
||
| T3 | 前 5 期各 25，合计 >100 | 表单报错，禁止保存 |
|
||
| T4 | 6→3 期 | 比例 `[50,10,40]`；3 条明细 |
|
||
| T5 | 3→6 期 | 比例 `[50,10,0,0,0,40]`；6 条明细 |
|
||
| T6 | 改提前天数 30→15 | 未缴应缴日重算（确认后） |
|
||
| T7 | 2 期 yjf + 改比例 | yjf 金额不变；未缴按归一化比例分 remaining |
|
||
| T8 | 编辑旧数据（无新字段） | 默认 30 天；比例均分展示 |
|
||
| T9 | 保存 | 后端校验比例和=100、金额和=合同 |
|
||
| T10 | 查看弹窗 | 展示提前天数与比例 |
|
||
|
||
---
|
||
|
||
## 10. 不在本次范围
|
||
|
||
- 缴费确认 / 退费列表页的筛选默认值（仍为「前 10 天」业务文案，与协议提前天数无关）
|
||
- 小程序端
|
||
- 按比例的历史数据批量迁移脚本（仅读兼容）
|
||
|
||
---
|
||
|
||
## 11. 实现顺序建议
|
||
|
||
1. DB 迁移 + Model/Schema/CRUD 字段
|
||
2. 前端 `protocol-payment-installment.ts`：比例算金额、提前天数参数
|
||
3. `protocol-fq-params-change.ts` / `protocol-pay-mode-switch.ts` 扩展
|
||
4. `ProtocolFormDialog.vue` UI + 联动
|
||
5. 后端校验 + 计算参数化
|
||
6. `ProtocolViewDialog.vue` 只读展示
|
||
7. 联调测试 T1–T10
|
||
|
||
---
|
||
|
||
**审阅**：请确认本 spec 无遗漏后，进入 `writing-plans` 生成实现任务清单。
|