2.8 KiB

Raw Blame History

商机新建接口补齐字段（opp-create-fields）

背景

对比原型 A3-1-1-2-1「新增/编辑商机」表单与商机侧直接新建接口 POST /api/opportunity （CreateOpportunityRequest / OpportunityIntakeSpec / OpportunityIntakeImpl），确认接口与接口文档漏了 7 类字段。经 grilling 逐条拍板如下。

决策（grilling 已确认，2026-09）

#	原型字段	结论
1	项目区域（省/市/区三级级联）	前端三级级联，区/县折叠进 `cityCode`，不新增 `districtCode`（对称 lead 约定「市码或区/县码均可，不单建 district_code」）。仅放宽 `cityCode` 的 Schema/注释说明。
2	项目金额	补进 create 入参。`Opportunity.projectAmount` 已存在，DTO/文档漏带。
3	项目详细地址	补进 create 入参 + 实体加 `address`（照 `Lead.address` 形状 varchar(255)）。
4	客户类型	映射到 `customer_role`（商机关联客户角色字典）。不碰 A4 的 `customer_type`。
5	是否主要客户	create 收 `isPrimaryIntended`（1=主要意向客户 / 0=普通关联客户）。创建时允许零主要意向客户（否→普通关联，后补/切换走添加关联客户端点）。CONTEXT「关联客户」不变式相应放宽。
6	商机关键联系人 + 关键人所在公司	create 预留快照字段：`keyContactId`（可空，引用 A4 联系人）+ `keyContactNameSnapshot` + `keyContactCompanySnapshot`。客户联系人归 A4 延后，stub 兜底。
7	项目概况	= 后端 `remark`（同字段改名，不新增列）。DTO/文档展示名「备注」→「项目概况」，补「线索转商机时映射」注释。

不算缺口

项目阶段：create 由系统落首节点（applyInitialStage），非入参。
来源线索：血缘 sourceLeadId 已存在。
甲方（partyAClear / partyA）：已存在。

影响面

代码：crm-opportunity
- CreateOpportunityRequest（DTO）
- Opportunity（实体，加 4 列）
- OpportunityIntakeSpec（内部契约）
- OpportunityIntakeImpl（建档透传 + linkPrimaryCustomer 尊重 isPrimaryIntended/customerRole）
- OpportunityCreateServiceImpl（adapter 翻译）
领域文档：crm-opportunity/CONTEXT.md（关联客户不变式放宽 + 词汇）
接口文档仓：D:\code\crm-api-docs\A3 商机管理\新建商机\新建商机.bru

边界（本期不做）

线索转入入口（OpportunityCreationPortImpl）透传新字段：暂不接线，LEAD_CONVERT 传 null/默认。新字段均为 DIRECT 新建入口场景字段，线索转入的映射留待线索侧需求明确后另开票。
客户联系人搜索：归 A4 客户/联系人模块，A4 建成后走真源。