101 lines
6.7 KiB
Markdown
101 lines
6.7 KiB
Markdown
# 合同管理模块 — 重写移植断点记录
|
||
|
||
> **日期**：2026-05-31
|
||
> **状态**：阶段 E 已完成（步骤 28 代码验收 + 文档更新；联调手测见 `08-verify.md`）
|
||
> **原则**：业务逻辑先梳理再开发；Java → Python 逐行翻译；HTTP 语义对齐原 CRM（GET/PUT/DELETE），不强制门户 POST 约定
|
||
|
||
---
|
||
|
||
## 已完成
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 删除后端 | `contract.py`、`contract_approval.py`、`contract_product.py`、`contract_change.py`、`contract_template.py`、`crm_contract_routes.py`、`crm_contract_sub_routes.py`、对应 `schemas/crm/contract*.py` |
|
||
| 删除前端 | `views/crm/contract/`、`api/crm/contract/`、`useContractPerm.ts`、`migrate-contract-*.py` |
|
||
| 拷贝前端 | 自 `shanxia/crm/web/src/views/crm/contract/` 与 `api/crm/contract/` 原样覆盖 |
|
||
| 路由保留 | `sqxp.ts` 中 contract 相关路由未动 |
|
||
| ORM 保留 | `backend/app/models/crm_models.py` 中 `CrmContract*` 模型保留（映射已有表） |
|
||
| 报价转合同 | `quote.to_contract` 已恢复，调用 `create_from_quote` |
|
||
| Java 快照 | `docs/crm-migration/reference/java/contract/` 保留作翻译权威源 |
|
||
|
||
## 已知阻塞（下一步机械适配前）
|
||
|
||
1. 拷贝页使用 `@/utils/request`、`useDict`、`v-hasPermi` — 需按 `ref-lessons-learned.md` 适配 shanxia2.0
|
||
2. ~~`CustomerDetailDialog.vue` 仍 import `@/api/crm/contract/types`~~ — 步骤 9 已补全 `types.ts` 并接通跨模块引用
|
||
3. ~~合同 API 路由已全部移除 — 列表/详情请求会 404，属预期~~ — 步骤 16–19 已恢复 `GET /contract/list` 与 `GET /contract/{id}`
|
||
4. ~~`ToContractDialog` 转合同后端暂不可用~~ — 步骤 26 已恢复 `to_contract`
|
||
|
||
---
|
||
|
||
## 28 步实施方案（续做从此勾选）
|
||
|
||
### 阶段 A：业务梳理（不写代码）
|
||
|
||
- [x] **1** 阅读 `CrmContractController.java` + `ICrmContractService.java`，导出完整接口矩阵到 `04-api-spec.md`（含 HTTP 方法） | ✅ 2026-05-31
|
||
- [x] **2** 阅读 `CrmContractServiceImpl.buildQueryWrapper`，写 Tab/联合搜索/审批子查询中文说明 → `02-business-logic.md` | ✅ 2026-05-31
|
||
- [x] **3** 梳理状态机：draft → approving → approved → executing → finished；invalid 分支与删除约束 | ✅ `02-business-logic.md` §10（2026-05-31）
|
||
- [x] **4** 梳理审批流：`crm_contract_approval` 多步、`is_current`、`canApprove` | ✅ `02-business-logic.md` §4、§10.4（2026-05-31）
|
||
- [x] **5** 对比 `docs/sql/sx.sql` 与 `shanxia2.0.sql` 的 `crm_contract*` 字段差异，列 DDL 清单 | ✅ `03-ddl-diff.md` + `incremental_crm_contract_rewrite.sql`（2026-05-31）
|
||
- [x] **6** 标注跨模块调用：`updateReceivedAmount`、`updateInvoiceAmount`、回款/开票 Service 触发点 | ✅ `05-cross-module-calls.md`（2026-05-31）
|
||
|
||
### 阶段 B：前端 OpenSpec 适配（功能对齐，列表页 Fresh Mint）
|
||
|
||
- [x] **7** API + 列表页 Fresh Mint：`@/utils/http` + `/web/crm/contract`（Java GET/PUT/DELETE 语义）；`types.ts`；`useContractPerm`；`index.vue` 按 quote 骨架改造 | ✅ 2026-05-31
|
||
- [x] **8** 拷贝页全局替换：`useDict` → `dictStore`；`proxy.$modal` → `$modal`；移除 RuoYi 专有 import（含 OSS → `crm-attachment`、产品 API 路径、`exportContract`） | ✅ 2026-05-31
|
||
- [x] **9** 补 `types.ts`（主合同 + 变更/模板/审批子类型 + `CreateFromQuoteForm`）；`CustomerDetailDialog` / `ToContractDialog` 跨模块引用 `@/api/crm/contract/types` | ✅ 2026-05-31
|
||
- [x] **10** 权限：`v-hasPermi` → `useContractPerm`（列表/详情/变更/模板/审批子页 + menuCode 对齐 04-api-spec） | ✅ 2026-05-31
|
||
- [x] **11** 依赖组件：`CustomerDetail`、`ImagePreview`、`TinyMceEditor`、`QuoteSelector` 路径核对 | ✅ 2026-05-31
|
||
- [x] **12** `pnpm dev` 编译通过，合同列表页可打开（API 可报错） | ✅ 2026-05-31
|
||
|
||
### 阶段 C：DDL
|
||
|
||
- [x] **13** 输出 `docs/sql/incremental_crm_contract_rewrite.sql` | ✅ 2026-05-31（见 `03-ddl-diff.md`；须在测试库手动执行）
|
||
- [x] **14** 测试库执行 DDL，核对 Model 字段顺序与 SQL 一致 | ✅ 2026-05-31（用户已执行 SQL；已补 `CrmContractProductPriceTier` Model）
|
||
|
||
### 阶段 D：后端逐段翻译（对齐原 CRM HTTP）
|
||
|
||
Java 快照：`docs/crm-migration/reference/java/contract/`
|
||
|
||
- [x] **15** 新建 `schemas/crm/contract.py`（Bo/Vo 字段与 Java 一致） | ✅ 2026-05-31
|
||
- [x] **16** `buildQueryWrapper` + `queryPageList` + `canApprove` → `crud/crm/contract.py` | ✅ 2026-05-31
|
||
- [x] **17** `queryById` + 产品明细 + 供方名称 enrichment | ✅ 2026-05-31
|
||
- [x] **18** `insertByBo` / `updateByBo` / `deleteWithValidByIds` | ✅ 2026-06-01
|
||
- [x] **19** `crm_contract_routes.py`：注册 `GET /crm/contract/list` 等（**不用**门户 POST 包装，或双轨：原路径 + 网关转发） | ✅ 2026-05-31（list + detail）；2026-06-01 全量写/审批/统计路由
|
||
- [x] **20** 审批：`submitApproval` / `batch` / `withdraw` + `contract_approval.py` | ✅ 2026-06-01
|
||
- [x] **21** 状态：`startExecute` / `finishContract` / `invalidContract` | ✅ 2026-06-01
|
||
- [x] **22** 附件：`uploadFile` / `uploadAttachmentsWithCategory` | ✅ 2026-06-01
|
||
- [x] **23** 统计：`statisticsOverview` / `ByStatus` / `ByType` / `Trend` / `queryExpiring` | ✅ 2026-06-01
|
||
- [x] **24** 扩展：`renewContract` / `createFromQuote` / `export`；`signContract` / `batchAssign` / `downloadPdf` / `createFromOpportunity` | ✅ 2026-06-01
|
||
- [x] **25** 子模块路由（按需）：change / template / approval 独立页 → `crm_contract_sub_routes.py`（含 CRUD、export、transfer） | ✅ 2026-06-01
|
||
- [x] **26** 恢复 `quote.to_contract` 调用 `create_from_quote` | ✅ 2026-06-01
|
||
|
||
### 阶段 E：UI Fresh Mint + 验收
|
||
|
||
- [x] **27** `index.vue` + 4 对话框 Fresh Mint（参照 `quote/index.vue`） | ✅ 2026-05-31（4 子对话框 + 修复 `handlePrintContract` 模板损坏）
|
||
- [x] **28** 手测 Tab/筛选/审批/执行/作废/导出；更新 `module-status.md` | ✅ 2026-05-31（`08-verify.md` 代码项 ✅；浏览器手测待联调）
|
||
|
||
---
|
||
|
||
## 新会话续做粘贴模板
|
||
|
||
```markdown
|
||
继续合同管理重写移植。
|
||
断点文档：docs/crm-migration/plans/contract/07-restart-checkpoint.md
|
||
当前步骤：__ / 28
|
||
```
|
||
|
||
---
|
||
|
||
## 业务逻辑速查（步骤 A 展开版见 02-business-logic.md）
|
||
|
||
| 操作 | 前置状态 | 结果状态 |
|
||
|------|----------|----------|
|
||
| 提交审批 | draft | approving + approval pending 记录 |
|
||
| 撤回 | approving | draft + 删 pending 审批 |
|
||
| 开始执行 | approved | executing |
|
||
| 完成 | executing | finished |
|
||
| 作废 | 非 finished | invalid |
|
||
| 删除 | draft | 软删 |
|
||
|
||
**无合同专用定时任务**；回款/开票金额回写由其它 Service 调用 `updateReceivedAmount` / `updateInvoiceAmount`。
|