|
|
|
|
# Map: 客户模块端到端验收（E2E 实测 + Bruno 接口文档 + 前端 demo + 测试报告）
|
|
|
|
|
|
|
|
|
|
`wayfinder:map`
|
|
|
|
|
|
|
|
|
|
## Destination
|
|
|
|
|
|
|
|
|
|
**客户模块端到端验收交付包，两件套 + 配套资产全部落地**：
|
|
|
|
|
|
|
|
|
|
1. **Bruno 接口文档集合**（`D:\code\crm-api-docs\A4 客户管理\`，换机后 D 盘）— 9 Controller 55 端点按原型页面分组生成 .bru，请求示例 = E2E 实测真实值注入；参数/出参/状态码（67001–67016 等）/权限（RBAC fail-open + @DataScope）/脱敏规则描述齐备，前端工程师可直接看懂并用于联调（参照 A3 商机管理 82 .bru 的结构与表述风格）。
|
|
|
|
|
2. **E2E 测试报告**（`.scratch/customer-e2e/e2e-report.md`）— 以蓝湖 v29 A4 页族原型为第一依据（**原型 > spec > 问用户**），对客户模块全量 55 端点做 API 级实测 + demo 浏览器级测试，逐流程三档结论（✅ 通过 / ⚠ 行为不符 / ❌ 缺失或阻断）+ P0/P1/P2 分档的缺陷编号清单（含原型对照）。**只报告不修复**（用户拍板）。
|
|
|
|
|
3. 配套中间资产（前端联调共享）：单文件前端 demo（`demo/index.html`，对标商机 969 行版）+ 幂等 seed 脚本与远程库客户测试数据。
|
|
|
|
|
|
|
|
|
|
地图做完 = 文档集合 + 报告交付、可交接；缺陷修复另起 effort。
|
|
|
|
|
|
|
|
|
|
## Notes
|
|
|
|
|
|
|
|
|
|
### 范围拍板（chart grill 20260903，四问全选推荐项）
|
|
|
|
|
|
|
|
|
|
- **示例值来源 = 实测注入真实值**：E2E 实测（seed + specimens）先行，Bruno 文档示例后注入（对称商机票 11 模式）。文档交付在实测之后。
|
|
|
|
|
- **测试环境 = 本地起服 + 远程共享库**（8.129.84.155）：e2e- 前缀 seed 造客户数据，前端联调可共享。
|
|
|
|
|
- **缺陷处置 = 只报告不修复**：缺陷只入编号清单（P0/P1/P2 分档 + 现象/复现/接口/原型依据），修复另起 effort（对称 opportunity-fix 模式）。
|
|
|
|
|
- **E2E 范围 = 全量 55 端点**：核心域 + 交割/导入/提醒规则全流程 + demo 浏览器级测试（对称商机 150 用例规模）。
|
|
|
|
|
|
|
|
|
|
### 环境事实（20260903 chart 会话实核；本机 = e: 盘换机后环境）
|
|
|
|
|
|
|
|
|
|
- **代码基线**：HEAD `43887d3`（`dc8aada` = 客户模块票 09-13 收尾 + 票 14 review 修复）。实现 100% 完成：票 01-14 全交付，三模块测试 521/0/0 全绿。9 Controller 55 端点（含票 12 新增 members/focus 组）。
|
|
|
|
|
- **DB 凭据就在配置文件**（用户 20260903 实锤）：`crm-app/src/main/resources/application.yml` 默认值直接指向远程库 `jdbc:mysql://8.129.84.155:3306/crm`，root / `Itc@123456`；Redis 同机同密码。**起服无需传 DB 环境变量**。
|
|
|
|
|
- **MinIO 凭据**（用户 20260903 实锤）：AK=`admin` / SK=`Itc@123456`（默认 minioadmin 会被远程拒）。
|
|
|
|
|
- **起服命令**（商机先例已验，仓库根目录）：`$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`（日志 `logs/crm-app.log`）。⚠ 重打包前**先停 8080 的 java 进程**（jar 锁）；⚠ fat jar 可能落后源码（Maven 增量陷阱，重打包后核对）。
|
|
|
|
|
- **debug token**：`GET /api/auth/debug/token?userId=<uid>`（verify profile；`application-verify.yml` 存在于 crm-app resources）。
|
|
|
|
|
- **Bruno 集合**：`E:\code\crm-api-docs`（git 仓，**agent 不提交，用户审查后自行提交**）。当前 236 个 .bru；**A4 客户管理目录已建但空壳**（仅 folder.bru + README.md）；结构参照 `A3 商机管理`（6 个页面级子目录 + folder.bru + README.md + 82 .bru）。⚠ 根目录现为**裸 collection**（bruno.json + collection.bru，无 workspace.yml/collections/）——若 Bruno 3.x 打不开需结构升级（bruno-coldstart 有升级先例），票 06 动手前按用户 Bruno 版本定。
|
|
|
|
|
- **bruno-sync skill**：`C:\Users\Administrator\.qoder\skills\bruno-sync`；根目录 `bruno-sync.config.json` 的 sourceRoots **不含 crm-customer**，用 skill 前需加 `crm-customer/src/main/java`。铁律 1「结构听源码，表述听人」：手改实参值/示例再生时逐字保留，对账钥匙 = METHOD + 路径。
|
|
|
|
|
- **蓝湖原型通路**：v29 清单 `.scratch/lanhu-latest/axure-v29.json` 已在本地，每页直接 `https://lanhu-axure-file.oss-cn-beijing.aliyuncs.com/{sign_md5}` 拉 HTML，**无需 Cookie/MCP**。提取脚本 fetch-v29-customer-pages.mjs / extract-annotations.mjs 同目录（select option 需专门抓取、不在 div_text 里）。A4 页族现缓存仅 a4-4-1 一页（.scratch/lanhu-latest/v29-customer-pages/，其余 12 个是 A3 商机页），**A4 其余页需重拉**。
|
|
|
|
|
- 远程库存量：商机 e2e- seed 13 条（历经流转已偏离基线，重置可跑 `python .scratch/opportunity-e2e/seed-opportunity.py`）；客户数据 = 票 12 冒烟残留（quick-create 的 KH20260903xxx 等）；字典 24 组在线（customer_type 18 值 / contact_source 4 值 / industry 两级树）。
|
|
|
|
|
|
|
|
|
|
### 底稿资产（本图不吃回头草）
|
|
|
|
|
|
|
|
|
|
- **接口底稿**：`.scratch/customer-module/API-SUMMARY.md`（票 13 交付：55 端点按原型界面分组 + 错误码 67001–67016 总表 + 已知缺口 5 项）。
|
|
|
|
|
- **对齐底稿**：票 12 十页静态对齐结论（`HANDOFF-2026-09-03.md` §3.7.2，不符②③④⑤已修复）；spec 决策 D1–D29（`.scratch/customer-module/map.md` 自包含）。
|
|
|
|
|
- **踩坑表**：HANDOFF §4 坑①–㉕（PS 中文 body mojibake ㉑、pymysql autocommit 快照冻结 ㉕、@Comment 单引号 ⑳、BOM 纪律等——**实测脚本动手前先读**）。
|
|
|
|
|
- **E2E 先例**：`.scratch/opportunity-e2e/` 全套可对标复制（spec-flows.md / env-inventory.md / seed-opportunity.py / e2e-core.py / demo/index.html / e2e-report.md 范本）。
|
|
|
|
|
|
|
|
|
|
### 判定纪律（商机翻案教训，实测必守）
|
|
|
|
|
|
|
|
|
|
- **禁止按 RESTful 推断接口路径**：本项目接口 flat 风格，判「❌ 未实现」前必须核对 Controller 源码 / Bruno 集合的实际路径。
|
|
|
|
|
- **判定依据优先级**：原型第一（v29 一手拉取）→ spec（D1–D29 + issues/NN-answer.md）→ 仍不明确 grill 用户。
|
|
|
|
|
- **脚本一律 Python requests**（PS5.1 发中文 body 会把库里写坏——坑㉑实锤）；库检每步新连接 autocommit=True（坑㉕）；孤立 401 先重试再判缺陷。
|
|
|
|
|
- 三档结论口径：✅ 通过 / ⚠ 行为与原型不符 / ❌ 缺失或阻断；缺陷编号 D-01 起递增。
|
|
|
|
|
- 已知缺口（API-SUMMARY §5：QuickCreateDTO 无 confirmSimilar、页签 5·6 与汇总卡 5 字段恒 null、联系人子表导入划出等）预登记为「范围外/记录」，不算新缺陷。
|
|
|
|
|
|
|
|
|
|
### 默认技能
|
|
|
|
|
|
|
|
|
|
- `/bruno-sync` — 票 06 文档生成（动手前先读 skill 机制 + bruno-sync.config.json）
|
|
|
|
|
- `/webapp-testing` — 票 08 demo 浏览器级自测（Playwright）
|
|
|
|
|
- `/grilling` + `/domain-modeling` — 实测中新暴露的原型歧义 graduate 时
|
|
|
|
|
- `/research` — 票 01 原型拉取 + 流程盘点
|
|
|
|
|
|
|
|
|
|
## Decisions so far
|
|
|
|
|
|
|
|
|
|
<!-- chart 期四项拍板已写入上方「范围拍板」；工作期决策逐票追加于此 -->
|
|
|
|
|
|
|
|
|
|
- [01 — A4 原型重拉 + 流程盘点](issues/01-prototype-flows.md) — spec-flows.md 交付：16 流程 F-01..16 + 55 端点实核总账；groupColumn 白名单实为 stage/star/relation（底稿笔误订正）；U-01..04 挂号；A4 41 页重拉完成（fetch-v29-a4-pages.mjs）
|
|
|
|
|
- [02 — 本机起服冒烟 + 环境盘点](issues/02-boot-smoke-env.md) — env-inventory.md 交付：冒烟全绿（含 D-01 P0 修复+真库复验，用户拍板顺手修）；64 表/用户 6047/部门 814/字典 24 组全清单；编号水位 KH202609030005、公海空池；唯一角色 ROLE_ADMIN(data_scope=4) → 跨用户权限语义列票 04 观察点；seed 约束 5 条
|
|
|
|
|
- [03 — seed 脚本 + 联调数据](issues/03-seed-script.md) — seed-customer.py ALL GREEN（7/7，幂等重跑已验证）+ seed-data-manifest.md：17 客户+2 商机+4 联系人+跟进/归档/公海/协同样例，KH202609030006-0022；并发策略拍板 = e2c- 命名空间独占（与商机域 e2e- 隔离）+ 重跑重建 + 消费方读 seed-ids.json；契约速查沉淀（SaveResultDTO 双形态/ISO T 分隔/opp_source_02）；新观察点 W-01 contact_source 字典组缺失
|
|
|
|
|
- [04 — 客户核心域实测](issues/04-core-domain-test.md) — e2e-core.py 112 用例 ✅110/⚠2/❌0 + report-core.md + specimens-core.json（45 端点）；新缺陷 D-02（P2 follow 过去时间未拦）/D-03（P2 缺 version 报 67001 非 67005）；D-01 复验通过；契约发现 12 条（ISO T/Long→String/cnt/PUT 全量覆盖/assign→TRANSFER/enter_pool_time 生命周期/archive-batch 整批拒）供票 06 消费
|
|
|
|
|
- [05 — 重流程实测](issues/05-heavy-flow-test.md) — e2e-heavy.py 6 轮收敛 ✅54/⚠4/❌0 + report-heavy.md + specimens 19 端点；新缺陷 D-05(P1 导入 INSERT 行必失败：is_biz_negotiated 缺省列)/D-04(P2 insertFail 炸 varchar(500) 明细全丢)/D-07(P1 交割 assignable 稳定超时)；D-06 撤回（脚本取 records，PageResult 实际序列化 content）；Job 实测（U-02 重启 env 注入 cron）：落表/payload/排除/幂等=每轮补下一条升级链（remindSeq 0..29 连续）/锚点刷新置 INVALID；观察点：升级提醒链无上限推进
|
|
|
|
|
- [06 — Bruno 接口文档生成 + 真实示例注入](issues/06-bruno-docs.md) — 57 .bru / 10 目录落地 D 盘文档仓（换机 E:→D: 改 3 处路径；旧机错误产物 67 文件清理后重跑）；分组决策：目录=tag 原文（根级 `客户管理/超期提醒规则/` 2 端点）、crm-preference 6 端点不生成副本（tag 挂 A3，README 文字索引 scopeKey=customer.*）；verify_a4.py 对账 57 钥匙双向全命中 PASS；裸 collection 不升级（Not-yet 结案）；README 占位重写（9 子目录索引+归位说明+维护纪律）；示例值注入 specimens 实测真值
|
|
|
|
|
- [07 — 单文件前端 demo](issues/07-frontend-demo.md) — demo/index.html 831 行交付：5 tab（列表三 workspace+批量操作/详情 6 子页签+全归属动作/导入/交割/设置+查重试玩），三层查重 confirmSimilar 流、reminder 字段名与 F-15 契约逐字对齐、D-02/D-05/D-04/D-07 角标内嵌；saved-view 与页签 5/6 按已知缺口不渲染；浏览器级验证移交票 08
|
|
|
|
|
- [08 — demo 浏览器级自测](issues/08-webapp-testing.md) — 终轮 31 PASS/0 FAIL 全绿 + console/page errors=0 + 30 截图（Playwright chromium headless，四轮迭代）；自测前修 6 处 demo 契约偏差（联系人字段名/PUT-DELETE 路径/failures 路径/API_BASE/unifiedCreditCode/follow_way 字典）；自测中修 2 处 demo 真缺陷（oneBy focus 族 URL 形态：POST /{id}/focus 路径变量，ownership 族 flat ?id= 不变；交割 tab transferPage(1) 翻页语义错→(0)）；CORS-block 报错=404 无 CORS 头误报经验沉淀；R1 假撞码代码致脏客户落库已 claim→archive 正门清理（clean_pollution.py 可复用）；脚本侧教训：tableHtml 空态行也是 1 tr、IMP_ST 英文文案、DELETE 后需轮询等重载
|
|
|
|
|
- [09 — E2E 报告聚合（终稿交付）](issues/09-report-aggregation.md) — e2e-report.md 178 行八章交付：170 API 用例（✅164/⚠6/❌0）+ demo 31 步 = 201 步全绿零阻断；缺陷有效 6 条（D-01 P0 已修 + P1×2 D-05/D-07 未修 + P2×3 D-02/03/04 未修，D-06 撤回）与 API-SUMMARY §5 缺口合并去重；U-01..04 全部销号；W-01 与升级提醒链无上限维持挂账为联调观察点；静态对齐差异章归纳六类动态实测增量；交付确认四件套全落地（Bruno 57 .bru 对账 PASS + 报告 + demo + seed）——**地图做完，缺陷修复另起 effort**
|
|
|
|
|
|
|
|
|
|
## Ticket 依赖图
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
01 (research: 原型重拉+流程盘点) ─┬→ 03 (task: seed 脚本) ─┬→ 04 (task: 核心域实测) ─┐
|
|
|
|
|
02 (task: 起服冒烟+环境盘点) ─────┘ ├→ 05 (task: 重流程实测) ─┼→ 06 (task: Bruno 文档) ─┐
|
|
|
|
|
└→ 07 (task: 前端 demo) → 08 (task: demo 自测) ─┤
|
|
|
|
|
└→ 09 (task: 报告聚合)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Not yet specified
|
|
|
|
|
|
|
|
|
|
- ~~**实测中原型歧义**~~ — **结案**：U-01..04 全部销号（票 09 报告 §五收口表）；实测未新暴露需 grilling 的歧义，无 graduate。
|
|
|
|
|
- ~~**Bruno 3.x workspace 结构升级是否顺带做**~~ — **结案（不升级）**：票 06 实测裸 collection（bruno.json + collection.bru）可打开，维持现状；如未来升级按 bruno-coldstart 先例另起。
|
|
|
|
|
|
|
|
|
|
## Out of scope
|
|
|
|
|
|
|
|
|
|
- **修复任何缺陷** — 本次只报告（用户拍板）；修复另起 effort。
|
|
|
|
|
- **敏感信息三档脱敏 / 客户合并 / 客户导出** — spec 阶段已划出（API-SUMMARY §5），E2E 只按现状记录。
|
|
|
|
|
- **联系人子表导入** — REVIEW-HANDOFF 明确划出（原型 9.2-9 说 V1 支持，按定稿划出）。
|
|
|
|
|
- **OCR / 企查查外部服务内部** — 只留 seam，不深挖。
|
|
|
|
|
- **平台通知发送**（超期提醒 Job 只落待发不直接发）— spin-out。
|
|
|
|
|
- **客户阶段「重潜 / 已成交」触发链路** — D20 拍板 seam 化本期无调用方（报备成功链路/A5 均不可达），不测不可达流程；`CustomerStagePort.promote` 契约本身 H2 已覆盖。
|
|
|
|
|
- **demo 托管 / 真实账号密码登录页** — 单文件 + debug token 选人即可（商机先例）。
|
