luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
145 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Branch: master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
crm-backend-matt/.scratch/customer-module/issues/08-transfer.md

10 KiB
Raw Permalink Blame History

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

Type: research Status: resolved 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

Status: resolved（含 1 个 ⚠ 决策挂号：直属销售总监确定方式）

A. 流程模型（定稿，两段式）

发起交接(离职人员→接收总监)  →  客户分配(接收总监→具体销售)
   owner 变为总监               owner 变为销售
   生成交接单(待分配)            逐客户/批量分配
  • 只允许离职/调动/区域调整的销售本人发起本人名下客户的交接（主管/管理员不可代办，原型二.2 明文）。
  • 可交接客户 = 该销售为唯一负责人 且 未删除 且 非公海；仅协同人的客户不纳入。
  • 接收总监：离职 = 系统自动确定唯一直属销售总监；调动/区域调整 = 在本人启用的直属销售总监范围内搜索选择。
  • 交接单：全部变更成功才生成（整批原子）；生成唯一交接编号 + 状态「待分配」+ 进度 0/N。

B. 实体（定稿）

B1. 交接单 customer_transfer

Java 字段 列名 类型 说明
id id bigint 主键
transferNo transfer_no varchar(32) 交接编号（唯一，生成规则对称商机编号）
fromUserId / fromUserName from_user_id / from_user_name — 离职/调动人员快照
toDirectorId / toDirectorName to_director_id / to_director_name — 接收总监快照
reason reason varchar(20) 交接原因字典：员工离职/岗位调动/区域调整
remark remark varchar(500) 备注（选填）
totalCount total_count int 本次交接客户总数
assignedCount assigned_count int 已分配数（进度 = assigned/total）
status status tinyint 0待分配 / 1已完成
createBy / createTime / updateBy / updateTime — — BaseEntity

无孤立单大写字母陷阱。

B2. 交接明细 customer_transfer_detail

Java 字段 列名 类型 说明
id id bigint 主键
transferId transfer_id bigint 交接单 id
customerId customer_id bigint 客户 id
assignStatus assign_status tinyint 0待分配 / 1已分配
assignUserId / assignUserName assign_user_id / assign_user_name — 分配对象快照（待分配时 NULL）
assignTime assign_time datetime 分配时间
  • UNIQUE(transfer_id, customer_id) 去重。

C. 事务语义（定稿，跨模块）

  1. 发起交接（整批原子）：
    • 遍历本次客户，对每个客户：owner_user_id → to_director_id；移出 from_user 团队身份；保留原协同人。
    • 对每个客户的关联商机（crm-opportunity）owner_user_id → to_director_id。
    • 关联项目 owner 同步 = seam（A5 未建；本图只定义 port 契约，实现时项目侧跳过并标注）。
    • 任一失败 → 全部回滚，不生成交接单（原型三.确认交接 §7 明文）。
  2. 客户分配（整批/单个）：
    • 待分配明细 → 选分配对象（接收总监有权分配范围 + 启用的销售 + 不得为 from_user 本人 + 不得是当前负责人）→ owner_user_id → assign_user_id，同步关联商机/项目 owner。
    • 单个失败不整体回滚（批量按逐条独立事务），失败项列原因。
  3. 防重入：同一 from_user 存在未完成交接单时，禁止再次发起（原型三.确认交接 §1）。

D. 契约（定稿）

POST /api/customer/transfer/initiate         发起交接（整批原子，返回交接编号）
GET  /api/customer/transfer/{id}/preview     发起前客户预览（按原因算可交接客户）
GET  /api/customer/transfer/{id}             交接详情
GET  /api/customer/transfer/page             交接记录（交接编号/人员/原因/状态过滤）
POST /api/customer/transfer/{id}/assign      客户分配（单个或批量 customerIds + assignUserId）
GET  /api/customer/transfer/{id}/assignable  可分配销售列表（接收总监范围 + 启用）

E. ⚠ 挂号：直属销售总监怎么定（需拍板）

原型要求：离职时系统自动确定唯一直属销售总监；调动/区域调整时在启用的直属销售总监范围选择。核心是「直属销售总监」的确定口径：

我的推荐：不加 SysUser 字段，用组织架构现有层级推导——按 from_user 所在部门向上找「部门负责人」（dept.leader_user_id 或等价），若该负责人是「销售总监」角色则命中；无/停用/多条则按原型阻断并提示「联系管理员维护组织关系」。

理由：① 组织架构已有部门负责人概念，不引入新字段；② 直属关系是组织属性而非用户属性，加 superior_user_id 会带来维护和一致性问题；③ 原型明说「无/停用/多条直属关系 → 阻断」，天然容忍推导失败。

备选：SysUser 加 superior_user_id（直属上级），由后台维护；查询 O(1)，但需改 auth 模块 + 维护成本。

你选哪个？选推荐则票 08 冻结；选备选则回填 crm-auth 加字段。

F. 回填 / 下游

  • 票 03：owner 变更（分配=换主）复用 oplog 语义；交割是分配动作的跨模块扩展版。
  • 票 07：oplog 记录 TRANSFER 动作 + customer_transfer 表变更；跨模块同步操作人显「系统」+ 交接编号。
  • crm-opportunity：需要商机侧提供「按 customer_id 批量改 owner」的 port（或复用商机分配逻辑）。
  • A5 项目：项目 owner 同步 seam（port 契约占位）。
  • crm-dict：transfer_reason 分组（员工离职/岗位调动/区域调整）。

G. 待产品确认（⚠）

# 问题 影响
P0-1 交接单「已完成」的判定：assignedCount == totalCount 自动完成，还是总监手动点「完成交接」？原型进度 0/N → 推荐自动完成（全部分配完即完成） status 迁移