crm-backend-matt/crm-rule/CONTEXT.md

# 业务规则（crm-rule）

多域规则中心（票 01）：线索规则子域（公海池配置 + 行政区划）与商机规则子域（公海规则、后续阶段模板/方案卡模板/有效跟进规则，原型 A7-3-2）分域共住本模块，**完全独立无共表无共抽象**（范式都不同：池实体 vs 版本化规则配置）。依赖方向单向 `crm-rule → (crm-auth / crm-dict)`，**不得反向依赖 crm-lead / crm-opportunity**——规则表不知道线索/商机实体存在。

## 线索规则子域

线索公海池的配置域：公海池实体（归属部门 + 省/市/区）、人员（负责人 / 协作人 / 成员）、领取规则、超时回收 / 失效 / 领取上限配置。公海池表复用 `lead` 数据范围模块（决策 [K]）。

## Language

**公海池**:
线索的归集容器与规则载体，`crm-rule` 的核心聚合根，存于 `lead_pool`。定义一个部门下线索的领取规则（回收天数 / 失效天数 / 持有上限 / 每日领取上限）与人员编制。**一部门一池**，`UNIQUE(dept_id)`；池名全局 `UNIQUE`。
_Avoid_: 线索池、公海、资源池、pool（英文单说）

**归属部门**:
公海池所属的部门节点，`dept_id`，是「一部门一池」的唯一键。同时冗余 `team_dept_id`（团队 = 部门树上级节点）。归属部门决定池及池内线索的数据范围天花板。
_Avoid_: 所属部门、部门、团队部门

**负责市场**:
公海池覆盖的行政区划，多值——省份多值表 + 市/区多值表两张关联表。存国标 code（`varchar(12)`，支持前缀 LIKE 祖先查询，对齐 `sys_region`）。同一部门的多个市场取并集在**同一个**池里（一部门一池），不拆多池。
_Avoid_: 覆盖区域、地区、辖区

**负责人**:
公海池的主管理人，池-人绑定表中 `role=OWNER`。被设为负责人会落一条池维度的行级授权（`resource_type=pool`），使其能越过部门天花板看到池内线索。**负责人身份不授予池配置写权**（决策 [E]）——改池配置走功能权限 × 数据范围。
_Avoid_: 池主、管理员、owner（owner 在 crm-lead 是领取人）

**协作人**:
公海池的协助管理人，池-人绑定表中 `role=COLLAB`。与负责人一样落池维度行级授权（只读，越过部门天花板看池内线索）。移出协作人名单那一刻即失效，授权行硬删（决策 [PRD-3]）。
_Avoid_: 协助人、副负责人、collaborator

**成员**:
有资格领取该池线索的销售集合。**动态推导、不落表**——成员 = 归属部门的部门子树内全部用户，按组织架构实时算。不是池-人绑定表里的行（绑定表只存 OWNER / COLLAB）。
_Avoid_: 池成员表、领取人白名单、参与者

**回收天数**:
池配置字段 `recycle_days`，喂给线索的回收计时 N。DB DEFAULT = 7。
_Avoid_: 超时天数、N、recycle

**失效天数**:
池配置字段 `expire_days`，喂给线索的失效计时 M。DB DEFAULT = 180。
_Avoid_: 有效期、M、expire

**持有上限**:
池配置字段 `hold_limit`，单个销售在本池最多同时持有的线索数。只算「已领取 + 跟进中」，不含已转商机 / 过期失效 / 作废。DB DEFAULT = 200。
_Avoid_: 最大持有、上限、hold

**每日领取上限**:
池配置字段 `daily_claim_limit`，单个销售每个自然日（`DATE(op_time) = CURRENT_DATE`）在本池最多领取的线索数。DB DEFAULT = 10。
_Avoid_: 日领取限、领取限额、daily limit

**池删除保护**:
公海池软删；但**池下有非终态线索时禁止删除**（非终态 = 未分发 / 待领取 / 已领取 / 跟进中）。防止孤儿线索。
_Avoid_: 级联删除、强制删除

**池占用查询端口**:
公海池删除守卫的跨模块出站契约 `PoolLeadOccupationPort`（crm-rule 定义，crm-lead 实现，ADR-0025）。方法 `hasActiveLeads(poolId)` 返回 boolean——true=池下有非终态线索（禁止删除）。与 `OpportunityCreationPort`（crm-lead 定义等商机实现）方向相反的同型 outbound port；crm-rule 通过 `ObjectProvider` 可选注入，port 未实现时 fail-safe 拒删。
_Avoid_: 占用检查服务、lead 查询接口（要点是「crm-rule 声明契约、crm-lead 实现、依赖倒置不破坏方向」）

**池批量删除**:
`deletePoolBatch` 一行委派 crm-base `BatchRunner.run(ids, self::deletePool, PoolBatchFailItem::bizOf, PoolBatchFailItem::unknownOf)`（ADR-0028）——非原子、逐条经 self 代理走独立事务、部分成功；失败项 `PoolBatchFailItem`（poolId + `PoolBatchFailReason` + message）与 code→reason 翻译、兜底文案（「删除失败」）由本域自持（ADR-0023 D5）。曾内联的同构编排（与 crm-lead 旧 runBatch 逐字重复）已删除——批量编排协议的家在 crm-base。
_Avoid_: 批量删除服务、池批处理（要点是「编排委派 BatchRunner + 失败语义留在域内」）

## 商机规则子域（票 05 起）

**商机公海规则**:
商机公海/回收/领取/提醒的**版本化规则配置** `opportunity_pool_rule`（票 05 原型 A7-3-2-5）：同一 `rule_code` 多版本每版本一行，范式 = 草稿/发布中/已停用 + `version_no`（与票 06 阶段模板、票 07 方案卡模板同族 V-CONFIG），**不是** `lead_pool` 那种「一部门一池」实体（无省/市/区地理维度、无领取/持有上限）。五配置项：`allow_manual_pool` / `auto_recycle_enabled`+`recycle_days` / `allow_free_claim` / `recycle_remind_enabled`+`remind_days`（提醒依赖回收启用，`remind_days < recycle_days` 硬校验）。适用范围两档：所有部门通用（可设默认）/ 对应部门专用（适用部门多值子表 `opportunity_pool_rule_dept`）。
_Avoid_: 商机公海池（无池实体）、商机池、线索池

**规则版本状态机**:
`IOpportunityPoolRuleService` 承担的版本生命周期约束（票 05「二」）：同 `rule_code` 仅一草稿一发布中；发布使原发布中转停用、原发布中默认自动取消默认（默认唯一是自动顶替非拒绝）；发布时校验**部门覆盖唯一**（一个部门只被一条发布中规则覆盖，重叠拒发 64012）——保证匹配「最低层级必唯一命中」；编辑发布中/停用版本→生成新草稿（版本号 minor 顺延 V1.0→V1.1，同 code 已有草稿则拒 64011）；复制→独立新规则（新 `rule_code` + V1.0 草稿）；仅草稿可删。版本号/编码系统生成只读。三票（票 05/06/07）逐字重复的版本机制——minor 顺延、编码顺延、纯状态迁移——收敛于 `service.impl.VersionedConfigSupport` 基类（三 ServiceImpl 继承，领域校验/子表替换仍各票自持）；三票版本关联子表的版本列统一 `rule_version_id` / `template_version_id`（快照子表如 `opportunity_scheme_card_field.template_id` 保持原名）。
_Avoid_: 商机状态机（那是 opp_status 归属流转轴，两回事）、直线版本号（minor 顺延非末尾+1）

**公海规则匹配引擎**:
`OpportunityPoolRuleMatcher`（快照式 API：`loadPublished()` 一次加载全部发布中规则 + 部门子表，`match(ownerDeptId)` 纯内存匹配）：部门专用（apply_scope=2 命中）优先 → 通用默认（apply_scope=1 且 is_default=1）兜底 → **非默认通用不兜底**（null = 无规则不动作）。公海规则**实时匹配不锁版本**（与阶段模板锁版相反，PRD §5.4）——每次 Job 扫描重载快照。供商机侧维护 Job 批量扫描，避免逐商机查库。
_Avoid_: 锁版本（公海规则实时）、按查看人部门匹配（锚点是商机自身 owner_dept_id）

**方案卡字段库种子**:
`SchemeFieldDefInitializer`（@Order(15)）首装植入两样东西：系统字段库 `opportunity_scheme_field_def`（16 项，含 `site_survey_files` 现场勘察资料 ATTACHMENT，`delete_key` 软删唯一索引）+ 全公司通用**兜底模板**（固定编码 `OPP_SCHEME_TPL_01`，发布中 8 字段，PRD §7.2/附录 A：建卡入口无候选时兜底；编码与 `nextCode` 顺延兼容——首装种子持 01、后续新建从 02 起）。幂等键=模板编码，任意状态（含已停用）存在即跳过——管理员停用兜底模板后重启不复活。
_Avoid_: 前台配置接口建字段库（种子属首装初始化）、停用后重启复活（幂等键含已停用）