跟进任务

嘉宾跟进任务系统允许外部系统消费平台生成的跟进任务。任务由平台定时生成，外部系统通过开放接口拉取并执行。

概述

任务生成：平台每天 09:00 自动生成待执行任务（Top-N 高评分嘉宾入队 + 预生成任务）
任务消费：外部系统通过接口拉取 pending 状态的任务，执行后回传结果
任务类型：当前支持 match_share（匹配推荐分享），可扩展更多类型

任务状态流转

pending → dispatched → completed
                     → failed
                     → skipped

状态	说明
`pending`	待执行，等待外部系统拉取
`dispatched`	已派发，已被外部系统拉取，等待结果回传
`completed`	已完成，外部系统回传了成功结果
`failed`	已失败，外部系统回传了失败结果
`skipped`	已跳过，无可执行内容

`GET /api/open/v1/follow-up/tasks` — 任务列表

权限：open:follow-up:read

查询参数：

参数	类型	必填	说明
status	string	否	任务状态，默认 `pending`
task_type	string	否	任务类型，如 `match_share`
date	string	否	计划执行日期，格式 `YYYY-MM-DD`
page	int	否	页码，默认 1
page_size	int	否	每页条数，默认 50，最大 200

响应示例：

json

{
    "code": 200,
    "message": "success",
    "data": {
        "list": [
            {
                "id": 101,
                "follow_up_id": 50,
                "guest_id": 2001,
                "guest_name": "张三",
                "company_id": 3,
                "task_type": "match_share",
                "task_day": 2,
                "scheduled_date": "2026-08-05",
                "status": "pending",
                "guest_brief": {
                    "gender": 2,
                    "age": 26,
                    "city": "上海",
                    "education": "本科",
                    "occupation": "设计师"
                }
            }
        ],
        "total": 23
    }
}

`GET /api/open/v1/follow-up/tasks/{id}` — 任务详情

权限：open:follow-up:read

路径参数：

参数	类型	说明
id	int	任务 ID

响应示例：

json

{
    "code": 200,
    "message": "success",
    "data": {
        "task": {
            "id": 101,
            "follow_up_id": 50,
            "guest_id": 2001,
            "task_type": "match_share",
            "task_day": 2,
            "scheduled_date": "2026-08-05",
            "status": "pending"
        },
        "guest": {
            "id": 2001,
            "name": "张三",
            "gender": 1,
            "age": 28,
            "height": 178,
            "education_level": 4,
            "income_level": 3,
            "occupation": "工程师",
            "native_place": "杭州",
            "req_age_min": 22,
            "req_age_max": 32,
            "req_height_min": 158,
            "req_education_min": 3,
            "self_intro": "性格开朗，喜欢旅行..."
        },
        "matchmaker": {
            "id": 10,
            "name": "李红娘",
            "phone": "138xxxx1234",
            "wechat": "lihongniang",
            "avatar": "https://...",
            "company_id": 3,
            "company_name": "XX婚恋",
            "certified": true,
            "guest_count": 45,
            "match_count": 12
        },
        "already_recommended_guest_ids": [1001, 1005, 1023],
        "history_match_count": 3
    }
}

说明：already_recommended_guest_ids 包含该跟进记录中已推荐过的嘉宾 ID 列表，用于避免重复推荐。

`POST /api/open/v1/follow-up/tasks/{id}/dispatch` — 派发任务

权限：open:follow-up:write

说明：拉取/锁定任务，状态从 pending 变为 dispatched。使用行锁保证并发安全，同一任务只能被一个外部系统派发。

路径参数：

参数	类型	说明
id	int	任务 ID

响应示例：

json

{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 101,
        "status": "dispatched"
    }
}

错误响应：

json

{
    "code": 409,
    "message": "任务不存在或状态不是 pending"
}

`POST /api/open/v1/follow-up/tasks/{id}/complete` — 完成任务

权限：open:follow-up:write

说明：回传执行成功结果，状态从 dispatched 变为 completed。

路径参数：

参数	类型	说明
id	int	任务 ID

请求体：

json

{
    "matched_guest_id": 3005,
    "match_score": 92.5,
    "share_link": "https://ai.dourong.com/guest/3005?ref=follow_up_101",
    "share_channel": "wechat",
    "extra": {}
}

字段	类型	必填	说明
matched_guest_id	int	否	推荐的匹配嘉宾 ID
match_score	float	否	匹配评分
share_link	string	否	分享链接
share_channel	string	否	分享渠道：`wechat` / `sms` / `app` 等
extra	object	否	额外数据

响应示例：

json

{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 101,
        "status": "completed"
    }
}

幂等说明：对已完成的任务重复调用 complete，返回成功（idempotent: true），不重复更新统计。

`POST /api/open/v1/follow-up/tasks/{id}/fail` — 标记失败

权限：open:follow-up:write

说明：回传执行失败结果，状态从 dispatched 变为 failed。

请求体：

json

{
    "error_code": "NO_CANDIDATE",
    "error_msg": "无符合条件的候选嘉宾"
}

字段	类型	必填	说明
error_code	string	否	错误码
error_msg	string	否	错误描述

响应示例：

json

{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 101,
        "status": "failed"
    }
}

`POST /api/open/v1/follow-up/tasks/{id}/skip` — 跳过任务

权限：open:follow-up:write

说明：标记任务跳过（如无可推荐嘉宾），状态从 dispatched 变为 skipped。

请求体：

json

{
    "reason": "嘉宾已归档"
}

字段	类型	必填	说明
reason	string	否	跳过原因

响应示例：

json

{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 101,
        "status": "skipped"
    }
}

调用流程示例

1. 获取待执行任务
   GET /api/open/v1/follow-up/tasks?status=pending

2. 获取任务详情（含嘉宾资料和红娘信息）
   GET /api/open/v1/follow-up/tasks/101

3. 锁定任务（防止其他系统重复拉取）
   POST /api/open/v1/follow-up/tasks/101/dispatch

4. 执行业务逻辑（如调用匹配引擎）
   ...

5. 回传执行结果
   POST /api/open/v1/follow-up/tasks/101/complete
   {
       "matched_guest_id": 3005,
       "match_score": 92.5,
       "share_link": "https://..."
   }

超时处理

任务派发后默认 4 小时内需回传结果
超时未回传的任务会在每天 22:00 自动回退为 pending（最多重试 3 次）
超过最大重试次数后标记为 failed

任务类型扩展

当前支持的任务类型：

类型	说明
`match_share`	匹配推荐分享 — 为跟进中的嘉宾推荐匹配对象

未来可扩展更多任务类型，如资料完善提醒、约见邀请引导等。

跟进任务 ​

概述 ​

任务状态流转 ​

GET /api/open/v1/follow-up/tasks — 任务列表 ​

GET /api/open/v1/follow-up/tasks/{id} — 任务详情 ​

POST /api/open/v1/follow-up/tasks/{id}/dispatch — 派发任务 ​

POST /api/open/v1/follow-up/tasks/{id}/complete — 完成任务 ​

POST /api/open/v1/follow-up/tasks/{id}/fail — 标记失败 ​

POST /api/open/v1/follow-up/tasks/{id}/skip — 跳过任务 ​

调用流程示例 ​

超时处理 ​

任务类型扩展 ​

跟进任务

概述

任务状态流转

`GET /api/open/v1/follow-up/tasks` — 任务列表

`GET /api/open/v1/follow-up/tasks/{id}` — 任务详情

`POST /api/open/v1/follow-up/tasks/{id}/dispatch` — 派发任务

`POST /api/open/v1/follow-up/tasks/{id}/complete` — 完成任务

`POST /api/open/v1/follow-up/tasks/{id}/fail` — 标记失败

`POST /api/open/v1/follow-up/tasks/{id}/skip` — 跳过任务

调用流程示例

超时处理

任务类型扩展