# 08 — 客户交割（跨模块同步商机/项目负责人）

Type: research
Status: open
Blocked by: 02, 03

## 问题

定客户交割全流程：发起交接 → 客户分配 → 交接记录 + 详情。核心难点是**跨模块负责人同步变更事务**（客户+关联商机+关联项目一起换主，要么全成要么全不成）。

## 一手证据（蓝湖缓存 txt）

- `a4-7-1_客户交割_发起交接_.txt` — 发起交接页（三 tab 之首）+ 交接原因/预览/确认弹窗 + **公共规则/字段规则/客户及关联业务变更/加载与操作反馈**（关键 spec 段）
- `a4-7-2_客户交割_客户分配_.txt` — 客户分配 tab（接收总监分配到具体销售）
- `a4-7-3_客户交割_交接记录_.txt` — 交接记录 tab
- `a4-7-4_交接记录详情.txt` — 交接记录详情

## 已知事实（关键提炼）

- **三 tab**：发起交接 / 客户分配 / 交接记录（+ 记录详情）。
- **交接原因**：员工离职 / 岗位调动 / 区域调整（单选必选）。
- **发起人**：仅销售**本人**可发起本人名下客户交接（不允许主管/管理员代发起）。
- **接收人**：仅交接人员的**直属销售总监**；员工离职时系统自动定唯一总监，岗位调动/区域调整时手选启用的直属总监。
- **可交接客户范围**：交接人员**当前为唯一负责人**的**未删除、未进入公海**客户；仅协同人身份的不纳入。
- **员工离职**：必须交接**全部可交接客户**（无勾选框）；**岗位调动/区域调整**：至少勾选1个，跨分页勾选。
- **发起交接后同步变更**：客户负责人 → 接收总监；**该客户全部关联商机 + 项目负责人同步变更为同一接收人**；协同人保留；商机/项目其他数据不变。
- **原子性**：客户+商机+项目负责人**全部成功**才算本客户处理成功；不允许出现「客户变了但关联商机未变」的中间态；任一失败整批不生效、不生成正式交接记录、当前表单/搜索条件/勾选保留。
- **客户分配 tab**：接收总监按交接批次把客户分配给具体销售（单条/批量）；分配对象排除交接来源人本人；同步变更客户+关联商机+项目负责人；成功后原负责人(接收总监)移出团队。
- **未完成交接约束**：同一交接人员有未完成交接记录时不允许再次发起。
- **交接记录**：唯一交接编号；初始分配状态=待分配，进度=0/N；随分配推进；跟操作日志区分（跨模块自动变更的操作人显示"系统"+注明交接编号）。

## 待拍板点

1. **跨模块负责人同步的事务边界**：
   - **推荐 A（同步事务）**：本地事务包含 customer 表 + 调用 crm-opportunity 的 `batchTransferOwner(oppIds, newOwner)` + 调用 crm-project 的同名接口；任一失败整批回滚。但 crm-project 未建 → 本图只做客户+商机两侧同步，项目侧留 seam（`ProjectOwnerTransferPort`）。
   - **推荐 B（异步 saga）**：客户先变，商机/项目通过消息异步跟；失败重试；对账。
   - 我倾向 **A（同步事务）**：原型明说「不允许出现中间态」→ saga 语义不匹配。同库单体阶段跨模块事务可行（同一 DataSource）。
2. **`customer_transfer` 表结构**：id/transfer_no/handover_user_id/receiver_dean_id/reason(enum)/remark/status(待分配/进行中/已完成)/total_count/assigned_count/create_time/finish_time。
3. **`customer_transfer_item` 子表**：id/transfer_id/customer_id/original_owner/new_owner(初始=接收总监)/final_assignee(分配后=最终销售)/status(待分配/已分配/失败)/fail_reason。
4. **「直属销售总监」怎么定**：读 crm-auth 的 SysDept 树 + 角色配置？→ 需与 crm-auth 现有事实核对，可能加个 `SysUser.superior_user_id` 字段（多角色时用「主直属」）。**本票关键 seam**。
5. **未完成交接锁**：数据层用 `handover_user_id` 上有一条 status ∈ (待分配/进行中) 的记录做互斥；发起前查一次。
6. **跳过与部分成功**：客户分配 tab 按客户逐条校验，任一失败不影响其他客户；返回 Toast 成功/失败数 + 逐条失败原因（部分失败不整体回滚）——**与发起交接的强原子性不同**（发起交接=全批同一事务，分配=按客户独立事务）。
7. **操作日志**：跨模块自动变更操作人显示「系统」+ 注明交接编号（票 07 oplog 字段 `operator_source` 支持 "system+transferNo=XXX"）。

## Answer

_(待 resolve)_