# 01 · CustomerOwnershipWriter：客户归属写入器（收五处手搓换主协议 + enter_pool_time 修复）

- **Status:** open
- **Type:** task

来源：`/improve-codebase-architecture` 第四轮（2026-09-07，候选 #1）+ grilling 八项拍板。决策全文见 **ADR-0034**（`docs/adr/0034-customer-ownership-writer.md`）；术语见 `crm-customer/CONTEXT.md`「归属写入器」。本票单票一体（组件 + 五接线 + bug 修复 + 测试 + 文档），实现另起会话。

## 目标

customer 表 owner 列族的换主协议（快照四列 + D25 锚点 + 在职守卫 + CAS 空列清空）从 5 份手搓收成单一事实源；顺手修复 assign / 交割两段 `enter_pool_time` 未清空的现存契约违约。

## A. 新组件 ×2（`com.crm.customer.service`，具体 @Component 零接口，Writer 家族同构）

1. **`CustomerOwnershipWriter`** 三动词，mutate + 落库一体（事务边界留调用方外层 @Transactional）：
   - `initOwnerOnCreate(Customer entity, Long ownerUserId)`：mutate-only（insert 留调用方）。ownerUserId 空 = 公海分支（清四列快照 + enterPoolTime=now + 锚点 NULL）；非空 = 守卫 + 快照 + 锚点=now。
   - `changeOwner(Customer c, Long targetUserId)`：在职守卫（67012）→ 同主拒绝（67012）→ 快照四列 → 锚点空则 now、非空保留（统一规则，五场景无损）→ enterPoolTime **wrapper 显式清空** → CAS 落库（0 行 → 67005）。守卫依赖 IAuthUserService / ISysDeptService，落库依赖 CustomerMapper。
   - `releaseToPool(Customer c)`：清 owner 两列（wrapper）+ enterPoolTime=now + 锚点保留 + CAS。协同人清空（teamMemberMapper.releaseAllByCustomerId）与进行中商机守卫**留调用方**。
2. **`CustomerNoGenerator`** `nextCustomerNo()`：KH+yyyyMMdd+4 位序（当日 MAX 续号），合并两版防御分支——脏序号 catch NumberFormatException 重起 1 + 封顶 9999。

守卫错误码统一直抛 67012（消息「销售负责人不存在、已停用或已离职」/「不能分配给当前负责人」），对称 CustomerDedupService 域内直抛；不用专用异常翻译（那是跨域 seam 口径）。

## B. 五调用点接线

| 调用点 | 改法 |
| --- | --- |
| `CustomerServiceImpl.create` | applyOwner → `initOwnerOnCreate`；nextCustomerNo → generator（构造器加 2 参） |
| `CustomerOwnershipServiceImpl.claim` | applyOwnerSnapshot + casUpdate → `changeOwner(c, currentUserId())`；claim 的 enterPoolTime wrapper 清空随之并入（现状行为不变） |
| `CustomerOwnershipServiceImpl.assign` | 同上 `changeOwner(c, targetUserId)`——**bug 修复点：enter_pool_time 从未清空（实体置 null + 平式 updateById 被 MP NOT_NULL 策略跳过），此处起真正清空** |
| `CustomerTransferServiceImpl.initiate` / `assignOne` | 内联换主循环 / applyAssigneeSnapshot + casUpdate → `changeOwner`（两处都修复 enter_pool_time） |
| `CustomerImportExecutor.createCustomer` | 手搓快照 + 锚点 + nextCustomerNo → `initOwnerOnCreate` + generator（离职 submitter 该行 fail——行为变化，见 D） |

删各服务的 applyOwner / applyOwnerSnapshot / applyAssigneeSnapshot / validateTargetUser / casUpdate / nextCustomerNo 私有方法（validateTargetUser 若仍被批量前置校验引用则保留一处）。

## C. 测试（双层）

1. 新增 `CustomerOwnershipWriterIntegrationTest`（H2，CustomerH2Harness 自举）：设主锚点空则 now / 非空保留、**enterPoolTime 清空含 assign 场景（bug 防回归）**、公海分支、同主拒绝 67012、离职守卫 67012、CAS 冲突 67005、NoGenerator 脏序号重起 1 + 封顶 9999。
2. 既有 4 个流程集成测试（WorkspaceOwnership / Transfer / Import / ServiceImpl）原样保留作端到端锚；补 assign/交割后 enterPoolTime 清空断言（现状零断言即漏网原因）。

## D. 行为变化清单（ADR 已记，bruno 同步）

1. assign / initiate / assignOne 换主后 enter_pool_time 真正清空（修复违约，实体 javadoc 契约恢复）。
2. create / quickCreate 端点 owner 守卫失败 67001 → **67012**（bruno 文档同步）。
3. 交割发起人 = 部门 leader 的自分配被同主拒绝（原先静默换主给自己）。
4. 导入建档离职 submitter：原先不设防静默写快照 → 该行 fail（executor 逐行软处置兜住）。

## 验收

- `mvn test -pl crm-customer -am` 全绿；BOM 扫描 clean（AGENTS.md 编码条款）；
- 全模块 grep 手动 `new CustomerServiceImpl|CustomerOwnershipServiceImpl|CustomerTransferServiceImpl|CustomerImportExecutor|CustomerWorkspaceServiceImpl` 的测试构造点并同步加参（历史坑：加依赖后手动 new 的测试编译红）；
- ADR-0034 / CONTEXT.md 词条已落（本票前序已完成）；bruno 的 create/quickCreate 错误码示例同步 67012。

## Comments

- grilling 拍板记录（八问全选推荐项）：只收协议机制 / mutate+落库一体 / 三动词 / 统一 67012 / NoGenerator 独立 / CustomerOwnershipWriter 定名 / 双层测试 / 单票一体。
- 锚点统一规则推演：create 恒 now ⇔ 实体锚点 null 时「空则 now」；assignOne 不设 ⇔ 锚点必非空时「非空保留」——五场景零行为变化（除 D 清单）。