crm-backend-matt/.scratch/customer-module/API-SUMMARY.md

# 客户模块接口汇总（返工后同步版）

> **载体**：本文为速查汇总；完整契约以 knife4j 在线文档为准（`http://<host>:8080/doc.html`，`@Schema`/`@Operation` 注解齐全，与实现签名一致）。
> **范围**：crm-customer 全部端点 + 跨模块依赖（crm-rule 客户规则族 / crm-preference 平台偏好三件套）。crm-rule 其余族（线索池/商机池规则/方案卡模板/阶段模板/地区）不在客户域文档范围。
> **状态**：customer-rework 返工收尾同步版（2026-09-05，返工票 11）——URL 全量重塑为扁平动作动词（R3，零 `@PathVariable`/`PUT`/`DELETE`，写端点全 POST 表单绑定）、战略协议上线（票 12）、形态/列偏好平台接入（票 05/06）、查重设置补齐（票 04）、批量工商更新（F6）与导入重复策略（F8）落定。本文 URL 与代码 `@*Mapping` 已脚本对账零差异（票 11 ⑤）。

## 0. 通用约定

- **认证**：`Authorization: Bearer <token>`（网关注入用户上下文；`SecurityUtils.getRequiredUserId()`）。
- **统一响应**：`Result<T>` = `{code, success, message, data}`；`code=0` 成功，非 0 业务错误（§1 错误码）。
- **分页**：请求继承 `BaseParam`（`current`/`size`，非 pageNo/pageSize）；响应 `PageResult<T>` = `{content, total, ...}`，取列表 `getContent()`。
- **ID 精度**：雪花 Long 在 JSON 中**序列化为字符串**（前端勿做 Number 运算）。
- **风格（ADR-0017）**：写端点一律 POST + 表单绑定（无 `@RequestBody`），读端点 GET + 查询参数传 id；全客户域零 `@PathVariable`/`@PutMapping`/`@DeleteMapping`。**唯一例外**：crm-preference saved-view 保存用 `@RequestBody` JSON（平台端点不在 ADR-0017 改造范围，§2.14）。
- **权限**：
  - RBAC 功能权限：`ApiPermissionInterceptor` 注册规则匹配；**未匹配规则 fail-open 放行**（新端点无需登记即生效）。
  - 数据范围：workspace 列表/看板等查询经 `@DataScope(module="customer", ownerColumn="owner_user_id", deptColumn="owner_dept_id")` 注入可见范围（我的客户=负责人或协同人；公海=无归属）。
- **脱敏现状**：查重相似命中 `CustomerSimilarHitDTO.masked`；详情敏感信息三档（手机号/证件等分档脱敏）**V1 未纳入**（定稿划出，§5）。
- **时间**：`yyyy-MM-dd HH:mm:ss`；跟进/操作日志日期分组由前端按日渲染。

## 1. 错误码总表（67xxx，`CustomerConstants`）

| 码 | 常量 | 含义 |
|---|---|---|
| 67001 | CODE_CUST_INVALID | 客户入参非法（必填缺失/格式错误；公海看板拒绝、看板取卡缺 groupValue 同用此码） |
| 67002 | CODE_CUST_NOT_EXIST | 客户不存在或已被删除 |
| 67003 | CODE_CREDIT_CODE_DUP | 统一社会信用代码已被占用（L3 硬拦 / DB UNIQUE 兜底友好化） |
| 67004 | CODE_STATUS_NOT_ALLOWED | 当前状态不允许此操作（归档/恢复/抛公海守卫） |
| 67005 | CODE_CAS_FAIL | 乐观锁 CAS 冲突 |
| 67006 | CODE_ARCHIVE_BLOCKED | 归档被阻断：存在进行中商机 |
| 67007 | CODE_POOL_BLOCKED | 抛公海被阻断：存在进行中商机 |
| 67008 | CODE_CONTACT_INVALID | 联系人入参非法/不存在或不属于该客户 |
| 67009 | CODE_FOLLOW_INVALID | 跟进入参非法（方式/内容缺失，下次跟进时间早于本次） |
| 67010 | CODE_TRANSFER_DUP_RUNNING | 交割被阻断：存在未完成交接单（防重入） |
| 67011 | CODE_TRANSFER_FORBIDDEN | 交割被阻断：无可交接客户/接收总监不合法/非本人发起 |
| 67012 | CODE_ASSIGN_INVALID | 分配非法：明细已分配/对象越权/为发起人本人/为当前负责人 |
| 67013 | CODE_IMPORT_PRECHECK_FAIL | 导入预校验失败（文件/表头/行数/模板版本/**非法 duplicateStrategy**） |
| 67014 | CODE_IMPORT_STATUS_NOT_ALLOWED | 导入任务状态不允许此操作 |
| 67015 | CODE_DEDUP_RULE_MISSING | 查重设置单例缺失 |
| 67016 | CODE_MEMBER_INVALID | 成员管理非法：名单空/含负责人/重复加入/用户停用/成员不存在 |
| 67017 | CODE_AGREEMENT_INVALID | 战略协议非法：等级缺失或越界/协议不存在或无权访问（返工票 12） |

crm-rule 查重设置保存校验用 **64023**（matchMode∈{1,2}、threshold∈[0,100]），crm-preference 形态白名单校验用 **68xxx** 段——分属各自模块段位，不在上表。

## 2. 接口清单（按页面/子域）

### 2.1 三 workspace：列表 / 看板（`CustomerWorkspaceController /api/customer/workspace`）

| 方法 | 路径 | 说明 | 入参 |
|---|---|---|---|
| POST | `/api/customer/workspace/page` | 列表分页（saved-view 过滤器接入） | `CustomerWorkspacePageParam` 表单绑定 |
| POST | `/api/customer/workspace/board/summary` | 看板分组数量汇总（仅返回有数据分组，空列骨架前端补全） | 同上（groupColumn；无需 groupValue） |
| POST | `/api/customer/workspace/board/cards` | 看板单组卡片（口径与列表/summary 一致） | 同上（**必传 groupValue**，否则 67001） |

**`CustomerWorkspacePageParam` 关键入参**（继承 `BaseParam` 分页/keyword/排序）：

| 入参 | 说明 |
|---|---|
| `workspace` | `mine`（我的客户）/ `overview`（客户总览）/ `pool`（客户公海），必填 |
| `viewType` | 内置五视图（硬编码不落库，F7 终态）：`ASSIGNED` 我负责的 / `COLLABORATING` 我协同的 / `FOLLOW_UP_DUE` 待跟进（next_follow_time 到期未跟）/ `FOCUSED` 我关注的 / `RECENT` 最近访问（`customer_view_log` 倒序锚点）；空=基础集。**workspace 适配**：mine 全五；overview 无 FOLLOW_UP_DUE；pool 仅 RECENT/FOCUSED；**越界视图不硬拒，SQL 自然空集**。F7 口径收窄：ownerOnly 等布尔字段未做，viewType 单参数承载五视图 |
| `savedViewId` | 叠加自定义视图（§2.14 saved-view）检索条件于数据集之上，不改 `@DataScope` 边界；**RECENT 不接**（独立排序口径）；视图不存在静默不叠加 |
| `archiveStatus` | 1 有效 / 2 已归档；默认 1（D19 归档=删除语义） |
| `customerStage` / `customerStarLevel` / `relationStarLevel` / `customerType` / `industryCode` / `provinceCode` | 共用列筛选（阶段 1/2/3；星级 1~5；类型字典 code；行业一级 code；省国标 code） |
| `groupColumn` | 看板分组列（仅 board 两端点）：白名单 `stage`→customer_stage / `star`→customer_star_level / 其他→relation_star_level |
| `groupValue` | 看板分组取值（board/cards 必传） |

**看板边界（返工票 03）**：pool 看板 67001 拒绝（「公海无卡片视图」，公海仅列表/分屏两视图）；board/cards 不接 saved-view。

出参 `CustomerListRowDTO`：主表快照 + 关联业务计数（`opportunityCount` 经 opportunity_customer 真源 join 真算 / `projectCount` 恒 null 显 "--"）。

### 2.2 公海与归属动作（`CustomerOwnershipController /api/customer`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/claim?id=` | 领取（幂等口径见实现；领取即赋 `last_valid_follow_time` 锚点，D25） | 67002/67004 |
| POST | `/api/customer/claim-batch?ids=` | 批量领取 → `BatchResult{successes,failures[]}` | 同上 |
| POST | `/api/customer/assign?id=&userId=` | 分配（校验启用在职，口径同 validateTargetUser） | 67002/67012 |
| POST | `/api/customer/assign-batch?ids=&userId=` | 批量分配 | 同上 |
| POST | `/api/customer/release-pool?id=` | 抛公海（前置：无进行中商机；清 owner+协同人，软删 team_member） | 67002/67007 |
| POST | `/api/customer/release-pool-batch?ids=` | 批量抛公海（逐条独立事务，部分成功 → `BatchResult`） | 67002/67007 |

公海列表即 `POST /api/customer/workspace/page` + `workspace=pool`（检索：类型/行业；排序：进入公海时间，D29）。

### 2.3 新增 / 编辑 / 查重 / 工商回填（`CustomerController /api/customer`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/create` | 新增（form 绑定 `CustomerCreateDTO`；三层查重内建；ownerUserId 空=进公海记 enter_pool_time） | 67001/67003/67015 |
| POST | `/api/customer/edit?id=` | 编辑（`id` + `CustomerUpdateDTO` 表单；CAS：`version` 带回；归属字段不可改。冒烟实测需一并提交 `version`+`isBizNegotiated`+`isChild`，缺省因 DB NOT NULL 无默认而失败，关联 §5 D-05） | 67001/67002/67003/67005 |
| GET | `/api/customer/detail?id=` | 详情（编辑页全字段回显，字典回显名；=详情页签 1） | 67002 |
| POST | `/api/customer/page` | 基础分页（keyword/阶段/档案/类型；DataScope） | — |
| GET | `/api/customer/check-name?name=&excludeId=` | 名称相似查重（L2；匹配方式/阈值走查重设置 D4-rev2，精确/模糊两分支） | 67015 |
| GET | `/api/customer/check-credit-code?creditCode=` | 信用代码查重（L3 硬拦预检，系统强制无开关） | 67003 |
| GET | `/api/customer/company-lookup?companyName=` | 工商联想（企查查 seam，V1 可空实现；**参数名 `companyName`**） | — |
| POST | `/api/customer/company-lookup/batch-update?ids=` | **批量更新工商信息（F6）**：逐客户按名称查工商源并**只补空缺字段**；单次上限 100；行级部分成功，五种状态软处置 `UPDATED/SKIPPED/NO_HIT/CONFLICT/NOT_FOUND`；一期 port stub 恒 NO_HIT，真实企查查接入后自动激活 | 40001（空/缺 ids，全局参数缺失码，r2 实测）/67001（上限超 100，含 101 重复 id） |

**查重弹窗返回结构**：`CustomerSaveResultDTO{needConfirm=true, similarHits:[{customerId, customerName, ownerName, customerStage, archiveStatus, masked}]}`（未落库）；确认后带 `confirmSimilar=true` 重发（create / quick-create 均支持）。

### 2.4 商机弹窗快建 + 商机侧硬依赖（`/api/customer`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/quick-create` | 快建（`CustomerQuickCreateDTO` 最小集 + `confirmSimilar` 透传（返工票 04）；服务端默认 owner=当前用户、is_child=否、isBizNegotiated=否；命中相似未确认 → needConfirm） | 67001/67003 |
| POST | `/api/customer/search` | 商机侧客户搜索（名称/联系人/电话三维模糊 + 类型精确；DataScope） | — |
| GET | `/api/customer/contacts?customerId=` | 商机详情带出联系人（跨模块 port 消费方） | 67002 |

### 2.5 客户详情：公共头部 + 8 页签（`CustomerDetailController /api/customer`）

| 页签 | 方法与路径 | 说明 | 主要错误码 |
|---|---|---|---|
| 公共头部 | GET `/api/customer/detail-head?id=` | 聚合（快照+跟进摘要+待跟进提醒+关联业务计数；**汇总卡 5 字段恒 null 显 "--"**：wonProjectAmount/planEstimateAmount/ongoingOpportunityAmount/contractAmount/paidAmount，grill Q18 契约=前端渲染 4 卡不显 0）。**副作用**：upsert `customer_view_log` 刷新「最近访问」锚点（F7 viewTouch 收口，UNIQUE(user_id,customer_id) 去重、高频行为不落 oplog） | 67002 |
| 页签 1 客户信息 | GET `/api/customer/detail?id=` | =编辑页 detail 回显 | 67002 |
| 页签 2 联系人 | GET `/api/customer/contacts?customerId=` | 子表列表 | — |
| 页签 3 跟进记录 | GET `/api/customer/follow/page?id=` | 时间倒序+日期分组前端；过滤 follow_way/keyword/时间范围 | 67002 |
| 页签 4 关联商机 | GET `/api/customer/opportunity/page?id=` | port 反查 crm-opportunity；失败前端显 "--" | 67002 |
| 页签 5 关联项目 | — | 恒显 "--"（A5 未建，§5） | — |
| 页签 6 战略协议 | §2.6 | **已上线**（返工票 12）：`GET /api/customer/agreement/list?customerId=` | 67017 |
| 页签 7 团队成员 | GET `/api/customer/member/list?id=` | 负责人+协同人，ROLE_OWNER 在前 | 67002 |
| 页签 8 操作日志 | GET `/api/customer/oplog/page?id=` | `OplogPageParam`（startTime/endTime/**action**/keyword 匹配 detail）；action 值域 **17 种**见 §3 | 67002 |

**写跟进**：`POST /api/customer/follow/add?id=`（`FollowCreateDTO` 表单：followWay/followContent/nextFollowTime；append-only 不可改删；副作用刷新 `last_valid_follow_time` 超期锚点）——67002/67009。

### 2.6 战略协议五端点（`CustomerAgreementController /api/customer/agreement`，返工票 12）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/agreement/create` | 新增（`AgreementDTO` 表单） | 67001/67017 |
| POST | `/api/customer/agreement/edit?id=` | 编辑（`id` + `AgreementDTO`；**归属不可换客户**，编辑以库内归属为准） | 67001/67002/67017 |
| POST | `/api/customer/agreement/delete?id=` | 删除 | 67002/67017 |
| GET | `/api/customer/agreement/detail?id=` | 详情 | 67002/67017 |
| GET | `/api/customer/agreement/list?customerId=` | 页签 6 列表 | — |

**`AgreementDTO` 字段**：`customerId`（新增必填；编辑忽略）/ `agreementLevel`（1~3 必填）/ `amount`（文本可空）/ `remark` / `fileFileId` + `customerName`（仅出参）。

**快照联动**：新增/编辑/删除协议同步刷新客户主表 `strategic_agreement_level`（删除=清空快照）；oplog 记 `AGREEMENT_ADD/EDIT/DELETE`；67017 语义=等级缺失或越界/协议不存在或无权访问。

### 2.7 联系人独立菜单（`CustomerContactController /api/customer/contact`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/contact/create` | 新增（`ContactDTO` 表单；必填 name/jobTitleName/phone，冒烟实测） | 67001/67008 |
| POST | `/api/customer/contact/edit?id=` | 编辑（`id` + `ContactDTO`） | 67001/67008 |
| POST | `/api/customer/contact/delete?id=` | 删除 | 67002/67008 |
| GET | `/api/customer/contact/detail?id=` | 详情 | 67002 |
| GET | `/api/customer/contact/page` | 列表分页（`ContactPageParam`=BaseParam；keyword 匹配姓名/电话/所属客户名） | — |
| GET | `/api/customer/contact/search?keyword=&limit=` | 全局搜索（商机「商机关键联系人」数据源：姓名/电话模糊，带出所属公司名；**limit 默认 20**） | — |
| GET | `/api/customer/contact/check-phone?phone=&excludeId=` | 电话软提示（D26：跨客户命中只提示疑似重复、不阻断；**受查重设置「联系电话」开关控制**） | — |

`ContactDTO` 字段：`customerId` / `name` / `jobTitleName` / `jobTitleId` / `jobTitleCategory` / `jobTitleLevel` / `phone` / `isKeyContact` / `isInternal` / `giftRemark` / `source`（contact_source 字典：组会/组局/转介绍/其他）+ 出参 `customerName`/`customerNo`。写动作记 oplog `CONTACT_ADD/EDIT/DELETE`（F10）。

### 2.8 团队成员管理（`CustomerDetailController /api/customer`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| GET | `/api/customer/member/list?id=` | 成员列表（负责人+协同人，ROLE_OWNER 在前） | 67002 |
| POST | `/api/customer/member/add?id=` | 添加协同人（`id` + `MemberAddDTO{memberUserIds[]}` 表单；两阶段校验整批拒绝；批内幂等去重；姓名快照；oplog MEMBER_ADD） | 67002/67016 |
| POST | `/api/customer/member/remove?id=&memberUserId=` | 移除协同人（软删 delete_key=id 可重复加入；oplog MEMBER_REMOVE） | 67002/67016 |

### 2.9 关注 / 重点客户标记（`CustomerFocusController /api/customer`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/focus?id=` | 关注（幂等；行存在性=关注态） | 67002 |
| POST | `/api/customer/unfocus?id=` | 取关（物理删行，连带清重点标记） | — |
| POST | `/api/customer/star?id=` | 标记重点客户（未关注自动建行 starred=1；幂等） | 67002 |
| POST | `/api/customer/unstar?id=` | 取消重点标记（保留行仅置 starred=0；幂等） | — |
| POST | `/api/customer/focus-batch?ids=` | 批量关注（逐个幂等；对称商机） | 67002 |

一行两态语义：`customer_focus` 行存在=关注，`starred` 列=重点标记；均不写 oplog。

### 2.10 归档 / 恢复（`CustomerOwnershipController /api/customer`）

`POST /api/customer/archive?id=`（前置无进行中商机；归档=删除语义 D19）、`POST /api/customer/archive-batch?ids=`、`POST /api/customer/restore?id=`——67002/67004/67006。

### 2.11 客户交割（`CustomerTransferController /api/customer/transfer`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| GET | `/api/customer/transfer/preview` | 待交接客户预览（离职总监名下有效客户） | — |
| POST | `/api/customer/transfer/initiate` | 发起交接（`TransferInitiateDTO` 表单：`reason` 必填 resign/transfer_post/region_adjust；`toDirectorId` 选填——离职场景系统按组织推导（D22）；`remark`；整批原子 @Transactional；owner 联动商机/项目 port；oplog TRANSFER 系统操作含交接编号） | 67010/67011/67012 |
| GET | `/api/customer/transfer/detail?id=` | 交接单详情（进度=assignedCount/totalCount） | — |
| GET | `/api/customer/transfer/page` | 交接单分页（`TransferPageParam`） | — |
| POST | `/api/customer/transfer/assign?id=&customerIds=&assignUserId=` | 明细分配（`BatchResult` 行级部分成功） | 67012 |
| GET | `/api/customer/transfer/assignable?id=` | 可分配销售列表（**D-07 P1 已知缺陷：稳定超时**，§5） | — |

状态：交接单 0 待分配→1 已完成（全分配自动置位 D23）；明细 0/1。

### 2.12 客户导入（`CustomerImportController /api/customer/import`）

| 方法 | 路径 | 说明 | 主要错误码 |
|---|---|---|---|
| POST | `/api/customer/import/upload` | 上传预校验（MultipartFile file + importMode + **duplicateStrategy 可选（F8）**；DRAFT 落库待确认；**响应回显 duplicateStrategy**） | 67013 |
| GET | `/api/customer/import/template` | 下载模板（版本 V1 锚点） | — |
| POST | `/api/customer/import/confirm?taskId=` | 确认执行（两段式） | 67014 |
| GET | `/api/customer/import/result?taskId=` | 结果（行级部分成功：总数/成功/失败） | — |
| GET | `/api/customer/import/failures?taskId=` | 失败明细 | 67014 |
| GET | `/api/customer/import/page` | 任务分页（`ImportPageParam`：status/importMode） | — |

**F8 `duplicateStrategy`（D24 冻结语义）**：可选参数，`SKIP`（缺省，文件内重复组全部标失败不写入）/ `OVERWRITE`（文件内自上而下**最后一条通过校验的行 UPDATE 生效**）；非法值 67013 拦截；**作用面仅文件内重复组**，不触名称相似 SUSPECT 判定。

状态机：0 DRAFT→1 RUNNING→2 DONE/3 FAILED（重复确认 67014）。

### 2.13 客户规则设置（跨模块：crm-rule 客户规则族）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/rule/customer/reminder` | 超期未跟进提醒当前单例配置（总开关/首次触发天数默认 30/二次提醒间隔默认 7/各自独立开关） |
| POST | `/api/rule/customer/reminder/save` | 保存（`CustomerReminderRuleDTO` 表单：masterEnabled/firstTriggerEnabled/firstTriggerDays/secondIntervalEnabled/secondIntervalDays；开关缺省视为关） |
| GET | `/api/rule/customer/dedup` | 查重设置当前单例配置（返工票 04 补齐） |
| POST | `/api/rule/customer/dedup/save` | 查重设置保存（`CustomerDedupRuleDTO` 表单：masterEnabled/nameEnabled/nameMatchMode（1 精确 2 模糊）/similarityThreshold（0–100，出厂 80）/phoneEnabled；校验越界 **64023**；开关缺省视为关、方式缺省→模糊、阈值缺省→80；**统一社会信用代码为系统强制规则，无配置列、消费侧恒开**） |

- 保存=全量覆盖即生效；两单例均 `CustomerXxxRuleInitializer`（@Order）首装种子、幂等。
- 消费侧：crm-customer `RuleBackedCustomerDedupSettingProvider`（@Primary）读单例驱动新增/编辑内建查重——总开关∧单项开关控名称/电话，阈值/匹配方式透传（EXACT 分支=trim+大小写不敏感全等；模糊=ngram），单例缺失回退出厂值；匹配方式消费边界=新增/编辑内建查重（导入路径维持模糊）。

### 2.14 平台偏好三件套（跨模块：crm-preference）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/preference/get?scopeKey=` | 列偏好读取（显隐+顺序；无则 null） |
| POST | `/api/preference/save` | 列偏好保存（scopeKey + visibleKeys + columnOrder 可空，逗号分隔表单值；一次写入） |
| GET | `/api/preference/view-form/get?scopeKey=` | 形态偏好读取（null=未设置，前端默认 list） |
| POST | `/api/preference/view-form/save` | 形态偏好保存（scopeKey + viewForm：list/split/board；白名单平台校验 68xxx） |
| GET | `/api/preference/view/list?scopeKey=` | 自定义视图列表（按 seqNo） |
| POST | `/api/preference/view/save` | 视图保存（scopeKey 表单参数 + **SavedView `@RequestBody` JSON**——全平台唯一 JSON 例外，返工票 05/11 口径）；viewId 空=新建、非空=覆盖编辑；isDefault 单值互斥 |
| POST | `/api/preference/view/delete?scopeKey=&viewId=` | 删除自定义视图 |
| POST | `/api/preference/view/set-default?scopeKey=&viewId=` | 设为该 scope 默认视图（单值互斥） |

**scopeKey 清单**（saved-view / 列偏好 / 形态偏好三件套共用码位，`CustomerConstants`）：

| scopeKey | 用途 | 说明 |
|---|---|---|
| `customer.overview` / `customer.mine` / `customer.pool` | 客户总览 / 我的客户 / 客户公海 | 三件套共用 |
| `contact.list` | 联系人列表 | 列偏好 + 形态偏好 |
| `opportunity.sales` / `opportunity.manage` / `opportunity.public_pool` | 商机三菜单（返工票 07，参考线索） | 列偏好 + 形态偏好；sales 与 saved-view 同码位 |

**view-form 边界**：公海（`customer.pool`）仅 list/split 两形态，board 被平台拒绝（白名单校验 680xx，返工票 03/05）；总览/我的客户/联系人三形态均可。固定列校验（客户名称不可隐藏、勾选/序号/操作列不参与、重置默认）归前端（R5 拍板，与线索一致）。

> ⚠ **r2 实测漂移（2026-09-06，e2e-incr I-06，e2e-report-v2 §六）**：实现 `ViewFormServiceImpl` 白名单仅全局三值 {list,split,board}，**无 pool 特判**（crm-preference 全模块无 pool 分支）——公海 scopeKey 保存 board 形态实回 code=0，上方「拒绝 680xx」约定暂未实现。前端不得依赖拒绝行为；待实现侧补特判或产品改口径（记档非缺陷）。

### 2.15 健康检查

`CustomerPingController /api/customer`：`GET /api/customer/ping`（联通性，无业务）。

## 3. 状态 / 值域附录

- **archive_status**：1 有效 / 2 已归档（无合并态 D19）；**customer_stage**：1 潜在 / 2 重潜（D20 seam 不触发）/ 3 已成交（三态只前进，CAS；**本期两个跃迁均不触发，实际只有「潜在」**）。
- **编号**：客户 `KH+yyyyMMdd+4 位`；交割 `JG+yyyyMMdd+4 位`。
- **viewType**（内置五视图，硬编码）：`ASSIGNED` / `COLLABORATING` / `FOLLOW_UP_DUE` / `FOCUSED` / `RECENT`；workspace 适配矩阵见 §2.1。
- **导入模式**：APPEND_ONLY / UPDATE_ONLY / UPSERT；**重复策略**：SKIP / OVERWRITE；任务状态 0 DRAFT / 1 RUNNING / 2 DONE / 3 FAILED；模板版本 V1。
- **oplog action 值域（17 种）**：`CREATE / UPDATE / FOLLOW / ARCHIVE / RESTORE / TRANSFER / CLAIM / POOL / STAGE_CHANGE / MEMBER_ADD / MEMBER_REMOVE` + `CONTACT_ADD / CONTACT_EDIT / CONTACT_DELETE`（F10）+ `AGREEMENT_ADD / AGREEMENT_EDIT / AGREEMENT_DELETE`（票 12）。detail 叙事形态 `把 {字段} 从 {旧} 修改为 {新}`（D13）；阶段变化 operator=系统；导入记 CREATE+UPDATE。⚠ 代码侧 `OplogPageParam` 的 @Schema 描述仍写 11 种（滞后未改——票 11 不动代码），以本表 17 种真值为准。
- **通知**：`FOLLOW_OVERDUE`；状态 0 待发 / 1 已发 / 2 已失效。
- **交割**：交接单 0 待分配→1 已完成；明细 0/1；`transfer_reason` = resign（离职）/ transfer_post（岗位调动）/ region_adjust（区域调整）。
- **查重设置**：nameMatchMode 1 精确 / 2 模糊；similarityThreshold 0–100（出厂 80）；信用代码恒开无配置。

## 4. 联调速查

- knife4j：`http://localhost:8080/doc.html`；token 放 `Authorization: Bearer`。
- 写端点均为 **form 绑定**（无 @RequestBody），全客户域唯一 JSON 例外 = crm-preference saved-view save（§2.14）。
- 冒烟脚本范式：`tmp/smoke-t10.py`（43 步全链 0 fail，覆盖清单见 [RETEST-REPORT.md](../customer-rework/RETEST-REPORT.md) §2；脚本本体换机未随仓——复跑时服务起停/环境参照 `.scratch/customer-e2e/map.md` 环境事实段与 customer-rework 交接篇工具坑节）。
- 已知缺陷验证模式：D-07 assignable 超时按缺陷模式记录、不阻断冒烟（§5）。

## 5. 已知缺口与范围外（如实记录，避免联调踩坑）

1. ~~QuickCreateDTO 无 confirmSimilar 字段~~ **已补齐（返工票 04）**：`CustomerQuickCreateDTO.confirmSimilar`（默认 false）透传主表 create；命中相似未确认 → needConfirm=true + similarHits（未落库），确认后带 confirmSimilar=true 重发。
2. ~~查重设置页（A7-3-3-2）无对外端点~~ **已补齐（返工票 04）**：crm-rule `customer_dedup_rule` 单例 + `GET /api/rule/customer/dedup` + `POST /api/rule/customer/dedup/save`（§2.13）；crm-customer `RuleBackedCustomerDedupSettingProvider`（@Primary）读单例驱动新增/编辑内建查重，单例缺失回退出厂值。
3. 详情**页签 5（关联项目）**恒显 "--"（A5 未建）；**页签 6 战略协议已上线（§2.6）**；汇总卡 5 字段恒 null（进行中商机总额可经 port 扩展后切真值）。
4. **敏感信息三档脱敏 + 查看日志**、**合并客户**、**客户导出**：定稿划出（范围外）。
5. 联系人子表导入：原型 9.2-9 提及，按 REVIEW-HANDOFF 划出 V1。
6. **D-07（P1 已知缺陷）**：`GET /api/customer/transfer/assignable` 稳定超时（根因：根部门全树递归 + 逐用户 getDeptNames N+1；e2e-heavy 30s×2 + probe 60s 双复现）。修复排期独立 effort，返工范围外。
7. 导入 **D-04（P2）** 失败明细 `fail_reason` 列超长写不进 / **D-05（P1）** `is_biz_negotiated` NOT NULL 无默认值：已知缺陷记档（票 09 audit），维持原状。