7.3 KiB
线索业务（crm-lead）
线索的全生命周期业务域：线索实体与 7 状态机、四视图（公海 / 我的线索 / 我的关注 / 线索管理）、领取 / 分配 / 反馈 / 转商机 / 释放等流转，以及超时回收与失效两个定时任务。依赖方向单向 crm-lead → crm-rule → (crm-auth / crm-dict)；公海池实体归 crm-rule，本模块只消费。访问控制走三机制模型（详见 .scratch/clue-module/权限与数据可见性-PRD.md）。
Language
线索:
一条待转化的销售机会记录，crm-lead 的核心聚合根。有单一状态字段 leadStatus（7 态），归属由 owner_user_id（领取人）+ dept_id（所属公海池归属部门）表达。全生命周期最终走向「已转商机」或被清理。
Avoid: clue、商机（商机是转化后的下游实体）、客户
领取人:
当前持有该线索的销售，存于 owner_user_id。只有「已领取 / 跟进中」态有领取人；释放、超时回收、进入作废时清空。领取人是「我的线索」视图的第一层业务过滤依据（owner_user_id = 当前用户）。
Avoid: 负责人（负责人是公海池概念）、持有者、拥有人
创建人:
录入该线索的用户，全生命周期不变。删除权限的判定依据之一——删除 = (状态≠已转商机) AND (管理员 OR 创建人)（强确认；已转商机为删除禁区）。
Avoid: 录入人、owner（owner 是领取人）
所属公海池归属部门:
线索的 dept_id，恒等于其所属公海池的归属部门，全生命周期不变动（决策 [I]）。是数据范围天花板过滤的唯一部门维度。销售可领取/可见其所属**部门集合（主+兼职）**的公海池线索（grill #5）；领取口径与 crm-auth ABAC DEPT 档一致（都按部门集合算，ADR-0005），“能领=能看”自洽。
Avoid: 领取人部门、归属部门、owner_dept
反馈情况:
线索的独立字段（有效 / 无效 / 未反馈），不进状态机，与 leadStatus 并存。是「反馈=无效自动作废」「反馈=有效使作废恢复」两条迁移边的触发内容，但字段本身独立记录。
Avoid: 反馈状态、跟进结果、线索质量
反馈记录:
销售对线索的一次跟进记录，存于独立表 lead_feedback（DRAFT / SUBMITTED 两态，草稿可暂存、可上传附件）。主表冗余最新一条的反馈情况值供列表展示；释放 / 回收时反馈快照不清空（供下一位参考）。
Avoid: 跟进记录、feedback（英文）、备注
未分发: 线索状态之一：管理员新建 / 导入但未归属任何公海池，悬于池外。仅管理员可将其分配到池。与「待领取」的区别是「是否已归池」。 Avoid: 未分配、待分配、草稿态
待领取: 线索状态之一：已分配进某公海池、尚无领取人，池内成员可自领。是领取 / 分配的来源态，也是释放 / 回收 / 激活作废的目标态。 Avoid: 公海线索、未领取、待认领
已领取: 线索状态之一：某销售持有、尚未产生反馈。领取后即可转商机，不强制先反馈。启动回收计时 N。 Avoid: 已认领、私海线索、跟进态
跟进中: 线索状态之一：持有销售已产生至少一次反馈。再次反馈为自环并续期回收计时 N。 Avoid: 联系中、有效（有效是反馈情况）
已转商机:
线索终态：已调 OpportunityCreationPort 转化为商机。锁死——不可释放 / 回收 / 反馈 / 编辑，回收与失效两个计时器均冻结。
Avoid: 已成交、已转化、完成
过期失效: 线索状态之一：失效计时 M 到期（从创建时间起算）。可发生在任何非终态；失效时若被持有则保留领取人、只读。可被管理员激活（F2）恢复到失效前状态与原领取人，并重置 N 和 M。 Avoid: 过期、失效、废弃
线索作废:
线索状态之一：销售提交反馈且反馈情况=无效时自动进入（无需手动点按钮），入口态为「已领取 / 跟进中」。进入时清空 owner_user_id。可恢复——管理员可分配给新销售（仍保持作废态），被分配销售提交反馈=有效时恢复到「已领取」。失效计时 M 在作废态下继续跑。
Avoid: 作废、无效线索（无效是反馈情况）、删除
回收计时 N:
超时回收公海的计时器：仅线索被销售领取到私海（已领取 / 跟进中）后计时，N 天内无新反馈则自动退回公海（→待领取、清领取人）。有反馈则续期重计，退回公海则清零。天数取所属公海池的 recycle_days。
Avoid: 超时时间、回收天数、N 天
失效计时 M:
线索失效的计时器：从创建时间起全程持续跑，无论在公海或私海、不受回收操作影响、不清零。到期直接置「过期失效」。仅「已转商机」冻结、「管理员激活」重置。天数取所属公海池的 expire_days。
Avoid: 有效期、失效天数、M 天
分配:
管理员把线索指派出去的动作，是可选深度动作：可只分配到公海池（未分发→待领取），或一步指定到某销售（→已领取，领取人=被指派销售）。分配 = 改 owner_user_id，不发行级授权通行证（决策 [D]）。作废线索也可被分配（分配后仍作废）。
Avoid: 指派、派发、授权
释放: 持有销售主动把线索退回公海的动作：已领取 / 跟进中 → 待领取，清领取人，回收计时 N 清零。与超时回收（系统自动）目标态相同，区别是触发方。 Avoid: 退回、放弃、回收（回收是系统动作）
激活: 管理员对过期失效线索的恢复动作（F2）：恢复到失效前状态与原领取人，重置 N 和 M。注意与「作废恢复」不同——作废靠「分配+反馈=有效」恢复，不走激活。 Avoid: 恢复、复活、重置
关注:
用户对线索的收藏关系，存于 lead_follow。「我的关注」视图 = id IN 关注表 AND 部门天花板。关注不走行级授权（决策 [F]）——可见性每请求按当前部门实时算，防止「人事误操作→关注→改回部门→长期越权」。关注总数现算不冗余。
Avoid: 收藏、订阅、star
操作日志:
线索的统一操作留痕表 lead_history，全量记录 11 种动作（CREATE / CLAIM / ASSIGN / FEEDBACK / CONVERT / RELEASE / RECYCLE / EXPIRE / ACTIVATE / VOID / EDIT）。反馈记录在此只记引用（正文在 lead_feedback）；作废（VOID）在 detail 保留原持有人供审计。是审计与纠纷排查的唯一来源，不靠授权表本身。详情页「历史记录」Tab 只展示 5 种（领取 / 释放 / 反馈 / 转商机 / 编辑），其余为审计用不上页。
Avoid: 变更记录、审计表、log
转商机端口:
线索转化为商机的出站契约 OpportunityCreationPort（商机模块尚不存在，本模块只定接口）。触发前置 = status IN (已领取, 跟进中)，反馈情况不参与判定。幂等 = 状态终态保护 + 商机侧 UNIQUE(source_lead_id)。事务前提：首个实现必须与 crm-lead 同库共享事务（本地事务性回滚）；若未来商机独立部署，转商机需重设计为最终一致 + 补偿。
Avoid: 商机接口、转化服务、OpportunityService