holy后端

README.md

@@ -0,0 +1,43 @@
+# Holy蟹搜索监测平台业务后端
+
+该服务位于 Web 前端与现有小红书爬虫服务之间：
+
+```text
+Web 前端 -> 本业务后端（默认 8000）-> xiaoti-framework 爬虫服务（默认 5000）
+```
+
+业务后端负责生成公开任务 ID、保存任务列表、异步调用爬虫、同步状态与进度，以及保存结果文件。浏览器不再直接访问爬虫接口。
+
+## 启动
+
+```bash
+cd "/Users/xiaoti/Downloads/Holy蟹搜索监测平台-后端服务-20260723"
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+python app.py
+```
+
+默认连接远程爬虫服务 `http://43.139.175.114:12007`。如地址不同，设置：
+
+```bash
+export CRAWLER_BASE_URL="http://实际爬虫地址:端口"
+```
+
+SQLite 数据库默认保存在 `data/holy_crab.db`，任务文件保存在 `data/files/`。
+
+## 已实现接口
+
+- `POST /api/v1/tasks`：创建任务并立即返回业务任务 ID
+- `GET /api/v1/tasks`：任务列表、搜索、状态筛选和分页
+- `GET /api/v1/tasks/{taskId}`：任务状态、进度、结果及文件
+- `POST /api/v1/tasks/{taskId}/cancel`：取消任务
+- `POST /api/v1/tasks/{taskId}/retry`：重新发起任务
+- `GET /api/v1/tasks/{taskId}/files`：文件列表
+- `GET /api/v1/tasks/{taskId}/files/{fileId}/preview`：预览
+- `GET /api/v1/tasks/{taskId}/files/{fileId}/download`：下载
+
+当前接入规则与原前端保持一致：深度任务调用爬虫 `/api/v1/xhs/wen/sources`，轻度和常规任务调用 `/api/v1/xhs/wen/overview`。
+
+取消操作会立即把业务任务标记为 `cancelled`，业务 Worker 不再接收爬虫结果。现有爬虫服务没有取消接口，因此已经发出的远端采集请求不能被强制中止；后续如爬虫服务增加取消接口，可在 `cancel_task` 中继续转发。