crm-backend-matt/.scratch/customer-e2e-r2/map.md

# Map · 客户模块第二轮 E2E（返工后契约全量回归 + 增量 + UI 扩展）

label: wayfinder:map
created: 2026-09-05

## Destination

客户模块在返工后契约上的第二轮 E2E 验证收官：round-1 全量套件（e2e-core 112 例 / e2e-heavy 6 轮）改写到扁平动作动词契约并重跑，补齐返工新增端点的 API 用例（战略协议五端点 / 查重设置 / F6 批量工商 / F8 duplicateStrategy / confirmSimilar / view-form / 联系人 oplog action）；demo 页扩展新能力入口并扩展 Playwright UI 冒烟。产出 `.scratch/customer-e2e-r2/e2e-report-v2.md`（对照 round-1 ✅164/⚠6/❌0 逐项 delta）与刷新后的缺陷清单。

## Notes

**Charting 拍板（2026-09-05，用户三问三答）**

1. 目的地 = **全量回归 + 增量覆盖**（非只测增量 / 非缺陷验证轮 / 非深化覆盖轮）
2. 缺陷**只测不修**：已知缺陷用例按「缺陷验证模式」记录（预期失败、不阻断、不重复排查），修复永远另起 effort
3. **UI 层扩展覆盖**：demo 页要先长出新入口（战略协议 / 查重设置 / 批量工商 / 导入策略），再扩 Playwright 用例

**契约与环境（沿用 round-1 + 返工图沉淀）**

- 契约权威：`.scratch/customer-module/API-SUMMARY.md`（73 端点）+ `.scratch/customer-rework/dump_api_out.txt`（Controller 扫描基准）；原型树 `.scratch/api-docs-reorg/lanhu-tree-v29.md`
- 环境：verify profile 本地起服 + 远程共享库（8.129.84.155，application.yml 内置默认；`CRM_MINIO_AK/SK` 环境变量）、debug token `GET /api/auth/debug/token?userId=`；ping 401 = 鉴权门 ≠ 服务挂
- Maven 增量陷阱：先删 `crm-app/target` 旧 fat jar 再 package（fat jar 落后源码坑）；构建用 IDEA 自带 maven + corretto-17
- Playwright：`.scratch/customer-e2e/.venv10` 可复用（chromium-1234 已缓存零下载）；**跑增量套件 e2e-incr.py 需先给 venv10 补装 openpyxl**（票 02 实核缺失），compile/对账用 venv10 解释器（shell `python` 不在 PATH）
- 测试残留：`e2c-` 前缀 + archive 正门清理

**工作约定**

- 脚本**就地改写**：`e2e-core.py` / `e2e-heavy.py` / `demo_smoke10.py` 在 `.scratch/customer-e2e/` 原地改（同名延续或复制 r2 版本，票内定）；报告与结果产物落 `.scratch/customer-e2e-r2/`
- 缺陷编号沿用 D-xx 续编（round-1 已有 D-01…D-07；D-01 已修本轮复验预期转绿，D-05/D-07/D-04 缺陷模式）
- Bruno 文档本轮**只对账不重构**：发现漂移记档，小漂移顺手 patch 可接受，大漂移另起
- round-1 资产索引：`.scratch/customer-e2e/map.md`（十票全 resolved，含全部环境坑位）+ `e2e-report.md` + `seed-ids.json` + `specimens-core/heavy.json` + `demo_smoke10.py`

## Decisions so far

- [01 · e2e-core / e2e-heavy 契约改写](issues/01-suite-rewrite.md) — 复制 r2 版本两脚本（884/910 行），34 处 URL/method + 7 处断言语义改写，静态对账 PASS（55 调用 = 54 命中 + 1 预期例外）；产物 matrix-r2.md + calls-r2.json，票 02 输入 10 端点清单已锁定
- [02 · 返工新增端点 API 用例](issues/02-api-increment.md) — 承载决定独立 `e2e-incr.py`（620 行，I-01…I-07，夹具 e2c-r2i-A/B 幂等），票 02 范围 10 端点全覆盖 + F8/viewTouch/oplog 六 action/缺省语义/64023 全落用例；静态对账 PASS（20 调用 = 105 基准全命中）；**实核发现 pool·board 白名单漂移**（§2.14 称拒绝、实现无 pool 特判，用例分支记档）——fog「view-form/oplog UI 覆盖」据此收敛**不进 demo**（per-user 单字符串状态 + 值域扩展无独立 UI 语义）；移交票 04：venv10 补装 openpyxl 后跑 core→heavy→incr
- [03 · demo 页新入口扩展](issues/03-demo-new-entries.md) — 四入口全落地（+90 行）：战略协议 subtab 五端点（编辑不带 customerId、缓存列表回显）/ 查重设置面板（GET 回显 + save 空阈值经 qs 丢弃走缺省 80）/ F6 批量工商（五状态徽标、stub 恒 NO_HIT 如实呈现）/ F8 导入策略下拉（upload 原调用加字段）；字段名自 AgreementDTO/CompanyBatchUpdateDTO 源码实锤；静态验证 node --check + 39 唯一路径（票 10 的 31 零扰动 + 新 8）；**原型缓存 D 盘不在本机**，形态按契约+demo 风格落地（票 05 如需对照先迁缓存）
- [04 · 起服全量执行](issues/04-api-regression-run.md) — **233 例 = ✅221 ⚠9 ❌3，新缺陷 0**（core 112 ✅109⚠3❌0 数据态修复后复跑 / heavy 58 ✅52⚠4❌2 / incr 63 ✅60⚠2❌1）；⚠9 全预期（D-02/03/05/07 缺陷模式复现 + 取证断言 + pool·board 预埋探测兑现）；❌3 全归因用例侧（票 01 把「升级链每轮补条」收窄成「恰好 1 条」的改写偏差 ×2 + 空 ids 实回 40001 分支盲区 ×1），DB 证据 Job 行为与 r1 一致；D-01 转绿、D-08 未触发（I-07 UPDATE 路径 DONE）；**数据态坑沉淀：heavy F-13 交割圈定 BUDDY 名下全量且 teardown 不还原——复跑即漂移 collab owner**（已两次还原 + 票 05 移交注意）；残留正门清 10 条，终态 e2c-* 活跃=seed 名单；fog「heavy 执行深度」定全跑（~7.5min）
- [05 · demo Playwright 扩展冒烟](issues/05-ui-smoke-extended.md) — 新建 `demo_smoke_r2.py`（smoke10 基线 11 步保留 + 详情页签 6 个）**20 步全 PASS 首轮一次过**：协议 CRUD 五端点闭环 + 客户快照同步实证（delete 实为软删墓碑，DB 口径 deleted=0）/ 查重设置 save→回读→原值双保险恢复 / F6 勾选→NO_HIT 徽标如实呈现 / F8 OVERWRITE 回显；console/page error=0、57 请求零旧契约形态；**BUDDY 解耦落实**（写操作挂自建客户、交割只预览不 initiate、collab owner 复核未漂移）；残留终态 e2c-*=16=seed 基准 + dedup 单例原值（scan-residue-t05.py 实扫）
- [06 · e2e-report-v2 聚合](issues/06-report-v2.md) — **收官交付 `.scratch/customer-e2e-r2/e2e-report-v2.md`**（八章节）：233 API 用例 ✅221⚠9❌3 + UI 20 步全 PASS = **无产品回归**；❌3 全归因用例侧（F-15 改写收窄×2 / I-04 空 ids 40001 盲区×1）；新缺陷 0，D-01 转绿兑现、D-08 未触发、D-05 UPDATE 路径新证据；翻转 4 项（confirmSimilar 销号/查重单例落地/oplog 17 种/D-05 收窄）；客户域覆盖 64/73 + 维持 9 项对账；**fog 处置定案**：§2.14 pool·board 漂移警示 + §2.2 补登记 40001 已记档式 patch API-SUMMARY，stage=2 非文档项，Bruno 仓无需同步。**01–06 全 resolved，destination 达成，地图收官**

## Not yet specified

（无——全部收敛。原两条 fog 已定案：①「Bruno 文档漂移处置边界」→ 票 06 报告 §六落定（§2.14 漂移警示 + §2.2 补 40001 已 patch API-SUMMARY；stage=2 非文档项）；②「heavy 执行深度」→ 票 04 现场定全跑（~7.5min）。）

## Out of scope

- 缺陷修复（D-05/D-07/D-04 及本轮新发现缺陷的修复——只报告，修复另起 effort）
- 深化维度（权限矩阵加密、并发、脏数据边界等——charting 拍板不选深化覆盖轮）
- 客户导出 / 联系人导入 / 客户查重合并（沿用返工图划出）
- `deploy\demo\index.html`（线索 demo，不涉及；round-1 票 10 已钉）
- Bruno 文档结构重构（本轮只对账）

## 票与 blocking

- 04 依赖 01+02（套件改写与增量用例就位才能起服执行）
- 05 依赖 03+04（demo 新入口就位 + API 层已验稳，UI 冒烟才有意义）
- 06 依赖 04+05（API 与 UI 两路结果齐才能聚合报告）

Frontier：**空——地图收官（2026-09-06）**。01–06 全 resolved，destination 达成；终稿 `.scratch/customer-e2e-r2/e2e-report-v2.md`。

```
01 ✅ + 02 ✅ ──> 04 ✅    （套件改写 + 增量用例就位 → 起服执行，已完成）
03 ✅ + 04 ✅ ──> 05 ✅    （demo 新入口 + API 层验稳 → UI 冒烟，已完成）
04 ✅ + 05 ✅ ──> 06 ✅    （两路结果齐 → 聚合报告，已收官）
```

## 参考索引

- round-1 地图：`.scratch/customer-e2e/map.md`（Decisions-so-far 十票）
- demo 契约对照表：`.scratch/customer-e2e/issues/10-demo-contract-sync.md`（24 行映射坑位直接复用）
- 返工回归基准：`.scratch/customer-rework/RETEST-REPORT.md`（冒烟 43 步覆盖清单，脚本已丢失，票 02 从报告重建断言语义）
- 原型缓存：`D:\code\crm-需求梳理\lanhu-mcp\data\axure_extract_bade4454_screenshots\`（`.txt` 为主，OCR 兜底）