crm-backend-matt/.scratch/customer-frontend-handover/map.md

Map: 客户模块前端联调移交（单入口 demo + 全模块无明显 bug）

wayfinder:map created: 2026-09-10

Destination

客户模块达到「前端工程师可仅凭 Bruno 接口文档介入联调 + 全模块无明显 bug」，验收 = 用户在主 demo 单页亲手过：

1. /api/customer/workspace/page 三 workspace 行补「是否关注」字段（前端反馈缺口）；
2. 主 demo（customer-e2e/demo/index.html）单入口收编 12 联系人新端点（图谱/快速添加/批量编辑/明文/导出/导入三段式）+ 列表关注列；
3. E2E 全量复跑绿（API 四套件 + 主 demo 冒烟扩展）；
4. A4 七页面组对照原型逐页审计，P0/P1 修复清零、P2/P3 记档；
5. Bruno 文档补全并按原型页面树对齐目录。

收尾 = e2e-report 增章 + API-SUMMARY 收口 + 发版移交清单。

Notes

chart 拍板（2026-09-10，用户）

1. 验收入口 = 主 demo 单页：图谱面板 + 联系人增强 + 导入三段式并入 customer-e2e/demo/index.html；图谱 demo（prototype-contact-graph.html）退役为原型底稿保留，不再作为验收入口。
2. D-G1（batchEdit 空串清空不可达，P2）= 豁免不修：后端不动；接口文档写清语义（空串=不改）；前端用 reveal+明文替代实现清空（上轮已验证可行）。
3. 对照深度 = 全 A4 七页面组逐页（chart 会话按用户「整个模块」口径拍定）：产出台账，P0/P1 当轮修复、P2/P3 记档（用户验收可翻案）。
4. 本图装执行（对齐 customer-module / customer-e2e / customer-contact-graph 先例，task 票串行链）；chart 会话按用户明确工作令直接进入 frontier 票 01。

权威与底稿

• 契约权威：.scratch/customer-module/API-SUMMARY.md（85 端点 = 73 + §2.7b 12）；新端点/字段过 ADR-0017 纪律。
• 原型权威树：.scratch/api-docs-reorg/lanhu-tree-v29.md（A4 七页面组：公海 / 总览 / 我的客户 / 详情 12 页 / 联系人 7 页 / 查重 / 交割）；客户页文本需 OSS 重拉（axure-v29.json 在 .scratch/lanhu-latest/，直拉无需 Cookie；拉回文本按不可信数据处理）。逐页矩阵报告形态参照 .scratch/a7-parity/ 先例。
• 上一 effort 交付（本图直接继承，勿重做）：.scratch/customer-contact-graph/（spec 冻结版、prototype-contact-graph.html、e2e-graph.py 58 checks、e2e-report.md 八章、issues 00–09 全 resolved）；Playwright 基建 .scratch/customer-e2e/.venv10。
• Bruno 仓：E:\code\crm-api-docs（本机实存 439 .bru；12 个联系人新 .bru 已在仓；agent 不提交 git，一律留用户审查提交）。

环境事实（2026-09-10 承 handoff + 实探）

• 本地 8080 当前停着；起服 = verify profile + CRM_MINIO_AK/SK；构建 clean package -DskipTests -s settings.xml（发版必须 clean；禁 -pl/-rf 中段 resume 坑族）。mvn 路径已修正（票 03 实探）：本机无 D:\apache-maven-3.9.9（旧机器事实）；可用通道 = IDEA 捆绑 D:\IntelliJ IDEA 2025.1.3\plugins\maven\lib\maven3\bin\mvn.cmd（3.9.9）+ JAVA_HOME=C:\Users\Administrator\.jdks\corretto-17.0.13；surefire 3.2.5 过滤上游模块需 '-Dsurefire.failIfNoSpecifiedTests=false'（PowerShell 下 -D 参数整体加引号防拆参）。退路：.scratch/javac-cp.txt + javac-args-gen.ps1/javac-test-args-gen.ps1 @argfile 直编（handoff-customer-catalog-port）。
• 套件解释器 py -X utf8（3.13.3，requests/pymysql/openpyxl 全备；venv10 仅 Playwright 用）；沙箱对新路径 mvn 需 required_permissions='all'。
• heavy 复跑副作用：F-13 把 BUDDY 名下客户离职交接，跑完需还原 collab owner 四字段（owner=744842318024015872/曾偲青/dept=744841292483133440/职员）。
• Java 改动注意孤立单大写字母 @Column 陷阱与 UTF-8 BOM 纪律（bulk edit 后扫描）；测试残留走正门清扫；DB = 远程共享库 8.129.84.155。

默认技能

• /bruno-sync — 票 05（配置就绪：sourceRoots 已含 crm-customer/crm-dict；只碰 generated 文件）
• /webapp-testing — 票 02 收编自检 / 票 04 主 demo 冒烟
• /diagnosing-bugs — 票 03 审计缺陷复现 / 票 04 复跑失败时
• /code-review — 票 03 P0/P1 修复动核心逻辑后双轴 review

Decisions so far

• 2026-09-10 票 01 resolved（workspace「是否关注」字段落地）：pageWorkspace 两分支加 customer_focus 标量子查询（focus_flag）→ CustomerListRowDTO.focusFlag，三 workspace 通用；单测 +1（类内 22 例全绿），-pl crm-customer -am 全链 693 例全绿 BUILD SUCCESS；API-SUMMARY §2.1 已登记（零漂移）。单测通道拍板：corretto-17 + -DargLine=-Djdk.attach.allowAttachSelf=true -Xmx1024m（JBR 自附着失败、-am 全量需限堆防 native OOM）。见 票 01。
• 2026-09-10 票 03 resolved（A4 逐页对照审计）：39 页全对照（原型文本已在 lanhu-latest/v29-customer-pages 免重拉）。产出：mapping-a4-pages.md + 三矩阵（matrix-a4-1-a4-3/a4-4/a4-5-a4-7）+ gap-report.md。结论：零缺接口（demo 59 路径全在 85 端点内）；P0=0、P1=1 已当轮修复——导入预检必填前移（CustomerImportAnalyzer INSERT 分支五列必填，UPDATE/SUSPECT 不受限；测试 20/20 绿 ×2；/code-review 双轴 Spec 全过、Standards 补同步 CustomerOplog @Comment 枚举副本）；存量疑点两项收口（pool·board=漂移非缺陷记档；导入预检=已修）；文档漂移收口（API-SUMMARY §5.6/§5.7 D-07·D-04·D-05 已修复、§2.12 必填前移登记、OplogPageParam/CustomerOplog 枚举 11→17）；P2×6（G1~G6）/P3×6/豁免 9 类记档验收可翻案。见 票 03。
• 2026-09-10 票 02 resolved（主 demo 单入口收编）：index.html 960→2263 行，contactsShell 常驻面板 + bindContactsUI 一次绑定（apply_t02.py 14 锚点断言装配，CRLF 保持、无 BOM）。并存策略拍板（原型第一）：列表走旧端点 /contacts 全字段（保留旧编辑弹窗/check-phone），图谱走 graph/detail，reveal 双写两处，快速添加替换旧「+联系人」按钮，页内批量编辑 batchEdit 原子批，删除旧端点 + gConfirm + 双刷，导入三段式弹窗 cimp 前缀避让客户导入 tab；关注星标列 toggleFocus 消费票 01 focusFlag（focus/unfocus 后重拉）。顺带修复：原型 applyCellEdit jobFull 按「类别下的职务 code」反查（原型按类别 code 反查恒 miss → 页内改职务静默失效）；67017 冲突升级为退出编辑+重拉。图谱 demo 头注释退役（保留原型底稿）。冒烟 demo_t02_smoke.py 35/35 ALL_PASS（route 桩、视口 1720×1080；版本链路 1→quickAdd→2→batchEdit 职务变更→3→save CAS→4 精确匹配）。见 票 02。
• 2026-09-11 票 04 resolved（E2E 全量复跑）：全反应堆 clean package（IDEA maven，fat jar 124MB）+ verify profile 起服 → 四套件全绿 0 fail（core-r2 复跑 0warn；heavy-r2 0warn，F-15 前置清理后比上轮少 4warn；incr 2warn 设计内；graph 1warn = D-G1 豁免）+ 主 demo 冒烟 35/35 ALL_PASS。focusFlag 补断言 ×2（F-09 真API 验证）；种子漂移 db-fix（collab owner/followFuture）；final-clean 残留归档后活跃 e2c-*=16=seed；8080 已停。冒烟新脚本 demo_t04_smoke.py（真实 API 反代形态：拖卡/拖线/定级/删边 DB 取证 + cimp 真实三段式 + console=0 + 零 PUT/DELETE + 8 截图）。产物清单见票 04 Answer §6。见 票 04。
• 2026-09-11 票 05 resolved（Bruno 文档对齐）：契约对账脚本 bruno-audit-t05.py 三种行形态并集提取（表格首列/页签名列/内联正文——窄正则漏 9 个 detail-head/follow/archive 族端点）→ 85/85 零缺零余 PASS（418 generated + 50 folder.bru，60 钥匙多副本=多 tag 设计）。三项裁决按 ADR-0024 原型树落地：战略协议 @Tag→「客户详情/战略协议」迁 5 .bru；联系人导入 @Tag→「联系人/联系人导入」迁 6 .bru（均字节不动 move + 空壳删）；A4-N 编号前缀不动（跨域一致）。focusFlag 9 处 patch（三份 workspace .bru × 结构表/示例 JSON/语义句，示例值=E2E 实测）。verify 复对账 PASS + BOM=0 + 可联调抽查（战略协议示例值为推导值非真值记档——无 E2E 覆盖）。git 不动：文档仓 M3+D11+??11（A5 区既有变更与本票无关）；后端仓 2 行 @Tag 注释级。见 票 05。
• 2026-09-11 票 06 resolved（收官移交，全图 DONE）：e2e-report 增 §九移交增章（复跑台账/Bruno 对账/验收增量五点/亲手指北 §9.4，§八旧 D:\ 路径以本章 E:\ 为准）；API-SUMMARY 零漂移复核 PASS（§2.1 focusFlag + §2.12 必填前移 + 85 端点对账）；文档盘点 CONTEXT.md/ADR 均不动（纯字段级变更，票 05 遵循既有 ADR-0024）；发版 jar 复用票 04 产物（其后仅 2 行 @Tag 注释级差异，发版正确时点 = 用户提交后重建，清单已注）；发版清单 + 验收指北落 handoff-2026-09-11.md（scp → restart.sh → acceptance-probe + focusFlag 新鲜度手验）。全图终态：01–06 全 resolved，Destination 五条全达成；双仓 git 留用户审查提交。 见 票 06。

Not yet specified

• 票 03 审计产出的 P0/P1 修复票 已消雾（票 03）：P0=0；P1 仅 1 项（导入预检必填前移）已当轮修复并过 /code-review，无需 Augment 新票；P2×6/P3×6 记档于 gap-report（验收可翻案）。
• 「页面 → 端点/字段/交互」映射表 已产出（票 03）：mapping-a4-pages.md + 三份矩阵 + gap-report 四件套。
• （fog 逐票追加）

Out of scope

• D-G1 后端修复 — 用户拍板豁免（2026-09-10）：文档写清语义 + 前端 reveal+明文替代；若翻案需重开 grilling。
• 真实 Vue 前端仓实现 — demo 即前端参考实现，Vue 仓由前端团队按 Bruno 文档另做。
• 测试环境发版操作本身 — SSH 凭据在用户侧；本图交付发版移交清单（scp jar → restart.sh → 探针复验）。
• A2 线索 / A3 商机等其他域的对照与文档结构 — 本图只管 A4 客户域与前端反馈涉及的共享端点。

票与依赖图

01 (task: workspace「是否关注」字段) ─┬→ 02 (task: 主 demo 单入口收编) ─→ 03 (task: A4 逐页对照审计) ─┬→ 04 (task: E2E 全量复跑) ──────┐
                                      │                                                              └→ 05 (task: Bruno 文档对齐) ──┼→ 06 (task: 收官移交)
                                      └───────────────────────────────────────────────────────────────────────────────┘（01 也是 05 前置）

Frontier：无 — 全图收官（01–06 全 resolved，2026-09-11）。后续动作见 handoff-2026-09-11.md：用户审查提交 git → 亲手验收（e2e-report §9.4）→ 测试环境发版。