> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Task 生成、更新与关闭机制

> **Historical research / Superseded（2026-07-15）**：本文保留旧场景和历史问题，不再定义 Task lifecycle、SLA、Outcome 或 AI authority。现行规范见 [Task System Design](/product-design/v3/tasks-feature/task-domain-lifecycle.md)。

Contact Analysis（Pipeline 2 / contacts-analyzer）按**业务目标**识别客户当前场景，判定是否需要跟进。分类准则：这次跟进要达成什么业务目的？

***

# 第一部分：生成机制

## 一、触发方式

Follow-up Task 由 **Contact Analysis（Pipeline 2）** 生成。Per-Call AI（Pipeline 1）**不生成** Task，但可以通过设置 `follow_up_needed=yes` 触发 Pipeline 2 运行。

| 触发方式                  | 说明                                                                         | 频率          |
| --------------------- | -------------------------------------------------------------------------- | ----------- |
| **Cron 触发**           | 每日凌晨 06:00 UTC 自动运行，扫描过去 24h 有活动的客户，综合分析所有通话 + SMS + Contacts 数据           | 每日 1 次      |
| **Per-Call AI 触发**    | Per-Call AI（Pipeline 1）分析单通通话后设置 `follow_up_needed=yes`，直接触发 Pipeline 2 运行 | 每通通话后（条件触发） |
| **On-Demand Refresh** | 员工在 Tasks 页面点击 **"Refresh AI"** 按钮，立即对当前门店执行一次 Contact Analysis            | 手动触发，1 小时冷却 |

> **为什么 Per-Call AI 不直接生成 Task？** 单通通话的信息量不足以做出可靠的跟进判定。Contact Analysis 综合该客户的全部通话历史、SMS、Contacts 数据，才能准确判断是否需要跟进、跟进什么。Per-Call AI 的角色是**实时信号检测**——发现需要跟进的信号后触发 Pipeline 2 做综合判定。

### On-Demand Refresh

员工在两次 Cron 之间打了多通电话，想要 AI 立即根据最新通话数据更新任务列表，而不必等到次日凌晨。

| 项目       | 规则                           |
| -------- | ---------------------------- |
| **触发方式** | 点击 Tasks 页面的 "Refresh AI" 按钮 |
| **分析范围** | 与 Cron 触发相同（4 表全量数据）         |
| **冷却时间** | 同一门店 1 小时内只能触发一次             |
| **处理方式** | SQS 异步，前端每 2 秒轮询，最多等 15 秒    |

> 架构详情见 [AI 插入点行业调研](../../../industry-knowledge/ai-insertion-analysis-industry.md)。

***

## 二、AI 输出与 Task 字段映射

Contact Analysis 的输出直接映射为 Follow-up Task 的关键字段：

| AI 输出字段                       | → Task 字段                   | 说明                                               |
| ----------------------------- | --------------------------- | ------------------------------------------------ |
| `actionNeeded`                | —                           | `true` 时生成 Task；`false` 时不生成                     |
| `suggestedActions[].action`   | `suggestedActions[].action` | 一句话行动建议，显示在任务卡片第 3 行                             |
| `suggestedActions[].reason`   | `suggestedActions[].reason` | AI 为什么建议这个操作，供管理者参考                              |
| `suggestedActions[].priority` | `priority`                  | High / Medium / Low，决定截止时间窗口（取最高优先级）             |
| 业务目标分类                        | `typeCategory`              | AI 根据场景判定标签（如 LEAD OUTREACH、CANCELLATION RISK 等） |

> 字段定义详见 [Task 字段设计](/product-design/v1/tasks-feature/tasks-field-design.md)；`typeCategory` 枚举值见 [Task 字段设计 §二](/product-design/v1/tasks-feature/tasks-field-design.md)。

***

## 三、优先级判定规则

### 3.1 三级优先级与业务目标映射

| 优先级           | 含义                          | 对应业务目标                               |
| ------------- | --------------------------- | ------------------------------------ |
| 🔴 **High**   | Revenue at risk — 营收面临风险    | 投诉挽留、支付恢复、避免流失                       |
| 🟡 **Medium** | Opportunity exists — 存在转化机会 | 促进成交、促进升级、冻结恢复、挽回客户                  |
| 🔘 **Low**    | Routine follow-up — 常规跟进    | 风险已消除的后续监测（如投诉已解决的满意度确认、成功回归后的活跃度跟踪） |

> **逻辑**：已有营收可能流失 → High；潜在营收可以争取 → Medium；无明确风险或机会的例行跟进 → Low。

### 3.2 AI 判定因素

| 判定因素     | High                | Medium        | Low           |
| -------- | ------------------- | ------------- | ------------- |
| **收入风险** | 会员有取消意向、投诉未解决、支付失败  | —             | —             |
| **漏斗位置** | 试课后未成交（离签约最近）       | 触达后未预约、爽约待重约  | 留了语音信箱、"下周再聊" |
| **时间窗口** | 黄金窗口内（爽约当天、试课后 24h） | 窗口还有余量（1-3 天） | 无明确窗口压力       |
| **客户信号** | 客户主动询价、明确表达兴趣       | 有过互动但意向不明     | 无回应、需要再次触达    |

### 3.3 优先级 → 截止时间窗口

| 优先级        | 截止窗口（默认值）          | 示例                                |
| ---------- | ------------------ | --------------------------------- |
| **High**   | 任务生成时间 + **4 小时**  | 上午 10:00 生成 → due by 下午 2:00      |
| **Medium** | 任务生成时间 + **24 小时** | 上午 10:00 生成 → due by 明天上午 10:00   |
| **Low**    | 任务生成时间 + **72 小时** | 上午 10:00 生成 → due by 3 天后上午 10:00 |

> 以上为系统默认值，店铺管理者可在设置中按优先级分别自定义。截止时间需排除静默时间（夜间 9 PM \~ 8 AM）。
>
> 截止时间、排序等完整规则见 [Tasks Overview §4.1](/product-design/v1/tasks-feature/tasks-overview.md)。

***

## 四、业务场景

### 4.1 新 Lead 首次联系（LEAD OUTREACH）

新 Lead 到达系统，需要在 SLA 窗口内首次联系。由 lead-tracking Lambda 在 Lead 到达时直接创建，不经过 Contact Analysis。

| 客户场景                         | actionNeeded | 时间要求         | 行动策略建议              |
| ---------------------------- | ------------ | ------------ | ------------------- |
| 新 Lead 到达（网页表单/电话咨询/walk-in） | **是**        | **5 分钟 SLA** | 立即联系，介绍会籍方案，安排参观或试课 |

> **判定依据**：系统事件驱动 — 新 Lead 进入系统时由 lead-tracking Lambda 自动创建，`source_type='lead'`。

### 4.2 Lead 持续跟进（LEAD FOLLOW-UP）

Lead 首次联系后未转化，需要持续跟进推动进入下一步。

| 客户场景              | actionNeeded | 时间要求                   | 行动策略建议          |
| ----------------- | ------------ | ---------------------- | --------------- |
| 接通但未预约            | **是**        | 首次沟通后 24h 内            | 发送感兴趣的信息，针对顾虑回应 |
| 有兴趣但未决定           | **是**        | Day 3 → Day 7 → Day 14 | 持续推进，话术根据客户类型调整 |
| 提醒未接通             | **是**        | 2-4h 换时段               | 换时段重试           |
| 条件性拒绝（Bad Timing） | **是**        | 客户提到的时间点前 1 周          | 条件变化时重新联系       |

> **判定依据**：Contact Analysis 综合通话历史判定。`leadStatus` 为 `new` / `attempted` / `connected` 且未进入 terminal 状态时持续生成。

### 4.3 预约后促进成交（BOOKED NOT CONVERTED）

Lead 已预约试课但未完成签约，需要跟进推动转化。

| 客户场景   | actionNeeded | 时间要求                  | 行动策略建议           |
| ------ | ------------ | --------------------- | ---------------- |
| 已预约但爽约 | **是**        | 爽约当天                  | 友好询问原因，重新安排时间    |
| 到店但未试课 | **是**        | 离店后 2-4h              | 消除试课顾虑，提供灵活安排    |
| 试课但未成交 | **是**        | 试课后 2-4h（短信）→ 24h（电话） | 回顾体验亮点，解决顾虑，限时优惠 |

> **判定依据**：Contact Analysis 判定。`leadStatus` 为 `booked` / `showed` / `trialed`，已过预约时间，且未 `converted`。

### 4.4 促进升级（UPGRADE）

现有会员有升级机会，需要推动升级以提升客单价。

| 客户场景         | actionNeeded | 时间要求          | 行动策略建议          |
| ------------ | ------------ | ------------- | --------------- |
| 会员表达升级意向但未行动 | **是**        | 沟通后 24-48h    | 发送升级方案对比，强调增量价值 |
| 员工推荐升级但客户犹豫  | **是**        | Day 3 → Day 7 | 提供限时升级优惠或试用体验   |
| 消课率高的活跃会员    | **是**        | 识别后 1 周内      | 主动推荐进阶课程或升级套餐   |

> **判定依据**：通话分析直接判定（会员表达升级意向但未行动、员工推荐升级但客户犹豫）；系统数据判定（消课率高的活跃会员）。

### 4.5 投诉挽留（COMPLAINT RETENTION）

客户投诉（主动表达不满），需要跟进直到投诉闭环。

| 客户场景  | actionNeeded | 时间要求          | 行动策略建议     |
| ----- | ------------ | ------------- | ---------- |
| 问题未解决 | **是**        | 按紧急度：数小时 → 每天 | 直到问题解决     |
| 问题已解决 | **是**        | 解决后 48h 内     | 确认满意度，化危为机 |
| 投诉升级  | **是**        | 处理后 24h 内     | 高优先级，管理者介入 |

> **判定依据**：通话分析直接判定 — 从通话内容中的问题描述、解决确认、情绪升级等信号分析得出。

### 4.6 支付恢复（PAYMENT RECOVERY）

会员支付失败（卡过期、余额不足等），自动重试未成功，需要人工催回更新支付方式。

| 客户场景        | actionNeeded | 时间要求          | 行动策略建议             |
| ----------- | ------------ | ------------- | ------------------ |
| 信用卡过期       | **是**        | 失败后 48h 内首次电话 | 告知支付失败，引导更新支付方式    |
| 扣款失败（余额不足等） | **是**        | 自动重试失败后 48h   | 友好提醒，避免因支付问题导致账户中断 |

> **判定依据**：系统数据判定 — 由支付网关返回的失败状态 + 自动重试结果驱动。

### 4.7 避免流失（CANCELLATION RISK）

客户出现流失信号，需要主动干预留住客户。

| 客户场景           | actionNeeded | 时间要求      | 行动策略建议            |
| -------------- | ------------ | --------- | ----------------- |
| 会员表达取消意向       | **是**        | 24h 内     | 了解原因，提供挽留方案       |
| 提供了方案（调课/换教练等） | **是**        | 1-2 周后    | 确认方案是否落实、客户是否恢复活跃 |
| 客户说"再想想"       | **是**        | 1 周 → 2 周 | 不强压，定期温和跟进        |

> **判定依据**：通话分析直接判定（表达取消意向、提供了方案、客户说"再想想"）。

### 4.8 冻结恢复（FREEZE RECOVERY）

会员冻结即将到期或已到期，需要主动联系确认回归并重新激活出勤习惯。

| 客户场景     | actionNeeded | 时间要求      | 行动策略建议           |
| -------- | ------------ | --------- | ---------------- |
| 冻结即将到期   | **是**        | 到期前 2 周   | 确认回归意向，帮忙预约第一节课  |
| 冻结已到期未出勤 | **是**        | 到期后 3-5 天 | 欢迎回来，了解阻碍原因，安排课程 |

> **判定依据**：系统数据判定 — 由冻结到期日 + 出勤记录驱动。

### 4.9 挽回客户（WIN-BACK）

前会员主动联系或表达回归意向，需要推动重新签约。

| 客户场景           | actionNeeded | 时间要求     | 行动策略建议             |
| -------------- | ------------ | -------- | ------------------ |
| 前会员主动咨询回归      | **是**        | 当天 → 24h | 安排参观，介绍当前会籍方案和回归优惠 |
| 前会员回复 SMS 表达兴趣 | **是**        | 24-48h   | 趁热打铁，预约到店时间        |

> **判定依据**：通话分析直接判定（前会员主动联系）；SMS 内容分析（回复表达兴趣）。

### 4.10 活动推广（EVENT PROMOTION）

推动会员报名挑战赛或活动，产生一次性收入。

| 客户场景       | actionNeeded | 时间要求        | 行动策略建议                  |
| ---------- | ------------ | ----------- | ----------------------- |
| 活动报名窗口开放   | **是**        | 报名截止前 1-2 周 | 电话/SMS 推荐适合的活动，强调往期参与体验 |
| 会员曾参加过类似活动 | **是**        | 报名开放后 3 天内  | 优先联系老参与者，利用熟悉感推动报名      |

> **判定依据**：系统数据判定 — 由活动日历 + 会员历史参与记录驱动。

### 4.11 特别推广（SPECIAL PROMOTION）

推广客户洽谈或已有推广合作需跟进扩展。

| 客户场景       | actionNeeded | 时间要求      | 行动策略建议          |
| ---------- | ------------ | --------- | --------------- |
| 企业 HR 咨询团购 | **是**        | 24h 内     | 安排会议，介绍推广方案和折扣  |
| 已有推广合作需扩展  | **是**        | 季度回顾后 1 周 | 跟进新增员工意向，维护合作关系 |

> **判定依据**：通话/SMS 分析判定（企业咨询）；系统数据判定（推广合作到期或季度回顾）。

### 4.12 终态（不生成跟进任务）

以下场景 AI 判定 `actionNeeded = false`，不生成 Follow-up Task。

| 客户场景                 | actionNeeded | 说明             |
| -------------------- | ------------ | -------------- |
| 已成交                  | **否**        | —              |
| 明确拒绝（Not Interested） | **否**        | 标记为绝对拒绝，停止一切跟进 |
| 确认到店                 | **否**        | —              |
| 客户满意、无异常             | **否**        | —              |

> **判定依据**：通话分析直接判定 — 均可从通话内容直接分析。

***

# 第二部分：更新与关闭机制

## 五、员工手动更新

员工可以通过 UI 调整任务的截止时间（dueAt），状态会实时重算：

| 操作                 | 触发方式                              | 效果                                                                      |
| ------------------ | --------------------------------- | ----------------------------------------------------------------------- |
| **Adjust（调整截止时间）** | 点击任务卡片的 "Adjust" 按钮，选择新日期/时间，填写原因 | `dueAt` 更新，状态自动重算（ongoing / due soon / overdue），变更记录写入 `dueAtChangelog` |

### 状态重算规则

当 `dueAt` 被调整后，任务状态根据新的截止时间实时重算：

| 条件                                    | 状态           |
| ------------------------------------- | ------------ |
| `dueAt < NOW()`                       | **overdue**  |
| Lead Outreach：`dueAt - NOW() < 2 min` | **due soon** |
| Follow-up：`dueAt - NOW() < 1 hour`    | **due soon** |
| 其他                                    | **ongoing**  |

> `dueAtChangelog` 记录每次调整的 from、to、reason、changedBy、changedAt，供管理者审计。
>
> **注意：员工调整与 AI 重建的冲突问题（待确认）**
>
> Contact Analysis（Pipeline 2）下次运行时会 auto-close 旧 task 并创建新 task。当前实现中，新 task 的所有字段（dueAt、priority 等）均来自 AI 新一轮分析，员工之前的调整（如客户说"下周二再打"导致的 dueAt 变更）不会被带到新 task 里。P2 虽然会读旧 task（用于避免重复创建），但不会读取 `dueAtChangelog` 中的员工调整记录。
>
> 这意味着员工的手动调整可能在 P2 下次运行后丢失。需要与后端确认是否应该：（1）让 AI prompt 包含旧 task 的 dueAtChangelog，使 AI 在分析时考虑员工已做的安排；（2）新 task 在代码层面继承旧 task 中员工手动调整过的 dueAt。

***

## 六、关闭方式

Follow-up Task 有两种关闭方式：AI 自动关闭和员工手动关闭。

### 6.1 AI 自动关闭（closeType = auto\_closed）

| 触发系统                             | 触发时机                                      | 机制                                                                    |
| -------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
| **Contact Analysis（Pipeline 2）** | Cron / Per-Call AI 触发 / On-Demand Refresh | 每次运行时先 auto-close 该客户的旧 `contact_analysis` 类 task，再根据最新分析决定是否创建新 task |

AI 自动关闭的典型场景：

| 触发场景                   | 说明                         |
| ---------------------- | -------------------------- |
| 客户主动来电/来 SMS 且目标已达成    | 客户已主动完成了任务目标对应的动作          |
| 客户明确拒绝（Not Interested） | AI 判定为绝对拒绝，停止一切跟进          |
| 客户通过其他渠道已完成行动          | 如客户自行线上预约、已到店等，AI 从后续通话中推断 |

### 6.2 员工手动关闭（closeType = manual\_closed）

员工点击 \[Close Task] 按钮，选择一个 `businessResult` 即可关闭任务。

> autoCloseResult 枚举和 businessResult 枚举详见 [Tasks 字段设计](/product-design/v1/tasks-feature/tasks-field-design.md)；营收归因详见 [任务与营收归因](/product-design/v1/tasks-feature/revenue-attribution.md)；关闭流程详见 [Tasks Overview §4.2](/product-design/v1/tasks-feature/tasks-overview.md)。