# 用户操作与验收说明

## 1. 启动服务

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

```bash
cp .env.example .env
```

打开 `.env`，填写：

```text
TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=
```

启动：

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

浏览器打开：

```text
http://localhost:8000
```

## 2. 创建任务

首页选择平台：

- 小红书
- 抖音

可调整抓取规模：

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

轻量验收建议使用：

```text
1 热点 × 1 内容 × 10 评论
```

默认规模验收使用：

```text
5 热点 × 5 内容 × 50 评论
```

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

## 3. 查看任务状态

任务状态包括：

- 运行中
- 已完成
- 失败

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

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

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

## 4. 查看报告

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

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

报告页面会展示：

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

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

## 5. 文件导出

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

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

## 6. 小规模验收

分别创建两个任务：

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

通过标准：

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

## 7. 默认规模验收

分别创建两个任务：

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

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

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

## 8. 常见问题

### 8000 端口被占用

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

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

如果是旧容器：

```bash
docker compose down
docker compose up -d --build
```

不要临时改成 8001。

### API Key 缺失

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

```text
TIKHUB_API_KEY=
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=
```

### 任务长期 running

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

```bash
docker compose logs --tail=120 app
```

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

### 评论数量少于请求上限

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

### 报告摘要失败

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

### 重置本地数据库

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

```bash
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，步骤与本地类似：

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

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

```bash
docker compose exec app python -m app.demo_seed
```

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

```text
data/corrupt-backups
```

## 9. 推荐提交节奏

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

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

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