crm-backend-matt/.scratch/clue-module/issues/03-线索状态机权威定义.md

# 线索状态机权威定义

Type: grilling
Status: claimed
<!-- C（线索作废）待产品确认；其余边继续 grill -->

## Question

将散落在各原型页面的状态收敛为 `crm-lead` 的**权威状态机**，作为全域第一块地基。已定：单字段、7 个状态——`待领取 / 已领取 / 未分发 / 过期失效 / 线索作废 / 已转商机 / 跟进中`。

需在本 ticket 定清：

1. **每个状态的精确定义**：各状态代表什么、与"反馈情况（有效/无效/未反馈）"这个独立字段如何并存（"跟进中"是流转态，"有效/无效"是反馈态）。
2. **合法迁移边**：画出状态转移图。关键路径：
   - 待领取 →（领取/分配）→ 已领取 →（反馈）→ 跟进中 →（转商机）→ 已转商机
   - 待领取/未分发 与 已领取 的关系（"未分发"是管理侧对"待领取但需分配"的叫法，还是独立态？）
   - 过期失效 / 线索作废 的入口（谁把线索置为作废？失效由定时任务置？）
   - 释放：已领取/跟进中 →（释放）→ 待领取（清领取人）
3. **各状态下允许的操作**（编辑/详情/反馈/转商机/释放/删除/领取/分配/关注）——收敛四个视图里不一致的按钮渲染规则为一张"状态 × 操作"权威矩阵。
4. **回收对状态的影响**：超时回收 → 待领取 + 清领取人；这算不算一条显式迁移边。

产出：状态定义表 + 状态转移图 + "状态 × 操作"矩阵，写入 ## Answer；未来写进 `crm-lead/CONTEXT.md`。

## Open questions（阻塞定稿）

- **[C] 线索作废的触发/入口/可逆性 —— 待产品确认。** 原型全文未说明谁触发作废、从哪些状态进入、作废后是否回流公海、能否恢复。原型旁证："我的线索"里反馈"无效/空号"的行状态显示为"线索作废"，暗示"反馈=无效"可能触发作废，但自动/手动、可逆性均未定。**本 ticket 在 C 明确前不能标 resolved。**
- **[F] 管理员激活已失效线索后回到什么状态？** 已定：见下方定稿 [F]。

## 已 grill 定稿的结论（增量记录，最终汇总进 ## Answer）

- **[A] 未分发 vs 待领取 = 是否已归池**：未分发 = 管理员新建/导入但尚未分配到任何公海池（悬于池外）；待领取 = 已分配进某公海池、尚无归属销售、池内成员可自领。二者是独立状态。
- **[A-初始态] 初始状态由"建时是否归池"决定**：销售在"我的线索"新增（自动带出本人所属池）→ 已归池 → 待领取（勾"是否领取"则直接→已领取）；管理员在"线索管理"新建/导入未指定池 → 未分发；指定了池 → 待领取。
- **[A-分配] "分配"是可选深度动作**：可只分配到公海池（未分发→待领取），也可一步指定到某销售（未分发/待领取→已领取，领取人=被指派销售）。
- **[B] 转商机前置 = 已领取 或 跟进中**（B2）：领取后即可转，不强制先反馈；"反馈=有效"仅展示，不作门槛。转商机后状态→已转商机。
- **[D] 过期失效的归属（以产品最新规则为准，已纠正早前 D1）**：失效可发生在任何持有态下——若失效时线索正被销售持有，则仍挂领取人名下、只可查看不可删除；若失效时在公海（未领取/未分发），则是一条无归属的失效线索。失效线索一律不可删。
- **[E] 双计时器（以产品最新规则为准，已推翻早前 E1推断）——两套独立逻辑，起点不同、互不干扰**：
  1. **超时回收公海（N 天）**：仅线索被销售领取到私海后开始计时；N 天无跟进自动退回公海；退回公海则该计时器清零，下次领取重新计时。作用：约束销售拿到线索后及时跟进。
  2. **线索失效时长（M 天）**：从线索【创建时间】起持续计时，无论在公海还是在我的线索（已领取），时间持续跑、不受回收公海操作影响、不会清零。到期直接置失效（无论当时在公海还是私海）。
  3. **管理员手动激活已失效线索** → 失效计时器重置，从激活时间重新计算 M 天有效期。
- **[F] 激活后目标状态 = F2 恢复原态**：管理员激活失效线索 → 恢复到失效前的状态与原领取人（失效前是已领取/张三→恢复为已领取/张三；失效前在公海→恢复为待领取/未分发对应态）。
- **[G] 释放/回收目标态 = 待领取**：手动释放与超时回收一律 → 待领取 + 清领取人（回原公海池待领，不回未分发）。
- **[H] 已转商机 = 终态**：不能再释放/回收/反馈；超时回收与失效两个计时器均冻结。（覆盖原型"已转商机仍可编辑/反馈"的说法，以产品为准：终态锁死。）

## Answer（权威状态机；C 明确前为准定稿，标 blocked-on-product）

> 说明：以下为除"线索作废"(C) 外的完整定稿。作废相关的边/矩阵格用 `⚠C` 标出，待产品确认后补。

### 一、状态定义表（单字段 `leadStatus`，7 态）

| 状态 | 含义 | 领取人 | 计时器 | 备注 |
|------|------|--------|--------|------|
| 未分发 | 管理员新建/导入，**未归属任何公海池**，悬于池外 | 无 | 失效(M)跑 | 仅管理员可分配 |
| 待领取 | 已分配进某公海池，尚无归属销售，池内成员可自领 | 无 | 失效(M)跑 | 领取/分配的来源态 |
| 已领取 | 某销售持有、尚未产生反馈 | 有 | 回收(N)跑 + 失效(M)跑 | 领取后即可转商机 |
| 跟进中 | 持有销售已产生至少一次反馈 | 有 | 回收(N)跑 + 失效(M)跑 | 反馈使 已领取→跟进中 |
| 已转商机 | 已转化为商机，**终态** | 保留 | 全部冻结 | 不可释放/回收/失效/反馈 |
| 过期失效 | 失效计时(M)到期；可发生在任何非终态 | 失效时若被持有则保留、否则无 | 冻结（除激活重置） | 只读、**不可删除**；可被管理员激活恢复 |
| 线索作废 | ⚠C 待产品确认 | ⚠C | ⚠C | ⚠C |

反馈情况（有效/无效/未反馈）是**独立字段**，不进状态机。

### 二、状态转移图

```
              ┌─────────────── 管理员分配到池 ───────────────┐
              │                                              ▼
   [新建/导入未归池]                                     [待领取] ◀────┐
        │                                              │  ▲  │        │
        ▼                                              │  │  │        │ 释放 / 超时回收N(清领取人)
   ┌─[未分发]                                          │  │  │        │
   │     │ 分配到池                                     │  │  └──领取/分配──┐
   │     └──────────────────────────────────────────▶ │  │              ▼
   │     │ 分配并指定销售                                │  └───────────[已领取]
   │     └──────────────────────────────────────────────────────────▶ │  │
   │                                                                   │  │ 反馈(首次)
   │                                                                   │  ▼
   │                                                              [跟进中]
   │                                                                │  │
   │  销售在"我的线索"新增(自动归本人池) ─▶ [待领取] (勾"是否领取"─▶[已领取])
   │                                                                │  │ 转商机(已领取/跟进中)
   │                                                                ▼  ▼
   │                                                           [已转商机] (终态)
   │
   └── 失效计时M到期(从创建时间算,不清零,任何非终态) ─▶ [过期失效]
                                                        │  ▲
                                          管理员激活(F2,恢复失效前态+原领取人)
                                                        └──┘
   [线索作废] ⚠C 触发/入口/可逆性待产品确认
```

### 三、迁移边清单

| # | from | 触发 | to | 副作用 |
|---|------|------|-----|--------|
| 1 | (新建·管理员未归池) | 新建/导入 | 未分发 | 启动失效计时M(创建时间) |
| 2 | (新建·已归池/销售新增) | 新建/导入(指定池) | 待领取 | 启动失效计时M |
| 3 | 待领取(销售新增勾"领取") | 新增即领 | 已领取 | 设领取人=本人；启动回收计时N |
| 4 | 未分发 | 管理员分配到池 | 待领取 | 归池 |
| 5 | 未分发/待领取 | 管理员分配并指定销售 | 已领取 | 设领取人=被指派销售；启动回收N |
| 6 | 待领取 | 成员自助领取 | 已领取 | 设领取人=本人；启动回收N |
| 7 | 已领取 | 首次反馈 | 跟进中 | 写反馈记录 |
| 8 | 跟进中 | 再次反馈 | 跟进中(自环) | 写反馈记录；回收N续期(见下) |
| 9 | 已领取/跟进中 | 转商机(B2) | 已转商机(终态) | 调 OpportunityCreationPort；写"转商机"记录；冻结所有计时器 |
| 10 | 已领取/跟进中 | 手动释放 | 待领取 | 清领取人；回收计时N清零 |
| 11 | 已领取/跟进中 | 超时回收(N天无跟进) | 待领取 | 清领取人；回收计时N清零 |
| 12 | 任何非终态(未分发/待领取/已领取/跟进中) | 失效计时M到期 | 过期失效 | 若被持有则保留领取人；只读 |
| 13 | 过期失效 | 管理员激活(F2) | 恢复失效前状态+原领取人 | **重置 N 和 M**（`recycle_deadline=now+pool.N`，`expire_deadline=now+pool.M`） |
| C | ⚠ | ⚠ | 线索作废 | ⚠ 待产品确认 |

**计时器口径**：
- 回收N：仅私海(已领取/跟进中)计时；"无跟进"=N天内无新反馈；有反馈则续期重计N；退回公海则清零。
- 失效M：从**创建时间**起全程持续跑，不受在公海/私海、回收操作影响，不清零；仅"已转商机"冻结、"管理员激活"重置。

### 四、状态 × 操作 权威矩阵

（✓=可操作，�— 不可见/不可操作；按状态收敛四视图按钮渲染，角色权限叠加见 ticket 05）

| 操作 | 未分发 | 待领取 | 已领取 | 跟进中 | 已转商机 | 过期失效 | 线索作废 |
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| 详情(查看) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 编辑 | ✓ | ✓ | ✓(持有人) | ✓(持有人) | ✓— (终态锁) | ✓— (只读) | ⚠C |
| 领取 | ✓— | ✓(成员) | ✓— | ✓— | ✓— | ✓— | ✓— |
| 分配 | ✓(管理) | ✓(管理) | ✓— | ✓— | ✓— | ✓— | ✓— |
| 反馈 | ✓— | ✓— | ✓(持有人) | ✓(持有人) | ✓— (终态锁) | ✓— | ⚠C |
| 转商机 | ✓— | ✓— | ✓(持有人) | ✓(持有人) | ✓— | ✓— | ✓— |
| 释放 | ✓— | ✓— | ✓(持有人) | ✓(持有人) | ✓— | ✓— | ✓— |
| 关注/取关 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 删除 | ✓(管理) | ✓(管理) | ✓(管理·强确认) | ✓(管理·强确认) | ✓(管理·强确认) | ✓(管理/持有人·强确认) | ⚠C |
| 激活 | ✓— | ✓— | ✓— | ✓— | ✓— | ✓(管理) | ✓— |

> 注：编辑/反馈的"(持有人)"表示仅当前领取人可操作；"管理"表示需部门负责人/超管权限（详见 ticket 05）。已转商机为终态，编辑/反馈按产品拍板一律锁死（覆盖原型旧说法）。

### 五、待产品确认后收尾

- **[C] 线索作废**：触发方/入口状态/作废后归属与可逆性 → 补边 C、矩阵 ⚠C 格、状态定义表末行。C 明确即可将本 ticket 置 resolved。

---

## Amendment 1（2026-08-12 grill）

### A1.1 边 #13 激活时 N 也重置（grill #6）

**改前**：激活只重置 M（`expire_deadline = now + pool.M`），N 保持失效前的值（若已过期则被下一次 tick 回收）。

**改后**：激活时 **N 和 M 均重置**：
- `recycle_deadline = now + pool.recycle_days`（若失效前是已领取/跟进中）
- `expire_deadline = now + pool.expire_days`

**理由**：产品确认 M 的起始时间 = 线索创建时间或重新激活时间；N 同理也应从激活时刻重新起算，给足完整的跟进窗口，否则激活后立刻被 tick 回收。

**影响**：边 #13 副作用列已更新；PRD §6.8 已更新；原型引擎 `activate()` 已修改。

### A1.2 过期失效线索可删（grill #4 + #11）

**改前**：矩阵“过期失效 × 删除” = `✗ 不可删`。

**改后**：矩阵“过期失效 × 删除” = `✓(管理/持有人·强确认)`。

- **管理**可删（强确认）——grill #4
- **持有人**可删自己的过期失效线索（强确认）——grill #11，原型“我的线索”页面有删除按钮

**理由**：过期失效是只读死数据，如果管理员不激活，永久占在列表里；让持有人自己清掉合理。

**影响**：矩阵已更新；PRD §3.3 已更新。