crm-backend-matt/.scratch/customer-contact-graph/issues/03-graph-backend.md

03 · 图谱域后端实现

• Type: task
• Status: resolved
• Blocked by: 01, 02

Question

按 spec 实现图谱域后端（crm-customer）：

1. 边表实体 + Repository（含系统边否决 tombstone 语义；孤立单大写字母 @Column 陷阱自查）。
2. 自动生成引擎：job_title_level → 层级布局 + 系统边生成（多顶层并列/同级并列/未识别层级区/公司节点虚拟位），职务修改后按 spec 语义增量更新。
3. 端点：图谱读（全量节点+边+布局）/ 边 add / 边 delete / 布局 save；校验自连/循环/重复（错误码按 spec）；并发冲突检测；保存成功记关系变更日志（是否扩 oplog 值域 17→N 种按 spec）。
4. 明文查看 reveal 端点 + 查看日志表（若 spec 划入图谱票则此处做，否则归票 04）。
5. 单测：循环检测 / 层级排列 / 多父 / 否决持久化 / 冲突。
6. ADR + crm-customer/CONTEXT.md 双文档化（图谱契约 + crm-dict 缝合点）。

验收：mvn -pl crm-customer -am test 全绿；本地起服 curl 冒烟（建边→读图谱→删边→否决复验）。

Answer

resolved 2026-09-10。spec D6「只有手动边」作废票面第 1/2 条的系统边 tombstone / 自动生成引擎假设，实现以 spec 为准（ADR-0037）。落地清单：

• 表：customer_contact_edge（uk_edge_pair 三列唯一 + idx_edge_customer，无软删快照语义）+ customer_contact_graph（版本行，执行拍板 id PK + uk_graph_customer 唯一索引，替代 spec 草案 customer_id PK——BaseEntity 雪花主键零例外）+ customer_contact.level_source 列（tinyint not null default 1）。
• 错误码顺延执行拍板：spec 草案号位 67017 已被战略协议 CODE_AGREEMENT_INVALID 占用 → 67018 版本冲突 / 67019 边非法 / 67020 结构校验。
• 端点：GET /api/customer/contact/graph/detail?customerId= + POST /api/customer/contact/graph/save（ADR-0017 纪律；深 tag「A4 客户管理/客户详情/联系人图谱」三级；嵌套表单 indexed 绑定）。
• 校验链执行拍板（集成测试红转绿驱动）：等级调整约束（67020）先于边校验（67019）——「撤级但留边」报「先取消全部连线」而非「端点未定级」；首定级豁免（原 null→X 不受调整约束，先定级后连线是正常流程）；撤级 null 走 LambdaUpdateWrapper 显式 set（MP updateById NOT_NULL 默认策略跳过 null 字段，同 CustomerOwnershipWriter 坑）；无环由单父 + 严格递减数学保证免 DFS。
• 联动（D9）：联系人 create 后 bumpVersion；delete 前级联物理清边（physicalDeleteByContact）+ bumpVersion。版本 CAS 走 ContactGraphVersionWriter 显式 SQL。
• 测试：CustomerContactGraphIntegrationTest 12/12 + 既有全回归，crm-customer 全模块 198 例全绿；BOM 扫描干净（13 个图谱相关文件）。
• 文档：ADR-0037 + crm-customer/CONTEXT.md（新增「联系人图谱」词条，「联系人」「H2 测试 schema」词条随动）。
• 验收口径执行拍板：票面「否决复验」已随 D6 作废；起服 HTTP 冒烟归票 07 E2E 套件（单测已等价覆盖校验链全部分支）；reveal 明文端点与埋点表（spec §2.4）归票 04。