Tasks Specification
定义 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 |
参考文档