# 报价单管理模块迁移方案 — 05 业务逻辑与特殊场景

> **原则**：本节为开发门禁。未在本节逐条对照 Java 快照实现前，**不得**修改 `backend/app/crud/crm/quote*.py` 或新增报价相关路由。  
> **Java 快照**：`docs/crm-migration/reference/java/quote/service/impl/`

---

## 1. 定时任务 / 触发器

| 类型 | 报价单模块 | 说明 |
|------|------------|------|
| MySQL 触发器 | 无 | |
| 定时 Job | 无 | 过期状态可在访问分享链时懒更新，与 Java `viewByShareCode` 一致 |
| Spring 事件 | 无 | |

---

## 2. 状态机

```
draft（草稿）
  → submitted（已提交）           # submitQuote
  → invalid（已作废）             # invalidQuote（draft 也可作废）

submitted
  → draft                         # withdrawApproval（删 pending 审批）
  → accepted（审批通过）          # 全部 approver approved
  → rejected（审批失败）          # 任一 approver rejected
  → expired（已过期）             # expire_date 过期 / 分享访问时懒更新
  → invalid                       # invalidQuote

accepted
  → contract（已转合同）        # toContract
  → invalid

contract / invalid → 终态（除 invalid 重复作废报错）
```

| 规则 | Java 行为（须对齐） |
|------|---------------------|
| 编辑 | 仅 `draft`（`updateByBo`） |
| 删除 | 仅 `draft`；已 `contract_id` 不可删 |
| 提交 | 仅 `draft`；提交后创建审批 + 尝试生成 PDF（失败不阻断） |
| 转合同 | 仅 `accepted`；无产品明细拒绝；不可重复转 |
| 作废 | 非 `invalid` 均可；remark 追加 `\n【作废原因】{remark}` |
| 分享访问 | 可能设 `viewed`（字典无此项，保留 Java 行为） |

**状态 dict_value 禁止修改**：`draft` / `submitted` / `accepted` / `rejected` / `expired` / `contract` / `invalid`

---

## 3. 报价单编号 `generateQuoteNo`

格式：`{供方编码}DD-{yyyyMMdd}{3位序号}`，例 `SXDD-20251017001`

| 规则 | Java |
|------|------|
| 默认供方编码 | `SX`（仅 `supplier_id` 为空时；P0 供方模块上线后须从 `crm_supplier_info.supplier_code` 读取） |
| 序号范围 | 同前缀 + 同 `quote_date` 下递增 |
| 冲突 | 最多重试 10 次 |
| 新增 | 空号或含 `***` 预览标记时生成 |
| 改报价日期 | **整号重生成**，标题同步更新 |
| 改供方 | 只替换编码前缀，**保留** `DD-yyyyMMdd001` 段 |
| 改客户/供方 | 按 `quoteType` 重算 `quoteTitle` |

---

## 4. 报价主题自动生成

| quoteType | 格式 |
|-----------|------|
| `sales`（默认） | `{供方简称}-{客户简称}（{quoteNo}）` |
| `purchase` | `{客户简称}-{供方简称}（{quoteNo}）` |

供方简称默认 `山峡`；客户/供方简称来自主数据 `shortName`。

---

## 5. 金额计算 `calculateAmount`

```
行小计 = price × quantity × (1 - line_discount/100)
total_amount = Σ 行小计
discount_amount = total_amount × discount_rate/100
final_amount = total_amount - discount_amount
```

无产品时：三项金额均为 0。

---

## 6. 新增 `insertByBo` 默认值

| 字段 | 默认 |
|------|------|
| `version` | `V1.0` |
| `parent_id` | `0` |
| `is_latest` | `1` |
| `status` | `draft` |
| `quote_type` | `sales` |
| `validity_days` | `30` |
| `quote_date` | 今天 |
| `expire_date` | `quote_date + validity_days` |
| `owner_user_id` | 当前用户 |

保存前：`resolveQuoteProductIds` → `calculateAmount` → insert 主表 → `batchInsert` 明细。

---

## 7. 修改 `updateByBo`

- 校验旧单 `status == draft`
- 产品明细：**先 `deleteByQuoteId` 再 `batchInsert`**
- 客户/供方/报价日期变更时的编号与标题规则见 §3、§4

---

## 8. 提交 `submitQuote`

1. `status`: `draft` → `submitted`
2. `createApprovalRecords(id, approverIds)` — step 从 1 递增
3. 调用 PDF 生成；成功则 `pdf_url`、`pdf_generated=1`（异常仅 log）

---

## 9. 审批 `approveQuote`

| approvalResult | 主单 status |
|----------------|-------------|
| `approved` | 若该 quote 无剩余 `pending` → `accepted` |
| `rejected` | 立即 `rejected`，`reject_reason = "审批拒绝: " + opinion` |

审批记录：`pending` → `approved`/`rejected`，写 `approval_time`。

---

## 10. 撤回 `withdrawApproval`（审批 Service）

- 主单须 `submitted`
- 物理删除（或软删，与 Java delete 一致）所有 `pending` 审批
- 主单 `status` → `draft`

---

## 11. 新版本 `createNewVersion`

- 复制主表字段 + 产品明细
- 新单：`status=draft`，`is_latest=1`，`parent_id=旧 id`，新 `version` 字符串
- 旧单：`is_latest=0`
- **同 `quote_no`**

---

## 12. 转合同 `toContract`

1. 校验 `accepted`、无 `contract_id`、有产品
2. 构建 `CrmContractBo`（`contract_type=sale`，金额=`final_amount`，备注含 quoteNo）
3. 复制产品 → `CrmContractProductBo`（`delivery_status=pending`）
4. 调用合同 `insertByBo`
5. 报价单：`status=contract`，`contract_id=新合同 id`

**依赖**：P1 合同 `insertByBo` 已实现（见 `plans/contract/01-prerequisite-create-for-quote.md`）。

---

## 13. 分享 `generateShare` / `viewByShareCode`

| 项 | Java |
|----|------|
| share_code | 8 位随机 |
| share_link | 配置域名 + shareCode（Java 硬编码 localhost，门户改配置） |
| 密码 | 可选明文存 `share_password` |
| 过期 | `share_expire_time = now + validityDays` |
| 公开访问 | 无 JWT；校验 share_code、密码、分享过期、报价 expire_date |
| 访问副作用 | view_count+1、last_view_time、写 share_log、可能改 status |

---

## 14. PDF / 模板

| API | 行为 |
|-----|------|
| `saveTemplate` | 仅更新 `template_content`（LambdaUpdate 避免乐观锁） |
| `getTemplate` | 返回 longtext HTML |
| `generatePdf` | HTML 渲染 → 存文件（Java 实为 HTML，扩展名 .pdf）→ MinIO URL |

模板文件见快照：`resources/templates/quote-pdf.html`

---

## 15. 产品 ID 解析（外部）

`CrmProductServiceImpl.resolveProductIdForQuoteItem`：按名称/规格/分类/单位/税率匹配；未命中则**自动新建产品**。

门户须在 `product.py` 实现同名语义，或在 `quote.py` 内对照 Java 内联。

---

## 16. 开发对照打勾表

实施每个 Python 函数前，在 Java 快照中定位方法并在此打勾：

- [ ] `buildQueryWrapper`
- [ ] `insertByBo` / `updateByBo` / `deleteWithValidByIds`
- [ ] `queryById`（含 productList、冗余填充）
- [ ] `submitQuote`
- [ ] `approveQuote` / `withdrawApproval` / `canUserApprove`
- [ ] `createNewVersion` / `queryVersions`
- [ ] `toContract`
- [ ] `generateShare` / `viewByShareCode`
- [ ] `invalidQuote` / `acceptQuote` / `rejectQuote`
- [ ] `statisticsOverview` / `statisticsStatus` / `statisticsTrend`
- [ ] `saveTemplate` / `getTemplate` / `generatePdf`
- [ ] `resolveProductIdForQuoteItem`（产品模块）