245 lines
10 KiB
Markdown
245 lines
10 KiB
Markdown
# 合同管理 — 跨模块调用梳理（步骤 6）
|
||
|
||
> **权威源码**：`shanxia/crm/backend/ruoyi-modules/ruoyi-crm/`
|
||
> **日期**：2026-05-31
|
||
> **目的**：Python 重写 `CrmContractServiceImpl` 时，明确哪些金额字段由合同自身维护、哪些由回款/开票模块回调，避免漏实现或双轨不一致。
|
||
|
||
---
|
||
|
||
## 1. 总览
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph inbound["入站：谁调用合同 Service"]
|
||
Q[QuoteServiceImpl]
|
||
O[OpportunityServiceImpl]
|
||
P[PaymentServiceImpl]
|
||
CC[CrmContractController]
|
||
end
|
||
|
||
subgraph contract["CrmContractServiceImpl"]
|
||
insert[insertByBo / updateByBo]
|
||
recv[updateReceivedAmount]
|
||
inv[updateInvoiceAmount ⚠️ 未被调用]
|
||
end
|
||
|
||
subgraph outbound["出站：合同调用谁"]
|
||
CP[ContractProductService]
|
||
PP[PaymentPlanService.batchGenerate]
|
||
SI[SupplierInfo / Customer / Contact / User]
|
||
QT[Quote / Opportunity Mapper 写回]
|
||
end
|
||
|
||
subgraph invoice["CrmInvoiceServiceImpl"]
|
||
inline[updateContractInvoiceAmount 私有方法]
|
||
end
|
||
|
||
Q -->|insertByBo| insert
|
||
O -->|insertByBo + generateContractNo| insert
|
||
P -->|queryById 校验| contract
|
||
P -->|5 处回调| recv
|
||
CC --> contract
|
||
insert --> CP
|
||
insert --> PP
|
||
insert --> SI
|
||
invoice -->|issue / invalid| inline
|
||
inline -->|直接 UPDATE crm_contract| contract
|
||
```
|
||
|
||
| 合同金额字段 | 写入方式 | 当前门户 shanxia2.0 |
|
||
|-------------|---------|---------------------|
|
||
| `received_amount` / `unreceived_amount` | 回款模块回调 `updateReceivedAmount` | 回款模块**未移植**；列表/详情**只读展示** DB 字段 |
|
||
| `invoice_amount` / `uninvoice_amount` | 开票模块私有 `updateContractInvoiceAmount`（**非** `updateInvoiceAmount`） | 开票模块**未移植**；同上只读 |
|
||
|
||
---
|
||
|
||
## 2. `updateReceivedAmount(contractId)`
|
||
|
||
### 2.1 实现逻辑（Java）
|
||
|
||
位置：`CrmContractServiceImpl.java` L1264–1295。
|
||
|
||
1. 查询 `crm_payment`：`contract_id = ?` 且 `del_flag = 0`
|
||
2. **对所有记录** `amount` 求和 → `receivedAmount`（**不过滤** `status`）
|
||
3. 读合同 `amount`
|
||
4. 更新合同：`received_amount = 求和`，`unreceived_amount = amount - received_amount`
|
||
5. `@Transactional`；合同不存在时 log error 并返回 `false`
|
||
|
||
**与回款统计的差异**：`PaymentServiceImpl.statisticsOverview` 仅把 `status = confirmed` 计入金额；`updateReceivedAmount` **包含 pending / confirmed / invalid / rejected** 等所有未删记录。新增 pending 回款时也会立刻回调，而 `reject()` **不**回调（注释写「待确认未计入」，与 insert 行为矛盾）。Python 重写须**原样复刻**此行为，除非产品单独立项修正。
|
||
|
||
### 2.2 触发点（`CrmPaymentServiceImpl`）
|
||
|
||
| 方法 | 条件 | 说明 |
|
||
|------|------|------|
|
||
| `insertByBo` | `entity.contractId != null` | 插入后立即回调（状态为 `pending`） |
|
||
| `updateByBo` | 更新成功且 `entity.contractId != null` | 仅更新**新** contractId；若改绑合同，**不**刷新旧合同 |
|
||
| `deleteWithValidByIds` | 删除成功后，收集到的每个 `contractId` | 仅允许删 `pending` |
|
||
| `confirm` | 确认成功且有关联合同 | |
|
||
| `invalid` | 作废成功且有关联合同 | |
|
||
| `reject` | — | **不调用** `updateReceivedAmount` |
|
||
|
||
插入前校验：`queryById(contractId)` 读 `unreceivedAmount`（空则取 `amount`），要求 `bo.amount <= unreceivedAmount`。
|
||
|
||
### 2.3 门户现状
|
||
|
||
- `module-status.md`：回款管理（`crm_payment` + 计划表）**未开始**
|
||
- 合同重写阶段：**实现** `updateReceivedAmount` 函数供将来回款模块 import；合同 CRUD **不**主动重算（除非 Java 同等逻辑在 insert 初始化 0）
|
||
- 步骤 26 恢复 `quote.to_contract` 后，新合同 `received_amount = 0` 即可
|
||
|
||
---
|
||
|
||
## 3. 开票金额：两套逻辑并存
|
||
|
||
### 3.1 `updateInvoiceAmount(contractId)` — 接口存在、**无调用方**
|
||
|
||
位置：`CrmContractServiceImpl.java` L1981–2012。
|
||
|
||
1. 查 `crm_invoice`：`contract_id = ?`，`del_flag = 0`
|
||
2. 对 **`amount`（不含税）** 求和
|
||
3. `invoice_amount = 求和`，`uninvoice_amount = contract.amount - 求和`
|
||
|
||
全库 grep：**无任何 Service 调用**此方法（仅接口 + 实现定义）。
|
||
|
||
### 3.2 `CrmInvoiceServiceImpl.updateContractInvoiceAmount` — **实际生效路径**
|
||
|
||
私有方法 L838–873；**直接** `contractMapper.updateById`，不经过 `ICrmContractService`。
|
||
|
||
| 发票方法 | 何时更新合同 | 累加字段 | 方向 |
|
||
|---------|-------------|---------|------|
|
||
| `insertByBo` | 否 | — | 申请中不计入 |
|
||
| `updateByBo` | 否 | — | |
|
||
| `approve` | 否 | — | 审批通过仍不计入 |
|
||
| **`issue`** | 是 | **`totalAmount`（价税合计）** | `isAdd = true` |
|
||
| **`invalid`** | 是（状态为 invoiced/delivered/received） | **`totalAmount`** | `isAdd = false` |
|
||
| `express` / `receive` | 否 | — | |
|
||
|
||
新增/审批前校验：读合同 `uninvoiceAmount`，用本次 **`totalAmount`** 与剩余可开比较（`insertByBo` L131–141）。
|
||
|
||
**与 `updateInvoiceAmount` 的不一致**：
|
||
|
||
| 维度 | `updateInvoiceAmount` | `updateContractInvoiceAmount` |
|
||
|------|----------------------|------------------------------|
|
||
| 汇总字段 | `invoice.amount` | 开票/作废时的 `totalAmount` |
|
||
| 触发时机 | 全表重算（若被调用） | 增量加减 |
|
||
| 是否在用 | 否 | 是 |
|
||
|
||
Python 重写建议：
|
||
|
||
- 合同模块保留 `update_invoice_amount()`（全量重算版，对齐 Java 接口，供运维/迁移脚本）
|
||
- 开票模块移植时实现 **`update_contract_invoice_amount_increment`**，行为对齐 `CrmInvoiceServiceImpl` 私有方法
|
||
- **不要**在开票 `issue/invalid` 时改调全量重算，除非产品确认统一
|
||
|
||
### 3.3 门户现状
|
||
|
||
- `crm_invoice` / `crm_invoice_item`：**未移植**
|
||
- 已有 `crm_invoice_info` 是**客户开票信息**，与合同已开票金额无关
|
||
|
||
---
|
||
|
||
## 4. 合同模块内部对金额字段的处理
|
||
|
||
### 4.1 `insertByBo`
|
||
|
||
- `received_amount` / `invoice_amount` 默认 `0`
|
||
- `unreceived_amount = amount - received_amount`
|
||
- `uninvoice_amount = amount - invoice_amount`
|
||
- 若 BO 带 `paymentPlans` → `paymentPlanService.batchGenerate(contractId, plans)`（回款**计划**，非实收）
|
||
|
||
### 4.2 `updateByBo`（仅 draft）
|
||
|
||
- 修改 `amount` 时：**保留**原 `received_amount` / `invoice_amount`
|
||
- 重算 `unreceived_amount` / `uninvoice_amount` = 新 `amount` − 原已收/已开
|
||
|
||
### 4.3 `renewContract`
|
||
|
||
- 新合同：`received_amount = 0`，`invoice_amount = 0`，`unreceived/uninvoice = amount`
|
||
|
||
### 4.4 统计 API
|
||
|
||
`statisticsOverview` / `statisticsTrend` 等对列表合同字段 **SUM**，不实时查 payment/invoice 子表。
|
||
|
||
---
|
||
|
||
## 5. 其他入站调用（非金额）
|
||
|
||
| 调用方 | 方法 | 用途 |
|
||
|--------|------|------|
|
||
| `CrmQuoteServiceImpl.toContract` | `contractService.insertByBo` | 报价转合同（非 HTTP `createFromQuote`） |
|
||
| `CrmOpportunityServiceImpl` 赢单 | `generateContractNo` + `insertByBo` | 自动建 draft 合同，回写 `opp.contract_id` |
|
||
| `CrmContractController` | 全套 REST | 见 `04-api-spec.md` |
|
||
| `CrmPaymentServiceImpl` | `queryById` | 回款金额校验 |
|
||
|
||
`createFromQuote` / `createFromOpportunity`（Controller 入口）内部也是 `insertByBo` + 更新 quote/opportunity 状态。
|
||
|
||
---
|
||
|
||
## 6. 合同模块出站依赖（重写时一并注册）
|
||
|
||
| 依赖 | 用途 |
|
||
|------|------|
|
||
| `ICrmContractProductService` | 产品明细 CRUD、续签复制 |
|
||
| `CrmContractProductPriceTierMapper` | 框架合同调价区间 |
|
||
| `ICrmContractApprovalService` | `canUserApprove` |
|
||
| `ICrmPaymentPlanService` | 新建合同时 `batchGenerate` |
|
||
| `CrmPaymentMapper` | 仅 `updateReceivedAmount` 读表 |
|
||
| `CrmInvoiceMapper` | 仅 `updateInvoiceAmount` 读表（当前无外部触发） |
|
||
| `CrmQuoteMapper` / `CrmOpportunityMapper` | createFrom* / 商机赢单 |
|
||
| `CrmContractTemplateMapper` | createFromTemplate |
|
||
| `ICrmSupplierInfoService` | 供方简称、编号规则 |
|
||
| `ICrmProductService` | 商机转合同自动建产品 |
|
||
| `UserService` | 负责人姓名 |
|
||
| Customer / Contact Mapper | 冗余名称填充 |
|
||
|
||
---
|
||
|
||
## 7. 前端关联（步骤 7+ 适配时注意）
|
||
|
||
| 位置 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| `contract/index.vue` 列表/详情 | `receivedAmount`、`unreceivedAmount`、`invoiceAmount`、`uninvoiceAmount` | 来自合同 VO，非子表实时查询 |
|
||
| `ExecuteDialog.vue` | 同上 + 回款率 | 打开执行弹窗前读合同详情 |
|
||
| `InvalidDialog.vue` L111 | `res.data.invoicedAmount` | **字段名错误**：Java VO 为 `invoiceAmount`；作废前开票提示可能始终为 0，步骤 27 UI 适配时修正 |
|
||
|
||
---
|
||
|
||
## 8. shanxia2.0 实施策略
|
||
|
||
### 阶段 D（合同后端重写）
|
||
|
||
1. 在 `crud/crm/contract.py` 实现 `update_received_amount(db, contract_id)`，逻辑对齐 §2.1
|
||
2. 同文件实现 `update_invoice_amount(db, contract_id)`（对齐 §3.1，预留接口）
|
||
3. `insert_by_bo` / `update_by_bo` 按 §4 维护四个金额字段
|
||
4. **不**在合同路由内实现回款/开票 CRUD
|
||
|
||
### 回款/开票模块移植后
|
||
|
||
| 模块 | 必须回调 |
|
||
|------|---------|
|
||
| 回款 | `insert` / `update` / `delete` / `confirm` / `invalid` → `update_received_amount`（**不含** `reject`） |
|
||
| 开票 | `issue` / `invalid` → 增量更新（对齐 §3.2），或封装为 shared helper |
|
||
|
||
### 步骤 26
|
||
|
||
恢复 `quote.to_contract` 时调用新 `insert_by_bo`，无需触发回款/开票回调。
|
||
|
||
---
|
||
|
||
## 9. Python 重写检查清单
|
||
|
||
- [ ] `update_received_amount`：payment 求和 **无 status 过滤**，`del_flag=0`
|
||
- [ ] 回款 5 个触发点与 Java 一致；`reject` 不回调
|
||
- [ ] `update_invoice_amount` 全量重算实现但默认不被开票模块调用
|
||
- [ ] 开票模块：`issue/invalid` 用 **totalAmount** 增量更新（将来实现）
|
||
- [ ] `update_by_bo` 改 `amount` 时不覆盖已收/已开累计值
|
||
- [ ] `renew_contract` 新合同金额字段清零
|
||
- [ ] `insert_by_bo` 可选 `payment_plans` → 调用 payment_plan 模块（若未移植则跳过或 stub）
|
||
- [ ] 前端 `InvalidDialog`：`invoicedAmount` → `invoiceAmount`
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-05-31 | 步骤 6：梳理 updateReceivedAmount / 开票双轨 / 入站出站 / 门户策略 |
|