crm-backend-matt/.scratch/customer-demo-ref/issues/02-rule-family-contract.md

# 02 规则族契约摸底（查重设置 / 公海池配置 / 超期提醒）

Type: research
Status: resolved
Blocked by: —

## Question

三个规则族的实现契约与 Demo 呈现输入：

1. **查重设置**（现有 demo 已有，A7-3-3-2 crm-rule 单例）：端点、出入参 DTO 字段、取值枚举——核实即可。
2. **公海池配置**（大概率全新）：后端端点是否已存在？在哪个模块（crm-rule / crm-customer）？出入参、原型依据页（lanhu v29 树中哪页，A7-3-3-x?）。**若后端未实现**：Demo 侧按纪律「不修后端」应如何呈现（只读占位 + 明示未实现？）——给出契约事实供 06 号票设计现象展示。
3. **超期提醒配置**（A7-3-3-1）：同 1，核实即可。

另核实：三者的 Bruno .bru 文档是否已写（`D:\code\crm-api-docs`）、menuBindings 是否已配（仓根 `bruno-sync.config.json`）。

## Pointers

- 现有 demo 设置页实现：`.scratch/customer-e2e/demo/index.html` 搜「超期」「查重设置」。
- 后端规则模块：仓内找 crm-rule 相关模块目录与 Controller；`.scratch/customer-module/API-SUMMARY.md` 看是否收录。
- 原型：`.scratch/api-docs-reorg/lanhu-tree-v29.md` 中 A7-3-3 相关行；蓝湖提取文本在 `D:\code\crm-需求梳理\lanhu-mcp\data\`（如需页面字段细节读对应 .txt）。
- 错误码段：67xxx 已用到 67024（新取号需顺延——本票只记录事实）。

## Answer

### 结论速览

| 规则族 | 后端端点 | 原型页（v29） | Bruno .bru | menuBindings |
|---|---|---|---|---|
| 查重设置 A7-3-3-2 | 已实现 `GET/POST /api/rule/customer/dedup(/save)` | `a7-3-3-2_客户管理设置_客户查重设置_` | 已写（2 个） | 已配 |
| 超期提醒 A7-3-3-1 | 已实现 `GET/POST /api/rule/customer/reminder(/save)` | `a7-3-3-1_客户管理设置_超期未跟进提醒_` | 已写（2 个） | 已配 |
| 公海池配置 | **未实现**（无端点、无实体、原型亦无配置页） | **v29 无此页** | n/a | n/a |

### 1. 查重设置（A7-3-3-2，crm-rule 单例）— 已实现，核实通过

- Controller：`crm-rule/src/main/java/com/crm/rule/controller/CustomerDedupRuleController.java`，`@RequestMapping("/api/rule/customer/dedup")`，tag `A7 后台管理/业务规则/客户规则/客户管理设置（客户查重设置）`。全局单例 id=1（初始化器首装植入）。
- 端点：
  - `GET /api/rule/customer/dedup` → `Result<CustomerDedupRuleDTO>`（读单行）
  - `POST /api/rule/customer/dedup/save`（表单绑定，ADR-0017，无 `@RequestBody`）→ 全量覆盖、保存即生效
- `CustomerDedupRuleDTO` 字段：

| 字段 | 类型 | 取值/枚举 | 缺省行为 |
|---|---|---|---|
| id | Long | 单例固定 1 | — |
| masterEnabled | Integer | 1 启用 / 0 禁用（仅控名称/电话提示） | 缺省视为 0 |
| nameEnabled | Integer | 1/0（名称查重独立开关） | 缺省视为 0 |
| nameMatchMode | Integer | 1 精确 / 2 模糊 | 缺省回出厂 **2（模糊）** |
| similarityThreshold | Integer | 0–100 | 缺省回出厂 **80** |
| phoneEnabled | Integer | 1/0（电话精确命中仅提示不阻断，D26） | 缺省视为 0 |
| updateTime | LocalDateTime | GET 回显只读 | — |

- 校验：显式传入 `nameMatchMode ∉ {1,2}` 或 `similarityThreshold ∉ [0,100]` → **64023**（`CODE_CUSTOMER_RULE_INVALID`，crm-rule 段），不落库（`CustomerDedupRuleServiceImpl`）。
- 统一社会信用代码：系统强制规则，**无配置字段**（无列、消费侧恒开），原型页标注「精确重复时禁止创建客户，不可关闭」。
- 单例缺失：67015 `CODE_DEDUP_RULE_MISSING`；消费侧 `RuleBackedCustomerDedupSettingProvider`（@Primary）读单例驱动新增/编辑内建查重，缺失回退出厂值。
- 原型阈值预设 → 数值映射（`a7-3-3-2` .txt §4.1）：宽松=70、标准（推荐）=80（默认）、严格=90、自定义=0–100 输入。
- demo 现状：`.scratch/customer-e2e/demo/index.html` L355-365 表单 + L1434-1457 `loadDedup/saveDedup`，调的 URL 与上表一致。
- Bruno：`D:\code\crm-api-docs\A7 后台管理\业务规则\客户规则\客户管理设置（客户查重设置）\{读取查重设置,保存查重设置}.bru`（示例值/参数表齐全）。
- 收录：`.scratch/customer-module/API-SUMMARY.md` L241-242、L285、L297。

### 2. 公海池配置 — 后端未实现（重点结论）

事实链（四条独立证据互相印证）：

1. **原型 v29 无此配置页**：`lanhu-tree-v29.md` L64 —— A7-3-3 客户规则只有两个子页（A7-3-3-1 超期未跟进提醒 / A7-3-3-2 客户查重设置）；`a7-3-3-1` 页面左侧导航同样只有这两项。`a7-2-3_客户管理设置_*` 四个文件是 v20 旧副本（草稿箱/backup），非 v29 权威位置。
2. **客户公海在原型上是「固定规则虚拟池」而非可配置实体**：`a4-1-1_客户公海列表_列表视图_.txt` §3 公海准入规则原文：「客户档案状态为"有效"且销售负责人为空的客户，属于客户公海」；移入公海入口设在客户总览；整页无任何池配置/自动回收规则配置 UI。A4-1 分区 [2] 只有列表/分屏两个视图页。
3. **后端无端点**：crm-rule 全部 9 个 Controller 中没有 CustomerPool 配置类——唯一 pool 配置是 `LeadPoolController @ /api/rule/pool`，那是**线索**公海池（tag `A2 线索管理/线索设置`，管理显式 `LeadPool` 实体 + 省市区/人员关联表：page/detail/saveOrUpdate/delete/delete-batch/import/export）。crm-customer 侧也没有配置 Controller：客户公海是 workspace 视图（`CustomerWorkspaceController @ /api/customer/workspace`，`workspace=pool`，owner 为空按部门可见）+ `CustomerOwnershipController` 的动作端点（`/api/customer/claim(-batch)`、`/assign(-batch)`、`/release-pool(-batch)`）。`CustomerPoolPageParam` 只是公海列表查询参数（extends `CustomerWorkspacePageParam`），不是配置载体。
4. **Bruno / menuBindings**：n/a——无端点无页，自然两者皆无。

**Demo 呈现输入（供 06 号票设计现象展示）**：

- 按纪律「不修后端」，公海池配置在 demo 设置 Tab 应呈现为**只读占位卡片 + 明示未实现**（置灰/禁用交互），说明文案可用事实：「后端未实现；原型 v29 亦无客户公海配置页——客户公海为准入固定规则（档案有效 + 销售负责人为空），非可配置实体池」。
- 相邻已实现能力可正常演示：公海列表 `workspace=pool`、领取 `POST /api/customer/claim`、抛公海 `POST /api/customer/release-pool`（demo 已有 L178/L202-203/L1013/L1081）。
- **不可混入**：线索侧 `/api/rule/pool`（公海池分页/新建编辑等）虽存在且形态完整，但属线索域（LeadPool 实体池），不能当客户公海配置接进客户 demo；仅可作为「线索=显式实体池 vs 客户=虚拟池固定规则」的对照说明。

### 3. 超期提醒配置（A7-3-3-1，crm-rule 单例）— 已实现，核实通过

- Controller：`crm-rule/.../controller/CustomerReminderRuleController.java`，`@RequestMapping("/api/rule/customer/reminder")`，tag `A7 后台管理/业务规则/客户规则/客户管理设置（超期未跟进提醒）`，RBAC 功能权限 `customer.reminder.rule`。全局单例 id=1。
- 端点：
  - `GET /api/rule/customer/reminder` → `Result<CustomerReminderRuleDTO>`
  - `POST /api/rule/customer/reminder/save`（表单绑定）→ 全量覆盖、保存即生效
- `CustomerReminderRuleDTO` 字段：

| 字段 | 类型 | 取值/枚举 | 缺省行为 |
|---|---|---|---|
| id | Long | 单例固定 1 | — |
| masterEnabled | Integer | 1/0 总开关 | 缺省视为 0 |
| firstTriggerEnabled | Integer | 1/0 首次触发独立开关 | 缺省视为 0 |
| firstTriggerDays | Integer | 正整数（出厂 **30**） | 非正整数 → 64023 |
| secondIntervalEnabled | Integer | 1/0 二次提醒独立开关 | 缺省视为 0 |
| secondIntervalDays | Integer | 正整数（出厂 **7**） | 非正整数 → 64023 |
| updateTime | LocalDateTime | GET 回显只读 | — |

- 出厂常量：`CustomerRuleConstants.DEFAULT_FIRST_TRIGGER_DAYS=30`、`DEFAULT_SECOND_INTERVAL_DAYS=7`（DB DEFAULT 同值）。
- 原型依据（`a7-3-3-1` .txt）：总开关 + 首次触发时间（默认 30 天）+ 二次提醒间隔时间（默认 7 天），各配独立启停；提醒渠道为钉钉推送 + 应用内通知；底部保存/取消。与 DTO 完全对齐。
- 消费侧：`CustomerReminderJob` 每轮只补「下一条未建到期提醒」（升级提醒链），锚点 = 最近有效跟进时间。
- demo 现状：`index.html` L343-352 表单 + L1410-1432 `loadReminder/saveReminder`，URL 与上表一致。
- Bruno：`客户管理设置（超期未跟进提醒）\{当前提醒规则,保存提醒规则}.bru`（含 E2E 实测真值）。
- 收录：API-SUMMARY.md L239-240。

### 附带核实

- `bruno-sync.config.json` menuBindings：L23-24 已覆盖两个客户规则设置页（`viewType: null, scopeKey: null`，单例页无需 scope，符合预期）；L13 的 `A4 客户管理/客户公海` 是公海**列表视图** binding（`pool` / `customer.pool`），不是配置页，勿混淆。
- API-SUMMARY.md 已完整收录两端点族（L239-242）。
- 错误码事实（仅记录）：67xxx 已用至 **67024**（`crm-customer/.../constant/CustomerConstants.java:36` `CODE_CONTACT_IMPORT_STATUS_NOT_ALLOWED`），新取号从 67025 顺延；本票涉及的相关码：64023（crm-rule 段，规则校验越界）、67015（查重设置单例缺失）。

### 证据路径

- 后端：`D:\code\crm-backend-matt\crm-rule\src\main\java\com\crm\rule\controller\{CustomerDedupRuleController,CustomerReminderRuleController,LeadPoolController}.java`；`...\domain\dto\{CustomerDedupRuleDTO,CustomerReminderRuleDTO}.java`；`...\constant\CustomerRuleConstants.java`；`...\service\impl\{CustomerDedupRuleServiceImpl,CustomerReminderRuleServiceImpl}.java`；`D:\code\crm-backend-matt\crm-customer\src\main\java\com\crm\customer\controller\{CustomerWorkspaceController,CustomerOwnershipController}.java`、`...\domain\param\CustomerPoolPageParam.java`
- demo：`D:\code\crm-backend-matt\.scratch\customer-e2e\demo\index.html`（L338-376 设置表单、L1409-1457 load/save、L178/L1013 公海动作）
- 原型：`D:\code\crm-需求梳理\lanhu-mcp\data\axure_extract_bade4454_screenshots\a7-3-3-1_客户管理设置_超期未跟进提醒_.txt`、`a7-3-3-2_客户管理设置_客户查重设置_.txt`、`a4-1-1_客户公海列表_列表视图_.txt`（§3 公海准入规则）
- 树：`D:\code\crm-backend-matt\.scratch\api-docs-reorg\lanhu-tree-v29.md`（L64 A7-3-3 仅两子页）
- Bruno：`D:\code\crm-api-docs\A7 后台管理\业务规则\客户规则\` 下 4 个 .bru；对照（线索域）`线索规则\公海池*.bru` 7 个
- 配置/汇总：`D:\code\crm-backend-matt\bruno-sync.config.json`（L13、L23-24）；`D:\code\crm-backend-matt\.scratch\customer-module\API-SUMMARY.md`（L239-242、L285、L297、L33/L44）