crm-backend-matt/.scratch/opportunity-acceptance/acceptance-checklist.md

# 商机模块整改 — 人工验收清单与移交说明（opportunity-acceptance · 票 04）

- **生成时间**：2026-08-31（Agent 自测 31/31 全绿后移交）
- **被测对象**：`.scratch/opportunity-e2e/demo/index.html` × verify 后端（fat jar + 远程 DB）
- **佐证**：[selftest-report.md](selftest-report.md)（31 断言 + 29 截图）· [e2e-report.md](../opportunity-e2e/e2e-report.md)（177 用例）· [defect-fix-audit.md](defect-fix-audit.md)（23/23 锚点）

---

## 零、移交说明（先读这节，30 秒）

**怎么验**：按本清单「二、演示脚本」从上到下点一遍 demo（约 15 分钟），每步对照「预期」即可；不必看代码、不必调 API。

**验什么**：三个结论——① 后端修复可信（重点 D-01：新建落首阶段 + 阶段进度 5 节点）；② 测试全绿（Agent 已替你跑完 31 断言 UI 自测 + 177 用例 E2E，本清单是抽查性人工复核）；③ Demo 可演示（全功能面可操作、无静默失败）。

**哪绿哪黄**：
- 🟢 **绿**：清单里所有「预期」项——Agent 自测已全部截图实证（每步附 accept-NN 截图链接），人工复核应看到同样结果；
- 🟡 **黄**：「四、现存问题总清单」列出的各项——**已知且已有归属，不要当新 bug 报**（过时标注、UI 写入口缺口、数据形态、外部依赖、挂起 P2）；
- ⚠ **外部依赖**：附件上传依赖 MinIO（F08），演示环境须带 MinIO 凭据起服，否则附件功能不可用（后端本身无问题，E2E 已单独验证）。

**发现不符怎么办**：截图 + 一句话现象，回 `.scratch/opportunity-bugfix/` 补票（或新开 effort），不要在本 effort 内修。

---

## 一、环境准备（5 分钟）

1. **起服**（仓库根目录，PowerShell）：
   ```powershell
   $env:SPRING_PROFILES_ACTIVE='verify'; $env:CRM_MINIO_AK='admin'; $env:CRM_MINIO_SK='Itc@123456'
   java -jar crm-app\target\crm-app-1.0.0-SNAPSHOT.jar
   ```
   （连远程 DB 8.129.84.155/crm；起服手册：`.scratch/opportunity-e2e/boot-verify.md`）
2. **打开 Demo**：浏览器直接打开 `file:///D:/code/crm-backend-matt/.scratch/opportunity-e2e/demo/index.html`。
   预期：自动登录，左上角显示「已登录：罗伟健」（管理员）。🟢 [accept-01 佐证见列表截图](shots/accept-01-列表-我负责的.png)
3. **（可选）基线重置**：`python .scratch/opportunity-e2e/seed-opportunity.py`（先清后造幂等，ID 会变）。自测留下的 `accept-` 前缀数据不影响演示；介意可重置。

---

## 二、演示脚本（按顺序点，每步预期）

> 条数为自测时点值，**随演示操作浮动，数字本身不是断言**。

### 第一幕：列表多视图（🟢 [accept-01~04](shots/accept-01-列表-我负责的.png)）

| 操作 | 预期 |
|---|---|
| 默认「我负责的」视图 | 有数据（自测时 4 条：seed 1 + 自测新建 3） |
| 切「管理全量」 | 条数明显变多（自测时 17 条），分页正常 |
| 切「公海」 | 待领取商机（自测时 3 条），**且停留在第 1 页**（demo-B1 修复验证点：切视图不得出现空页/错误页码） |
| 关键词输入「智慧园区」→ 查询 | 仅命中行（自测时 2 行），查询后回到第 1 页 |

### 第二幕：看板（🟢 [accept-05](shots/accept-05-看板汇总.png)）

| 操作 | 预期 |
|---|---|
| 切「看板」视图 | 按阶段分列的卡片汇总正常渲染（无 loading 卡死） |

### 第三幕：详情九子表（🟢 [accept-06~20](shots/accept-06-详情总览-阶段进度5节点.png)）

点开任一商机（如「e2e-A-推进-智慧园区二期」）进详情。**顶部先看阶段进度条：5 个节点，当前阶段高亮 CURRENT**。

| Tab | 预期 |
|---|---|
| 跟进 | 列表 + toolbar（20260829 修复点①）；**写一条跟进 → 列表刷新且置顶为最近有效跟进**（修复点③，时间戳变化） |
| 现场勘察 | 列表 + toolbar 正常 |
| 关联客户 | 3 条只读展示（🟡 写入口缺失 = 已知缺陷族，见第四节） |
| 团队成员 | 3 条只读展示（同上） |
| 方案卡 | 3 卡列表；点开任一卡详情 → **键值对 8 项完整**（20260829 修复点②） |
| 附件 | 空态文案正常；⚠ 上传功能依赖 MinIO 起服凭据 |
| 操作日志 | **分形态渲染**（文本/JSON/差异等不同形态均可读，20260829 修复点④） |
| 阶段历史 | 有记录；🟡 from/to 显示原始 stageId（seed 快照为空，非渲染缺陷） |
| 工作计划（票 03 新接入） | 三形态 badge：**逾期/临期/进行中** 实时判定；登记完成 → finishTime 服务端回填；编辑可部分更新；删除 → 列表消失（软删） |

### 第四幕：新建商机双路径（🟢 [accept-21/22](shots/accept-21-新建-六必填拦截.png)）—— **D-01 核心验证点**

| 操作 | 预期 |
|---|---|
| 点「+ 新建商机」→ 直接提交（空表单） | **errbox 逐字段提示六个必填缺失**（与后端 66001 同款文案，不弹裸 alert） |
| 补全六必填（名称/来源/招标形式/项目区域省·市/项目属地；省→市为联动下拉）→ 提交 | toast 显示新商机 id → **自动直达新详情页：阶段进度 5 节点、落首阶段 CURRENT**（D-01 修复终验：新建不再 500） |
| 表单其余字段 | 可选填：行业/商机类型缺（后端 oppType 已支持，demo 未做）、甲方是否明确/甲方名称/备注有；**「客户信息」区块只有甲方两个字段，关联客户搜索框未做（后端链路已就绪，见 P-10）**——与原型 A3-1-1-2-1 的差异是已知偏离，不要当 bug 报 |

### 第五幕：状态机（🟢 [accept-23~25](shots/accept-23-暂缓对话框.png)）

在刚新建的商机详情页：

| 操作 | 预期 |
|---|---|
| 「暂缓」→ 对话框选原因（**下拉为字典项**，非裸文本框）→ 确认 | **badge 变「暂缓中」**；点击有反应（框关闭 + 成功提示，demo-B2 修复验证点：无返回值端点不得静默失败） |
| 「取消暂缓」 | **badge 变回「推进中」** |

### 第六幕：规则三族（🟢 [accept-26~29](shots/accept-26-规则-公海与提醒.png)）

| 页面 | 预期 |
|---|---|
| 公海与提醒规则 | 列表正常；点详情 → 版本/状态/节点·字段明细对话框 |
| 商机阶段设置 | **预设模板 `OPP_STAGE_TPL_01` 在列**；对它执行停用或删除 → **被拒，报 64018 保护错**（D-01 配套保护验证点） |
| 方案卡模板 | 24 行模板列表正常 |

### 第七幕：数据权限（🟢 [accept-30](shots/accept-30-切换用户A.png)）

| 操作 | 预期 |
|---|---|
| 切换用户 → A 赖永利 | 列表条数与 admin 视角不同（数据权限生效），页面正常渲染 |

---

## 三、D-01 专项验证点（两个口径都写清）

| 口径 | 验什么 | 本清单落点 |
|---|---|---|
| **D-01（opportunity-fix）**：`POST /api/opportunity` 必 500 | fail-fast 60001 / 预设模板 64018 不可删停 / 成功新建落首阶段 5 节点 | 第四幕（新建成功）+ 第六幕（64018 保护）。60001 仅在**无发布中模板**时出现——seed 环境有模板，正常演示不触发，属预期 |
| **D-01（opportunity-bugfix）**：关联客户添加 404 | API 级修复 | 后端六写端点已修复（票 04：F11/F12 探测 HTTP 200 + t04-verify 27/27）；**demo 前端未做写入口按钮**（现存问题 P-2），UI 上不演示写操作，以 e2e-report.md 177 用例结论为准 |

## 四、现存问题总清单（哪黄 + 为什么 + 去哪儿了）

> **缺陷总账**：bugfix effort 登记的 22 条缺陷（D-01~D-22）已**全部闭环——19 条修复 + 3 条翻案关闭**（D-08/D-18/D-19 经 v29 原型与 PRD 复核，判定 e2e 期望写错、实现本身正确）。因此**后端功能面没有已知未修缺陷**；下列为真实现存事项，共五类：

### A. Demo 前端层（本轮自测后仍存在的 UI 缺口）

| # | 问题 | 说明 | 验收时 |
|---|------|------|---|
| P-1 | **D-xx mark 徽标过时** | 页面各处悬浮的 D-01/D-07/D-08/D-13/D-15/D-16/D-17/D-20/D-21 等徽标是写死在 demo 里的历史缺陷标注，对应后端缺陷**均已修复或翻案**（如 D-07 暂缓编辑现被 66003 守卫拦截、D-15 看板已按视图过滤），demo 提示未同步清理 | 看到 mark 不要当现存缺陷，悬停内容仅作历史参考 |
| P-2 | **关联客户/团队成员写入口缺失** | 后端六端点（customer/add·search·set-primary、team/add·delete·update）已修复可用，但 demo 前端未实现添加/编辑按钮，仅只读列表展示 | 这两个子表在 UI 上无法演示写操作，后端行为以 e2e F11/F12 用例为证 |
| P-3 | 暂缓态「编辑」按钮仍显示 | 点击后被 66003 友好拦截（errbox 提示「暂缓中禁写守卫」），非静默失败 | 展示形态问题；拦截行为本身是 D-07 修复的正确表现 |
| P-10 | **新建商机表单缺「客户信息」区块**（与原型 A3-1-1-2-1 不符，用户验收发现） | 原型客户信息区 = 甲方是否明确*/甲方名称 + *关联客户（搜索）/商机关键联系人（搜索）/客户联系人（搜索）/*客户角色/*是否主要客户，业务规则另要求「新增至少关联一个客户」。**分层看依赖**：① 甲方两字段——不依赖，demo 已做；② 关联客户本体——**后端链路完全就绪**：create 入参已预留 `customerId`/`customerName`（票 12 设计注释明写「引用 A4，A4 未就绪前可空」），传值即自动建主要意向客户关联（opp_customer，isPrimaryIntended=1）+ 刷主表冗余（票 13），线索转商机路径已在用；③ **搜索选择体验——真正依赖 A4 客户管理模块**：原型字段规则 15 明写「数据来源于客户管理模块」，客户列表/联系人主数据未建则无候选可搜，关键联系人/客户联系人搜索、选客户自动带出所属公司同理；④「新增至少关联一个客户」「客户角色自选」因此暂缓——D-14 六必填裁决（名称/来源/招标形式/省/市/属地）不含客户，create 时角色固定为「意向客户」 | 不是后端缺陷（契约已预留并降级）；A4 落地后 demo 可补搜索版表单；过渡期可选手填 id+名称快照的简化版（后端即刻可验） |

### B. 测试基线与数据形态（非代码缺陷）

| # | 问题 | 说明 |
|---|------|------|
| P-4 | E2E 残留唯一 ⚠：F13 工作目标 U08 宽断言 | seed 切阶段样例未填 workGoal 导致宽断言退化为弱校验，非代码问题；177 用例 ✅176/⚠1/❌0 中的 ⚠ 即此 |
| P-5 | 阶段历史行显示原始 stageId | seed 直插历史的 from/to 名称快照为空，demo 回退显示 id——数据形态非渲染缺陷 |
| P-6 | 库内留存 accept- 前缀自测数据 | 自测新建 3 商机 + e2e-A 跟进等；不影响功能与 seed 基线，介意可 `python .scratch/opportunity-e2e/seed-opportunity.py` 全量重置（ID 会变） |

### C. 环境外部依赖

| # | 问题 | 说明 |
|---|------|------|
| P-7 | 附件上传依赖 MinIO ⚠ | 起服必须带 `CRM_MINIO_AK/SK` 凭据，否则附件 Tab 上传不可用（后端功能本身 E2E 已验证 ✅，见 F08 六用例全绿） |

### D. 工程状态（须知悉，非缺陷）

| # | 事项 | 说明 |
|---|------|------|
| P-8 | **工作区改动未 commit** | 票 12 工作计划四端点 + 本 effort 三处 demo 修复（B1/B2/B3）均直接改工作区（本 repo 惯例无 commit 流程）；如需入库请明确指示 |
| P-9 | fat jar 增量构建坑 | 起服前须 `clean package`（增量 package 静默拿旧 jar 仍 BUILD SUCCESS），详见 map.md 环境节 |

### E. 挂起项（P2 后续迭代，本 effort 明确 out of scope）

- **A1X 全量工作计划模块**：工作日历/计划管理/出差与拜访——本次仅交付商机详情页工作计划 Tab 四端点 + demo 接入；
- **A4 客户管理模块**：客户公海/客户总览/查重合并/交割等；
- **外部集成类交互**：推送方案 / 督办 / 一键拉群 / 转项目（继承 opportunity-bugfix out-of-scope）。

> 另有展示层噪音：列表条数/分页数字随操作浮动，**数字本身不是断言**。

## 五、验收通过标准

- 第二~七幕全部与「预期」一致 → **验收通过**，本 effort 关闭；
- 任一步不符 → 截图留证，回 `opportunity-bugfix` 补票；UI 层疑似问题可先跑一遍 Agent 自测比对（见下）排除环境因素。

## 六、复跑与佐证

```powershell
# Agent 自测复跑（31 断言，前置：后端 8080 在跑）
python -X utf8 .scratch\opportunity-acceptance\accept-selftest.py
```

- 机器可读结果：`selftest-result.json`（终轮 31/31 PASS，0 页面异常 0 console error）
- 截图目录：`shots/`（accept-01 ~ accept-30，索引见 [selftest-report.md](selftest-report.md) §三）