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 开工前纠偏。