# CSP Quest World 第三方 REST 接入指南

本文档用于第三方系统（脚本、自动化平台、企业内部系统）快速接入 CSP Quest World 的 REST API。

## 1. 基础信息

- 线上基础地址：`https://csp.hao.work/admin139/api/v1`
- 文档入口（Swagger）：`https://csp.hao.work/api-docs`
- OpenAPI JSON：`https://csp.hao.work/admin139/api/openapi.json`
- 数据格式：`application/json`

## 2. 鉴权方式

受保护接口支持两种方式，任选其一：

1. Bearer Token（推荐）
- 先调用 `/auth/login` 获取 `token`
- 请求头带上：`Authorization: Bearer <token>`

2. Basic 账号密码（适合第三方直连）
- 请求头带上：`Authorization: Basic <base64(username:password)>`
- 示例：`alice:password123` -> `YWxpY2U6cGFzc3dvcmQxMjM=`

说明：
- 两种方式都可访问全部 REST 接口。
- 管理员接口仍需管理员账号（如 `admin`）才能通过权限校验。

## 3. 快速调用示例

### 3.1 登录获取 Token

```bash
curl -X POST 'https://csp.hao.work/admin139/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"password123"}'
```

### 3.2 使用 Bearer 调用

```bash
curl 'https://csp.hao.work/admin139/api/v1/me' \
  -H 'Authorization: Bearer <token>'
```

### 3.3 使用 Basic 调用

```bash
curl 'https://csp.hao.work/admin139/api/v1/me' \
  -H 'Authorization: Basic YWxpY2U6cGFzc3dvcmQxMjM='
```

## 4. Python 示例（requests）

```python
import base64
import requests

BASE = "https://csp.hao.work/admin139/api/v1"
username = "alice"
password = "password123"

basic = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("utf-8")
headers = {"Authorization": f"Basic {basic}"}

resp = requests.get(f"{BASE}/me", headers=headers, timeout=15)
resp.raise_for_status()
print(resp.json())
```

## 5. 响应约定

- 成功：`{ "ok": true, "data": ... }`（Auth 接口除外）
- 失败：`{ "ok": false, "error": "..." }`

常见状态码：
- `200`：成功
- `400`：请求参数错误
- `401`：未登录或鉴权失败
- `403`：有登录身份但权限不足（如非管理员访问管理员接口）
- `404`：资源不存在
- `409`：状态冲突（例如任务已在运行）

## 6. 安全建议

1. 生产环境优先用 HTTPS。
2. 若可控，优先使用 Bearer Token，减少明文密码在网关/代理日志出现的风险。
3. 使用 Basic 时建议为第三方集成准备专用账号，并定期更换密码。
4. 管理员账号只用于管理员接口，不建议用于普通业务拉取。

## 7. 爬虫自动化接口（管理员）

- 爬虫列表：`GET /admin/crawlers?status=&limit=`
- 新增目标：`POST /admin/crawlers`，Body：`{ "url": "https://example.com" }`
- 重新入队：`POST /admin/crawlers/{id}/queue`
- 运行记录：`GET /admin/crawlers/{id}/runs?limit=20`
- 守护状态：`GET /backend/crawler-guard/status`

说明：
- 新地址入库后，后端守护会自动执行：规则生成（LLM）→ 自动测试 → 自动运行。
- `crawler-guard/status` 返回 `active_requeue_interval_sec`，用于确认周期重跑间隔（默认 43200 秒，即 12 小时）。
- 飞书群内 `@机器人` 的文本消息若含 URL，也会自动入库到爬虫列表。