crm-backend-matt/.scratch/opportunity-bugfix/retest-verdicts.md

# 22 条缺陷复测裁决（retest-verdicts.md）

> 票 02 产出（20260829）。判定优先级：**原型 v29 > PRD > 问用户**。
> 原型证据均出自 `.scratch/opportunity-bugfix/lanhu-pages/`（v29 文本库，票 01），引用格式 `页名 · 批注小节`；PRD 引用 `.scratch/opportunity-module/商机业务-PRD.md` 节号。
> **裁决汇总：✅ 确认 19 / ⚠ 翻案 3（D-08、D-18、D-19）/ ❓ 0。** 翻案 3 ≤ 5，符合票 02 验收预期。

## P1（13 条）

### D-01 关联客户添加端点 404 — ✅ 确认

- **原型证据**：`A3-1-1-2-4 添加关联客户`（弹窗全景：客户查询区 + 搜索结果表 8 列 + 关联信息设置区 + 确认/取消/+ 快速创建客户）；`A3-1-1-1-2 客户信息 · 验收标准 6`：「点击"添加关联客户"后，可以正常添加新的关联客户」；交互说明 2：「确认后，系统将该客户关联到当前商机，刷新客户信息列表」。
- **修复方向**：`OpportunitySubController` 补 `POST /api/opportunity/customer/add`（flat 风格），按 ADR-0017 请求 DTO；域规则照 `crm-opportunity/CONTEXT.md`（一商机多客户、customerRole/isPrimaryIntended、无删除动作）。

### D-02 客户搜索端点 404 — ✅ 确认

- **原型证据**：`A3-1-1-2-4 · 详细说明 3/5`：「客户查询区：支持按客户名称、联系人、联系电话及客户类型查询客户」「客户搜索结果区：以表格形式展示…并支持单选」；表格列头（选择/客户名称/客户类型/地区/联系人/联系电话/客户负责人）。
- **修复方向**：补 `POST /api/opportunity/customer/search`，按名称/联系人/电话/类型过滤 + 分页，数据范围限当前用户可见客户。

### D-03 设为主要意向端点 404 — ✅ 确认

- **原型证据**：`A3-1-1-1-2 · 交互说明 4`：「点击"设为主要"后，将该客户设置为当前商机的主要意向客户。设置成功后，关系标记需同步更新」；`业务规则 2`：「同一商机原则上只能有一个主要意向客户。当用户将某客户设为主要后，原主要客户需自动变更为普通关联客户」；`变更记录`：「设为主要：二次确认后将唯一的主要意向客户替换至选中行」。
- **修复方向**：补 `POST /api/opportunity/customer/set-primary`，切主三步事务（旧主降普通 + 新主置主 + 快照回写，见 CONTEXT.md）。

### D-04 团队成员添加端点 404 — ✅ 确认

- **原型证据**：`A3-1-1-1-8 团队成员`：「+ 添加成员」按钮 + 成员表 7 列 + 8 行样例；`A3-1-1-2-8 添加团队成员&一键拉群` 整页。
- **修复方向**：补 `POST /api/opportunity/team/add`；行级授权白名单语义照 CONTEXT.md。

### D-05 团队成员移除端点 404 — ✅ 确认

- **原型证据**：`A3-1-1-1-8 · 批注 u474`：「操作列根据成员身份进行权限区分。普通成员提供"编辑"和"移除"入口」；「移除」按钮 ×4（u367-370）。
- **修复方向**：补 `POST /api/opportunity/team/delete`；商机负责人行不可移除（只能移交，原型 u474「商机负责人额外提供移交入口」）。

### D-06 团队成员角色编辑端点 404 — ✅ 确认

- **原型证据**：`A3-1-1-1-8 · 批注 u474`：「普通成员提供"编辑"和"移除"入口」；「编辑」按钮 ×5（u362-366）+「移交」（u417）。
- **修复方向**：补 `POST /api/opportunity/team/update`（项目角色/职责编辑）；移交 `handover` 已存在（E9），其 team 表同步语义（grill 拍板）已实现，勿重复动。

### D-07 暂缓态可编辑 — ✅ 确认

- **依据**：PRD §3.3：「暂缓中(3)：允许 E5/E6/E9；推进节点/转项目受限（需先取消暂缓）；**一切编辑操作全禁，必须先取消暂缓回到推进中才能写（写跟进/子表写同禁，P1-7 拍板）**」。原型 `A3-1-1-2-6 · 验收标准 10`：「暂缓期间，推进节点、推送方案、转项目等受限操作需按规则隐藏、置灰或给出提示」——不与 PRD 冲突（原型未细列编辑，PRD 明文全禁）。
- **修复方向**：edit/写跟进/子表写路径加暂缓态守卫（`opp_status=3` 拒绝，抛 `CODE_STATUS_NOT_ALLOWED` 族错误码，对称 ADR-0021 两级口径）。

### D-08 暂缓态可直接关闭 — ⚠ 翻案（e2e 期望写反）

- **翻案理由**：PRD §3.2 E6 关闭边明文「起始态 **2,3→4**」；§3.3 暂缓中「**允许 E5/E6/E9**」。暂缓态关闭是 PRD 定义的合法迁移边。原型 `A3-1-1-2-6 · 到期处理规则`：「负责人需人工确认恢复推进、继续暂缓或**关闭商机**」——关闭在暂缓语境下原型亦认可。e2e 报告 D-08 所引「§3.3 状态机无 3→4 出边」与现行 PRD 原文不符。
- **动作**：e2e 报告该条状态改「行为正确」；票 05 若含「拦截暂缓态关闭」子项则剔除；回归脚本 F14 相关断言反转（3→4 应成功）。

### D-09 禁领规则（allowFreeClaim=0）未生效 — ✅ 确认

- **原型证据**：`A7-3-2-5-2 公海与提醒规则(新增/编辑页) · 交互说明 7`：「用户勾选"允许适用范围内的销售自由领取商机"后…可从公海主动领取商机。**取消勾选后，不提供自由领取入口**，商机需通过其他授权方式进行分配」；`业务规则 7`：「启用自由领取后，仅适用范围内且具备对应公海权限的销售人员可以领取商机」；`A3-3-1-1-2 领取 · 交互说明 4`：「确认后，系统校验当前商机是否仍处于可领取状态」。
- **修复方向**：claim 路径接入 `PoolRuleMatcher.loadPublished()`（现仅回收 Job 消费）：按商机匹配生效规则版本，`allowFreeClaim=0` 时 claim 拒绝（业务错误码，提示走分配）。

### D-10 阶段模板编辑发布中生新草稿 50001 — ✅ 确认（实现 bug，与原型无关）

- **原型证据**：`A7-3-2-5-2 · 业务规则 1`（三族同构语义）：「同一规则同一时间仅允许存在一个草稿版本和一个发布中版本。新版本发布成功后，原发布中版本自动调整为已停用」——版本化编辑流是原型明确语义。
- **根因**：`OpportunityStageTemplateServiceImpl.resolveDraft` 编辑分支 `dto.toEntity()` 携带源版本 id 直接 `save()` → 主键冲突（同构同因）。
- **修复方向**：`toEntity()` 后 `setId(null)`（三族同改：Stage/SchemeCard/PoolRule 的 resolveDraft），复测「编辑发布中→生成新草稿（版本号递增）」。

### D-11 方案卡模板同构 50001 — ✅ 确认

- 同 D-10，`OpportunitySchemeCardTemplateServiceImpl.resolveDraft` 同改。

### D-12 公海规则同构 50001 — ✅ 确认

- 同 D-10，`OpportunityPoolRuleServiceImpl.resolveDraft` 同改。

### D-13 owner_dept_id 恒空 — ✅ 确认

- **原型证据**：`A7-3-2-5-2 · 适用对象`：「适用对象(仅'对应部门专用'时才选择)」——部门专用规则是原型明确功能，其匹配锚点即商机归属部门；详情页头部展示「所属部门：粤疆战队-广东15部」（`A3-1-1-1-8` u239-240 等各详情页头）；PRD E1：「设 owner + **部门/姓名快照**」、E9：「`owner_dept_id` 换为移交对象部门」。
- **修复方向**：四处写快照——创建=创建人部门；领取/分配=新负责人部门；移交=新负责人部门（E9 已定语义）。落点 `OpportunityCreateServiceImpl`（现注释「ownerDeptId 传 null」）+ `OpportunityTransitionImpl`（现依赖前端传 cmd.ownerDeptId，改为服务端按负责人解析，**不信任前端**）。

## P2（9 条）

### D-14 新建必填校验 500 类返回 — ✅ 确认（双缺失）

- **原型证据**：`A3-1-1-2-1 新增/编辑商机` 表单星号必填 **13 个**：商机名称/商机来源/商机行业/商机类型/项目阶段/招标形式/项目详细地址/项目区域/项目属地/甲方是否明确/关联客户/客户类型/是否主要客户（项目金额无星号=选填）。后端仅 2 必填 + 缺失时返回 500 类「系统内部错误」而非参数错误。
- **修复方向**：create/edit DTO 校验对齐必填集（至少核心 6 项：名称/来源/阶段/招标形式/区域/属地——客户区字段与 D-01 端点联动，随票 04 一并落地）；错误码改参数错误族。

### D-15 PUBLIC_POOL 看板 summary 未过滤 — ✅ 确认

- **依据**：PRD §6.8：「三种展示形态与『哪个视图/检索』正交——同一份列表数据三种渲染，**后端列表接口不变（同一查询、同一 DataScope、同一分页）**」；看板「列头带共 N 条计数」。summary 与 cards 必须同口径；实测 summary=7 vs 视图内公海态 2 违反同口径原则。
- **修复方向**：`board/summary` 加与 cards 相同的视图状态过滤（viewType 参数，票 11 已坐实两端点源码均无 viewType）。

### D-16 detail 六联动字段 null — ✅ 确认（范围收窄至 4 字段，2 字段翻案）

- **确认 4**：`方案卡状态`（概览批注：「方案卡摘要：展示当前最新方案卡的关键信息」）、`方案预算`（详情头部「方案预算：418.90 万元」展示）、`是否关注`（列表页「我的关注」视图为一级入口，`A3-1-1` u75/u543）、`最近跟进时间`（概览交互说明 3：「保存成功后…同步更新最近跟进时间」）。
- **翻案 2**：`节点停留天数`、`下阶段名` —— v29 原型概览页与 PRD 全文均无此二字段展示要求（e2e 报告引「PRD §7.9」实为 view_log 节，引用失准）。
- **修复方向**：detail 聚合补回显 schemeCardStatus/schemeBudget/followed/lastFollowTime 四字段；不做停留天数与下阶段名。

### D-17 方案卡提交后主表未回显 — ✅ 确认

- **原型证据**：同 D-16 方案卡摘要（概览需展示最新方案卡关键信息）；提交流程草稿→提交 cardStatus 1→2 已实测 ✅，缺的是主表回写。
- **修复方向**：方案卡 submit 事务内回写主表 `scheme_budget`/`scheme_card_status`（与 D-16 回显同根因族，一并修）。

### D-18 surveySeq 需调用方传 — ⚠ 翻案（v29 原型推翻上轮拍板 P1-2）

- **翻案理由**：`A3-1-1-2-10 新增现场勘察 · 字段说明 2`：「勘察次数：字段类型：下拉选择框。记录当前商机第几次进行现场勘察。**字段规则：必填；例如第一次、第二次、第三次等**」+ 表单控件 `*勘察次数`（带星号）。原型口径=用户必填下拉选次数，非系统自动生成。上轮拍板 P1-2「次数自动生成」与 v29 相悖，按优先级原型胜。实测「不传 surveySeq 被拒」符合原型。
- **动作**：行为正确，无需修复；上轮拍板 P1-2 记录为「被 v29 推翻」；e2e 断言维持。

### D-19 勘察补充说明未强制必填 — ⚠ 翻案（同上）

- **翻案理由**：`A3-1-1-2-10 · 字段说明 10`：「勘察补充说明…字段规则：**建议必填**，支持较长文本录入」+ 表单控件无星号（对比 `*勘察次数`/`*现场勘察日期`）；验收标准 6 只要求「未填写**必填**字段…不得提交」（必填集=申请方式/勘察次数/现场勘察日期/工程师）。「建议必填」=前端引导，非后端强制。实测「空说明成功」符合原型。上轮拍板 P1-3 被推翻。
- **动作**：行为正确，无需修复；拍板 P1-3 同记「被 v29 推翻」。

### D-20 oplog 流转不留痕 — ✅ 确认

- **原型证据**：`A3-1-1-1-9 操作日志 · 开发说明`：「操作日志用于记录…关键操作、**字段变更、状态流转**、附件上传、方案推送等行为」；`字段说明 4`：「字段名称…例如：**商机状态**、当前工作节点、方案预算、附件名称等」；`u510 批注`：「包含**系统自动触发流转与人工执行操作的归因**…需明确区分系统行为与人工操作」。实测 6 种流转仅 2 条 ROW_CHANGE 且 fieldName=null 直接违反。
- **修复方向**：每条迁移边（E1-E10）统一落 `opportunity_oplog`（fieldName=opp_status、旧值→新值、操作人=操作者或「系统」（E10 回收），对齐 PRD §3.4「审计切面记状态流转」双轨设计）。

### D-21 attachment/add bizType 契约矛盾 — ✅ 确认（代码实锤）

- **代码证据**：`OpportunitySubController.addAttachment` `@RequestParam(value="bizType", required=false)` vs `OpportunityAttachment` 实体 `varchar(32) **not null**` 无默认值 → 不传必 50001。
- **修复方向**：`required=true` + 参数校验注解限定值域 OPP/FOLLOW_UP/SITE_SURVEY/SCHEME_CARD（对齐 ADR-0017 显式契约）。

### D-22 versions 实体直出泄露 — ✅ 确认

- **代码证据**：三族 versions 端点返回 `Result<List<OpportunityStageTemplate|OpportunityPoolRule|OpportunitySchemeCardTemplate>>` 实体直出（含 creatorId/deleted/updaterId），违反 ADR-0017 Entity 禁令。
- **修复方向**：三族 versions 出参换 VO/DTO（剥离审计字段），同构三处一起改。

## 给修复票的范围结论

- **票 03（V-CONFIG + dept）**：D-10/11/12（三族 setId(null)）+ D-13（四处快照）——范围不变。
- **票 04（6 端点）**：D-01~06——范围不变；D-14 必填集的「客户区字段」与 D-01 联动，实现时对齐。
- **票 05（状态拦截 + 规则）**：D-07（暂缓编辑全禁）+ D-09（禁领接 claim）——**剔除 D-08**（翻案）。
- **票 06（P2 批）**：D-14/15/16（收窄 4 字段）/17/20/21/22——**剔除 D-18/19**（翻案）。
- **回归注意**：D-08/18/19 三处 e2e 断言需反转为「行为正确」断言（票 09 时处理）。

## ❓ 升级用户项

无强制拍板项。两项供知悉（不阻塞开工）：
1. D-08/18/19 三条翻案均已按「原型 > 拍板」纪律裁定，若你不同意某条翻案请在票 03-06 开工前提出。
2. D-07 的 PRD 依据是 P1-7 拍板（编辑全禁）而 v29 原型批注只列「推进类受限」——按 PRD 从严执行；若产品意图是「暂缓态允许编辑基础信息」，需在票 05 开工前纠偏。