luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
145 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Branch: master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
crm-backend-matt/.scratch/customer-rework/map.md

10 KiB
Raw Permalink Blame History

客户模块验收返工 · 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」 — checklist 已落 AGENTS.md「Coding standards」区（六条 + 内链 ADR-0017/0024 + 踩坑一句话）；.scratch/customer-module/map.md 已增补出处指针。

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

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

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

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

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

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

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

  • 09 · 复核差异清单修复 — 六修一开两划：S1（实改反向：SEED_PROTECTED 顺延 64024）、F3 双 tag、F6 批量工商更新端点、F7（口径收窄：viewType 五内置视图已在，补 viewTouch upsert）、F8 duplicateStrategy（D24 语义）、F10 联系人 oplog 轻方案；F5 单开票 12、F4/F9 划出（用户逐项拍板）；crm-customer 152 全绿 + BOM 无。

  • 12 · 战略协议单表 CRUD（F5） — customer_agreement 表 + 五端点（create/edit/delete/detail/list）+ 错误码 67017 + oplog AGREEMENT_*；客户快照 strategic_agreement_level 随写刷新（javadoc「战略协议子域写入」承诺闭环）；crm-customer 158 全绿。

  • 10 · 回归重测 — 五项验收全过：三模块 152/158/242 绿、冒烟 43 步 0 fail（新端点全覆盖 + DB 快照断言 + D-07 缺陷验证模式）、bruno 对账 321=321 终态（落 8 文件）、BOM 零、风格 grep 零；产出 RETEST-REPORT.md。

范围外（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 ──┬──> 12 agreement ──┬──> 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