crm-backend-matt/.scratch/customer-ownership-writer/issues/01-ownership-writer.md

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

• Status: resolved
• 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。

Answer

2026-09-07 落地（实现会话）：组件 ×2 + 五接线 + 双层测试 + bruno 同步全部完成；mvn test -pl crm-customer -am 全绿（crm-customer 186 tests / 0 failures，含依赖 7 模块全 SUCCESS），BOM 扫描 clean。

• 组件：CustomerOwnershipWriter（129 行）/ CustomerNoGenerator（40 行）如票 A 节；Writer 不挂 @Transactional（事务留调用方）。实现期修正一处：BaseMapper.update 返回 int 非 boolean，CAS 判 0 行用 == 0（!int 编译不过）。
• 五接线：create / claim / assign / initiate + assignOne / 导入建档全部改走 Writer + generator；claim 的公海守卫、商机守卫与 oplog 留各调用方，现状行为不变。
• 实施差异（票面未细化处，如实记）：
  • validateTargetUser 未删而 void 化保留——assignBatch 批量前置统一校验仍引用（B 节末行预留情形）；单条守卫已收编 Writer。
  • casUpdate 收敛为 casUpdateNoClear（this.updateById + 0 行→67005）留 OwnershipServiceImpl，仅 archive/restore 用。
  • 交割 initiate 的 CAS 失败消息统一为 Writer 文案「客户已被他人变更，请刷新后重试」（原「客户【name】已被他人变更」；测试无消息断言，安全）。
  • 导入建档离职 submitter：67012 被 executeImport 行级 catch 软处置兜住 → 该行 fail「执行异常：销售负责人不存在、已停用或已离职」（D4 预期形态）。
• 测试：CustomerOwnershipWriterIntegrationTest 14 用例全绿（锚点空则 now / 非空保留、assign 场景 enterPoolTime 清空防回归、建档两分支、同主/停用/缺失 67012、CAS 冲突 67005、抛公海保留锚点、NoGenerator 续号/脏序号重起/封顶 9999）；4 个流程集成测试补 6 处 getEnterPoolTime()).isNull() 断言（WorkspaceOwnership claim+assign、Transfer initiate+assignOne——两处均先注入存量脏值模拟、Import E2E 建档、ServiceImpl create 建档）。
• bruno：新增客户.bru / 快速创建客户.bru 错误码清单各加 - 67012 销售负责人不存在、已停用或已离职（分配客户 / 批量分配原有 67012 语义一致不动）。
• 测试构造点：全模块 grep 五服务手动 new 共 9 处（6 文件）——7 处改参同步（WorkspaceOwnership ×2、Transfer、ServiceImpl、Contact、CatalogPort、Import），CustomerWorkspaceServiceImpl ×2 签名未变无需动。

Comments

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