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

# Tasks Specification

> **Historical product spec / Superseded（2026-07-15）**：本文的 UI、`type_category` 和 `close_result` 是 V1 snapshot，不得作为新实现依据。现行规范见 [Task System Design](/product-design/v3/tasks-feature/task-domain-lifecycle.md)。

定义 Tasks 页面展示的所有数据的来源和计算方式。数据全部来自 **tasks 表**（`callytics-common/src/db/schema/tasks.ts`）。

***

## 一、数据来源字段

| 字段                   | DB 列名                  | 类型        | 用途                                                     |
| -------------------- | ---------------------- | --------- | ------------------------------------------------------ |
| `taskId`             | `task_id`              | uuid (PK) | 任务唯一标识                                                 |
| `contactPhone`       | `contact_phone`        | text      | 关联客户电话                                                 |
| `franchiseId`        | `franchise_id`         | text      | 多租户隔离                                                  |
| `siteId`             | `site_id`              | text      | 多租户隔离                                                  |
| `taskType`           | `task_type`            | text      | `'lead_outreach'` / `'follow_up'`                      |
| `typeCategory`       | `type_category`        | text      | 11 个业务场景（见 §二）                                         |
| `status`             | `status`               | text      | `'pending'` / `'closed'`（DB 只存这两个）                     |
| `closeType`          | `close_type`           | text      | `'auto_closed'` / `'manual_closed'`                    |
| `actionNeeded`       | `action_needed`        | boolean   | 是否需要跟进                                                 |
| `actionNeededReason` | `action_needed_reason` | text      | 为什么需要行动                                                |
| `suggestedActions`   | `suggested_actions`    | jsonb     | AI 建议列表 `[{action, reason, priority, priorityReason}]` |
| `priority`           | `priority`             | text      | `'high'` / `'medium'` / `'low'`                        |
| `sourceType`         | `source_type`          | text      | `'lead'` / `'contact_analysis'` / `'manual'`           |
| `dueAt`              | `due_at`               | timestamp | 截止时间                                                   |
| `closedAt`           | `closed_at`            | timestamp | 关闭时间                                                   |
| `closedByStaffName`  | `closed_by_staff_name` | text      | 关闭员工姓名                                                 |
| `closeResult`        | `close_result`         | text      | 13 个关闭结果（见 §三）                                         |
| `closeNote`          | `close_note`           | text      | 关闭备注                                                   |
| `createdAt`          | `created_at`           | timestamp | 创建时间                                                   |

> **Overdue / Due Soon 不存 DB**，由前端实时计算：Overdue = `status='pending' AND due_at < NOW()`，Due Soon = `status='pending' AND due_at BETWEEN NOW() AND NOW() + interval`。

***

## 二、前端展示

### 2.1 Summary Cards（顶部汇总）

| 前端展示名         | 计算方式                                                                    | 来源字段                |
| ------------- | ----------------------------------------------------------------------- | ------------------- |
| **OPEN** 总数   | `COUNT(status='pending')`                                               | `status`            |
| Ongoing 数量    | `COUNT(status='pending' AND due_at >= NOW() + interval)`                | `status` + `due_at` |
| Due Soon 数量   | `COUNT(status='pending' AND due_at BETWEEN NOW() AND NOW() + interval)` | `status` + `due_at` |
| Overdue 数量    | `COUNT(status='pending' AND due_at < NOW())`                            | `status` + `due_at` |
| **CLOSED** 总数 | `COUNT(status='closed')`                                                | `status`            |
| Manual 数量     | `COUNT(close_type='manual_closed')`                                     | `close_type`        |
| Auto 数量       | `COUNT(close_type='auto_closed')`                                       | `close_type`        |

### 2.2 筛选器

| 前端筛选名          | 来源字段            | 选项                                       |
| -------------- | --------------- | ---------------------------------------- |
| All Priorities | `priority`      | All / High / Medium / Low                |
| All Types      | `type_category` | All / 11 个 type\_category                |
| Open Date      | `created_at`    | All / Today / Last 7 Days / Last 30 Days |
| Close Date     | `closed_at`     | All / Today / Last 7 Days / Last 30 Days |

### 2.3 Task Card 展示字段

每个 task card 展示以下数据：

| 前端展示位置 | 前端展示名                                                        | 来源字段                                                     | 说明                                  |
| ------ | ------------------------------------------------------------ | -------------------------------------------------------- | ----------------------------------- |
| 顶部标签   | ONGOING / DUE SOON / OVERDUE / AUTO-CLOSED / MANUAL-CLOSED   | `status` + `due_at` + `close_type`                       | 状态标签，颜色区分                           |
| 第一行左   | 客户姓名                                                         | `contact_phone` → JOIN contacts `firstName` + `lastName` | 跨表关联                                |
| 第一行左   | 电话号码                                                         | `contact_phone`                                          | 直读                                  |
| 第一行左   | Lead / Member badge                                          | `contact_phone` → JOIN contacts `lifecycleStage`         | 跨表关联                                |
| 第一行右   | Due 时间                                                       | `due_at`                                                 | 格式：Due: Apr 5 9:18 PM               |
| 第二行左   | Priority badge                                               | `priority`                                               | HIGH / MEDIUM / LOW，颜色区分            |
| 第二行左   | Type Category badge                                          | `type_category`                                          | LEAD OUTREACH / CANCELLATION RISK 等 |
| 第三行    | AI Summary                                                   | `action_needed_reason` 或 JOIN contacts `customerSummary` | 任务描述                                |
| 第四行    | Suggested Action                                             | `suggested_actions[0].action`                            | AI 建议操作                             |
| 第五行    | First attempted / First connected / Last touch / Calls / SMS | 跨表派生 calls + messages                                    | 通话和消息统计                             |
| 底部按钮   | View Details                                                 | —                                                        | 展开详情                                |
| 底部按钮   | Close Task                                                   | —                                                        | 打开关闭弹窗                              |
| 关闭后额外行 | Close Type + Close Result + Close Note                       | `close_type` + `close_result` + `close_note`             | 仅已关闭 task 显示                        |

### 2.4 Close Task 弹窗

| 前端展示名                | 来源字段                      | 说明                         |
| -------------------- | ------------------------- | -------------------------- |
| Who are you?（下拉）     | 写入 `closed_by_staff_name` | 员工选择姓名                     |
| Close Result（13 选 1） | 写入 `close_result`         | 见 §三                       |
| Close Note（文本框）      | 写入 `close_note`           | `close_result='other'` 时必填 |

***

## 三、枚举值

### 3.1 type\_category（11 个）

| #  | type\_category         | 显示文字                 | task\_type      |
| -- | ---------------------- | -------------------- | --------------- |
| 1  | `lead_outreach`        | LEAD OUTREACH        | `lead_outreach` |
| 2  | `lead_follow_up`       | LEAD FOLLOW-UP       | `follow_up`     |
| 3  | `booked_not_converted` | BOOKED NOT CONVERTED | `follow_up`     |
| 4  | `cancellation_risk`    | CANCELLATION RISK    | `follow_up`     |
| 5  | `complaint_retention`  | COMPLAINT RETENTION  | `follow_up`     |
| 6  | `win_back`             | WIN-BACK             | `follow_up`     |
| 7  | `upgrade`              | UPGRADE              | `follow_up`     |
| 8  | `payment_recovery`     | PAYMENT RECOVERY     | `follow_up`     |
| 9  | `freeze_recovery`      | FREEZE RECOVERY      | `follow_up`     |
| 10 | `event_promotion`      | EVENT PROMOTION      | `follow_up`     |
| 11 | `special_promotion`    | SPECIAL PROMOTION    | `follow_up`     |

> **注**：当前 schema 为 9 个（缺 `complaint_retention`、`payment_recovery`、`freeze_recovery`、`event_promotion`、`special_promotion`，多了 `retention`、`renewal`、`referral`），需后端更新。

### 3.2 close\_result（13 个）

| #  | close\_result         | 显示文字                | 说明                             |
| -- | --------------------- | ------------------- | ------------------------------ |
| 1  | `lead_outreached`     | Lead Outreached     | 仅 Lead Outreach task，已尝试联系但未接通 |
| 2  | `converted`           | Converted           | 客户签约                           |
| 3  | `upgraded`            | Upgraded            | 客户升级                           |
| 4  | `complaint_resolved`  | Complaint Resolved  | 投诉解决                           |
| 5  | `payment_recovered`   | Payment Recovered   | 更新 credit card 成功              |
| 6  | `cancel_saved`        | Cancel Saved        | 挽留成功                           |
| 7  | `freeze_recovered`    | Freeze Recovered    | 冻结会员恢复活跃                       |
| 8  | `win_back`            | Win-back            | 前会员重新签约                        |
| 9  | `event_signed_up`     | Event Signed Up     | 会员报名活动                         |
| 10 | `promotion_converted` | Promotion Converted | 推广协议签约                         |
| 11 | `wrong_number`        | Wrong Number        | 号码错误                           |
| 12 | `do_not_contact`      | Do Not Contact      | 客户要求不联系                        |
| 13 | `other`               | Other               | 其他（需填 close\_note）             |

> **注**：当前 schema 为 11 个（缺 `lead_outreached`、`complaint_resolved`、`payment_recovered`、`freeze_recovered`、`event_signed_up`、`promotion_converted`，多了 `attempted`、`issue_resolved`、`renewed`、`referral_obtained`），需后端更新。

***

## 四、Schema 差异说明

当前 schema（`callytics-common/src/db/schema/tasks.ts`）和本文档设计目标有差异，需后端更新：

### type\_category 变更

| 动作  | 值                                   | 原因       |
| --- | ----------------------------------- | -------- |
| 重命名 | `retention` → `complaint_retention` | 更精确      |
| 删除  | `renewal`                           | 不是独立业务场景 |
| 删除  | `referral`                          | 不是独立业务场景 |
| 新增  | `payment_recovery`                  | 支付恢复     |
| 新增  | `freeze_recovery`                   | 冻结恢复     |
| 新增  | `event_promotion`                   | 活动推广     |
| 新增  | `special_promotion`                 | 特别推广     |

### close\_result 变更

| 动作  | 旧值                  | 新值                    | 原因                         |
| --- | ------------------- | --------------------- | -------------------------- |
| 重命名 | `attempted`         | `lead_outreached`     | 仅 Lead Outreach task       |
| 重命名 | `issue_resolved`    | `complaint_resolved`  | 匹配 Complaint Retention MRR |
| 删除  | `renewed`           | —                     | 不是独立 close result          |
| 删除  | `referral_obtained` | —                     | 不产生直接营收                    |
| 新增  | —                   | `payment_recovered`   | Payment Recovery MRR       |
| 新增  | —                   | `freeze_recovered`    | Freeze Recovery MRR        |
| 新增  | —                   | `event_signed_up`     | Event Revenue              |
| 新增  | —                   | `promotion_converted` | Promotion Revenue          |

***

## 参考文档

- [Tasks 字段设计](/product-design/v1/tasks-feature/tasks-field-design.md)
- [Task 生成、更新与关闭机制](/product-design/v1/tasks-feature/task-lifecycle.md)
- [任务与营收归因](/product-design/v1/tasks-feature/revenue-attribution.md)
- [Dashboard Specification](/product-design/v1/dashboard-feature/dashboard-spec.md)