From a8f5eeaff58a13958ce01d63b6c881d0c16a3c1e Mon Sep 17 00:00:00 2001
From: meijiali <你的邮箱@xxx.com>
Date: Fri, 3 Jul 2026 15:33:49 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E6=9C=AC=E5=9C=B0?=
 =?UTF-8?q?=E9=AA=8C=E6=94=B6=E5=92=8C=E9=83=A8=E7=BD=B2=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/MVP-WorkOrders.md  |  17 ++++
 docs/UserGuide.md       | 208 ++++++++++++++++++++++++++++++++++++++++
 tests/unit/test_docs.py |  21 ++++
 3 files changed, 246 insertions(+)
 create mode 100644 docs/UserGuide.md
 create mode 100644 tests/unit/test_docs.py

diff --git a/docs/MVP-WorkOrders.md b/docs/MVP-WorkOrders.md
index e7666b4..d884a8a 100644
--- a/docs/MVP-WorkOrders.md
+++ b/docs/MVP-WorkOrders.md
@@ -720,6 +720,23 @@ chore: 整理 Docker 启动与部署配置
 docs: 补充本地验收和部署说明
 ```
 
+完成记录：
+
+```text
+完成日期：2026-07-03
+相关 commit：docs: 补充本地验收和部署说明
+验证命令：
+- .venv/bin/python -m pytest tests/unit/test_docs.py -q
+- .venv/bin/python -m pytest tests/unit tests/integration -q
+- curl -f http://localhost:8000/health
+验收结论：
+- 新增 docs/UserGuide.md，覆盖启动、创建任务、小规模验收、默认规模验收、报告查看、导出、常见问题和数据库重置。
+- 用户指南明确固定入口 http://localhost:8000，说明不要临时改 8001。
+- 文档说明 API Key 缺失、任务长期 running、评论数量少于上限、报告摘要失败等排查方式。
+- 新增文档测试，防止关键章节被误删。
+遗留问题：无；进入 WO-10 发布候选验收。
+```
+
 ### WO-10 发布候选版本验收
 
 优先级：P0
diff --git a/docs/UserGuide.md b/docs/UserGuide.md
new file mode 100644
index 0000000..e7b24c1
--- /dev/null
+++ b/docs/UserGuide.md
@@ -0,0 +1,208 @@
+# 用户操作与验收说明
+
+## 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. 导出文件
+
+支持导出：
+
+- 热点报告 Markdown
+- 内容报告 Markdown
+- 热点评论 CSV
+- 内容评论 CSV
+
+CSV 使用 UTF-8-BOM，适合 Windows Excel 打开。评论内容中的换行会被替换为空格，`= + - @` 开头的内容会自动加单引号，避免被 Excel 当作公式执行。
+
+## 6. 小规模验收
+
+分别创建两个任务：
+
+```text
+小红书：1 × 1 × 10
+抖音：1 × 1 × 10
+```
+
+通过标准：
+
+- 任务最终为“已完成”。
+- 至少有热点、内容、评论、报告。
+- AI 成功率正常，或页面有明确“AI 样本不足”提示。
+- 能打开热点报告、内容详情页。
+- 能导出 Markdown 和 CSV。
+
+## 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
+```
+
+## 9. 推荐提交节奏
+
+按 `docs/MVP-WorkOrders.md` 的工单推进：
+
+```text
+完成一个工单 → 跑测试 → Docker 健康检查 → 网页验收 → commit
+```
+
+运行数据目录 `data/` 不提交到 Git。
diff --git a/tests/unit/test_docs.py b/tests/unit/test_docs.py
new file mode 100644
index 0000000..f3594a0
--- /dev/null
+++ b/tests/unit/test_docs.py
@@ -0,0 +1,21 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_user_guide_covers_startup_acceptance_exports_and_troubleshooting():
+    content = (ROOT / "docs" / "UserGuide.md").read_text(encoding="utf-8")
+
+    for required in [
+        "docker compose up -d --build",
+        "http://localhost:8000",
+        "1 × 1 × 10",
+        "5 × 5 × 50",
+        "导出文件",
+        "8000 端口被占用",
+        "API Key 缺失",
+        "任务长期 running",
+        "重置本地数据库",
+    ]:
+        assert required in content