crm-backend-matt/.scratch/customer-rework/map.md

# 客户模块验收返工 · map

- **Status:** charted
- **Destination:** crm-customer（含 crm-rule 客户部分、crm-preference 平台扩展、crm-opportunity 偏好接线）接口风格/文档规范/三形态偏好全面对齐项目规范与蓝湖原型；已知缺口修复；双镜头全量复核；重测通过；规范沉淀进 AGENTS.md；`.scratch/customer-module` 文档同步。**执行含在图内（用户覆写 plan-only 默认）**。
- **上游图:** `.scratch/customer-module/map.md`（spec 图 D1–D29 冻结，仅增补；实施结论见 `HANDOFF-2026-09-03.md`）
- **Charted:** 2026-09-05（7 轮 grilling，用户逐项拍板）

## 决策（R1–R11）

| # | 决策 | 依据 |
|---|---|---|
| R1 | 返工图独立目录 `customer-rework`，执行含图内：票直接改代码 + 同步更新 `.scratch/customer-module`（map 增补决策条目 + API-SUMMARY 重写 + HANDOFF 新篇）+ 重测 | 用户：改的同时同步更新、检查重测 |
| R2 | 规范沉淀 = AGENTS.md 新增「新模块接口接入 checklist」一节，内链 ADR-0017/0024 作依据；不开新 ADR | 病灶是"规范存在但实现会话没读"，checklist 必须挂在 agent 必读处 |
| R3 | 接口风格全量统一：crm-customer 全部端点 + crm-rule 客户提醒端点 → 扁平动作动词（参照 lead/opportunity：零 PathVariable、零 PUT/DELETE、写全 POST form、读 GET 查询参数）；`PUT /api/rule/customer/reminder` 的 `@RequestBody` 一并消灭（全仓唯一 ADR-0017 违规） | lead+opportunity 全仓 grep 实证；项目风格本就非严格 RESTful；模块未联调是零成本窗口 |
| R4 | bruno-sync 全链：config `sourceRoots` 加 crm-customer；menuBindings 补 A4 五菜单（公海/总览/我的客户/交割/联系人）+ A7 客户规则；全部 controller 深 tag 对照 v29 原型树重挂（一级=`A4 客户管理` 原文，非 `A4-2` 编号式）；`CustomerPingController` 保留端点不挂页签 | ADR-0024 修订纪律；`lanhu-tree-v29.md` 权威树 |
| R5 | 三形态后端边界：列偏好（字段设置）接平台 `/api/preference/get\|save`，客户 4 个 scopeKey（`customer.overview/mine/pool` + `contact.list`），固定列校验归前端（与线索一致）；分屏右侧复用既有详情聚合接口，公海"普通销售视角"= 前端按权限点裁剪页签，后端不加裁剪专用端点；看板对 `pool` 后端直接拒绝（67001/67004 口径），tags 只挂总览+我的客户 | 原型 a4-2-1/a4-3-1 三视图规则段；公海无看板（a4-1-1 L803）；商机范式 |
| R6 | 形态偏好（list/split/board 持久化）= crm-preference 新建 `user_view_form` 表（UNIQUE(user_id, scope_key)，view_form 枚举白名单）+ `ViewFormController`（`GET /api/preference/view-form/get` + `POST /api/preference/view-form/save`，form 绑定）；未设置→前端默认 list | 用户翻案：需求要存用户上次偏好，后端需要处理；方案 A |
| R7 | 商机模块偏好一并开发（参考线索）：列偏好 3 个 scopeKey（`opportunity.sales/manage/public_pool`，与 saved-view `opportunity.sales` 对齐）+ 形态偏好接入新平台端点；商机侧零新端点，只加常量 + 平台 tags 双归属 | 用户：加上商机的偏好，参考线索模块 |
| R8 | 已知缺口处置：**补** 查重设置页端点（`GET/POST /api/rule/customer/dedup`，风格统一后形态）+ QuickCreateDTO 加 `confirmSimilar` 透传；**修** 公海看板越范围（见 R5）；**维持划出** 客户导出、联系人导入（范围外记档，不翻案） | 用户拍板 Q6 |
| R9 | 全量复核 = 双镜头：① 规范镜头（AGENTS.md 新 checklist + ADR-0017/0024/0023 扫全部端点：风格/tags/Param-DTO/分页规范/错误码段位）；② 原型镜头（A4 全部 50 页 + A7-3-3 两页，三列表：接口存在性/语义正确/风格合规）。差异清单归并成票 | 用户："我相信还有很多问题" |
| R10 | 验收线：三模块（crm-rule/crm-customer/crm-opportunity）`mvn test` 全绿；冒烟脚本重跑全链 code=0（复用 smoke 范式，改新 URL）；bruno-sync 产出落 `E:\code\crm-api-docs` 且 A4 目录树对齐 v29 树、knife4j 分组同构；BOM 扫描 clean；`.scratch/customer-module` 文档同步完成 | 用户拍板 Q7 |
| R11 | 跨模块依赖走 Java service（商机→客户），HTTP 契约变更无连锁；前端尚未联调客户模块，URL 重塑零外部成本 | HANDOFF 3.6 实证 |

## Decisions so far

- [01 · AGENTS.md 沉淀「新模块接口接入 checklist」](issues/01-ag-checklist.md) — checklist 已落 AGENTS.md「Coding standards」区（六条 + 内链 ADR-0017/0024 + 踩坑一句话）；`.scratch/customer-module/map.md` 已增补出处指针。

- [02 · 端点风格全量统一（55 + 1 个端点）](issues/02-style-unify.md) — 8 Controller 26 端点重写为扁平动作动词+查询参数（workspace 进 Param DTO）；crm-rule 提醒规则 PUT+@RequestBody→POST /save 表单绑定，全仓唯一 ADR-0017 违规消灭；验收 grep 零命中 + mvn test 绿（rule 146 / customer 133）。


- [03 · 公海看板后端拒绝](issues/03-board-pool-close.md) — 已实施：board summary/cards 对 pool 拒 67001（用户两轮澄清定案：卡片视图在总览/我的客户，公海无）；+2 用例，customer 135 绿。中途一次误翻案已全额回滚（详见票内记账回滚记录）。

- [04 · 已知缺口：查重设置页端点 + QuickCreate.confirmSimilar](issues/04-gap-fixes.md) — crm-rule 从零建 `customer_dedup_rule` 单例栈（票面"复用既有单例"前提过时）+ confirmSimilar 透传（needConfirm 口径）；RuleBacked Provider @Primary 消费（D4-rev2），精确/模糊驱动 DedupService 分支；rule 152 / customer 144 绿，§5 两条销账。

- [05 · 平台形态偏好：user_view_form + 端点，客户/商机双接入](issues/05-view-form-platform.md) — crm-preference 新平台能力（对称列偏好范式，白名单平台校验 68xxx 新段）；客户 4 + 商机 3 scopeKey 常量接入，零业务新端点；tags 双归属 A4×4 + A3×3；preference 23 / customer 144 / opportunity 242 绿；D30 增补。

- [06 · 列偏好 scopeKey：客户 4 个 + 商机 3 个 + 平台 tags 双归属](issues/06-column-pref-scopes.md) — 客户/商机 COLUMN_SCOPE 常量块（对称 LeadConstants 注释写法）+ ColumnPreferenceController tags 扩三域归属（A2×4 + A4×4 + A3×3）；零新端点零逻辑变更，三模块测试维持绿。

- [07 · 深 tag 重挂 + bruno-sync 全链接通](issues/07-tags-bruno.md) — 11 Controller 深 tag 落地（grep 零残留）+ config/local 齐 + 文档仓全量对账收敛（309 钥匙=309 文件，new/delete/冲突全 0）；A4 树与 v29 七节点对齐、编号式绝迹；54 旧文件 + 10 空壳目录清理，全部可解释。

- [08 · 双镜头全量复核（规范 + 原型）](issues/08-audit-prototype.md) — audit-findings.md：镜头一五项全绿 + S1 错误码 64018 双绑；镜头二四种子收口 + 7 差异项（机械修 S1/F3，需决策 F4-F10）；09 票范围已回填。

## 范围外（Out of scope）

- 客户导出（原型有规则，维持 D2 划出，涉及脱敏口径，量级独立）
- 联系人导入（维持 D5 划出，随图谱 effort）
- 客户查重/合并（A4-6，维持划出）
- OCR 快捷新增（a4-3-3-3/4，维持划出）
- 敏感信息三档脱敏/查询日志（维持划出）
- 线索模块列偏好实际接线（scopeKey 常量已有，"预留未接线"维持现状）

## 票与 blocking

```
01 ag-checklist ──┬──> 02 style-unify ──┬──> 03 board-pool-close ──┐
                  │                     └──> 04 gap-fixes ─────────┤
                  │                                                 ├──> 08 audit ──> 09 audit-fixes ──┬──> 10 regression
                  │   05 view-form-platform ──┬──> 07 tags-bruno ──┤                                  │
                  │   06 column-pref-scopes ──┘                    │                                  │
                  └───────────────────────────────────────────────┘                11 docs-sync <────┘
```

- 01 是全部票的前置（checklist 是复核依据）
- 07（tags+bruno 产出）依赖 02（URL 定型）+ 05/06（scopeKey/viewType 定型才能写 menuBindings）
- 08（复核）依赖 02–07 全部已知修复完成后再审，避免复审已知问题
- 09 内容待 08 产出差异清单后回填
- 10/11 收尾并行

## 参考索引

- 原型树权威：`.scratch/api-docs-reorg/lanhu-tree-v29.md` A4/A7 段
- 原型缓存：`D:\code\crm-需求梳理\lanhu-mcp\data\axure_extract_bade4454_screenshots\`（`.txt` 为主，OCR 兜底）
- 风格参照：`crm-lead/.../controller/LeadController.java`、`crm-opportunity/.../controller/*.java`
- 平台参照：`crm-preference/.../ColumnPreferenceController.java`、`SavedViewController.java`、`UserColumnPreference.java`（表范式）
- 规范：`docs/adr/0017-*.md`、`docs/adr/0024-*.md`；`.scratch/controller-io-conventions/spec.md`
- 旧图冻结文档：`.scratch/customer-module/{map.md, API-SUMMARY.md, HANDOFF-2026-09-03.md}`
- bruno-sync skill：`C:\Users\luowj\.pi\agent\skills\bruno-sync\SKILL.md`；产出仓 `E:\code\crm-api-docs`