ddrwode/boss_dp

Fork 0

Files

ddrwode 530d7fe135 haha

2026-02-27 13:56:15 +08:00

15 KiB

Raw Blame History

BOSS 直聘自动化平台 - API 接口文档

Base URL: http://{服务器IP}:9000

认证方式: Cookie（auth_token），登录成功后自动通过 Set-Cookie 设置，后续请求自动携带。

请求格式: 支持 application/json 和 multipart/form-data

响应规范: 所有接口的 JSON 响应体均包含 code 字段，与 HTTP 状态码一致。成功时如 code: 200、code: 201；错误时如 code: 401、code: 404。原返回数组的接口会包装为 {"code": 状态码, "data": 原数组}。

一、健康检查

GET /health

说明: 检查服务器是否正常运行，无需登录。

状态码:

状态码	说明
200	成功，返回服务状态与在线 Worker 数
500	服务器内部错误（少见）

请求参数: 无

响应示例:

{
  "status": "ok",
  "workers_online": 2
}

返回字段	类型	说明
status	string	服务状态，固定 `"ok"`
workers_online	int	当前在线 Worker 数量

二、认证

POST /api/auth/login

说明: 管理员登录，无需认证。登录成功后通过 Set-Cookie 返回 auth_token。

状态码:

状态码	说明
200	成功，返回 token 并设置 Cookie
401	用户名或密码错误

请求参数:

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码

请求示例:

{
  "username": "admin",
  "password": "boss_dp_admin"
}

成功响应 (200):

{
  "token": "a1b2c3d4e5f6..."
}

失败响应 (401):

{
  "detail": "用户名或密码错误"
}

返回字段	类型	说明
token	string	登录 token（同时通过 Cookie 设置）

响应 Header:

Set-Cookie: auth_token=a1b2c3d4e5f6...; HttpOnly; Max-Age=31536000; SameSite=Lax

三、Worker 管理

以下接口均需登录（携带 auth_token Cookie）

GET /api/workers

说明: 获取所有已注册 Worker 列表。

状态码:

状态码	说明
200	成功，返回 Worker 数组
401	未登录或 token 失效

请求参数: 无

响应示例:

[
  {
    "worker_id": "worker-1",
    "worker_name": "本机",
    "browsers": [
      {
        "id": "abd63190eea84dc49429962f7bb330a4",
        "name": "第一个",
        "remark": ""
      }
    ],
    "online": true,
    "current_task_id": null
  }
]

返回字段	类型	说明
worker_id	string	Worker 唯一标识
worker_name	string	Worker 名称（电脑名）
browsers	array	该电脑上的比特浏览器环境列表
browsers[].id	string	浏览器窗口 ID
browsers[].name	string	浏览器窗口名称（环境名）
browsers[].remark	string	备注
online	boolean	是否在线
current_task_id	string/null	当前正在执行的任务 ID

GET /api/workers/{worker_id}

说明: 获取指定 Worker 的详细信息。

状态码:

状态码	说明
200	成功，返回单个 Worker 对象
401	未登录或 token 失效
404	Worker 不存在

路径参数:

参数	类型	必填	说明
worker_id	string	是	Worker ID

成功响应 (200): 同上单个 Worker 对象

失败响应 (404):

{
  "detail": "Worker worker-99 不存在"
}

四、账号管理

以下接口均需登录（携带 auth_token Cookie）

POST /api/accounts

说明: 添加账号（将浏览器环境名称绑定到指定电脑）。若已存在相同绑定则直接返回已有记录。

状态码:

状态码	说明
201	成功创建或返回已有记录
400	请求参数错误（如缺少 browser_name、worker_id）
401	未登录或 token 失效

请求参数:

参数	类型	必填	说明
browser_name	string	是	浏览器环境名称
worker_id	string	是	目标电脑的 Worker ID

请求示例:

{
  "browser_name": "第一个",
  "worker_id": "worker-1"
}

成功响应 (201):

{
  "id": 1,
  "worker_id": "worker-1",
  "browser_id": "name:第一个",
  "browser_name": "第一个",
  "boss_username": "",
  "is_logged_in": false,
  "current_task_id": null,
  "current_task_status": null,
  "checked_at": null,
  "created_at": "2026-02-14T16:00:00",
  "updated_at": "2026-02-14T16:00:00",
  "worker_name": "本机",
  "worker_online": true
}

GET /api/accounts

说明: 查询所有账号列表，包含电脑名称、在线状态、任务执行状态。

状态码:

状态码	说明
200	成功，返回账号数组
401	未登录或 token 失效

查询参数:

参数	类型	必填	说明
worker_id	string	否	按 Worker ID 过滤

响应示例:

[
  {
    "id": 1,
    "worker_id": "worker-1",
    "browser_id": "abd63190eea84dc49429962f7bb330a4",
    "browser_name": "第一个",
    "boss_username": "某用户",
    "is_logged_in": true,
    "current_task_id": "3f113d90bb32",
    "current_task_status": "success",
    "checked_at": "2026-02-14T16:05:00",
    "created_at": "2026-02-14T16:00:00",
    "updated_at": "2026-02-14T16:05:00",
    "worker_name": "本机",
    "worker_online": true
  }
]

返回字段	类型	说明
id	int	账号记录 ID
worker_id	string	绑定的 Worker ID
browser_id	string	比特浏览器窗口 ID
browser_name	string	浏览器环境名称
boss_username	string	BOSS 直聘用户名（检测后填充）
boss_id	string	BOSS 直聘用户 ID（检测登录成功时填充）
is_logged_in	boolean	是否已登录 BOSS
current_task_id	string/null	当前关联的任务 ID
current_task_status	string/null	当前任务状态：`pending` / `dispatched` / `running` / `success` / `failed`
checked_at	string/null	最近一次检测时间（ISO 格式）
created_at	string	创建时间
updated_at	string	更新时间
worker_name	string	电脑名称（运行时补充）
worker_online	boolean	电脑是否在线（运行时补充）

GET /api/accounts/{id}

说明: 查询单个账号详情。

状态码:

状态码	说明
200	成功，返回单个账号对象
401	未登录或 token 失效
404	账号不存在

路径参数:

参数	类型	必填	说明
id	int	是	账号记录 ID

成功响应 (200): 同上单个账号对象

失败响应 (404):

{
  "detail": "账号不存在"
}

DELETE /api/accounts/{id}

说明: 删除指定账号。

状态码:

状态码	说明
200	成功删除
401	未登录或 token 失效
404	账号不存在

路径参数:

参数	类型	必填	说明
id	int	是	账号记录 ID

成功响应 (200):

{
  "message": "账号已删除"
}

失败响应 (404):

{
  "detail": "账号不存在"
}

五、任务管理

以下接口均需登录（携带 auth_token Cookie）

统一任务入口：所有任务（检查登录、招聘等）都通过 POST /api/tasks 提交，通过 task_type 字段区分任务类型。

POST /api/tasks

说明: 提交新任务。通过 task_type 指定任务类型，系统自动路由到目标 Worker 执行。

状态码:

状态码	说明
201	成功，任务已创建并派发
400	未指定 worker_id 或 account_name
401	未登录或 token 失效
404	未找到拥有该浏览器环境的在线 Worker
503	Worker 不在线 / WebSocket 连接不存在 / 派发失败

请求参数:

参数	类型	必填	说明
task_type	string	是	任务类型：`check_login`（检查登录）、`boss_recruit`（招聘）
worker_id	string	否	目标 Worker ID（与 account_name 二选一）
account_name	string	否	浏览器环境名称（系统自动查找对应 Worker）
params	object	否	任务附加参数，默认 `{}`

路由规则: worker_id 优先；若未指定则通过 account_name 自动查找对应的在线 Worker。

请求示例 — 检查登录:

{
  "task_type": "check_login",
  "account_name": "第一个"
}

请求示例 — 招聘任务:

{
  "task_type": "boss_recruit",
  "worker_id": "worker-1",
  "params": {
    "keyword": "Python开发",
    "count": 10
  }
}

成功响应 (201):

{
  "task_id": "3f113d90bb32",
  "task_type": "check_login",
  "status": "dispatched",
  "worker_id": "worker-1",
  "account_name": "第一个",
  "params": {},
  "progress": null,
  "result": null,
  "error": null,
  "created_at": 1739520000.123,
  "updated_at": 1739520000.456
}

失败响应:

状态码	说明
400	未指定 worker_id 或 account_name
401	未登录或 token 失效
404	未找到拥有该浏览器环境的在线 Worker
503	Worker 不在线 / WebSocket 连接不存在 / 派发失败

GET /api/tasks

说明: 查询任务列表（内存中的任务）。

状态码:

状态码	说明
200	成功，返回任务数组
401	未登录或 token 失效

查询参数:

参数	类型	必填	说明
worker_id	string	否	按 Worker ID 过滤
status	string	否	按状态过滤：`pending` / `dispatched` / `running` / `success` / `failed` / `cancelled`
limit	int	否	返回数量限制，默认 50

响应示例:

[
  {
    "task_id": "3f113d90bb32",
    "task_type": "check_login",
    "status": "success",
    "worker_id": "worker-1",
    "account_name": "第一个",
    "params": {},
    "progress": "检测完成: 第一个 → 未登录 ()",
    "result": {
      "browser_id": "abd63190eea84dc49429962f7bb330a4",
      "browser_name": "第一个",
      "boss_username": "",
      "is_logged_in": false
    },
    "error": null,
    "created_at": 1739520000.123,
    "updated_at": 1739520030.789
  }
]

返回字段	类型	说明
task_id	string	任务唯一 ID（12 位十六进制）
task_type	string	任务类型
status	string	任务状态：`pending` → `dispatched` → `running` → `success`/`failed`
worker_id	string/null	执行任务的 Worker ID
account_name	string/null	关联的浏览器环境名称
params	object	任务参数
progress	string/null	执行进度描述
result	object/null	任务结果（成功时返回）
error	string/null	错误信息（失败时返回）
created_at	float	创建时间（Unix 时间戳）
updated_at	float	最后更新时间（Unix 时间戳）

GET /api/tasks/{task_id}

说明: 查询指定任务的状态和结果。

状态码:

状态码	说明
200	成功，返回单个任务对象
401	未登录或 token 失效
404	任务不存在

路径参数:

参数	类型	必填	说明
task_id	string	是	任务 ID

成功响应 (200): 同上单个任务对象

失败响应 (404):

{
  "detail": "任务 xxx 不存在"
}

六、任务类型说明

task_type	说明	必要参数	返回 result
`check_login`	检测浏览器环境中 BOSS 账号是否已登录	`account_name`（环境名）	`{ "browser_id", "browser_name", "boss_username", "is_logged_in" }`
`boss_recruit`	执行 BOSS 直聘自动招聘流程	`worker_id` + `params`	根据任务定义返回

七、任务状态流转

pending → dispatched → running → success
                              → failed
                    → cancelled

状态	说明
pending	任务已创建，等待派发
dispatched	已通过 WebSocket 发送给 Worker
running	Worker 正在执行中
success	执行成功
failed	执行失败
cancelled	已取消

八、联系记录（数据展示）

以下接口均需登录（携带 auth_token Cookie）

GET /api/contacts/query（按电话/微信号查询）

说明：根据已获取的电话号码或微信号查询联系记录，用于数据展示。对 contact 字段做模糊匹配。

状态码：

状态码	说明
200	成功，返回分页结果
400	未提供 contact 参数
401	未登录或 token 失效

查询参数：

参数	类型	必填	说明
contact	string	是	电话号码或微信号（支持部分匹配）
page	int	否	页码，默认 1
page_size	int	否	每页条数，默认 20

请求示例：

GET /api/contacts/query?contact=13800138000
GET /api/contacts/query?contact=wxid_abc&page=1&page_size=10

成功响应 (200)：

{
  "total": 2,
  "page": 1,
  "page_size": 20,
  "contact_keyword": "13800138000",
  "results": [
    {
      "id": 1,
      "name": "张三",
      "position": "Python开发",
      "contact": "13800138000",
      "reply_status": "已回复",
      "wechat_exchanged": true,
      "account_id": 1,
      "worker_id": "worker-1",
      "notes": "",
      "contacted_at": "2026-02-24T10:00:00",
      "created_at": "2026-02-24T10:00:00"
    }
  ]
}

返回字段	类型	说明
total	int	匹配总数
page	int	当前页
page_size	int	每页条数
contact_keyword	string	本次查询使用的关键词
results	array	联系记录列表（字段同联系记录模型）

失败响应 (400)：未提供 contact 参数时

{
  "detail": "请提供 contact 参数（电话号码或微信号）"
}

GET /api/contacts

说明：分页查询联系记录，支持按姓名、岗位、联系方式关键词搜索，以及按回复状态、是否交换微信筛选。

状态码：

状态码	说明
200	成功，返回 total、page、page_size、results
401	未登录或 token 失效

查询参数：search（关键词）、reply_status、wechat_exchanged、page、page_size。返回格式同上（含 total、page、page_size、results）。

九、通用错误格式

所有接口的错误响应统一为：

{
  "detail": "错误描述信息"
}

状态码	说明
400	请求参数错误
401	未登录或 token 失效
403	无权限
404	资源不存在
503	Worker 不在线或服务不可用

15 KiB Raw Blame History Unescape Escape

BOSS 直聘自动化平台 - API 接口文档

一、健康检查

GET /health

二、认证

POST /api/auth/login

三、Worker 管理

GET /api/workers

GET /api/workers/{worker_id}

四、账号管理

POST /api/accounts

GET /api/accounts

GET /api/accounts/{id}

DELETE /api/accounts/{id}

五、任务管理

POST /api/tasks

GET /api/tasks

GET /api/tasks/{task_id}

六、任务类型说明

七、任务状态流转

八、联系记录（数据展示）

GET /api/contacts/query（按电话/微信号查询）

GET /api/contacts

九、通用错误格式

15 KiB

Raw Blame History