8.0 KiB

Raw Permalink Blame History

商机模块前端联调工作量评估（最小可行范围）

评估日期：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. 关键风险 / 待产品确认（影响估算的变量）

联系人接口要不要真数据？ 若联调阶段前端就要看到真实联系人级联（而非空 stub），工作量从 2 h 升到 ~1 人日（需建 opportunity_customer_contact 快照子表）。建议先 stub，A4 就位补真源。
前端是否已按 /api/opportunity/customer/* 契约开发？ 若前端按报告里的理想路径 /api/customer/* 编码，则需前端改 baseURL 或后端加路由别名——需双方对齐一次（0.5 h 沟通）。
字段13/14 是否本期联调？ 若产品坚持本期联调关键联系人，需先拍板建模再估（超本次范围）。

评估基于：分析报告 + OpportunitySubController / OpportunityCustomerAddDTO / OpportunityCustomerMapper / CreateOpportunityRequest / DictDataInitializer / DictItemController 现状代码交叉核对。

8.0 KiB Raw Permalink Blame History