# 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](issues/01-workspace-focus-field.md)。 - **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](issues/03-a4-prototype-audit.md)。 - **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](issues/02-demo-single-entry.md)。 - **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](issues/04-e2e-full-rerun.md)。 - **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](issues/05-bruno-docs-align.md)。 - **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](issues/06-handoff-acceptance.md)。 ## 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）→ 测试环境发版。