crm-backend-matt/.scratch/customer-module/issues/08-transfer.md

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)