docs: 同步任务执行文档

docs/TaskDependency.md

@@ -0,0 +1,371 @@
+# TaskDependency.md：任务依赖关系与执行方案
+
+## 1. 文档依据
+
+本分析依据：
+
+- `docs/Tasks.md`
+- `docs/DevelopmentPlan.md`
+
+未发现 `docs/review-*.md` 文件。
+
+保存位置确认：本文保存为 `docs/TaskDependency.md`。原因是它属于开发任务执行计划的补充文档，文件名能直接表达用途，且不覆盖现有 source-of-truth 文档。
+
+## 2. 重要冲突与执行口径
+
+### 2.0 当前执行模式：初始阶段先串行
+
+当前项目处于初始单人开发和流程练习阶段。默认执行策略为：
+
+```text
+一个 Task -> 一个分支 -> 完成并验证 -> 一个 focused commit -> 审查通过后再进入下一个 Task
+```
+
+暂不启用并行开发，暂不创建 PR，除非用户明确要求切换到并行或 PR 工作流。
+
+分支命名沿用 `docs/CodexPrompts.md` 中的 `feat/tXX-short-description`。每个 Task
+完成后，优先创建一个能用一句话说明的 commit；若 Task 很大，允许拆成多个有意义、
+可测试、可回滚的小 commit，但当前练习阶段优先保持“一 Task 一 commit”。
+
+本文后续并行方案保留为未来提速参考，不是当前默认执行方式。
+
+### 2.1 T13 AI batch 降级策略存在文档冲突
+
+- `docs/Tasks.md` T13 明确要求：`batch size 固定为 20，不做动态缩减`，并写明 `不实现 batch size 减半逻辑`。
+- `docs/DevelopmentPlan.md` §7.3 与 §16 仍写有：第 3 次重试时 `batch_size` 减半。
+
+执行建议：后续实现前必须由用户确认以哪个文档为准。若按 `AGENTS.md` 的 source-of-truth 顺序，`docs/Tasks.md` 在执行 sequencing 上更具体，且其变更日志明确说明 T13 已移除减半逻辑，因此本文的依赖和并行计划按 T13「固定 batch size、最多 3 次整批重试」建模，但不替代用户确认。
+
+### 2.2 报告总结失败默认文案存在轻微差异
+
+- `docs/Tasks.md` T14 要求默认文案为：`总结生成失败，请查看上方统计数据。`
+- `docs/DevelopmentPlan.md` §8.1/§8.2 要求默认文案为：`总结生成失败，请查看详细数据`
+
+执行建议：实现 T14/T15 前需确认统一文案，避免测试和页面展示不一致。
+
+## 3. 依赖关系图（文字版）
+
+### 3.1 主链路依赖
+
+```text
+T01 初始化项目结构与依赖
+  -> T02 配置管理与环境变量
+  -> T03 数据库初始化与模型
+  -> T04 任务创建 API 与单任务执行器
+      -> T05 僵尸任务恢复
+      -> T06 首页 / 任务列表基础页面
+  -> T07 外部 API 基础客户端与重试
+      -> (T08 小红书字段映射 || T09 抖音字段映射)
+      -> T10 评论分页、间隔与去重
+      -> T11 抓取任务主流程集成
+      -> T12 AI Prompt 与结构化输出校验
+      -> T13 AI 重试、成功率统计
+      -> T14 内容条目级报告生成
+      -> T15 热点级报告生成
+      -> T16 AI + 报告集成到任务流程
+      -> T17 任务详情页
+      -> T18 热点级报告页
+      -> T19 内容条目详情页与评论明细
+      -> T20 导出服务
+      -> T21 模板宏、过滤器与静态交互
+      -> T22 Docker Compose 与部署
+      -> T23 最终测试与手工验收
+```
+
+### 3.2 平台抓取并行依赖
+
+```text
+T07 API 客户端与重试
+  -> T08 小红书字段映射 --\
+                           -> T10 评论分页、间隔与去重 -> T11 抓取任务主流程集成
+  -> T09 抖音字段映射 ----/
+```
+
+### 3.3 页面与导出依赖
+
+```text
+T06 首页基础页面
+  -> T17 任务详情页
+
+T14 内容条目级报告生成 -> T19 内容条目详情页
+T15 热点级报告生成     -> T18 热点级报告页
+T15 热点级报告生成     -> T20 Markdown 导出
+T11 抓取任务集成       -> T20 CSV 导出
+
+T17/T18/T19/T20
+  -> T21 模板宏、过滤器与静态交互
+```
+
+说明：T21 可在 T17-T20 之前先做 macro/filter 的底座，但它会修改多个页面共享文件。为了降低多人文件冲突，建议放到页面任务之后做统一收敛，或指定一个模板负责人先完成共享 macro，再串行接入页面。
+
+### 3.4 P1 可选任务依赖
+
+```text
+P1-01 任务列表自动轮询
+  depends on: T06, T21 的 app.js / partials 基础
+
+P1-02 原始 JSON 调试入口
+  depends on: T19
+
+P1-03 基础进度条
+  depends on: T04/T11 进度字段, T06/T17 页面
+```
+
+## 4. 任务级前置依赖清单
+
+| 任务 | 必须前置 | 主要原因 |
+|---|---|---|
+| T01 初始化项目结构与依赖 | 无 | 建立项目、依赖、测试和健康检查基础 |
+| T02 配置管理与环境变量 | T01 | 修改 `app/config.py`、`.env.example` 和配置测试 |
+| T03 数据库初始化与模型 | T01, T02 | 数据库 URL 与 SQLAlchemy 初始化依赖配置基础 |
+| T04 任务创建 API 与单任务执行器 | T03 | 需要 `tasks` 表、schema、session 和 FastAPI 应用 |
+| T05 僵尸任务恢复 | T04 | 依赖任务状态模型、task_service 和应用 lifespan |
+| T06 首页 / 任务列表基础页面 | T04 | 页面创建任务和列表展示依赖任务 API |
+| T07 外部 API 基础客户端与重试 | T02 | 依赖 TikHub base URL、API key、HTTP timeout/retry 配置 |
+| T08 小红书字段映射 | T07 | 依赖通用同步 HTTP client 与错误抽象 |
+| T09 抖音字段映射 | T07 | 依赖通用同步 HTTP client 与错误抽象 |
+| T10 评论分页、间隔与去重 | T08, T09, T02 | 同时修改两平台分页推进，依赖分页间隔配置 |
+| T11 抓取任务主流程集成 | T04, T07, T08, T09, T10 | 串起任务生命周期、平台抓取、入库和容错 |
+| T12 AI Prompt 与结构化输出校验 | T03, T02 | 依赖 comments 模型字段、AI 配置和 prompt 目录 |
+| T13 AI 重试、成功率统计 | T12, T04 | 依赖 AI schema 校验与 tasks 分析状态字段 |
+| T14 内容条目级报告生成 | T12, T13, T03 | 依赖已分析评论、reports 表和报告 prompt |
+| T15 热点级报告生成 | T14 | 聚合内容条目级统计，并扩展同一 report_service |
+| T16 AI + 报告集成到任务流程 | T11, T13, T14, T15 | 将抓取、AI、报告接入完整任务流程 |
+| T17 任务详情页 | T06, T11 | 需要任务进度、热点、内容条目和失败信息 |
+| T18 热点级报告页 | T15, T17 | 需要预生成热点报告和任务详情入口 |
+| T19 内容条目详情页与评论明细 | T14, T17 | 需要预生成 item 报告、评论 AI 字段和任务详情入口 |
+| T20 导出服务 | T14, T15, T18, T19 | Markdown 读取 reports；CSV 读取评论；按钮状态依赖页面模板 |
+| T21 模板宏、过滤器与静态交互 | T06, T17, T18, T19, T20 | 收敛各页面状态、情绪、标签、标题、导出交互 |
+| T22 Docker Compose 与部署 | T01, T02, T03；建议 T16/T21 后 | 依赖应用可启动、配置齐全、数据库初始化可用；完整验收依赖主功能基本完成 |
+| T23 最终测试与手工验收 | T01-T22 | MVP 闭环验收 |
+
+## 5. 可并行执行的任务
+
+并行判断原则：
+
+1. 前置依赖已满足。
+2. 任务之间不修改同一核心文件。
+3. 若测试文件共享，如 `tests/integration/test_routes.py` 或 `tests/unit/test_report_stats.py`，并行时必须提前拆分测试文件或指定一个人负责合并。
+
+### 5.1 强推荐并行
+
+| 并行任务 | 前置条件 | 不冲突理由 |
+|---|---|---|
+| T08 小红书字段映射 + T09 抖音字段映射 | T07 完成 | 分别修改 `app/platforms/xiaohongshu.py` 与 `app/platforms/douyin.py`，测试和 fixtures 独立 |
+| T20 导出服务的纯 service/unit-test 部分 + T18/T19 页面模板草稿 | T14, T15 完成 | `export_service.py` 和导出单元测试不触碰页面模板；路由与按钮接入需后续串行 |
+| T22 Docker Compose + 页面 polish 收尾 | T01-T03 基础稳定，应用可启动 | Docker 文件与页面模板/CSS/JS 基本独立；`.env.example` 修改需避开 T02 |
+
+### 5.2 可并行但需要合并纪律
+
+| 并行任务 | 前置条件 | 合并纪律 |
+|---|---|---|
+| T05 僵尸任务恢复 + T06 首页基础页面 | T04 完成 | 都会修改 `app/main.py`；T05 聚焦 lifespan/task_service，T06 聚焦模板路由，需一个人最终合并 main.py |
+| T12 AI schema + T14 报告统计测试设计 | T03 完成 | T14 实现依赖 T12/T13，但报告统计测试数据和期望可先写；注意不提前假定 T13 冲突策略 |
+| T17 任务详情页 + T20 导出服务测试设计 | T14/T15 基础模型稳定 | T20 的按钮 disabled 测试依赖页面模板，服务层 CSV/Markdown 测试可先行 |
+| T18 热点报告页 + T19 内容条目详情页 | T17, T14, T15 完成 | 模板文件不同，但都改 `app/main.py` 和 `tests/integration/test_routes.py`，需路由合并约定 |
+| T20 导出服务完整任务 + T21 macro/filter 预研 | T14, T15 完成 | T20 route/按钮和 T21 filter/static 会共享 `app/main.py`、模板和静态文件，需拆分边界 |
+| P1-01 自动轮询 + P1-03 进度条 | P0 页面完成 | 都会修改 `index.html`、`task_rows.html`、`app.js`、`app.css`，建议同一前端负责人处理 |
+
+### 5.3 不建议并行
+
+| 任务组合 | 原因 |
+|---|---|
+| T01/T02/T03/T04 | 都修改核心骨架、配置、模型、main.py，依赖强且文件重叠多 |
+| T10 与 T08/T09 | T10 会修改两平台分页实现，容易覆盖字段映射阶段改动 |
+| T11 与 T04/T10 | T11 集成任务流程依赖任务创建和分页完成，且会集中修改 `task_service.py`、`crawl_service.py` |
+| T13 与 T16 | 都修改 AI 调用接入和 `task_service.py`，应先完成 T13 单元能力，再接入 T16 |
+| T14 与 T15 | 都集中修改 `report_service.py` 和 `test_report_stats.py`，建议串行；多人时可先约定接口后由同一人合并 |
+| T17/T18/T19/T21 同时落地 | 共享 `main.py`、`test_routes.py`、`test_template_filters.py`、`base.html` 和 CSS/JS，冲突概率高 |
+
+## 6. 推荐并行分组方案
+
+### Group 0：文档冲突确认与执行口径冻结
+
+| 内容 | 任务 |
+|---|---|
+| 目标 | 确认 T13 是否固定 batch size；确认报告总结失败默认文案 |
+| 前置 | 无 |
+| 输出 | 明确实现口径，可写入 `docs/Tasks.md` 或新 review 文档 |
+| 文件冲突风险 | 低；若修改 docs，则只改相关文档 |
+
+### Group 1：项目基础串行启动
+
+| 顺序 | 任务 | 说明 |
+|---|---|---|
+| 1 | T01 | 项目结构、依赖、`/health` |
+| 2 | T02 | 配置和 `.env.example` |
+| 3 | T03 | 数据库和模型 |
+| 4 | T04 | 任务 API 和单 worker 执行器 |
+
+文件冲突风险：
+
+- 高度串行，不建议多人同时做。
+- 主要冲突文件：`app/main.py`、`app/config.py`、`app/db.py`、`app/models.py`、`app/schemas.py`、`tests/conftest.py`。
+
+### Group 2：任务恢复与首页基础
+
+| 可并行子组 | 任务 | 负责人边界 |
+|---|---|---|
+| 2A | T05 僵尸任务恢复 | `task_service.py` 恢复函数、lifespan 测试 |
+| 2B | T06 首页 / 任务列表基础页面 | templates/static、首页 route、任务列表测试 |
+
+组内顺序：
+
+```text
+T04 -> (T05 || T06) -> 合并 app/main.py 与路由测试
+```
+
+文件冲突风险：
+
+- `app/main.py`：T05 注册 lifespan，T06 注册页面路由。
+- `tests/integration/test_routes.py` 与 `tests/integration/test_task_recovery.py` 应分文件，降低冲突。
+- `tests/unit/test_template_filters.py` 后续 T21 还会继续修改。
+
+### Group 3：平台抓取并行
+
+| 可并行子组 | 任务 | 负责人边界 |
+|---|---|---|
+| 3A | T07 外部 API 基础客户端与重试 | 先串行完成，作为平台公共依赖 |
+| 3B | T08 小红书字段映射 | `xiaohongshu.py`、xhs fixtures、xhs mapping tests |
+| 3C | T09 抖音字段映射 | `douyin.py`、douyin fixtures、douyin mapping tests |
+| 3D | T10 评论分页、间隔与去重 | T08/T09 合并后串行完成 |
+| 3E | T11 抓取任务主流程集成 | T10 后串行完成 |
+
+组内顺序：
+
+```text
+T07 -> (T08 || T09) -> T10 -> T11
+```
+
+文件冲突风险：
+
+- T08/T09 冲突低。
+- T10 会同时修改 `app/platforms/xiaohongshu.py`、`app/platforms/douyin.py`、`app/services/crawl_service.py`，必须等 T08/T09 合并。
+- T11 修改 `app/services/task_service.py` 与 `app/services/crawl_service.py`，不要和 T10 并行改同一文件。
+
+### Group 4：AI 与报告
+
+| 可并行子组 | 任务 | 负责人边界 |
+|---|---|---|
+| 4A | T12 AI Prompt 与结构化输出校验 | `ai_service.py` 初版、comment prompt、AI fixtures |
+| 4B | T13 AI 重试、成功率统计 | T12 后串行扩展 `ai_service.py` 和 task analysis 字段 |
+| 4C | T14 内容条目级报告生成 | T13 后实现 `report_service.py` 初版 |
+| 4D | T15 热点级报告生成 | T14 后扩展同一 `report_service.py` |
+| 4E | T16 AI + 报告集成到任务流程 | T11/T13/T14/T15 后串行接入 |
+
+组内顺序：
+
+```text
+T12 -> T13 -> T14 -> T15
+T11 ----------------------\
+                           -> T16
+```
+
+文件冲突风险：
+
+- T12/T13 都改 `app/services/ai_service.py` 和 `tests/unit/test_ai_schema.py`，不建议并行。
+- T14/T15 都改 `app/services/report_service.py` 和 `tests/unit/test_report_stats.py`，不建议并行。
+- T16 同时改 `task_service.py`、`ai_service.py`、`report_service.py` 和两平台集成测试，必须在前面服务稳定后做。
+
+### Group 5：页面与导出
+
+| 可并行子组 | 任务 | 负责人边界 |
+|---|---|---|
+| 5A | T17 任务详情页 | `tasks/detail.html`、任务详情 route |
+| 5B | T18 热点级报告页 | `hotspots/report.html`、热点报告 route |
+| 5C | T19 内容条目详情页 | `items/detail.html`、评论明细 route |
+| 5D | T20 导出服务 | `export_service.py`、export routes、导出测试 |
+| 5E | T21 模板宏、过滤器与静态交互 | 共享 macro/static/title/filter 收敛 |
+
+推荐顺序：
+
+```text
+T16 -> T17
+T17 + T15 -> T18
+T17 + T14 -> T19
+T14 + T15 -> T20
+(T17/T18/T19/T20) -> T21
+```
+
+可并行执行：
+
+- T18 与 T19 可并行，但需避免同时大改 `app/main.py`。
+- T20 服务层可与 T18/T19 页面并行；模板按钮状态接入建议等页面模板稳定后统一做。
+- T21 建议作为页面组最后的收敛任务，统一抽 macro、filter、title 和 JS 行为。
+
+文件冲突风险：
+
+- `app/main.py`：T17/T18/T19/T20 都会添加路由。
+- `tests/integration/test_routes.py`：T17/T18/T19/T20 都会扩展。
+- `tests/unit/test_template_filters.py`：T17/T19/T20/T21 都可能修改。
+- `app/templates/base.html`、`app/static/app.js`、`app/static/app.css`：T06/T20/T21 共享。
+
+### Group 6：部署与最终验收
+
+| 顺序 | 任务 | 说明 |
+|---|---|---|
+| 1 | T22 Docker Compose 与部署 | 应用主体完成后做部署闭环 |
+| 2 | T23 最终测试与手工验收 | 覆盖单元、集成、coverage、Docker、双平台手工流程 |
+
+文件冲突风险：
+
+- T22 主要改 `Dockerfile`、`docker-compose.yml`、`.env.example`，与业务代码冲突低。
+- `.env.example` 已由 T02 修改，T22 修改前需读取最新文件。
+- T23 会修改 `README.md` 和 `docs/Tasks.md` 勾选完成项，只能在真实完成并验证后执行。
+
+## 7. 总体执行顺序建议
+
+```text
+Group 0 冲突确认
+  -> Group 1 基础串行启动
+  -> Group 2 恢复与首页
+  -> Group 3 平台抓取
+  -> Group 4 AI 与报告
+  -> Group 5 页面与导出
+  -> Group 6 部署与验收
+```
+
+若多人协作，最有价值的并行窗口是：
+
+1. T08 与 T09。
+2. T18 与 T19。
+3. T20 服务层与 T18/T19 页面层。
+4. T22 与页面 polish 收尾。
+
+最应避免的并行窗口是：
+
+1. T01-T04 基础骨架。
+2. T10/T11 抓取集成。
+3. T13/T16 AI 接入。
+4. T14/T15 报告服务。
+5. T21 共享模板收敛。
+
+## 8. 每组文件冲突风险汇总
+
+| 分组 | 冲突等级 | 高风险文件 | 风险说明 | 建议 |
+|---|---|---|---|---|
+| Group 1 基础 | 高 | `app/main.py`, `app/config.py`, `app/models.py`, `app/schemas.py`, `tests/conftest.py` | 基础文件会被连续扩展，接口和模型尚未稳定 | 串行执行 |
+| Group 2 恢复与首页 | 中 | `app/main.py`, `tests/integration/test_routes.py`, `tests/unit/test_template_filters.py` | lifespan、页面 route、模板测试可能同时变动 | 分清 route/lifespan 修改边界，最终统一合并 |
+| Group 3 平台抓取 | 中 | `app/services/crawl_service.py`, `app/platforms/xiaohongshu.py`, `app/platforms/douyin.py`, `tests/unit/test_comment_pagination.py` | T08/T09 低冲突；T10/T11 高耦合 | 只并行 T08/T09，T10/T11 串行 |
+| Group 4 AI 与报告 | 高 | `app/services/ai_service.py`, `app/services/report_service.py`, `app/services/task_service.py`, `tests/unit/test_ai_schema.py`, `tests/unit/test_report_stats.py` | 服务能力和集成接入依赖强 | T12-T16 基本串行 |
+| Group 5 页面与导出 | 高 | `app/main.py`, `tests/integration/test_routes.py`, `tests/unit/test_template_filters.py`, `app/templates/base.html`, `app/static/app.js`, `app/static/app.css` | 多页面和导出按钮都触碰共享模板与路由 | 服务层和模板层拆人，route 合并由一人负责 |
+| Group 6 部署验收 | 低到中 | `.env.example`, `docs/Tasks.md`, `README.md` | T22 与 T02 共享 env 示例；T23 会勾选任务 | T22 读取最新 env；T23 只在验证后勾选 |
+
+## 9. 多代理分工建议
+
+如使用多代理并行，建议每个代理使用独立分支，且不要让两个代理同时编辑同一文件。
+
+推荐分支示例：
+
+- `agent/codex-1/T08-xiaohongshu`
+- `agent/codex-2/T09-douyin`
+- `agent/codex-3/T18-hotspot-report-page`
+- `agent/codex-4/T19-item-detail-page`
+- `agent/codex-5/T20-export-service`
+
+主代理保留职责：
+
+1. 冻结文档冲突口径。
+2. 合并共享文件：`app/main.py`、`task_service.py`、`report_service.py`、共享测试文件。
+3. 运行完整验证。
+4. 更新 `docs/Tasks.md` 复选框。