hot_comment_radar/docs/UserGuide.md

用户操作与验收说明

1. 启动服务

首次使用先准备环境变量：

cp .env.example .env

打开 .env，填写：

TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=

启动：

docker compose up -d --build
curl -f http://localhost:8000/health

浏览器打开：

http://localhost:8000

2. 创建任务

首页选择平台：

• 小红书
• 抖音

可调整抓取规模：

• 热点数：默认 5
• 每热点内容：默认 5
• 每内容评论：默认 50

轻量验收建议使用：

1 热点 × 1 内容 × 10 评论

默认规模验收使用：

5 热点 × 5 内容 × 50 评论

点击“开始抓取”后会进入任务详情页。

3. 查看任务状态

任务状态包括：

• 运行中
• 已完成
• 失败

运行中任务会自动刷新。页面会展示：

• 已处理 / 总内容数
• 成功 / 失败内容数
• AI 成功率
• AI 样本不足提示
• 失败阶段、错误类型和错误信息

如果任务刚开始且还没有热点，会看到“正在抓取热点数据，请稍候...”。

4. 查看报告

任务完成后，在任务详情页可以进入：

• 热点级汇总报告
• 内容详情页

报告页面会展示：

• AI 总结
• 评论样本数
• 情绪分布
• Top 标签
• 典型评论
• 评论明细

如果报告尚未生成，页面会显示“报告生成中，请稍候...”，不会返回 500。

5. 文件导出

当前版本已关闭 CSV / Markdown 文件下载入口和接口。页面仍可直接查看：

• 热点级汇总报告
• 内容条目级报告
• 评论明细

6. 小规模验收

分别创建两个任务：

小红书：1 × 1 × 10
抖音：1 × 1 × 10

通过标准：

• 任务最终为“已完成”。
• 至少有热点、内容、评论、报告。
• AI 成功率正常，或页面有明确“AI 样本不足”提示。
• 能打开热点报告、内容详情页。
• 页面不展示 CSV / Markdown 下载入口。

7. 默认规模验收

分别创建两个任务：

小红书：5 × 5 × 50
抖音：5 × 5 × 50

注意：真实平台接口返回数量可能低于理论上限 1250 条评论。验收时重点判断：

• 任务是否完成。
• 是否有明确失败原因。
• 实际热点、内容、评论、报告数量。
• 页面和导出是否可用。

8. 常见问题

8000 端口被占用

先确认是否是本项目容器：

docker compose ps
lsof -nP -iTCP:8000 -sTCP:LISTEN

如果是旧容器：

docker compose down
docker compose up -d --build

不要临时改成 8001。

API Key 缺失

如果任务失败或没有真实数据，检查 .env：

TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=

任务长期 running

先打开任务详情页看进度。如果长时间没有变化：

docker compose logs --tail=120 app

重启服务后，遗留 running 任务会被标记为失败，并显示“系统重启，任务被中断”。

评论数量少于请求上限

这通常是平台真实返回不足，不一定是代码失败。以任务状态、成功内容数、报告生成情况和错误信息为准。

报告摘要失败

页面会显示默认文案，但统计、标签、典型评论和导出仍应可用。

重置本地数据库

仅在不需要保留历史任务时执行：

docker compose down
rm -f data/app.db data/app.db-wal data/app.db-shm
docker compose up -d --build
curl -f http://localhost:8000/health

公网云服务器部署

公网部署前先确认部署方式、访问密码、是否允许消耗真实 TikHub 和 AI Key。未经确认不要直接开放公网。

如果确认使用云服务器 Docker Compose，步骤与本地类似：

git pull
cp .env.example .env
docker compose up -d --build
curl -f http://127.0.0.1:8000/health

公网演示建议先初始化脱敏 Demo 数据：

docker compose exec app python -m app.demo_seed

如果页面出现数据库不可用提示，系统会尽量把 SQLite 文件备份到：

data/corrupt-backups

9. 推荐提交节奏

按 docs/MVP-WorkOrders.md 的工单推进：

完成一个工单 → 跑测试 → Docker 健康检查 → 网页验收 → commit

运行数据目录 data/ 不提交到 Git。