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

# Map: 客户模块后端 spec（crm-customer / crm-rule 客户规则）

> **⚠ 2026-09-05 验收返工已收官**：本图 D1–D29 冻结（spec 阶段已 resolve），验收发现的实现偏差（接口风格/tag/三形态偏好等）已由返工全部修复。返工决策与票见 **`.scratch/customer-rework/map.md`**（D1–D29 只增补不推翻；增量索引见本图末尾「返工增补」节）。

`wayfinder:map`

## Destination

一份可交接的后端规格说明书（spec），描述"客户(Customer)"域的后端设计，交给实现方（人或 agent）落地——对称商机地图（`.scratch/opportunity-module/`）的产出形态：**spec-only（只出决策 + 契约 + 领域模型，不写实现代码）**，做完后进 `/implement` 阶段。

- **`crm-customer`（新建模块）** — 客户业务域：客户主表 + 归属流转（有主/公海 + 交割换主）+ 客户阶段（潜在→重潜→已成交，只前进）+ 三 workspace（客户总览 / 我的客户 / 客户公海）+ 内置视图 + 自定义视图（复用 crm-preference）+ 新增/编辑（含查重校验 + 企查查工商回填 seam）+ 客户导入 + 客户详情 8 页签 + 跟进记录 + 操作日志 + 客户交割（跨模块同步商机/项目负责人）+ 联系人 CRUD + 全局搜索。
- **`crm-rule`（客户规则族，新增第三族）** — 后台"业务规则"下线索/商机/客户三族并列。客户规则本图**只做「超期未跟进提醒」**（全局单例配置，非版本化）。

> ⚠️ **待复核**：本 spec 已由用户在 grill Q1–Q19 拍板冻结，但用户要求 “换一个新会话独立复核”。**请先读 `REVIEW-HANDOFF.md`**（含我最担心的 9 个薄弱点 + 5 个我可能漏问的点），再逐条挑战 D1–D29，不要因为 map 里写了“已拍板”就跳过。

### 原型出处（蓝湖缓存，已本地提取）

- 主文档 `bade4454-52aa-44db-8ba2-dec594732ecb`（`【原型】itc信息化业务中台web端 V1.0`）。
- 截图/文本缓存目录：`D:\code\crm-需求梳理\lanhu-mcp\data\axure_extract_bade4454_screenshots\`（每页 4 文件：`.png`/`.txt`/`_annotations.json`/`_styles.json`；`.txt` 为主）。
- A4 客户模块页族：`a4-1 客户公海` / `a4-2 客户总览` / `a4-3 我的客户+新增+导入+OCR` / `a4-4 客户详情(8页签)` / `a4-5 联系人` / `a4-6 客户查重+合并` / `a4-7 客户交割`。规则侧 `a7-3-3 客户管理设置`。
- **前置依赖分析已存在**：`.scratch/opp-customer-dependency/商机模块前置客户接口依赖分析报告.md`（商机侧硬依赖的客户接口：`POST /api/customer/search` / `GET /api/customer/{id}/contacts` / `GET /api/customer/{id}` 等）——客户模块的一个已知锚点切片。

## Decisions so far

<!-- chart 期先行拍板（grill 定名阶段）；逐题底稿见对应 issue -->

- **[D1] 目的地形态 = spec-only，对称商机图** — 只产出决策/契约/领域模型，不写实现代码；做完进 /implement。（chart grill Q1）

- **[D2] 作用域三档划分（chart grill Q2 + Q4 修正）**：
  - **① 本图覆盖**：客户核心（实体+查重校验+公海+总览+我的客户+三视图+新增/编辑+导入+详情8页签(关联商机读 crm-opportunity✅)+跟进+操作日志）、联系人（CRUD+全局搜索）、客户交割、客户规则族「超期未跟进提醒」。
  - **② 依赖未建 A5 项目模块 → 留 seam**：客户阶段「已成交客户」（由项目中标驱动）本图只做到「潜在→重潜」；「关联项目」详情页签划出。
  - **③ 自成子域/复杂特性 → 划出本图**（Not-yet / Out-of-scope 记一笔）：战略协议（A4-4-9/10）、联系人图谱（职务二级联动+人脉连线）、**客户查重列表+客户合并（A4-6，grill Q4 拍板不做）**、企查查/OCR 外部服务（只定契约 seam，不深挖服务内部；OCR 快捷新增划出）。

- **[D3] 客户双轴建模（chart grill Q3）** — 对称商机双轴但两轴都更简单：
  - **轴1 归属**：**不做显式 tinyint 状态机**，改用两个正交维度：① `owner_user_id`+`owner_dept_id`(快照) 是否为空 = 有主/在公海（公海=owner 空的逻辑视图，对称商机公海）；② `archive_status`(有效1/已归档2) 独立字段，**已归档=删除语义**（软删，用列表筛选条件承载，默认排除已归档，加筛选可查）。迁移动作 = 领取/分配/抛公海/交割(换主)/归档。
  - **轴2 阶段**：主表 `customer_stage`(潜在1/重潜2/已成交3) 单字段，**只增不减、不可配置**（硬编码三态，非商机版本化模板），由外部成功结果驱动。本图定义完整三态字段与只前进 CAS，但**本期两个跃迁均 seam 化不自动触发**：潜在→重潜 由「方案卡提交并报备成功」驱动，报备成功链路本期不可达（D20 改票 B，留 seam）；已成交由 A5 项目中标驱动，A5 未建（留 seam）。**本期客户阶段实际只有「潜在」**。

- **[D4] 客户规则落 crm-rule + 全局单例形态（chart grill Q4）** — 客户规则族作 crm-rule 第三族（线索/商机/客户并列）。本图**只做「超期未跟进提醒」**（全局单例配置：总开关 + 首次触发天数(默认30) + 二次提醒间隔(默认7)；定时任务 + 钉钉/应用内通知），**不套 V-CONFIG 版本化**（区别于商机规则）。**「客户查重设置」不做**（A4-6 查重执行侧不做，查重口径写死在新增流程）。

- **[D4-rev1] 客户规则族范围修正（grill Q6，用户拍板）** — 客户规则族只含**两族**：`超期未跟进提醒`（票 10）+ `客户查重设置`（票 04 从「写死」改为**后台可配置**，全局单例形态待 Q7）。**星级设置、客户阶段设置不在客户规则族** → 星级退回硬编码枚举 1~5（票 02 原判），客户阶段退回硬编码三态只前进（票 05 原判）。a7-2-3 里那两页（星级/阶段设置）属于其他族/其他 effort，本图不消费。

- **[D4-rev2] 客户查重设置的消费范围（grill Q7，用户拍板 B）** — 客户查重设置做成 crm-rule **全局单例可配置**，本期**只消费于「新增/编辑的内建查重」**（票 04：信用代码硬拦 + 名称相似弹窗改用配置里的匹配方式+相似度 70/80/90%，替换「写死」）；**A4-6 查重页留作未来消费者**，本期不做扫描全库/合并。规则字段：总开关、规则组合(任意命中/全部命中)、客户名称(精确/模糊+相似度)、统一社会信用代码(精确)、联系电话(精确)。

- **[D5] 联系人建模（chart grill Q5）** — **联系人 = `crm-customer` 下独立实体表 `customer_contact`**（不单开 crm-contact 模块）；每个联系人 `customer_id` 必属一客户（无孤立），权限继承所属客户（联系人无独立 ACL）。**本图做**：联系人 CRUD（列表/详情/新增/编辑）+ 随客户新增内嵌明细 + 全局搜索接口（商机硬依赖）+ 联系人电话查重。**本图不做**：职务二级联动图谱、人脉关系连线、OCR 快捷新增、联系人导入。职务字段先存「职务名称文本 + 可空 标准职务id/类别/层级」三列占位，不实现联动选择器逻辑。

- **[D6] 新增客户查重口径（chart grill Q4-补）** — 新增/编辑客户的**查重校验做**、内建新增流程：① 统一社会信用代码全局唯一（硬拦），② 客户名称相似→保存时确认弹窗（可"仍要创建"）。查重阈值/口径**写死**，不做后台可配。A4-6 独立查重页 + 客户合并**不做**。

- **[D7] 客户主表字段清单已定稿（票 02 resolved）** — 建 `crm-customer` `customer` 主表，字段分八区：系统字段(BaseEntity)/系统生成(`customer_no`)/基本信息(名称·类型·省市区三级·行业两级·星级×2·人脉关系单位JSON)/归属(owner_user_id+owner_dept_id快照·名快照)/轴2阶段(`customer_stage`)+档案状态(`archive_status`)/快照冗余(`last_valid_follow_time`+战略协议等级+VIP等级)/关联信息(父子客户·总裁班·合作系统)/工商信息(企查查9项+`unified_credit_code` UNIQUE)/补充资料(remark+附件子表)。**无孤立单大写字母陷阱，全表无需 `@Column(name=...)`**。`@DataScope(module="customer", ownerColumn="owner_user_id", deptColumn="owner_dept_id")`。索引：uk_credit_code/idx_owner_stage/idx_dept_stage/idx_name/idx_parent/idx_last_follow。**✅ 已定**：`customer_type` = crm-dict 字典分组 `customer_type`，种子 18 值（见 D18）；行业选二级(与商机图D1一致)；星级用枚举1~5不走字典(硬编码)。详见 `issues/02`。

- **[D8] 客户超期未跟进提醒已定稿（票 10 resolved）** — 三层对称商机「回收提醒」范式但配置形态单例：①`crm-rule` `customer_reminder_rule` 单行表(id固定=1，全局单例，非版本化)存总开关+首次触发天数(默认30)+二次提醒间隔(默认7)+各自独立开关；②`crm-customer` `customer_pending_notice` 待发通知表(UNIQUE(customer_id,notice_type,plan_notify_time)幂等)；③`CustomerReminderJob`(@Scheduled cron 默认凌晨4点)只落待发不直接发(平台通知spin-out)。**提醒链确定性**：plan = anchor + firstTriggerDays + k×secondIntervalDays。锚点=`last_valid_follow_time`（**锚点 = 成为「有主」的时刻**：新建即指派=create_time；公海客户被领取=领取时刻；每次跟进刷新）。公海(owner空)/已归档不参与（合并态已按 D19 取消）——公海 `last_valid_follow_time=NULL` 不计时不提醒，领取时赋锚点。**「规则在客户新增时生效」= 新建即指派时初始化 last_valid_follow_time=create_time**。详见 `issues/10`、`issues/02`、`issues/07`。
- **[D18] 客户类型字典已定稿（grill Q8，用户拍板）** — `customer_type` 落 **crm-dict 字典分组 `customer_type`**（非硬编码枚举），种子 18 值：运营商、土建总包、机电总包、装修总包、教育局、投资（代建）公司、设计院、集成商、集成商（子客户）、咨询造价公司、甲方（企业用户）、甲方（普教）、甲方（中高职）、甲方（政府机关）、竞争同行、个人用户、操手、招标代理。注意含 4 个「甲方（…）」值 + 14 个非甲方角色值，证明客户类型 ≠ 仅甲方，是通用角色字典。主表 `customer_type` 存字典值编码（冗余名快照可选），列表/详情按字典名展示。

- **[D19] 归档=删除语义 + 去掉「已被合并」（grill Q9，用户拍板）** — 客户不再有「已被合并」态（合并本就在 Out-of-scope，A4-6 不做，状态值随之取消）。`archive_status` 收敛为 `有效1 / 已归档2` 两值；**已归档即删除**（软删），不做独立 tab/子页，只在列表加一个 `archive_status` 筛选条件：**默认排除已归档**，勾选后查询已归档。总览/我的客户主列表默认只出 `archive_status=1`。票 10 提醒排除条件同步收敛为「公海 + 已归档」。**§5.3 拍板 A（20260902，一期只做归档）**：**不提供任何前端「删除客户」入口**——用户侧只有归档（软删可恢复）+ 合并（源客户系统软删，且合并本体 Out-of-scope）；`deleted` 标志仅系统在合并时置 1，不开放手动删除、无前端删除按钮，DB 不做物理删除。详见 `issues/03`。

- **[D20] 重潜触发本期不实现、只留 seam（grill Q10 拍板 A → 第三轮 fresh 复核翻案，20260902 改票 B）** — **推翻「已提交(2)触发」的临时口径**。最新原型 `a4-4-1`（8-26）明文「任一方案卡**提交并报备成功**后 → 重潜客户」，是**两个条件**（提交 + 报备成功）；而「报备/推送成功」依赖推送链路（spin-out 本期不可达）。据此本期决定：**不自动触发潜在→重潜**，客户阶段实际只有「潜在」；`CustomerStagePort.promote` 的 seam **保留**（契约、CAS 只前进、幂等 全部保留），等报备成功链路（商机方案卡「已推送(3)」或 A5 回调）就绪后再由该链路调用 promote 触发重潜。**不用「已提交」凑合**——避免出现「提交了但报备没成功、客户却已重潜」的错误状态。customer_stage 字段/枚举/三态 CAS 机制不变（D11）。详见 `issues/05`。

- **[D21] 相似判定算法 seam 化（grill Q11，用户拍板）** — 客户名称相似度判定**抽成接口/端口**（`CustomerNameSimilarityPort` 或 `CustomerDedupService` 内可替换策略），一期只做**最简实现**，后续迭代可换算法。一期最简实现 = **MySQL ngram 分词器（token_size=2）+ FULLTEXT `MATCH ... AGAINST` 取候选 + 相似度计算**，全在 MySQL 内完成、不引外部服务；阈值从「客户查重设置」配置读取（70/80/90%）。接口契约稳定，算法实现可插拔，后续可换 Levenshtein / Jaccard / 外部相似度服务而不改调用方。详见 `issues/04`。

- **[D22] 直属销售总监 = 组织架构推导，不改 crm-auth（grill Q12，用户拍板 A）** — **分两种触发场景**：`transfer_reason=离职` → 系统**自动确定唯一**接收总监（按 from_user 所在部门向上找「部门负责人」`dept.leader_user_id` 或等价，该负责人是「销售总监」角色则命中；无/停用/多条直属关系 → 阻断并提示「联系管理员维护组织关系」）；`transfer_reason=岗位调动/区域调整` → **在本人启用的直属销售总监范围内自行搜索选择**（下拉选，**不阻断**）。**不在 SysUser 加 `superior_user_id` 字段**（直属关系是组织属性非用户属性，加字段带来维护/一致性成本）。详见 `issues/08`。

- **[D23] 交接单完成判定 = 自动完成（grill Q13，用户拍板 A）** — 交接单状态「已完成」由自定义判定：`assignedCount == totalCount`（全部待分配明细已分配）时自动置为已完成，**不设总监手动「完成交接」按钮**。每行明细独立分配，最后一行分配完自然触发终态；不引入二次确认状态机。详见 `issues/08`。

- **[D24] 文件内多行匹配同一客户默认「重复时不导入」（grill Q14，用户拍板 A）** — 导入时文件内多行匹配同一客户，`覆盖导入`/`重复时不导入` 互斥，**默认「重复时不导入」**：重复组全部标失败不写入，用户看失败明细处理。覆盖模式（按文件自上而下、最后一条通过校验的为准）作为可选项存在但不默认。详见 `issues/09`。

- **[D25] 超期提醒锚点 = 成为「有主」的时刻（grill Q15，用户拍板 A）** — 修正 D8 锚点语义：`last_valid_follow_time` 锚点在**客户成为有主时**赋初值，**公海不计时不提醒**。① 新建客户**直接指派负责人** → 锚点 = `create_time`（有人负责从建卡起算）；② 新建客户**进公海**（无负责人）→ `last_valid_follow_time = NULL`（无锚点，不提醒），**被领取/分配时 → 锚点 = 领取时刻**，从此重计首次提醒天数。`last_valid_follow_time IS NULL` + `owner_user_id IS NOT NULL` 双保险兜住公海。同步影响：票 02（字段初始化语义）、票 07（领取时赋锚点 + 跟进刷新）、票 03（领取/分配动作后置锚点）。详见 `issues/10`。

- **[D26] 联系人电话查重 = 可配置软提示（grill Q16 用户拍板 B → 第三轮 fresh 复核翻案，20260902 改票 A）** — **推翻「电话全局唯一索引」硬约束**。最新原型 `a7-3-3-2 客户查重设置`（8-26）明示：**统一社会信用代码**是系统强制规则（重复禁止创建、无关闭开关）；**联系电话**仅作「提示疑似重复」，**可被总开关单独关闭**，不禁止创建。据此：① DB **不建** `uk_contact_phone(phone)` 唯一索引；② 电话查重=**可配置软提示**，跟随 crm-rule 客户查重设置单例的「联系电话」开关（默认开）；③ 仅保留**表单级校验**——同一客户内两个联系人电话不得重复（来自票 04 B4 内联查重）；④ 跨客户电话撞号只提示、不阻断。修正 D12「电话全局唯一」旧口径为「电话查重提示」。详见 `issues/06`。

- **[D27] 联系人来源字典 `contact_source` 种子 = 原型 4 项（grill Q17，用户拍板 A）** — crm-dict 字典分组 `contact_source` 种子值：**组会、组局、转介绍、其他**。加值后续在字典补，本期不做额外枚举。详见 `issues/06`。

- **[D28] 汇总卡片占位一律渲染 + 显"--"（grill Q18，用户拍板 A）** — 客户详情 4 张汇总卡片（含 A5 预留的「合同总额·累计回款」）**一律渲染卡片**，无数据源/接口失败时值显 `--`（不显 0，不留白），保持布局稳定；A5 建好后自动接数据。与其他外部模块卡片失败显"--"口径统一。详见 `issues/07`。

- **[D29] 公海列表「进入公海时间」列保留 + 可排序（grill Q19，用户拍板 A）** — 公海列表 `enter_pool_time` 列保留作固定列，且加入票 11 排序字段池（支持升/降序；降序=先进先看）。复用 saved-view 排序机制，成本极低。详见 `issues/03`。

- **[D30] 形态偏好平台化：user_view_form + view-form 端点（customer-rework 票 05 增补，R6/R7）** — 用户上次选择的视图形态（list/split/board）跨会话记忆 = crm-preference 新平台能力：`user_view_form(user_id, scope_key, view_form)` 表（UNIQUE(user_id, scope_key)、无 create_by/update_by，对称 UserColumnPreference）+ `ViewFormController`（`GET /api/preference/view-form/get` null=未设置前端默认 list；`POST /api/preference/view-form/save` 表单绑定）+ 白名单平台校验（68xxx 段新开 `PreferenceConstants.CODE_VIEW_FORM_INVALID`，形态是平台语义值非业务字段池）。客户三页签+联系人（`customer.overview/mine/pool`、`contact.list`）+ 商机三菜单（`opportunity.sales/manage/public_pool`，sales 与 saved-view 同码位）接入 = 业务方只加常量、前端直调平台端点，零业务新端点。tags 双归属 A4×4 + A3×3（ADR-0024）。详见 `.scratch/customer-rework/issues/05-view-form-platform.md`。

- **[D9] 客户三视图/公海/总览已定稿（票 03 resolved）** — 三个 workspace（公海/总览/我的客户）= 逻辑视图，靠 `@DataScope` + `owner_user_id IS NULL` + `archive_status` 过滤区分，不建独立表。内置视图/常用检索硬编码不入库；三视图模式（列表/卡片/看板），看板分组 = customer_stage / customer_star / relation_star。归属迁移动作枚举（领取/分配/抛公海/交割换主/归档）+ oplog + `enter_pool_time`。已归档走 `archive_status` 筛选（D19），无「已被合并」tab；领取/分配动作后置 `last_valid_follow_time` 锚点（D25）。详见 `issues/03`。

- **[D10] 新增/查重/企查查已定稿（票 04 resolved）** — 分层查重（输入相似提示 / 提交精确 / 落库前终检），核心服务 `CustomerDedupService`；信用代码全局唯一硬拦，名称相似弹窗确认。查重口径从「客户查重设置」配置读（D4-rev2）。相似判定算法 seam 化，一期最简 = MySQL ngram FULLTEXT（D21）。企查查 = 外部服务契约 seam（port 占位 + 回填），不深挖服务内部。详见 `issues/04`。

- **[D11] 客户阶段只前进已定稿（票 05 resolved）** — `customer_stage` 潜在1/重潜2/已成交3，硬编码三态、只增不减；迁移用 `UPDATE ... WHERE customer_stage < ?` CAS 只前进。重潜触发本期不实现、只留 `CustomerStagePort.promote` seam（D20 改票 B：等「方案卡提交并报备成功」链路就绪再调用；不用「已提交」凑合）；seam 契约/CAS/幂等保留。已成交由 A5 项目中标驱动，留 seam。详见 `issues/05`。

- **[D12] 联系人 CRUD 已定稿（票 06 resolved）** — `customer_contact`（crm-customer 独立表，权限继承客户，无独立 ACL）；契约含 CRUD + 全局搜索（商机硬依赖 promote）+ 随客户新增内嵌明细。电话查重=可配置软提示、不建唯一索引（D26）；同客户内电话不重复为表单级校验；`contact_source` 字典种子 = 组会/组局/转介绍/其他（D27）。职务字段三列占位不做联动。详见 `issues/06`。

- **[D13] 客户详情/跟进/操作日志已定稿（票 07 resolved）** — 详情页 8 页签骨架（关联项目/战略协议 seam 显 "-"）；跟进 `customer_follow` append-only，跟进刷新 `last_valid_follow_time`；关联商机页签只读反查 crm-opportunity；团队成员页签；操作日志 `customer_oplog` 字段级（对称商机 oplog 范式，「把 {字段} 从 {旧} 修改为 {新}」）；**§5.5 拍板 A（20260902）**：`customer_oplog` **无限期保留**——审计日志不设保留期/清理/冷热分离（原型 L250「日志生成后不可修改或删除」= append-only 审计）。4 张汇总卡片外部模块失败显 "--" + 重试；预留占位卡一律渲染显 "--"（D28）。详见 `issues/07`。

- **[D14] crm-customer 领域上下文已建（票 01 resolved）** — 建 `crm-customer/CONTEXT.md` + `CONTEXT-MAP.md` 加行；依赖方向 `crm-opportunity → crm-customer`（商机反查客户/联系人），crm-customer 不反向依赖商机。详见 `issues/01`。

- **[D15] 客户交割已定稿（票 08 resolved）** — 两段式（发起交接 / 逐条分配）；`customer_transfer` + 明细表，发起时整批原子、分配时每行独立。跨模块副作用：换主同步商机 owner（crm-opportunity），项目 owner 同步留 seam。直属销售总监 = 组织架构推导（D22），完成判定 = 自动完成 assignedCount==totalCount（D23）。`transfer_reason` 字典（离职/岗位调动/区域调整）。详见 `issues/08`。

- **[D16] 客户导入已定稿（票 09 resolved）** — 三种导入方式（仅新增 / 仅更新 / 新增或更新）；匹配顺序 = 客户编号 → 信用代码，不按名称自动覆盖；异步任务模型（预校验/结果页/失败明细），行级部分成功；模板版本校验。文件内多行匹配同一客户默认「重复时不导入」（D24）。契约 `POST /api/customer/import/upload|/{taskId}/confirm`、`GET /{taskId}|/failures|/page|/template`。详见 `issues/09`。

- **[D17] 客户超期提醒规则表 + Job 已定稿（票 10 resolved）** — 见 D8（配置形态/提醒链/锚点）。补充：`customer_pending_notice` 待发通知表（对称 OpportunityPendingNotice，noticeType=OVERDUE_REMIND，notice_status 0待发/1已发/2已失效，payload JSON 含锚点快照）；Job 只落待发不直接发（平台通知 spin-out）；锚点语义按 D25（成为有主时刻）。详见 `issues/10`。

- **[D17b] 客户保存视图接入平台已定稿（票 11 resolved）** — 复用 `user_saved_view` 平台，不新建视图机制；3 个 scope_key（公海/总览/我的客户各一）；`CustomerSavedViewFilter` 字段池（未知字段/操作符跳过）；默认视图互斥继承平台；`enter_pool_time` 加入排序字段池（D29）。详见 `issues/11`。

## Not yet specified

<!-- in-scope fog，随前沿推进 graduate；每张票 resolve 后回到 Decisions so far -->

| 票 | 主题 | 依赖 | 前沿位置 |
|---|---|---|---|
| 01 | 客户域领域词汇 + CONTEXT.md 骨架 (task) | — | ✅ **resolved**（D14） |
| 02 | **客户主表字段清单** — 扇出最广，多票回填 | — | ✅ **resolved**（D7） |
| 03 | 归属流转 + 三 workspace + 内置视图查询口径 | 02 | ✅ **resolved**（D9） |
| 04 | 新增查重校验 + 企查查工商回填 seam | 02 | ✅ **resolved**（D10） |
| 05 | 客户阶段（潜在→重潜→已成交，只前进；本图只做前两态） | 02 | ✅ **resolved**（D11） |
| 06 | 联系人 CRUD + 全局搜索 + 商机侧硬依赖接口 | 02 | ✅ **resolved**（D12） |
| 07 | 客户详情 8 页签 + 跟进记录 + 操作日志 | 02, 05 | ✅ **resolved**（D13） |
| 08 | 客户交割（跨模块同步商机/项目负责人事务） | 02, 03 | ✅ **resolved**（D15） |
| 09 | 客户导入（Excel，OCR 划出） | 02 | ✅ **resolved**（D16） |
| 10 | 客户规则族「超期未跟进提醒」（crm-rule 全局单例） | — | ✅ **resolved**（D8） |
| 11 | 自定义视图接入 crm-preference（复用商机 saved-view） | 03 | ✅ **resolved**（D17） |

**Frontier**：**空**——全部 11 张票已 resolve。spec 冻结，交棒 `/implement`。

**已知 grill 挂号**（不阻塞开票，各票 resolve 时问用户拍板；已拍板的已销号）：
- ~~票 04 相似判定算法~~ **已销号（grill Q11 = seam 化，一期最简）**
- ~~票 05 重潜触发点~~ **已销号（grill Q10 = 保守，方案卡已提交(2)）**
- ~~票 03 归档/合并~~ **已销号（grill Q9 = 归档即删除 + 筛选条件）**
- ~~customer_type 枚举~~ **已销号（grill Q8 = 18 值字典）**
- **票 08**：直属销售总监怎么定（是否在 SysUser 加 `superior_user_id`）？【待问】
- **票 09**：Excel 导入的相似客户处理策略（跳过/创建带标/报错）【待问】
- **票 10**："规则在客户新增时生效"的确认解读——新增客户时初始化 `last_valid_follow_time = create_time`（本条已在 grill Q4-补 与用户初步对齐，票 resolve 时最终确认）【待问】

## Out of scope

<!-- 越过目的地，划出本 effort；不 graduate 除非目的地重画 -->

- **战略协议**（A4-4-9/10 等级/新增/编辑）— 独立子域，另 effort。
- **联系人图谱**（职务二级联动树 + 人脉关系连线 + 层级自动生成）— 复杂可视化，另 effort；本图职务只留占位列。
- **客户查重列表 + 客户合并**（A4-6-1/2/3）— grill Q4 拍板不做；查重口径写死在新增流程。
- **OCR 快捷新增**（联系人/客户 OCR 识别）— 外部服务，划出；只在新增流程留 seam。
- **企查查等工商数据服务内部**— 只定调用契约 seam（调用点/回填范围/异常/精确查重触发），不深挖服务实现。
- **客户阶段「已成交客户」**（由 A5 项目首次中标驱动）— 留 seam，A5 未建。
- **客户阶段「重潜客户」**（由「方案卡提交并报备成功」驱动）— 留 seam（D20 改票 B），报备成功链路（方案卡已推送3 或 A5 回调）本期不可达；`CustomerStagePort.promote` 契约已定，本期无调用方。**本期客户阶段实际只有「潜在」。**
- **「关联项目」详情页签**（读 A5 项目模块）— A5 未建，划出。
- **联系人导入**— 划出（客户导入本图做，联系人导入随图谱 effort）。

## 返工增补（2026-09-05 收官版）

- 2026-09-04：客户模块验收返工启动，图 `.scratch/customer-rework/map.md`（R1–R11）；AGENTS.md「Coding standards」新增「新模块接口接入 checklist」一节（出处：返工票 01）。
- 2026-09-05：返工**全部收官**（12 张票 resolved）。本图 D1–D29 冻结不变，以下为**增量决策索引**；完整细节以 `.scratch/customer-rework/map.md`「决策（R1–R11）」与「Decisions so far」+ 各票 Answer 为准。

**R1–R11 决策指针**（→ `.scratch/customer-rework/map.md`）：R1 返工图独立目录、执行含图内并同步文档；R2 规范沉淀=AGENTS.md checklist（不开新 ADR）；R3 接口风格全量统一（扁平动作动词，全仓唯一 ADR-0017 违规消灭）；R4 bruno-sync 全链 + 深 tag 对照 v29 重挂；R5 列偏好接平台端点 + 公海看板拒绝；R6 形态偏好平台化（user_view_form）；R7 商机偏好一并开发；R8 已知缺口补/划处置；R9 双镜头全量复核；R10 验收线五项；R11 跨模块依赖走 Java service。

**返工票增量决策（一行/票）**：

- **01 AGENTS.md checklist** — 六条 checklist 落「Coding standards」区 + 内链 ADR-0017/0024，新模块出票/收工各对照一遍。
- **02 端点风格统一** — 8 Controller 26 端点重写为扁平动作动词+查询参数；crm-rule 提醒规则 PUT+@RequestBody→POST `/save` 表单绑定。
- **03 公海看板后端拒绝** — board summary/cards 对 pool 拒 67001（用户两轮澄清定案：卡片视图在总览/我的客户，公海无）。
- **04 缺口补齐** — crm-rule 从零建 `customer_dedup_rule` 单例栈（`GET/POST /api/rule/customer/dedup[/save]`，64023 校验）+ QuickCreateDTO.confirmSimilar 透传（needConfirm 口径）；RuleBacked Provider @Primary 消费（D4-rev2 落地），精确/模糊驱动 DedupService 分支。
- **05 形态偏好平台化** — crm-preference 新建 `user_view_form` 表 + view-form 两端点（本图 **D30 增补**）；客户 4 + 商机 3 scopeKey 常量接入，零业务新端点。
- **06 列偏好 scopeKey** — 客户/商机 COLUMN_SCOPE 常量块 + 平台端点 tags 三域双归属（A2×4 + A4×4 + A3×3）。
- **07 深 tag + bruno-sync** — 11 Controller 深 tag 对照 v29 树重挂（编号式绝迹）；文档仓对账收敛 309=309。
- **08 双镜头全量复核** — audit-findings.md：镜头一（规范）五项全绿；镜头二（原型）7 差异项回填票 09。
- **09 复核差异修复** — 六修一开两划：S1/F3/F6/F7/F8/F10 修，F5 单开票 12，F4/F9 划出；viewTouch upsert 收口（RECENT「最近访问」数据源兑现）。
- **12 战略协议** — `customer_agreement` 单表 CRUD 五端点 + 错误码 67017 + oplog AGREEMENT_*；客户快照 `strategic_agreement_level` 随写刷新。
- **10 回归重测** — 三模块 152/158/242 绿；冒烟 43 步 0 fail；bruno 对账 321=321 终态；BOM/风格 grep 零；报告 `.scratch/customer-rework/RETEST-REPORT.md`。
- **11 文档同步** — 本节增补 + API-SUMMARY.md 整篇重写（§0–§5，73 端点 URL 对账零差异）+ HANDOFF-2026-09-05 新篇 + crm-customer/CONTEXT.md 同步。