This commit is contained in:
zlwu committed 2026-07-06 19:41:24 +08:00
1 parent cdaa0ac273
commit b7cd657f32
32 files changed
+2885 -1936

No files matched your search

@@ -0,0 +1,596 @@
# 采集协议单 · 缴费默认定价 Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 按「样本数 × 缴费模式」在新建/首次选模式时填充默认合同金额与分期模板;支持双样本 `djfq`(趸交+分期);趸交允许多条缴费明细;样本数/样本价变化不再自动改合同金额。
**Architecture:** 前端新增 `protocol-payment-presets.ts` 集中定价表与 `applyPaymentPreset()`;`PayMode` 扩展为 `dj | fq | djfq`,分期逻辑通过 `isInstallmentPayMode()` 统一处理 `fq` 与 `djfq`;后端校验放宽趸交多 `dfj`、合计校验,`djfq` 走分期分支;方案 B 用 `paymentDefaultsApplied` 标记避免重复填默认。
**Tech Stack:** Vue 3 · TypeScript · Element Plus · FastAPI · Python unittest · `tsx`(前端纯函数冒烟)
**Design spec:** `docs/superpowers/specs/2026-07-06-protocol-payment-defaults-design.md`
---
## File Map
| 文件 | 职责 |
|------|------|
| `web-admin/src/utils/protocol-payment-presets.ts` | **新建** 定价表、`getActiveSampleCount`、`applyPaymentPreset`、`isInstallmentPayMode` |
| `web-admin/scripts/test-protocol-payment-presets.ts` | **新建** 定价表冒烟脚本(`tsx` 运行) |
| `web-admin/src/utils/protocol-pay-mode-switch.ts` | `PayMode` 含 `djfq`;趸交多明细;切换时用 preset 重建 |
| `web-admin/src/utils/protocol-payment-installment.ts` | `alignFq*` / `syncFq*` 识别 `djfq` |
| `web-admin/src/utils/status-tag-registry.ts` | `djfq` 标签 |
| `web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue` | 模式 UI、首次默认、去掉样本价联动、保存校验 |
| `web-admin/src/views/cell-storage/protocol/ProtocolViewDialog.vue` | `djfq` 只读展示 |
| `web-admin/src/components/business/protocol-payment-detail-readonly/index.vue` | 分期字段展示含 `djfq` |
| `web-admin/src/views/quality-inspection/qc-work-order/QcWorkOrderProtocolPaymentPanel.vue` | 摘要 `djfq` 按分期展示 |
| `web-admin/src/utils/protocol-standard-import-parse.ts` | (P1)识别「趸交+分期」 |
| `backend/app/services/protocol_pay_mode_switch.py` | 趸交多明细合计校验;`djfq`→分期分支 |
| `backend/app/crud/collection_protocol.py` | `align_fq_*` 等 `djfq` 与 `fq` 同等 |
| `backend/app/services/qc_work_order_fee_summary.py` | `djfq` 标签与分期摘要 |
| `backend/tests/test_protocol_pay_mode_switch.py` | 更新/新增校验单测 |
| `backend/tests/test_protocol_payment_presets.py` | **新建**(可选)后端不依赖 preset,本任务以前端脚本为主 |
---
## 依赖顺序
```text
Task 1 (presets 纯函数)
→ Task 2 (后端校验)
→ Task 3 (pay-mode-switch + installment 工具)
→ Task 4 (标签/只读组件)
→ Task 5 (ProtocolFormDialog 主改动)
→ Task 6 (导入 P1 + 收尾 QA)
```
---
### Task 1: 定价表纯函数与冒烟测试
**Files:**
- Create: `web-admin/src/utils/protocol-payment-presets.ts`
- Create: `web-admin/scripts/test-protocol-payment-presets.ts`
- [ ] **Step 1: 创建 `protocol-payment-presets.ts`**
```typescript
// web-admin/src/utils/protocol-payment-presets.ts
export type PayMode = 'dj' | 'fq' | 'djfq'
export type PaymentPreset = {
contractAmount: number
installmentCount?: number
installmentAmounts?: number[]
}
const PRESETS: Record<1 | 2, Partial<Record<PayMode, PaymentPreset>>> = {
1: {
dj: { contractAmount: 22880 },
fq: {
contractAmount: 25880,
installmentCount: 6,
installmentAmounts: [6480, 3880, 3880, 3880, 3880, 3880]
}
},
2: {
dj: { contractAmount: 37880 },
djfq: {
contractAmount: 41000,
installmentCount: 5,
installmentAmounts: [22880, 6480, 3880, 3880, 3880]
},
fq: {
contractAmount: 44000,
installmentCount: 5,
installmentAmounts: [12960, 7760, 7760, 7760, 7760]
}
}
}
export function getActiveSampleCount(
samples: Array<{ sampleStatus?: string }>
): 1 | 2 {
const n = samples.filter((s) => String(s.sampleStatus || '') !== 'yzf').length
return (n >= 2 ? 2 : 1) as 1 | 2
}
export function resolvePaymentPreset(
sampleCount: 1 | 2,
payMode: PayMode
): PaymentPreset | null {
return PRESETS[sampleCount]?.[payMode] ?? null
}
export function isInstallmentPayMode(payMode: string): boolean {
return payMode === 'fq' || payMode === 'djfq'
}
export function availablePayModes(sampleCount: 1 | 2): PayMode[] {
return sampleCount === 2 ? ['dj', 'djfq', 'fq'] : ['dj', 'fq']
}
/** 校验双样本才能用 djfq */
export function isPayModeValidForSampleCount(
payMode: PayMode,
sampleCount: 1 | 2
): boolean {
return availablePayModes(sampleCount).includes(payMode)
}
```
- [ ] **Step 2: 创建冒烟脚本**
```typescript
// web-admin/scripts/test-protocol-payment-presets.ts
import assert from 'node:assert/strict'
import {
resolvePaymentPreset,
getActiveSampleCount,
isInstallmentPayMode,
isPayModeValidForSampleCount
} from '../src/utils/protocol-payment-presets'
const fq1 = resolvePaymentPreset(1, 'fq')!
assert.equal(fq1.contractAmount, 25880)
assert.deepEqual(fq1.installmentAmounts, [6480, 3880, 3880, 3880, 3880, 3880])
assert.equal(
fq1.installmentAmounts!.reduce((s, v) => s + v, 0),
fq1.contractAmount
)
const djfq2 = resolvePaymentPreset(2, 'djfq')!
assert.equal(djfq2.contractAmount, 41000)
assert.equal(djfq2.installmentCount, 5)
assert.equal(getActiveSampleCount([{ sampleStatus: 'ycj' }]), 1)
assert.equal(getActiveSampleCount([{ sampleStatus: 'ycj' }, { sampleStatus: 'yzf' }]), 1)
assert.equal(
getActiveSampleCount([{ sampleStatus: 'ycj' }, { sampleStatus: 'ycj' }]),
2
)
assert.equal(isInstallmentPayMode('djfq'), true)
assert.equal(isInstallmentPayMode('dj'), false)
assert.equal(isPayModeValidForSampleCount('djfq', 1), false)
assert.equal(isPayModeValidForSampleCount('djfq', 2), true)
console.log('protocol-payment-presets: OK')
```
- [ ] **Step 3: 运行冒烟**
```bash
cd web-admin && pnpm exec tsx scripts/test-protocol-payment-presets.ts
```
Expected: 输出 `protocol-payment-presets: OK`,exit 0。
---
### Task 2: 后端保存校验(趸交多明细 + djfq)
**Files:**
- Modify: `backend/app/services/protocol_pay_mode_switch.py`
- Modify: `backend/tests/test_protocol_pay_mode_switch.py`
- [ ] **Step 1: 修改 `validate_payment_details_for_save` 趸交分支**
将 `dj` 分支中「仅 1 条 dfj」改为「全部明细应缴合计 = 合同金额」:
```python
# backend/app/services/protocol_pay_mode_switch.py — pay_mode == "dj" 分支替换为:
if pay_mode == "dj":
total_due = sum(
_dec(r.get("due_amount") if r.get("due_amount") is not None else r.get("dueAmount"))
for r in rows
)
if contract and abs(total_due - contract) > 0.015:
raise ValueError(
f"趸交各明细应缴金额之和应为 {contract:.2f},当前为 {total_due:.2f}"
)
# 保留:存在 yjf 时,dfj 行 due 之和应等于 remaining(可选细化为与 total 一致即可)
```
删除:
```python
if len(dfj_rows) > 1:
raise ValueError("趸交模式仅允许一条待缴费明细")
```
以及单条 `dfj` 的 `expected` 校验(已由 `total_due` 覆盖)。
- [ ] **Step 2: `djfq` 走分期分支**
```python
installment_modes = ("fq", "djfq")
# ...
elif pay_mode in installment_modes:
# 原 fq 逻辑不变
```
- [ ] **Step 3: 更新单测**
`test_dj_rejects_multiple_dfj` 改名为 `test_dj_allows_multiple_dfj_when_sum_matches`:
```python
def test_dj_allows_multiple_dfj_when_sum_matches(self):
validate_payment_details_for_save(
"dj",
10000,
None,
[
{"payStatus": "dfj", "dueAmount": 2000},
{"payStatus": "dfj", "dueAmount": 8000},
],
)
def test_dj_rejects_multiple_dfj_wrong_sum(self):
with self.assertRaises(ValueError) as ctx:
validate_payment_details_for_save(
"dj",
10000,
None,
[
{"payStatus": "dfj", "dueAmount": 2000},
{"payStatus": "dfj", "dueAmount": 7000},
],
)
self.assertIn("之和应为", str(ctx.exception))
```
新增:
```python
def test_djfq_same_as_fq(self):
validate_payment_details_for_save(
"djfq",
41000,
5,
[
{"payStatus": "dfj", "installmentNo": 1, "dueAmount": 22880},
{"payStatus": "dfj", "installmentNo": 2, "dueAmount": 6480},
{"payStatus": "dfj", "installmentNo": 3, "dueAmount": 3880},
{"payStatus": "dfj", "installmentNo": 4, "dueAmount": 3880},
{"payStatus": "dfj", "installmentNo": 5, "dueAmount": 3880},
],
installment_ratios=[22880, 6480, 3880, 3880, 3880],
)
```
- [ ] **Step 4: 运行后端单测**
```bash
cd backend && source venv/bin/activate && python -m pytest tests/test_protocol_pay_mode_switch.py -v
```
Expected: 全部 PASS。
- [ ] **Step 5: 修改 `collection_protocol.py` 分期对齐**
约 L2814,将:
```python
if pay.pay_mode != "fq" or not pay.installment_count:
```
改为:
```python
if pay.pay_mode not in ("fq", "djfq") or not pay.installment_count:
```
全文检索 `pay_mode != "fq"` / `pay_mode == "fq"` 在同文件内一并调整。
---
### Task 3: 前端工具层(pay-mode-switch + installment)
**Files:**
- Modify: `web-admin/src/utils/protocol-pay-mode-switch.ts`
- Modify: `web-admin/src/utils/protocol-payment-installment.ts`
- [ ] **Step 1: 扩展 `PayMode` 并导入 preset**
```typescript
// protocol-pay-mode-switch.ts 顶部
import {
type PayMode,
isInstallmentPayMode,
resolvePaymentPreset,
getActiveSampleCount
} from '@/utils/protocol-payment-presets'
export type { PayMode }
```
- [ ] **Step 2: `canAddPaymentDetail` 趸交始终可添加**
```typescript
export function canAddPaymentDetail(payMode: string, _details: DetailLike[]): boolean {
if (isInstallmentPayMode(payMode)) return true
return true // dj:允许多条明细
}
```
- [ ] **Step 3: `evaluatePayModeSwitch` / `applyPayModeSwitch` 支持 `djfq`**
- `dj` → `djfq`:与 `dj` → `fq` 相同(无已缴才允许)
- `djfq` → `dj`:与 `fq` → `dj`
- `djfq` ↔ `fq`:按分期规则处理
- `applyPayModeSwitch` 重建分期明细时,从 `resolvePaymentPreset(sampleCount, toMode)` 取 `installmentAmounts`,无 preset 时回退 `defaultInstallmentAmounts`
- [ ] **Step 4: `protocol-payment-installment.ts`**
将所有 `payment.payMode !== 'fq'` / `=== 'fq'` 改为使用 `isInstallmentPayMode(payment.payMode as string)`(从 presets 导入)。
- [ ] **Step 5: 类型检查**
```bash
cd web-admin && pnpm exec vue-tsc --noEmit 2>&1 | head -40
```
Expected: 无新增 error(允许既有 warning)。
---
### Task 4: 标签与只读展示
**Files:**
- Modify: `web-admin/src/utils/status-tag-registry.ts`
- Modify: `web-admin/src/views/cell-storage/protocol/ProtocolViewDialog.vue`
- Modify: `web-admin/src/components/business/protocol-payment-detail-readonly/index.vue`
- Modify: `web-admin/src/views/quality-inspection/qc-work-order/QcWorkOrderProtocolPaymentPanel.vue`
- Modify: `backend/app/services/qc_work_order_fee_summary.py`
- [ ] **Step 1: `status-tag-registry.ts` 增加**
```typescript
djfq: { label: '趸交+分期', tagType: 'warning' } // 或 primary,与 fq 区分即可
```
- [ ] **Step 2: 只读组件分期条件**
`payment?.payMode === 'fq'` → `isInstallmentPayMode(payment?.payMode || '')`(ViewDialog、readonly、QcWorkOrderProtocolPaymentPanel)。
- [ ] **Step 3: 后端 `_PAY_MODE_LABELS`**
```python
_PAY_MODE_LABELS = {"dj": "趸交", "fq": "分期", "djfq": "趸交+分期"}
```
`build_protocol_payment_summary` 内 `pay_mode == "fq"` 改为 `pay_mode in ("fq", "djfq")`。
---
### Task 5: ProtocolFormDialog 主改动
**Files:**
- Modify: `web-admin/src/views/cell-storage/protocol/ProtocolFormDialog.vue`
- [ ] **Step 1: 缴费模式单选 UI**
```vue
<el-radio-group v-model="formData.payMode" @change="onPayModeChange">
<el-radio label="dj">趸交</el-radio>
<el-radio v-if="activeSampleCount === 2" label="djfq">趸交+分期</el-radio>
<el-radio label="fq">分期</el-radio>
</el-radio-group>
```
`activeSampleCount` = `computed(() => getActiveSampleCount(formData.samples))`。
- [ ] **Step 2: 分期区块条件**
`formData.payMode === 'fq'` → `isInstallmentPayMode(formData.payMode)`(模板内所有分期表单项、分期金额行)。
- [ ] **Step 3: 新增状态 `paymentDefaultsApplied`**
```typescript
const paymentDefaultsApplied = ref<Record<PayMode, boolean>>({
dj: false,
fq: false,
djfq: false
})
function applyPaymentPresetForMode(payMode: PayMode) {
const preset = resolvePaymentPreset(getActiveSampleCount(formData.samples), payMode)
if (!preset) return
formData.contractAmount = preset.contractAmount
if (isInstallmentPayMode(payMode) && preset.installmentCount) {
formData.installmentCount = preset.installmentCount
formData.installmentIntervalMonths = formData.installmentIntervalMonths ?? 6
formData.installmentStartDate =
formData.installmentStartDate || defaultInstallmentStartDateYmd()
formData.installmentAdvanceDays =
formData.installmentAdvanceDays ?? DEFAULT_INSTALLMENT_ADVANCE_DAYS
formData.installmentRatios = [...(preset.installmentAmounts || [])]
formData.paymentDetails = generateInitialFqDetails(
getFqParamsFromForm(),
preset.contractAmount
)
initPaymentDetailExpandFlags(formData.paymentDetails)
markPayDetailLocks(formData.paymentDetails)
syncLastConfirmedFqParams()
} else {
formData.paymentDetails = [
createPaymentDetailRow({
dueAmount: preset.contractAmount,
installmentDueDate: formData.lumpSumDeadline || '',
expanded: true
})
]
}
paymentDefaultsApplied.value[payMode] = true
}
```
- [ ] **Step 4: 改造 `onPayModeChange`**
在既有 `evaluatePayModeSwitch` 之前/之后:
```typescript
async function onPayModeChange(newMode: PayMode) {
const oldMode = lastConfirmedPayMode.value
// ... 既有 evaluate + apply 逻辑 ...
if (!paymentDefaultsApplied.value[newMode]) {
applyPaymentPresetForMode(newMode)
}
lastConfirmedPayMode.value = newMode
}
```
新建弹窗 `resetForm` / `openCreate` 时重置 `paymentDefaultsApplied` 全 `false`;编辑加载详情后全部标 `true`(不覆盖库内数据)。
- [ ] **Step 5: 去掉样本价 → 合同额自动联动**
`onSamplePriceChange` 改为空实现或仅刷新弱提示:
```typescript
function onSamplePriceChange() {
// 方案 B:不调用 syncContractAmount()
}
```
删除或停用 `syncContractAmount()` 内对 `formData.contractAmount` 的写入;保留函数供「恢复默认」P1 使用时可再启用。
可选弱提示(缴费 Tab):
```typescript
const samplePriceContractHint = computed(() => {
const sampleTotal = formData.samples
.filter((s) => s.sampleStatus !== 'yzf')
.reduce((sum, s) => sum + (Number(s.price) || 0), 0)
if (formData.contractAmount == null) return ''
if (Math.abs(sampleTotal - Number(formData.contractAmount)) > 0.01) {
return `样本价格合计 ${fmtMoney(sampleTotal)} 与合同金额不一致,请核对`
}
return ''
})
```
- [ ] **Step 6: 保存前校验 `djfq` 样本数**
在 `handleSubmit` 缴费校验段:
```typescript
if (
formData.payMode === 'djfq' &&
getActiveSampleCount(formData.samples) !== 2
) {
await ElMessageBox.alert('「趸交+分期」仅适用于 2 个样本,请切换缴费模式', '无法保存', {
type: 'warning'
})
return
}
if (!isPayModeValidForSampleCount(formData.payMode as PayMode, getActiveSampleCount(formData.samples))) {
await ElMessageBox.alert('当前缴费模式与样本数量不匹配', '无法保存', { type: 'warning' })
return
}
```
- [ ] **Step 7: 标准导入后标记默认已应用**
`applyPaymentFromImport` 末尾:
```typescript
paymentDefaultsApplied.value = { dj: true, fq: true, djfq: true }
```
- [ ] **Step 8: 编辑加载 `lastConfirmedPayMode`**
```typescript
lastConfirmedPayMode.value = (['fq', 'djfq'].includes(formData.payMode)
? formData.payMode
: 'dj') as PayMode
```
- [ ] **Step 9: 手动验证(开发环境)**
1. 新建 → 添加 1 样本 → 首次选「分期」→ 合同 25880、6 期金额正确
2. 再添加第 2 样本 → 合同/明细**不变**
3. 新建 2 样本 → 选「趸交+分期」→ 41000、5 期
4. 趸交 → 添加 2 条明细 2000+20880 → 保存成功
5. 2 样本 `djfq` 删 1 样本 → 保存拦截
---
### Task 6: 标准导入(P1)与收尾
**Files:**
- Modify: `web-admin/src/utils/protocol-standard-import-parse.ts`
- Run: `./scripts/update-graph.sh frontend`
- [ ] **Step 1: 导入识别 `djfq`**
`parsePayMode` 中:
```typescript
if (/趸交\s*[++]\s*分期|趸交.*分期/.test(v)) return { payMode: 'djfq' }
```
`ProtocolStandardImportParsed.payMode` 类型改为 `'dj' | 'fq' | 'djfq'`。
- [ ] **Step 2: 更新知识图谱**
```bash
./scripts/update-graph.sh frontend
```
- [ ] **Step 3: Lint**
```bash
cd web-admin && pnpm lint
cd backend && python -m pytest tests/test_protocol_pay_mode_switch.py -v
```
- [ ] **Step 4: 更新 design spec 状态**
`docs/superpowers/specs/2026-07-06-protocol-payment-defaults-design.md` 表头 `状态` → `已实现`。
---
## Spec 覆盖自检
| Spec § | Task |
|--------|------|
| §3 默认定价表 | Task 1 |
| §4 方案 B 填充时机 | Task 5 Step 3–4、7 |
| §5 趸交多明细 | Task 2、3、5 |
| §5.2 djfq 分期 | Task 2–5 |
| §6 模式切换修订 | Task 3、5 |
| §7 pay_mode=djfq | Task 2、4 |
| §8 UI | Task 4、5 |
| §8.3 样本价解耦 | Task 5 Step 5 |
| §9–10 前后端摘要 | Task 2–5 |
| §11 测试要点 | 各 Task Step 验证 |
| §4.3 恢复默认 P1 | **范围外**(未列入 Task) |
---
## 人工回归清单(提测)
- [ ] 新建 1 样本首次 `fq`:25880 / 6 期模板
- [ ] 新建 2 样本首次 `djfq`:41000 / 5 期
- [ ] 样本数 1→2 后金额不变
- [ ] 趸交 2+ 条 `dfj` 保存成功
- [ ] 分期合计 ≠ 合同额:前后端拦截
- [ ] 已缴锁定 + 模式切换:仍符合 2026-06-04
- [ ] 查看弹窗 / 质检费用摘要:`djfq` 标签与期次表
- [ ] 标准导入多笔趸交转账保存成功
---
## 执行方式
**Plan 已保存至** `docs/superpowers/plans/2026-07-06-protocol-payment-defaults.md`。
**两种执行方式:**
1. **Subagent-Driven(推荐)** — 每 Task 派发独立子代理,Task 间人工/代理复核
2. **Inline Execution** — 本会话按 Task 1→6 连续实现,每 Task 末 checkpoint
告知选用哪种方式即可开始实现。
@@ -0,0 +1,214 @@
# 采集协议单 · 缴费默认定价与明细规则设计
**日期**:2026-07-06
**范围**:`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-protocol-installment-config-design.md](./2026-06-10-protocol-installment-config-design.md)
**状态**:已实现
---
## 1. 背景与目标
业务方给出「样本数 × 缴费模式」下的**默认合同金额、默认期数、默认各期金额**。这些数值仅作录入辅助;用户可自由修改合同金额、分期期数、各期金额;趸交也可拆成多条缴费明细(如预付款 + 尾款)。
当前实现与目标的主要差距:
| 维度 | 现状 | 目标 |
|------|------|------|
| 合同金额来源 | 非作废样本 `price` 之和 | 按定价表填**默认**,用户可改;样本数变化**不**自动改金额 |
| 分期默认金额 | 均分或历史 50/10/10… | 固定模板(6,480 / 3,880…) |
| 分期默认期数 | 一律 6 期 | 1 样本 6 期;2 样本分期/混合 5 期 |
| 缴费模式 | `dj` / `fq` | 增加双样本 **趸交+分期** `djfq` |
| 趸交明细条数 | 后端禁止多条 `dfj` | 允许多条,合计 = 合同金额 |
| 默认填充时机 | 切分期、改样本价等会联动 | **方案 B**:仅新建或**首次**选缴费模式时填默认 |
---
## 2. 决策记录
| 议题 | 决定 |
|------|------|
| 默认值性质 | 仅初始填充,**不锁定**;用户可改合同金额、期数、各期金额 |
| 样本数变化 | **不**自动改合同金额、期数、明细(方案 B) |
| 缴费模式变化 | **首次**从空/未选切到某模式时填该模式默认;已选过且用户已编辑后,再次切换仍走既有「模式切换」确认流(见 §6) |
| 单样本分期默认合同额 | **25,880**(6,480 + 3,880×5) |
| 趸交默认合同额 | 优惠价:1 样本 **22,880**;2 样本 **37,880** |
| 双样本「趸交+分期」 | 新模式 `djfq`,默认 **41,000**,5 期:22,880、6,480、3,880、3,880、3,880 |
| 双样本纯分期 | 默认 **44,000**,5 期:12,960、7,760、7,760、7,760、7,760 |
| 趸交多条明细 | 允许;`Σ dueAmount(全部明细)= contractAmount`;保存时不再限制「仅 1 条 dfj」 |
| 样本 `price` 字段 | 仍维护样本单价;与合同默认**解耦**;导入/保存时可提示样本价合计与合同额不一致,**不阻断** |
| 定价表存放 | 前端 `protocol-payment-presets.ts`(常量);后端镜像校验逻辑不依赖默认表,只校验合计与条数 |
---
## 3. 默认定价表
有效样本数 = 当前协议单内 `sampleStatus !== 'yzf'` 的样本条数,取值 **1** 或 **2**(与现网一致,不支持 0 样本保存缴费)。
| 样本数 | `pay_mode` | 默认合同金额 | 默认期数 | 默认各期金额(元) |
|--------|------------|-------------|----------|-------------------|
| 1 | `dj` | 22,880 | — | 单条明细 `dueAmount = 22,880`(用户可拆多条) |
| 1 | `fq` | 25,880 | 6 | 6,480、3,880、3,880、3,880、3,880、3,880 |
| 2 | `dj` | 37,880 | — | 单条明细 `dueAmount = 37,880`(用户可拆多条) |
| 2 | `djfq` | 41,000 | 5 | 22,880、6,480、3,880、3,880、3,880 |
| 2 | `fq` | 44,000 | 5 | 12,960、7,760、7,760、7,760、7,760 |
**标签**:`djfq` 展示为「趸交+分期」;字典 `status-tag-registry` / 后端摘要增加 `djfq` → `趸交+分期`。
**双样本时缴费模式选项**:`dj`、`djfq`、`fq`(隐藏或禁用 `djfq` 当样本数 ≠ 2)。
---
## 4. 默认填充时机(方案 B)
### 4.1 会填充默认的场景
1. **新建协议单**,用户**第一次**选择缴费模式(`pay_mode` 从初始 `dj` 切到 `fq` / `djfq`,或新建后首次进入缴费 Tab 且明细为空时的初始化,与产品确认以「首次 `onPayModeChange` 且该模式从未应用过」为准)。
2. **新建协议单**,打开时若默认 `pay_mode=dj` 且 `paymentDetails` 为空:按 **当前样本数** 填趸交默认(合同额 + 1 条明细)。若此时样本数仍为 0,待用户添加第 1 个样本后**不**自动重填(方案 B);用户选模式或手动点「套用默认」时再填。
> **实现建议**:维护 `paymentDefaultsApplied: Record<PayMode, boolean>`(或 `lastAppliedPresetKey: string | null`)。某 `pay_mode` 第一次生效时调用 `applyPaymentPreset(sampleCount, payMode)`,并标记已应用。
### 4.2 不会自动改金额的场景
- 增删样本、样本作废/恢复
- 修改样本 `price`
- 修改合同金额后回头改样本
用户自行改合同额、期数、明细;仅触发**合计校验**与既有「分期参数变更 / 模式切换」确认流。
### 4.3 可选辅助(P1,非本期必须)
缴费主表旁「恢复默认」按钮:按当前样本数 + 当前 `pay_mode` 重新套用 §3 定价表,**需二次确认**。
---
## 5. 缴费明细与校验
### 5.1 趸交 `dj`
- 明细 **≥ 1** 条;用户可通过「添加明细」增加(含预付款场景)。
- `canAddPaymentDetail`:改为在 `dj` 下**始终允许**添加(或:待缴条数无硬上限,仅校验合计)。
- 保存校验:
- `Σ dueAmount(全部明细)` 与 `contractAmount` 差额 ≤ 0.01;
- 允许多条 `dfj`;
- 若存在 `yjf`:`Σ yjf.dueAmount + Σ dfj.dueAmount` 仍须等于 `contractAmount`(与现 `remaining` 逻辑一致,但允许多条 `dfj` 分摊剩余)。
### 5.2 分期 `fq` 与混合 `djfq`
- 明细条数 **=** `installment_count`(与现 `fq` 一致)。
- `installment_ratios` 存**各期金额(元)**,非百分比(与现网一致)。
- `Σ 各期 dueAmount = contractAmount`。
- `djfq` 在数据层按分期处理:每期有 `installmentNo`、应缴日;第 1 期金额语义为「趸交部分」,不做单独子表。
### 5.3 与标准信息导入
- 导入解析到的 `contractAmount`、多笔 `transfer` **覆盖**默认填充(与 [2026-07-02-protocol-standard-import-design.md](./2026-07-02-protocol-standard-import-design.md) 一致)。
- 导入后标记 `paymentDefaultsApplied` 全部为已应用,避免再自动覆盖。
---
## 6. 缴费模式切换(在 2026-06-04 上的修订)
既有切换规则(已缴锁定、确认流)**保留**。下列条目**修订**原 spec:
| 原规则 | 新规则 |
|--------|--------|
| 趸交仅 1 条有效明细 | 趸交可多条;切换生成时仍可合并为 1 条**默认**,用户随后可拆 |
| `pay_mode` 仅 `dj`/`fq` | 增加 `djfq`;`djfq` ↔ `fq` 按分期规则;`djfq` → `dj` 同 `fq` → `dj` |
| 切换后分期金额均分 | 切换后若走「重建明细」,使用 §3 对应默认各期金额(非均分) |
**双样本 → 单样本**(或反向):不自动改合同/明细(方案 B);若当前 `pay_mode=djfq` 且样本数变为 1,**阻断保存**并提示「请切换缴费模式」,或自动要求用户改模式(推荐:**保存前校验**样本数与 `djfq` 一致)。
---
## 7. 数据模型
### 7.1 `biz_protocol_payment.pay_mode`
| 值 | 含义 |
|----|------|
| `dj` | 趸交 |
| `fq` | 分期 |
| `djfq` | 趸交+分期(仅双样本) |
字段长度 `varchar(8)` 足够。无需新列;`installment_count` / `installment_ratios` 在 `djfq` 与 `fq` 用法相同。
### 7.2 迁移
- 字典项(若缴费模式走 dict):增加 `djfq`。
- 历史数据无 `djfq`,只读展示兼容即可。
---
## 8. UI
### 8.1 缴费模式
```text
[ 趸交 ] [ 分期 ] // 1 样本
[ 趸交 ] [ 趸交+分期 ] [ 分期 ] // 2 样本
```
### 8.2 分期金额区
- `fq` / `djfq`:展示期数、间隔、开始时间、各期金额输入格;默认期数/金额来自 §3。
- 合计行:`合计 xxx / 合同 xxx`(已有)。
### 8.3 样本价格
- 样本 Tab 的「价格」保留;**移除** `syncContractAmount()` 在样本价变更时对 `contractAmount` 的自动写入(方案 B)。
- 可选弱提示:样本价合计 ≠ 合同金额时展示 `form-tip`(不阻断保存)。
---
## 9. 后端改动摘要
| 文件 | 改动 |
|------|------|
| `protocol_pay_mode_switch.py` | `dj`:删除「仅 1 条 dfj」;改为明细总额校验;支持 `djfq` 走 `fq` 分支 |
| `collection_protocol.py` | 读写 `pay_mode=djfq`;列表/详情标签 |
| `qc_work_order_fee_summary.py` 等 | `djfq` 标签与分期展示 |
---
## 10. 前端改动摘要
| 文件 | 改动 |
|------|------|
| `protocol-payment-presets.ts` | **新建**,§3 定价表 + `applyPaymentPreset()` |
| `protocol-payment-installment.ts` | 默认金额生成改为调用 preset(均分仅作无 preset 时的兜底) |
| `protocol-pay-mode-switch.ts` | `dj` 多明细;`PayMode` 含 `djfq` |
| `ProtocolFormDialog.vue` | 模式 UI、首次填充、去掉样本价→合同额联动 |
| `ProtocolViewDialog.vue` | `djfq` 展示 |
| `status-tag-registry.ts` | `djfq` |
| `protocol-standard-import-parse.ts` | 识别「趸交+分期」文案 → `djfq`(P1) |
---
## 11. 测试要点
- [ ] 新建 1 样本,首次选 `fq` → 合同 25,880,6 期金额正确
- [ ] 新建 2 样本,首次选 `djfq` → 41,000,5 期正确
- [ ] 改样本数 1→2,合同/明细**不变**
- [ ] 趸交添加 2 条明细,合计 = 合同额,保存成功
- [ ] 趸交 2 条 `dfj` 预付款场景,保存成功
- [ ] 修改各期金额后合计 ≠ 合同额,前后端均拦截
- [ ] 模式切换 + 已缴锁定,仍符合 2026-06-04
- [ ] 2 样本 `djfq` 删至 1 样本,保存提示改模式
- [ ] 标准导入多笔转账 + 趸交,保存成功
---
## 12. 范围外
- 定价表后台可配置化(本期写死常量)
- 3 个及以上样本
- 按样本绑定不同缴费模式(每样本独立主表)
---
## 13. 修订记录
| 日期 | 说明 |
|------|------|
| 2026-07-06 | 初稿:默认定价表、方案 B、djfq、趸交多明细 |