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）