# 合同结算方式新增选项 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:** 为合同结算方式增加按量结算/月结/季结/其他四项，并让第五条条款按「条款驱动两项 vs 新四项约定句」规则解析，前后端一致。

**Architecture:** 字典扩 4 条；抽出前后端 `defaultClause(settlementMethod)`；保留 `{{SETTLEMENT_METHOD_CONTENT}}` + `settlement_clause_drafts[method]`；新四项默认文案为「请根据双方约定填写结算方式：{label}。供方开具13%增值税专用发票，无异议后，以现汇方式月结。」

**Tech Stack:** MySQL 字典、Python 3.9 / pytest、Vue 3 / TypeScript

**Spec:** `docs/superpowers/specs/2026-08-16-contract-settlement-method-options-design.md`

---

## File map

| 文件 | 职责 |
|------|------|
| `backend/scripts/migrate_20260816_crm_settlement_method_options.sql` | 幂等插入 4 条字典 |
| `backend/app/services/crm_settlement_clause.py` | 后端 defaultClause 纯函数 |
| `backend/app/crud/crm/contract.py` | `save_template` 调用纯函数 |
| `backend/tests/test_crm_settlement_clause.py` | 默认文案单测 |
| `web-admin/src/views/crm/contract/settlementClause.ts` | 前端解析/默认文案 |
| `web-admin/src/views/crm/contract/components/ContractDetailDialog.vue` | 改用共享函数 |
| `web-admin/src/views/crm/contract/detail.vue` | 改用共享函数（若仍保留同逻辑） |

---

### Task 1: 字典 SQL 迁移

**Files:**
- Create: `backend/scripts/migrate_20260816_crm_settlement_method_options.sql`

- [x] **Step 1: 写入幂等 INSERT**

```sql
-- backend/scripts/migrate_20260816_crm_settlement_method_options.sql
-- 合同结算方式：按量结算 / 月结 / 季结 / 其他
-- 可重复执行（幂等）

INSERT INTO `sys_dict_data` (
  `id`, `dict_label`, `dict_value`, `tag_type`, `dict_type`, `tenant_no`,
  `order_num`, `remark`, `create_by`, `create_dept_id`, `create_time`,
  `update_by`, `update_time`, `del_flag`
) VALUES
(
  'SXDC20260816SETTLE00000000000001', '按量结算', 'volume_settlement', '',
  'crm_settlement_method', 'shanxia2.0', 2, '', '1', '', NOW(), NULL, NOW(), 0
),
(
  'SXDC20260816SETTLE00000000000002', '月结', 'monthly_settlement', '',
  'crm_settlement_method', 'shanxia2.0', 3, '', '1', '', NOW(), NULL, NOW(), 0
),
(
  'SXDC20260816SETTLE00000000000003', '季结', 'quarterly_settlement', '',
  'crm_settlement_method', 'shanxia2.0', 4, '', '1', '', NOW(), NULL, NOW(), 0
),
(
  'SXDC20260816SETTLE00000000000004', '其他', 'other_settlement', '',
  'crm_settlement_method', 'shanxia2.0', 5, '', '1', '', NOW(), NULL, NOW(), 0
)
ON DUPLICATE KEY UPDATE
  `dict_label` = VALUES(`dict_label`),
  `dict_value` = VALUES(`dict_value`),
  `dict_type` = VALUES(`dict_type`),
  `tenant_no` = VALUES(`tenant_no`),
  `order_num` = VALUES(`order_num`),
  `del_flag` = 0,
  `update_time` = NOW();
```

- [x] **Step 2: 在目标库执行该 SQL，刷新管理端字典缓存后确认下拉出现 6 项**

---

### Task 2: 后端 defaultClause 纯函数 + 单测（TDD）

**Files:**
- Create: `backend/app/services/crm_settlement_clause.py`
- Create: `backend/tests/test_crm_settlement_clause.py`

- [x] **Step 1: 先写失败单测**

```python
# backend/tests/test_crm_settlement_clause.py
from app.services.crm_settlement_clause import default_settlement_clause


def test_advance_payment_clause():
    assert "款到发货" in default_settlement_clause("advance_payment")


def test_arrive_payment_clause():
    assert "货到付款" in default_settlement_clause("arrive_payment")


def test_monthly_settlement_clause_uses_label():
    text = default_settlement_clause("monthly_settlement")
    assert text.startswith("请根据双方约定填写结算方式：月结。")
    assert "13%增值税专用发票" in text


def test_volume_quarterly_other_labels():
    assert "按量结算" in default_settlement_clause("volume_settlement")
    assert "季结" in default_settlement_clause("quarterly_settlement")
    assert "其他" in default_settlement_clause("other_settlement")


def test_unknown_falls_back_to_arrive():
    assert default_settlement_clause("weird") == default_settlement_clause("arrive_payment")


def test_empty_falls_back_to_arrive():
    assert default_settlement_clause("") == default_settlement_clause("arrive_payment")
    assert default_settlement_clause(None) == default_settlement_clause("arrive_payment")
```

- [x] **Step 2: 运行确认失败**

```bash
cd backend && source venv/bin/activate && pytest tests/test_crm_settlement_clause.py -v
```

Expected: FAIL（模块不存在）

- [x] **Step 3: 实现纯函数**

```python
# backend/app/services/crm_settlement_clause.py
from __future__ import annotations

from typing import Optional

ADVANCE_PAYMENT = "advance_payment"
ARRIVE_PAYMENT = "arrive_payment"

CLAUSE_LABELS = {
    "volume_settlement": "按量结算",
    "monthly_settlement": "月结",
    "quarterly_settlement": "季结",
    "other_settlement": "其他",
}

ADVANCE_CLAUSE = (
    "款到发货。需方付款后安排发货，需方收到货物后，供方开具13%增值税专用发票。"
)
ARRIVE_CLAUSE = (
    "货到付款，需方收到供方货物后，供方开具13%增值税专用发票，无异议后，以现汇方式月结。"
)


def default_settlement_clause(settlement_method: Optional[str]) -> str:
    method = (settlement_method or "").strip() or ARRIVE_PAYMENT
    if method == ADVANCE_PAYMENT:
        return ADVANCE_CLAUSE
    if method in CLAUSE_LABELS:
        label = CLAUSE_LABELS[method]
        return (
            f"请根据双方约定填写结算方式：{label}。"
            "供方开具13%增值税专用发票，无异议后，以现汇方式月结。"
        )
    # arrive_payment 与未知值
    return ARRIVE_CLAUSE
```

- [x] **Step 4: 再跑单测，期望全部 PASS**

```bash
cd backend && source venv/bin/activate && pytest tests/test_crm_settlement_clause.py -v
```

---

### Task 3: 后端 `save_template` 改用纯函数

**Files:**
- Modify: `backend/app/crud/crm/contract.py`（`save_template` 内空草稿兜底，约 1661–1669 行）

- [x] **Step 1: 增加 import**

```python
from app.services.crm_settlement_clause import default_settlement_clause
```

- [x] **Step 2: 替换空草稿兜底**

将：

```python
method = (entity.settlement_method or "").strip() or "arrive_payment"
default_clause = (
    "款到发货。需方付款后安排发货，需方收到货物后，供方开具13%增值税专用发票。"
    if method == "advance_payment"
    else "货到付款，需方收到供方货物后，供方开具13%增值税专用发票，无异议后，以现汇方式月结。"
)
drafts = json.dumps({method: default_clause}, ensure_ascii=False)
```

改为：

```python
method = (entity.settlement_method or "").strip() or "arrive_payment"
drafts = json.dumps(
    {method: default_settlement_clause(method)},
    ensure_ascii=False,
)
```

---

### Task 4: 前端 `settlementClause.ts`

**Files:**
- Create: `web-admin/src/views/crm/contract/settlementClause.ts`

- [x] **Step 1: 新增共享模块**

```typescript
/** 与后端 app.services.crm_settlement_clause 保持一致 */

export const SETTLEMENT_ADVANCE = 'advance_payment'
export const SETTLEMENT_ARRIVE = 'arrive_payment'

export const SETTLEMENT_CLAUSE_LABELS: Record<string, string> = {
  volume_settlement: '按量结算',
  monthly_settlement: '月结',
  quarterly_settlement: '季结',
  other_settlement: '其他'
}

const ADVANCE_CLAUSE =
  '款到发货。需方付款后安排发货，需方收到货物后，供方开具13%增值税专用发票。'
const ARRIVE_CLAUSE =
  '货到付款，需方收到供方货物后，供方开具13%增值税专用发票，无异议后，以现汇方式月结。'

export function defaultSettlementClause(
  settlementMethod?: string | null,
  labelResolver?: (method: string) => string | undefined
): string {
  const method = (settlementMethod || '').trim() || SETTLEMENT_ARRIVE
  if (method === SETTLEMENT_ADVANCE) return ADVANCE_CLAUSE
  if (method in SETTLEMENT_CLAUSE_LABELS) {
    const label =
      (labelResolver && labelResolver(method)) || SETTLEMENT_CLAUSE_LABELS[method]
    return `请根据双方约定填写结算方式：${label}。供方开具13%增值税专用发票，无异议后，以现汇方式月结。`
  }
  return ARRIVE_CLAUSE
}

export function parseSettlementClauseDrafts(raw?: string | null): Record<string, string> {
  if (!raw) return {}
  try {
    const parsed = JSON.parse(raw)
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
    const drafts: Record<string, string> = {}
    Object.entries(parsed).forEach(([key, value]) => {
      if (typeof value === 'string' && value.trim()) {
        drafts[key] = value.trim()
      }
    })
    return drafts
  } catch {
    return {}
  }
}

export function resolveSettlementClauseContent(options: {
  settlementMethod?: string | null
  settlementClauseDrafts?: string | null
  labelResolver?: (method: string) => string | undefined
}): string {
  const method = (options.settlementMethod || '').trim() || SETTLEMENT_ARRIVE
  const drafts = parseSettlementClauseDrafts(options.settlementClauseDrafts)
  return drafts[method] || defaultSettlementClause(method, options.labelResolver)
}
```

---

### Task 5: `ContractDetailDialog.vue` 改用共享函数

**Files:**
- Modify: `web-admin/src/views/crm/contract/components/ContractDetailDialog.vue`

- [x] **Step 1: import**

```typescript
import {
  parseSettlementClauseDrafts,
  resolveSettlementClauseContent
} from '../settlementClause'
```

- [x] **Step 2: 删除组件内重复的 `getDefaultSettlementClauseContent` / 内层 `parseSettlementClauseDrafts`（`replacePlaceholders` 内与文件级各一处），改为调用共享函数**

在 `replacePlaceholders` 内，第五条取值改为：

```typescript
const getSettlementClauseContent = (): string =>
  resolveSettlementClauseContent({
    settlementMethod: contractData.settlementMethod,
    settlementClauseDrafts: contractData.settlementClauseDrafts,
    labelResolver: (method) => dictStore.getLabel('crm_settlement_method', method) || undefined
  })
```

文件级若仍有 `parseSettlementClauseDrafts` 供保存草稿使用，改为直接使用 import 的同名函数，删除本地实现。

- [ ] **Step 3: 手工验证**（需在浏览器确认）

1. 选月结 → 打开打印 → 第五条含「结算方式：月结。」
2. 选手改第五条并保存 → 再打开仍为改后文案
3. 选款到发货 → 仍为款到发货默认句
4. 生成 PDF 与弹窗一致

---

### Task 6: `detail.vue` 对齐（若仍含同逻辑）

**Files:**
- Modify: `web-admin/src/views/crm/contract/detail.vue`

- [x] **Step 1: 同样 import `resolveSettlementClauseContent` / `parseSettlementClauseDrafts`，删除本地重复实现，第五条解析走共享函数**（与 Task 5 相同规则）

若该页已废弃不再进入打印路径，仍建议对齐，避免双份逻辑分叉。

---

### Task 7: 验收与图谱

- [x] **Step 1: 再跑**

```bash
cd backend && source venv/bin/activate && pytest tests/test_crm_settlement_clause.py -v
```

Expected: PASS

- [ ] **Step 2: 对照 spec「验收要点」手工走一遍 6 项结算方式**（需在浏览器确认）

- [x] **Step 3: 更新图谱**

```bash
./scripts/update-graph.sh backend
./scripts/update-graph.sh frontend
```

（或按仓库惯例 `graphify update .`）

---

## Spec coverage

| Spec 要求 | Task |
|-----------|------|
| 字典 4 项 | Task 1 |
| defaultClause 六种 + 未知回退 | Task 2–3 |
| 前端打印/PDF 解析 | Task 4–5 |
| detail 双份逻辑对齐 | Task 6 |
| 草稿按 method 保存不覆盖 | 现有 save 路径 + Task 5 手工验 |
| 验收与图谱 | Task 7 |