feat: 完成源晶权限与经验系统并优化 me/admin 交互

docs/第三方REST接入指南.md

@@ -0,0 +1,101 @@
+# 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，也会自动入库到爬虫列表。