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.
152 Commits
1 Branch
0 Tags
446 MiB
 
 
 
 
 
Tree: a6c9609918
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'a6c9609918'
${ noResults }
crm-backend-matt/.scratch/customer-contact-graph/map.md

7.6 KiB
Raw Blame History

Map: 客户联系人图谱与联系人页签整节落地（A4-4-2 §6 全量）

wayfinder:map created: 2026-09-09

Destination

A4-4-2 联系人页签第 6 节需求全量落地并验收：6.4 联系人图谱（职务层级自动布局 + 公司节点 + 编辑器全套 + 持久化）+ 6.1 查询展示（脱敏点击明文 + 查看埋点）+ 6.2 快速添加 + 6.3 页内编辑 + 联系人导入三段式 + 职务/来源字典前置。终点 = 测试环境（ai.itc.vip/crm-api）亲手验收 + 两件套交付（Bruno 增量同步 + e2e-report）。

Notes

范围拍板（chart grill 2026-09-09，四问）

  1. 目的地 = 全链落地可验收（非 spec 冻结 / 非 POC）：图里装执行（task 票串行链，对齐 customer-module / customer-e2e 先例），终点落在测试环境人工验收。
  2. 随行项全部进图：图谱本体 + 职务二级联动选择器 + 字典前置（job_title 标准职务预置 + contact_source 分组，顺手销 W-01）+ 联系人导入三段式（当初票 06 约定「随图谱 effort」）。
  3. 列表侧增强也进图（A4-4-2 §6 整节）：6.1 查询展示 / 6.2 快速添加 / 6.3 页内编辑。脱敏口径拍板（用户）：不搞三档权限——所有人默认脱敏显示，页面点击临时明文，明文查看行为埋点记录（谁/何时/哪个联系人号码）。此拍板替代当初客户 E2E 划出的「三档脱敏」，仅适用于联系人电话，不自动扩展到其他域。
  4. 验收底盘 = 对齐 customer-e2e 先例全套：API E2E 增量套件 + demo Playwright 冒烟（含图谱编辑器交互）+ Bruno 文档同步 + e2e-report 聚合。

需求权威与底稿

  • 原型需求文本全量在案：.scratch/opportunity-bugfix/lanhu-pages/A4-4-2_客户详情（联系人）.md —— u533 = 6.1/6.2/6.3 列表侧需求、u536 = 6.4 联系人图谱 15 条完整需求（生成规则/公司节点/未识别层级/卡片悬停气泡/编辑模式/多父连线/系统边删除持久否决/循环检测/并发冲突/保存重置/验收标准）。判定纪律沿用：原型第一 > spec > 问用户。
  • 存量占位：CustomerContact 实体已有 job_title_name / job_title_id / job_title_category / job_title_level 四列（customer-module D5 留位，注释「图谱用」）；customer_module/map.md D5 = 图谱划出决策原文。
  • 导入先例：客户导入三段式（CustomerImportExecutor：template/preview+confirm/result + Analyzer 预检 + fail 明细 + clip500）；联系人导入对齐此形态，复用深度由票 01 定。
  • 契约权威：.scratch/customer-module/API-SUMMARY.md（73 端点）；新端点须增量登记并过 ADR-0017 纪律（flat 动词 + 查询参数传 id，禁 @PathVariable/PUT/DELETE/@RequestBody）。
  • 前端形态：本仓交付 = 后端 + 单文件 demo（.scratch/customer-e2e/demo/index.html 同款纪律，当前 961 行）；真实 Vue 前端另仓另人，demo 即参考实现。

环境事实（2026-09-09 实探）

  • 测试环境 https://ai.itc.vip/crm-api：jar 已含 rework+defectfix 最新构建；verify profile debug token 可用（GET /api/auth/debug/token?userId=739564171091247104）；数据 mine 15 / pool 3；contact_source 字典 0 项 = W-01（本图销号）。
  • 本地起服先例：verify profile + CRM_MINIO_AK/SK；Maven 增量陷阱（先删 fat jar）；E2E 解释器 py -X utf8；Playwright .scratch/customer-e2e/.venv10（chromium 已缓存）。
  • 新表（边/查看日志/导入表）走 ddl-auto: update 自动建（共享库加表不加列，无 DDL 票）；注意孤立单大写字母 @Column 陷阱（AGENTS.md 规则）与 UTF-8 BOM 纪律。
  • 跨模块缝合（crm-customer ↔ crm-dict 字典、联系人增强触碰脱敏口径）：按惯例 ADR + CONTEXT.md 双文档化（票 03/04 落点）。

默认技能

  • /prototype — 票 00 原型 demo（验证需求理解，单文件 mock）
  • /webapp-testing — 票 00 自检截图 / 票 08 demo Playwright
  • /grilling + /domain-modeling — 票 01 spec 冻结（HITL，一次一问，以票 00 demo 为活参照）
  • /bruno-sync — 票 09 文档同步（动手前先读 skill 机制 + bruno-sync.config.json）

Decisions so far

  • 2026-09-09 改序（用户）：先原型后 spec——新票 00 原型 demo（纯前端单文件 HTML + mock 数据，零后端依赖）插到最前，验证对 u533/u536 的需求理解；图谱全量 + 列表侧关键交互都进。验收通过 → 该原型升格为正式 demo 底座（票 06 改为「接真实后端 API」不重写）；理解偏差 → 改原型不进代码。票 01 spec 冻结改为「demo 验收后继续」，届时以 demo 为活参照（原型里 mock 实现的规则 = grilling 素材）。

Not yet specified

  • 图谱渲染形态细节（SVG vs 绝对定位 DOM 卡片、缩放/拖画布实现）— 票 06 现场定，不阻塞 spec。
  • job_title 层级分档映射细则（原型职务集 → 层级档位的枚举与联动规则）— 票 01 spec 定。
  • 自动生成边的增量语义（职务修改后全量重建 vs 差异更新；与手动边/否决记录的合并算法）— 票 01 定框架、票 03 落地时细化。
  • 联系人导入表复用深度（复用 customer_import_* 形态 vs 独立 contact_import_* 表）— 票 01/05 定。
  • 图谱规模上限（单客户联系人可达数百；布局引擎与全量读端点的规模预案）— 票 01 记录、票 03 验证。

Out of scope

  • 节点展开/折叠、联系人搜索与节点定位 — 原型 6.4 第 6 条明说「本期暂不支持」。
  • 跨客户人脉关系 — 原型 6.4 第 1 条明说「不展示跨客户关系」。
  • OCR 快捷新增 — customer-module D5 划出，未随行进图（按钮占位照旧）。
  • 商机域 A5-1-2-2「生态关系图谱」 — 商机域独立特性，与本图无关。
  • 真实 Vue 前端仓实现 — demo 即前端参考实现；Vue 仓由前端团队按 Bruno 文档另做。
  • 其他域的脱敏策略 — Q3 拍板仅限联系人电话；三档脱敏原决策不复活。

票与依赖图

00 (task: 原型 demo 验证理解) ─→ 01 (grilling: spec 冻结，以 demo 为活参照) ─┬→ 02 (task: 字典前置) ─┬→ 03 (task: 图谱后端) ─┐
                                                                        │                        ├→ 04 (task: 联系人增强后端) ─┼→ 06 (task: demo 接真实 API) ─┐
                                                                        │                        └→ 05 (task: 联系人导入) ────┤                        ├→ 08 (task: UI Playwright) ─┐
                                                                        │                                                       └→ 07 (task: E2E API 套件) ┘                            ├→ 09 (task: Bruno+报告)
                                                                        │                                                                                                              │
                                                                        └──────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ (07 也是 08/09 前置)

Frontier：票 00 原型 demo（唯一可取票）。