You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
13 KiB
13 KiB
商机模块整改 — 人工验收清单与移交说明（opportunity-acceptance · 票 04）
- 生成时间：2026-08-31（Agent 自测 31/31 全绿后移交）
- 被测对象：
.scratch/opportunity-e2e/demo/index.html× verify 后端（fat jar + 远程 DB） - 佐证：selftest-report.md（31 断言 + 29 截图）· e2e-report.md（177 用例）· 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 分钟）
- 起服（仓库根目录，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） - 打开 Demo：浏览器直接打开
file:///D:/code/crm-backend-matt/.scratch/opportunity-e2e/demo/index.html。 预期：自动登录，左上角显示「已登录：罗伟健」（管理员）。🟢 accept-01 佐证见列表截图 - （可选）基线重置：
python .scratch/opportunity-e2e/seed-opportunity.py（先清后造幂等，ID 会变）。自测留下的accept-前缀数据不影响演示；介意可重置。
二、演示脚本（按顺序点，每步预期）
条数为自测时点值，随演示操作浮动，数字本身不是断言。
第一幕：列表多视图（🟢 accept-01~04）
| 操作 | 预期 |
|---|---|
| 默认「我负责的」视图 | 有数据（自测时 4 条：seed 1 + 自测新建 3） |
| 切「管理全量」 | 条数明显变多（自测时 17 条），分页正常 |
| 切「公海」 | 待领取商机（自测时 3 条），且停留在第 1 页（demo-B1 修复验证点：切视图不得出现空页/错误页码） |
| 关键词输入「智慧园区」→ 查询 | 仅命中行（自测时 2 行），查询后回到第 1 页 |
第二幕：看板（🟢 accept-05）
| 操作 | 预期 |
|---|---|
| 切「看板」视图 | 按阶段分列的卡片汇总正常渲染（无 loading 卡死） |
第三幕：详情九子表（🟢 accept-06~20）
点开任一商机（如「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）—— 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）
在刚新建的商机详情页：
| 操作 | 预期 |
|---|---|
| 「暂缓」→ 对话框选原因（下拉为字典项，非裸文本框）→ 确认 | badge 变「暂缓中」；点击有反应（框关闭 + 成功提示，demo-B2 修复验证点：无返回值端点不得静默失败） |
| 「取消暂缓」 | badge 变回「推进中」 |
第六幕：规则三族（🟢 accept-26~29）
| 页面 | 预期 |
|---|---|
| 公海与提醒规则 | 列表正常；点详情 → 版本/状态/节点·字段明细对话框 |
| 商机阶段设置 | 预设模板 OPP_STAGE_TPL_01 在列；对它执行停用或删除 → 被拒，报 64018 保护错（D-01 配套保护验证点） |
| 方案卡模板 | 24 行模板列表正常 |
第七幕：数据权限（🟢 accept-30）
| 操作 | 预期 |
|---|---|
| 切换用户 → 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 自测比对（见下）排除环境因素。
六、复跑与佐证
# 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 §三）