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 当前执行模式：初始阶段先串行

当前项目处于初始单人开发和流程练习阶段。默认执行策略为：

一个 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 主链路依赖

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 平台抓取并行依赖

T07 API 客户端与重试
  -> T08 小红书字段映射 --\
                           -> T10 评论分页、间隔与去重 -> T11 抓取任务主流程集成
  -> T09 抖音字段映射 ----/

3.3 页面与导出依赖

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 可选任务依赖

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、任务列表测试

组内顺序：

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 后串行完成

组内顺序：

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 后串行接入

组内顺序：

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 收敛

推荐顺序：

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. 总体执行顺序建议

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