crm-backend-matt/.scratch/opportunity-bugfix/issues/04-fix-p1-endpoints.md

04: P1 修复 B — 补齐 6 个 404 写端点（D-01~06：关联客户 ×3 + 团队成员 ×3）

Type: task Status: resolved Blocked by: 02

任务

原型有按钮、实体已存在、只缺 Controller/Service 写端点的 6 个接口：

#	缺陷	端点（建议，flat 风格）	原型依据
D-01	关联客户-添加	POST /api/opportunity/customer/add	a3-1-1-1-2-4 添加关联客户弹窗 + 详情「添加关联客户」按钮
D-02	关联客户-搜索	POST /api/opportunity/customer/search（分页搜客户池候选）	同弹窗内搜索框
D-03	关联客户-设主要意向	POST /api/opportunity/customer/set-primary	同弹窗/列表切主交互
D-04	团队成员-添加	POST /api/opportunity/team/add	a3-1-1-1-8「+ 添加成员」
D-05	团队成员-移除	POST /api/opportunity/team/delete	同页「移除」
D-06	团队成员-编辑	POST /api/opportunity/team/update	同页「编辑」

实现要点（不是裸 CRUD，域规则在 CONTEXT.md）

关联客户（crm-opportunity/CONTEXT.md 规则）：

• 一商机多客户；有且仅一个主要意向客户（add 时若该商机已无主要意向且新客户设为主要则直接生效；已有主要时切主走 set-primary）。
• set-primary = 三步事务：旧主要置 0 → 新主要置 1 → 商机主表 primaryCustomerNameSnapshot 回写。
• 无删除动作（原型无删除按钮，别加 delete 端点）。
• search 是「候选客户池」搜索（从 crm 客户域搜，过滤已关联的），返回分页。

团队成员（规则）：

• 行级授权白名单：add 把用户加白名单（projectRole/permission 按 DTO）；delete 走软删（deleteKey 约定——看 OpportunityTeam 实体既有字段怎么设计的，与既有 delete_key 复用键约定一致）。
• 商机负责人必须在团队里：delete 时若目标是当前负责人要拦截（错误码风格对齐既有 64xxx/66xxx 家族）。
• 移交商机（handover）时 team 表同步维护的逻辑已存在，别动。

通用：

• Controller IO 遵 ADR-0017（Param DTO 进、Result 出）；权限注解对齐既有写端点（看 page/claim 等怎么标的）。
• 输入校验失败返回 400 类业务码（不是 500）。
• Bruno 集合 E:\code\crm-api-docs 里这 6 个端点此前不存在，票 10 会补文档；本票只管实现 + 单测。

验收

• 6 端点实测全通：add → list 回显 → update 改角色 → delete 软删 → set-primary 切主（旧主让位 + 快照回写）→ search 分页过滤已关联。
• 负路径：重复添加同一客户拦截；删除负责人拦截；无主要意向时 add 直设主要。
• mvn compile + 新增单测绿；e2e-core.py 相关段回归无回归。

Answer

（20260829 完成）6 端点全部落地，验收 5/5 达成。

实现总览

• 端点（OpportunitySubController 追加，flat 路径、隐式表单绑定，operatorId 取 SecurityUtils）：
  • POST /customer/add（D-01）：必填校验（66001）→ 重复预检（66011）→ isPrimary=1 时降旧主 → insert（deleteKey=0）→ 主表 primaryCustomerId/primaryCustomerNameSnapshot 回写。无 delete 端点（原型无删除按钮）。
  • POST /customer/search（D-02）：候选池按拍板「快照池降级」（20260829）——客户模块 A4 未建，OpportunityCustomerMapper.searchCandidatePool 取 opportunity_customer 存活行按 customer_id 去重（MAX(customer_name_snapshot)，兼容 ONLY_FULL_GROUP_BY），keyword 模糊 + NOT IN 排除当前商机已关联 + 分页；A4 建成切真源，签名不变。
  • POST /customer/set-primary（D-03）：2 参 @RequestParam；目标须已关联（66001）、已是主要幂等返回；三步事务：旧主降 0 → 新主置 1 → 主表快照回写，FIELD_CHANGE 日志。
  • POST /team/add（D-04）：批量 userIds 去重保序；全重整体拒 66012「该成员已存在」、部分重复跳过仅插新；username 快照服务端取 crm_auth_user（未知用户 66001）；permission 不传默认 READ_ONLY（v29 页面无权限编辑入口，后端语义按 grill 拍板保留）。
  • POST /team/update（D-06）：支持直接换人（v29 A3-1-1-1-8；目标已在队 66012，快照服务端刷新，无需先加后删）；负责人行三重锁 66013（换人/改项目角色/permission 禁改，仅 duty 可改——「请走移交 E9」）。
  • POST /team/delete（D-05）：软删 set(DeleteKey, id).set(Deleted, 1)（复用键约定，同成员可重新加入）；负责人行拒 66013。
• 新增错误码：66011 客户重复关联 / 66012 团队成员已存在 / 66013 负责人行锁定（OpportunityConstants，66xxx 家族）。
• 新增 duty 列：OpportunityTeam+duty varchar(200)（v29 团队页列 5「职责」，非必填文本），ddl-auto: update 自动建列。
• 操作日志：ROW_ADD/ROW_DELETE/FIELD_CHANGE + OplogLogType.ROW_CHANGE，opSource=MANUAL，bizRef 截 50 字。
• ADR-0017：4 DTO + 1 Param（extends BaseDTO/BaseParam，toEntity 写在 DTO）；无主键语义出参 OpportunityCustomerCandidateDTO 不继承 BaseDTO；无权限注解（sys_menu 无 opportunity 权限点，动态拦截器口径对齐既有子域端点）。

验收对照

验收项	结果
6 端点实测全通（add→list 回显→update→delete→set-primary→search）	t04-verify.py 27/27 全绿（客户域 10 + 团队域 16 + CLEANUP）
负路径：重复添加拦截	66011（客户）/ 66012（成员：全重拒 + 换人目标已在队）
负路径：负责人行拦截	66013 三重（删/换人/改角色），仅 duty 可改 ✅
负路径：无主要时 add 直设主要	C4：旧主 5002→0、新主 5003→1、主表快照=(5003,客户丙)
mvn compile	EXIT=0
单测	新增 OpportunitySubServiceImplTest 18/18；crm-opportunity 全模块 183/183（顺带清掉票 03 遗留 4 处失败——938aed9 把「无模板」改 fail-fast 未同步测试，测试侧对齐）
e2e-core 相关段回归	F11/F12 11/11 ✅ 缺陷 0——6 端点探测全从「404 无端点」翻绿；报告另存 *-t04-regression.*，原始报告已恢复

工程记录

• BeanUtils 按名复制坑：DTO oppId vs 实体 opportunityId 名字不同，copyProperties 静默不复制 → INSERT 缺 opportunity_id 报 50001。修法：toEntity() 内显式 entity.setOpportunityId(getOppId())（团队域没踩到因手动 set）。BeanUtils 型 toEntity 均需逐一核对字段名。
• Maven 增量构建静默跳过：package 日志 BUILD SUCCESS 但 jar:jar 因「输入未变」跳过重建，fat jar 落后源码（api-docs 无新端点报 40401）。判别法：解剖 fat jar 的 BOOT-INF/lib 内嵌模块 jar 查字节码字符串常量（setOpportunityId 在 = 修复在内）。
• 沙箱拦截杀进程：taskkill/Stop-Process 在沙箱内静默失效（输出通道死、进程存活）；Bash 带 required_permissions: all 出沙箱后 taskkill /F /T 直接成功。
• 脚本沉淀：.scratch/opportunity-bugfix/t04-verify.py（C/T/CLEANUP 三段，Sess 模式复用 t03）、t04-jarcheck2.py（jar 内容判别）。