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

# Dashboard 规格说明

定义 Dashboard 页面展示新增Overview的两个图表的数据来源和计算方式。

***

## 一、Total Tasks（任务状态分布）

数据全部来自 **tasks 表**。

### 1.1 顶部展示

| 前端展示名                                                               | 数据来源                                              | 说明                       |
| ------------------------------------------------------------------- | ------------------------------------------------- | ------------------------ |
| **Total Tasks**（标题）                                                 | 静态文案                                              | —                        |
| **459**（大数字）                                                        | 所有 task 总数（Ongoing + Due Soon + Overdue + Closed） | `COUNT(*) FROM tasks`    |
| 🔵 Ongoing: 132 · 🟡 Due Soon: 29 · 🔴 Overdue: 16 · 🟢 Closed: 282 | 4 种状态各自总数                                         | 见 §1.3 计算方式              |
| **Last Updated**（右上角）                                               | 数据查询时间                                            | `NOW()` — 显示当前实时数据，无历史回溯 |

### 1.2 数据来源字段

| 字段              | DB 列名           | 用途                               |
| --------------- | --------------- | -------------------------------- |
| `status`        | `status`        | `'pending'` / `'closed'`         |
| `type_category` | `type_category` | 11 个类型，每个类型一行柱状图                 |
| `due_at`        | `due_at`        | 判断 due soon / overdue（API 层实时计算） |

### 1.3 每条柱子的 4 个状态

| 状态           | 颜色   | 计算方式                                                                             |
| ------------ | ---- | -------------------------------------------------------------------------------- |
| **Ongoing**  | 🔵 蓝 | `status='pending' AND due_at >= NOW() + interval`                                |
| **Due Soon** | 🟡 黄 | `status='pending' AND due_at BETWEEN NOW() AND NOW() + interval`（interval 由店铺配置） |
| **Overdue**  | 🔴 红 | `status='pending' AND due_at < NOW()`                                            |
| **Closed**   | 🟢 绿 | `status='closed'`                                                                |

### 1.4 SQL

```sql
SELECT type_category,
  COUNT(*) FILTER (WHERE status='pending' AND due_at >= NOW() + interval) AS ongoing,
  COUNT(*) FILTER (WHERE status='pending' AND due_at BETWEEN NOW() AND NOW() + interval) AS due_soon,
  COUNT(*) FILTER (WHERE status='pending' AND due_at < NOW()) AS overdue,
  COUNT(*) FILTER (WHERE status='closed') AS closed
FROM tasks
GROUP BY type_category
ORDER BY (ongoing + due_soon + overdue + closed) DESC
```

每行右侧显示该 type\_category 的总数。

***

## 二、Impacted Revenue（营收归因表格）

数据来自 **tasks 表**（`close_result` 字段）+ **店铺配置**（假设价格/系数）。

### 2.1 顶部展示

| 前端展示名                             | 数据来源                                  | 说明                |
| --------------------------------- | ------------------------------------- | ----------------- |
| **Impacted Revenue**（标题）          | 静态文案                                  | —                 |
| **$3,362**（大数字）                   | 所有正向 close\_result 的 Actual 之和        | = Total Actual    |
| **▲ $320 vs previous 1 week**（趋势） | 当前周期 Total Actual - 上一周期 Total Actual | 随 1W / 1M / 3M 联动 |

### 2.2 Date Range 选择器

| 前端展示名                 | 说明                                                 |
| --------------------- | -------------------------------------------------- |
| Date Range（from → to） | 筛选 `tasks.closed_at BETWEEN from AND to` 的已关闭 task |
| 1W / 1M / 3M 快捷按钮     | 设置 from = NOW() - 7d/30d/90d，to = NOW()            |

> **时间基准是 `closed_at`（关闭时间）**，不是 `created_at`。营收归因在 task 关闭时确定（`close_result` 写入），因此按关闭时间统计。一个 3 月创建、4 月关闭的 task，算 4 月的营收。时间精度为天。
>
> - **Actual**：`WHERE closed_at BETWEEN from AND to AND close_result IN (9 个正向)`
> - **Expected**：`WHERE created_at <= to`（所有在该时间范围内创建或之前创建的 task，不限 closed\_at）
> - **Leakage**：Expected - Actual（包含该时间范围内还没关闭的 pending task）

**趋势对比逻辑**：自动取与当前选择相同天数的前一个周期对比。

```
对比 to   = 当前 from - 1 day
对比 from = 对比 to - (当前 to - 当前 from)
```

| 当前选择     | 当前周期        | 对比周期         | 趋势展示                 |
| -------- | ----------- | ------------ | -------------------- |
| 1W 快捷    | 3/25 - 3/31 | 3/18 - 3/24  | vs previous 1 week   |
| 1M 快捷    | 3/1 - 3/31  | 2/1 - 2/28   | vs previous 1 month  |
| 3M 快捷    | 1/1 - 3/31  | 10/1 - 12/31 | vs previous 3 months |
| 自定义 8 天  | 3/20 - 3/28 | 3/12 - 3/19  | vs previous 8 days   |
| 自定义 15 天 | 3/10 - 3/25 | 2/23 - 3/9   | vs previous 15 days  |

### 2.3 close\_result 枚举（13 个）

| 类型          | close\_result         | 营收类型                    |
| ----------- | --------------------- | ----------------------- |
| **正向（9 个）** | `converted`           | Conversion MRR          |
|             | `upgraded`            | Upgrade MRR             |
|             | `complaint_resolved`  | Complaint Retention MRR |
|             | `payment_recovered`   | Payment Recovery MRR    |
|             | `cancel_saved`        | Cancel Save MRR         |
|             | `freeze_recovered`    | Freeze Recovery MRR     |
|             | `win_back`            | Win-back MRR            |
|             | `event_signed_up`     | Event Revenue（一次性）      |
|             | `promotion_converted` | Promotion Revenue（一次性）  |
| **负向（2 个）** | `wrong_number`        | —                       |
|             | `do_not_contact`      | —                       |
| **中性（2 个）** | `lead_outreached`     | —                       |
|             | `other`               | —                       |

### 2.4 表格列定义

| 列名              | 含义                                | 计算方式                                           |
| --------------- | --------------------------------- | ---------------------------------------------- |
| **Expected**    | 如果所有 task 都达成理想结果的最大营收            | 按 `type_category` 统计所有 task 数 × 对应理想金额（见下方映射表） |
| **Actual**      | 已关闭 task 实际达成的正向 close\_result 营收 | 按 `close_result` 统计已关闭 task 数 × 对应配置金额（见下方金额表） |
| **Tasks**       | 该营收类型已关闭 task 数                   | 按 `close_result` 统计 `status='closed'` 的数量      |
| **Leakage**     | Expected - Actual                 | 红色展示                                           |
| **Description** | 说明                                | 静态文案                                           |

### 2.5 Expected 计算：type\_category → 理想金额

Expected 基于 `type_category`（11 个）计算，API 层固定映射，不存 DB：

| type\_category         | 理想 close\_result      | Expected 金额        | 说明                   |
| ---------------------- | --------------------- | ------------------ | -------------------- |
| `lead_outreach`        | —                     | 不计入 Expected       | 目标是接通，不直接产生营收        |
| `lead_follow_up`       | —                     | 不计入 Expected       | 目标是推动预约，不直接产生营收      |
| `booked_not_converted` | `converted`           | $149               | 理想：预约后到店签约           |
| `cancellation_risk`    | `cancel_saved`        | $149               | 理想：挽留成功              |
| `complaint_retention`  | `complaint_resolved`  | $149 × 0.60 = $89  | 理想：投诉解决后留存           |
| `win_back`             | `win_back`            | $149               | 理想：前会员重新签约           |
| `upgrade`              | `upgraded`            | $40                | 理想：升级套餐              |
| `payment_recovery`     | `payment_recovered`   | $149 × 0.75 = $112 | 理想：更新 credit card 成功 |
| `freeze_recovery`      | `freeze_recovered`    | $149 × 0.70 = $104 | 理想：冻结会员恢复活跃          |
| `event_promotion`      | `event_signed_up`     | $30                | 理想：会员报名活动            |
| `special_promotion`    | `promotion_converted` | $129               | 理想：特别推广签约            |

### 2.6 Actual 计算：close\_result → 实际金额

Actual 基于 `close_result`（9 个正向）计算，只算已关闭 task：

| close\_result         | Actual 金额          |
| --------------------- | ------------------ |
| `converted`           | $149               |
| `upgraded`            | $40                |
| `complaint_resolved`  | $149 × 0.60 = $89  |
| `payment_recovered`   | $149 × 0.75 = $112 |
| `cancel_saved`        | $149               |
| `freeze_recovered`    | $149 × 0.70 = $104 |
| `win_back`            | $149               |
| `event_signed_up`     | $30                |
| `promotion_converted` | $129               |

> **tasks 表没有金额字段**，营收金额由 API 层用 `close_result` 查店铺配置实时算出。默认值可在 [Rules → Revenue Benchmarks](/product-design/v1/rules-feature/rules-feature.md#6-revenue-benchmarks营收基准值) 编辑。

### 2.7 Leakage 来源

1. **还没关闭的 task**（pending）— 贡献了 Expected 但没有 Actual
2. **关闭了但不是正向结果的 task**（`lead_outreached` / `wrong_number` / `do_not_contact` / `other`）— Actual = 0
3. **type\_category 与 close\_result 不匹配**（如 `cancellation_risk` task 最终 `close_result = other`）

### 2.8 汇总行

| 前端展示名                            | Expected                                       | Actual                                      | Leakage           |
| -------------------------------- | ---------------------------------------------- | ------------------------------------------- | ----------------- |
| Recurring Revenue (MRR) Subtotal | 7 种 MRR type\_category 的 Expected 之和           | 7 种 MRR close\_result 的 Actual 之和           | Expected - Actual |
| One-Time Revenue Subtotal        | Event + Promotion type\_category 的 Expected 之和 | Event + Promotion close\_result 的 Actual 之和 | Expected - Actual |
| **Total**                        | MRR + One-Time Expected                        | MRR + One-Time Actual                       | Expected - Actual |

> 详见 [任务与营收归因](/product-design/v1/tasks-feature/revenue-attribution.md)。

***

## 参考文档

- [任务与营收归因](/product-design/v1/tasks-feature/revenue-attribution.md)
- [Tasks 字段设计](/product-design/v1/tasks-feature/tasks-field-design.md)
- [Rules Feature](/product-design/v1/rules-feature/rules-feature.md)
- [完整版 Dashboard Data Sources](/product-design/future-plans/dashboard-data-sources-full.md)