hot_comment_radar/docs/TaskDependency.md

# 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` 复选框。