# 线索业务（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