You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
96 lines
8.0 KiB
96 lines
8.0 KiB
5 days ago
|
# 商机模块前端联调工作量评估（最小可行范围）
|
||
|
|
|
||
|
|
> **评估日期**：2026-09-01
|
||
|
|
> **评估目标**：**仅**为"商机模块前端工程师能顺利与后端联调"这一最小可行范围估算工作量
|
||
|
|
> **范围纪律**：忽略 A4 客户模块完整功能建设、非必要功能完善、架构重构；只做"让前端各表单/弹窗/下拉框有真接口可打通"必须的事
|
||
|
|
> **依据**：`商机模块前置客户接口依赖分析报告.md` + 商机侧现状代码交叉核对（`crm-opportunity` / `crm-dict`）
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 0. 一句话结论
|
||
|
|
|
||
|
|
**满足前端联调的最小工作量 ≈ 0.5～1.5 人日**，**远小于**原分析报告隐含的"A4 客户模块提前开发（6 接口 + 2 字典 + 商机侧 5 项配套）"体量。
|
||
|
|
|
||
|
|
原因：分析报告是为"**A4 客户模块提前排期**"写的**依赖清单**（回答"客户模块要开发什么"）；而本次问题是"**前端能不能联调**"（回答"前端打接口会不会 404 / 拿不到数据"）。二者范围差一个数量级——**大部分 P0 联调路径商机侧已有降级实现，接口已经在跑，前端现在就能打通。**
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. 现状核对：哪些接口已经能联调（一手代码证据）
|
||
|
|
|
||
|
|
| 前端触点 | 报告列的"依赖接口" | 商机侧现状 | 前端能否联调 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| 关联客户搜索（字段15 / 弹窗查询区） | `POST /api/customer/search` | **已存在** `POST /api/opportunity/customer/search`（快照池降级，`OpportunityCustomerMapper.searchCandidatePool`） | ✅ **现在就能打**，返回 `customerId + customerName` |
|
||
|
|
| 添加关联客户提交 | 客户写入 | **已存在** `POST /api/opportunity/customer/add`（`OpportunityCustomerAddDTO`：customerId/角色/是否主要） | ✅ 能打通"选客户→提交"闭环 |
|
||
|
|
| 客户列表 / 设主要 | — | **已存在** `/customer/list`、`/customer/set-primary` | ✅ |
|
||
|
|
| 客户角色下拉（字段16 / 弹窗） | crm-dict `customer_role` | **已 seed**（`DictDataInitializer` 6 项：总包/工程商/…/投标公司） | ✅ 走通用 `GET /api/dict/item/enabled-list?groupCode=customer_role` |
|
||
|
|
| 新建商机主表单提交 | `POST /api/opportunity` | **已存在** `OpportunityCreateController` + `CreateOpportunityRequest`（已含 customerId/customerName 快照位） | ✅ 主链路可提交 |
|
||
|
|
| 客户类型下拉（弹窗筛选） | crm-dict `customer_type` | **未 seed** ❌ | ⚠ 下拉开天窗（见 §2 缺口1） |
|
||
|
|
| 客户联系人（字段17 级联 / 弹窗） | `GET /api/customer/{id}/contacts` | **无任何实现** ❌ | ❌ 打了 404（见 §2 缺口2） |
|
||
|
|
| 商机关键联系人全局搜索（字段13/14） | `GET /api/customer/contact/search` | **无实现**，且商机主表未建模 ❌ | ❌（P1，非必填，不阻塞主链路） |
|
||
|
|
| 快速创建客户（弹窗入口） | `POST /api/customer/quick-create` | **无实现** ❌ | ❌（P1，表单无此入口，不阻塞） |
|
||
|
|
| 查看客户详情跳转（Tab） | `GET /api/customer/{id}/detail` | **无实现** ❌ | ❌（P2，展示增强，不阻塞） |
|
||
|
|
|
||
|
|
**结论**：报告 P0 三件里，`customer/search` 和 `customer/{id}`（回显所需字段）实质已被商机侧降级接口覆盖，**唯一真正阻塞主链路联调的硬缺口是"按客户查联系人"（字段17 级联）**，外加一条 `customer_type` 字典 seed。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. 满足前端联调必须补的缺口（最小集）
|
||
|
|
|
||
|
|
### 缺口 1 — `customer_type` 字典 seed 【必做，工作量最小】
|
||
|
|
- **现状**：`customer_role` 已 seed，`customer_type` 完全缺失。
|
||
|
|
- **联调影响**：弹窗"客户类型"筛选下拉、客户信息 Tab"客户类型"列取不到选项 → 下拉开天窗。
|
||
|
|
- **最小做法**：在 `DictDataInitializer` 仿 `customer_role` 加一条 `GroupSeed("customer_type", "客户类型", …)`，6 项（总包/工程商/投资方/设计院/集成商/投标公司）。**纯 seed，无表结构变更。**
|
||
|
|
- **工作量**：**~0.5 h**（含重启验证 `enabled-list` 出数）。
|
||
|
|
|
||
|
|
### 缺口 2 — 客户联系人接口（字段17 级联）【主链路联调硬依赖】
|
||
|
|
- **现状**：`GET /api/customer/{id}/contacts` 无实现；商机侧亦无联系人子表。
|
||
|
|
- **联调影响**：验收标准 8"选关联客户后客户联系人范围同步更新"打不通 → 前端级联联动无接口可对。
|
||
|
|
- **最小做法（联调桩，非 A4 真实现）**：在商机侧加一个**降级 stub 端点**（对齐现有快照池套路），例如 `GET /api/opportunity/customer/{customerId}/contacts`，返回**空列表或固定 mock**，让前端级联逻辑能对上契约、不 404。真实数据待 A4。
|
||
|
|
- 若产品要求联调阶段就有真联系人数据，则需商机侧补 `opportunity_customer_contact` 快照子表 + 查询——**这已超出"最小联调"范围，建议延后**。
|
||
|
|
- **工作量**：**stub 版 ~1～2 h**；真实子表版 ~1 人日（不建议纳入本次）。
|
||
|
|
|
||
|
|
### 缺口 3 — 候选池出参补列（可选，联调体验增强）
|
||
|
|
- **现状**：`OpportunityCustomerCandidateDTO` 只有 `customerId + customerName`；弹窗结果表要 7 列（类型/地区/联系人/电话/负责人）。
|
||
|
|
- **联调影响**：**不阻塞**——前端能拿到 id+名即可完成"选客户→提交"闭环；其余列前端可先留空/占位。
|
||
|
|
- **建议**：**本次不做**（属 A4 真源就位后补齐，签名不变）。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. 明确排除项（不在"满足联调"范围）
|
||
|
|
|
||
|
|
| 排除项 | 报告优先级 | 排除理由 |
|
||
|
|
|---|---|---|
|
||
|
|
| A4 客户模块建库建模（`crm-customer` 模块、customer 主表） | 报告全篇前提 | 联调不需要真模块，降级接口已覆盖主链路 |
|
||
|
|
| `GET /api/customer/contact/search`（字段13/14 全局联系人搜索） | P1 | 非必填字段，主链路"选客户→选联系人→提交"不含此字段也走得通 |
|
||
|
|
| `POST /api/customer/quick-create` | P1 | 表单无此入口，仅弹窗有，不阻塞表单联调 |
|
||
|
|
| `GET /api/customer/{id}/detail` | P2 | 展示增强，可用基础信息接口过渡 |
|
||
|
|
| 商机侧字段13/14 主表建模（v29 增量） | §5.3 | 需产品拍板，属功能完善非联调阻塞 |
|
||
|
|
| 快照池切真源、出参7列补齐 | §5.4 / §缺口3 | A4 就位后的事，签名不变，联调路径不受影响 |
|
||
|
|
| 电话脱敏口径、重复商机校验阈值等待确认项 | §6 | 报告已注明"不阻塞接口排期" |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. 工作量汇总
|
||
|
|
|
||
|
|
| 任务 | 必要性 | 工作量 |
|
||
|
|
|---|---|---|
|
||
|
|
| ① `customer_type` 字典 seed（仿 customer_role） | **必做** | 0.5 h |
|
||
|
|
| ② 客户联系人接口 stub（`/customer/{id}/contacts` 返回空/mock，防 404） | **必做** | 1～2 h |
|
||
|
|
| ③ 联调回归：起服务，走一遍"搜客户→选客户→选角色→（联系人级联）→提交"全链路 + dict enabled-list 出数 | **必做** | 1～2 h |
|
||
|
|
| **小计（最小可行联调）** | | **约 0.5～1 人日** |
|
||
|
|
| ④（可选）候选池出参补 7 列 + 商机侧字段13/14 建模 | 缓 | +1～1.5 人日 |
|
||
|
|
|
||
|
|
> **给排期的一句话**：只为"前端能联调"——**半天到一天**即可（一条字典 seed + 一个联系人 stub 端点 + 一轮联调回归）。报告里那份 A4 完整接口清单是**客户模块自身的开发排期**，不应算进"商机前端联调"的工时里。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. 关键风险 / 待产品确认（影响估算的变量）
|
||
|
|
|
||
|
|
1. **联系人接口要不要真数据？** 若联调阶段前端就要看到真实联系人级联（而非空 stub），工作量从 2 h 升到 ~1 人日（需建 `opportunity_customer_contact` 快照子表）。**建议先 stub，A4 就位补真源。**
|
||
|
|
2. **前端是否已按 `/api/opportunity/customer/*` 契约开发？** 若前端按报告里的理想路径 `/api/customer/*` 编码，则需前端改 baseURL 或后端加路由别名——需双方对齐一次（0.5 h 沟通）。
|
||
|
|
3. **字段13/14 是否本期联调？** 若产品坚持本期联调关键联系人，需先拍板建模再估（超本次范围）。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
_评估基于：分析报告 + `OpportunitySubController` / `OpportunityCustomerAddDTO` / `OpportunityCustomerMapper` / `CreateOpportunityRequest` / `DictDataInitializer` / `DictItemController` 现状代码交叉核对。_
|