feat(frontend): 重构视频分析页面，支持多种搜索方式

主要更新： - 前端改用 Ant Design 组件（Table、Modal、Select 等） - 支持三种搜索方式：星图ID、达人unique_id、达人昵称模糊匹配 - 列表页实时调用云图 API 获取 A3 数据和成本指标 - 详情弹窗显示完整 6 大类指标，支持文字复制 - 品牌 API URL 格式修复为查询参数形式 - 优化云图 API 参数格式和会话池管理 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 22:01:55 +08:00
parent f123f68be3
commit 7cd29c5980
25 changed files with 2482 additions and 1324 deletions
@@ -64,6 +64,15 @@ KOL Insight 旨在解决这一痛点，提供批量数据查询和智能成本
 |----|----------|----------|
 | US-007 | 作为运营人员，我想要点击视频链接直接跳转，以便快速查看原视频 | 1. 视频链接可点击<br>2. 新窗口打开视频页面 |

+<!-- ITER: 2026-01-28 - 新增视频分析用户故事 -->
+<!-- NEW START -->
+#### P0 - 视频分析增强
+
+| ID | 用户故事 | 验收标准 |
+|----|----------|----------|
+| US-008 | 作为运营人员，我想要查看视频的详细分析数据（触达、A3、搜索、费用、成本指标），以便全面评估视频投放效果 | 1. 调用巨量云图API获取实时数据<br>2. 展示6大类25+指标<br>3. 成本指标自动计算<br>4. A3指标更新到数据库 |
+<!-- NEW END -->
+
 ### 2.3 用户旅程

 **核心用户旅程：批量查询 KOL 数据**
@@ -86,6 +95,7 @@ KOL Insight 旨在解决这一痛点，提供批量数据查询和智能成本
 ### 3.1 功能架构

 <!-- MODIFIED: 统一术语为"预估自然看后搜人数" -->
+<!-- ITER: 2026-01-28 - 新增巨量云图视频分析模块 -->
 ```
 KOL Insight
 ├── 数据查询模块
@@ -99,8 +109,13 @@ KOL Insight
 ├── 数据展示模块
 │   ├── 结果列表展示
 │   └── 视频链接跳转
-└── 数据导出模块
-    └── Excel/CSV导出
+├── 数据导出模块
+│   └── Excel/CSV导出
+└── 视频分析模块 (NEW)
+    ├── SessionID池管理
+    ├── 巨量云图API集成
+    ├── 实时数据获取与更新
+    └── 视频分析报表展示
 ```

 ### 3.2 功能详情
@@ -135,6 +150,19 @@ KOL Insight
 |--------|------|--------------|--------|----------|
 | 数据导出 | 将查询结果导出为 Excel/CSV 格式 | US-005 | P1 | 文件可下载，数据完整，中文列名 |

+<!-- ITER: 2026-01-28 - 新增巨量云图视频分析模块 -->
+<!-- NEW START -->
+#### 3.2.5 视频分析模块
+
+| 功能点 | 描述 | 关联用户故事 | 优先级 | 验收标准 |
+|--------|------|--------------|--------|----------|
+| SessionID池管理 | 从内部API获取Cookie列表，随机选取sessionid用于请求 | US-008 | P0 | 1. 调用内部API获取100个sessionid<br>2. 随机选取机制实现<br>3. 失败自动切换重试（最多3次） |
+| 巨量云图API封装 | 调用GetContentMaterialAnalysisInfo获取视频分析数据 | US-008 | P0 | 1. 正确构造请求参数<br>2. 超时设置10秒<br>3. 错误处理和日志记录 |
+| 视频分析接口 | GET /api/v1/videos/{item_id}/analysis | US-008 | P0 | 1. 返回6大类指标<br>2. 计算指标准确<br>3. 除零返回null |
+| 数据库A3指标更新 | 从API获取数据后更新数据库对应字段 | US-008 | P1 | 1. 更新total_new_a3_cnt<br>2. 更新heated_new_a3_cnt<br>3. 更新natural_new_a3_cnt<br>4. 更新total_cost |
+| 视频分析报表 | 前端展示6大类25+指标 | US-008 | P1 | 1. 基础信息展示<br>2. 触达/A3/搜索/费用/成本指标展示<br>3. 数值格式化 |
+<!-- NEW END -->
+
 ## 4. 非功能需求

 ### 4.1 性能需求
@@ -231,6 +259,8 @@ KOL Insight
 |------|------|--------|
 | PostgreSQL | 数据存储与查询 | 自建数据库 |
 | 品牌API | 根据品牌ID获取品牌名称 | 内部API (api.internal.intelligrow.cn) |
+| Cookie池API | 获取巨量云图SessionID列表 | 内部API (api.internal.intelligrow.cn) |
+| 巨量云图API | 获取视频分析数据 | 巨量云图 (yuntu.oceanengine.com) |

 <!-- NEW START -->
 **品牌API详情**：
@@ -240,6 +270,74 @@ KOL Insight
 - 文档：https://api.internal.intelligrow.cn/docs#/云图
 <!-- NEW END -->

+<!-- ITER: 2026-01-28 - 修复品牌API响应解析+添加认证 -->
+<!-- NEW START -->
+**品牌API认证与响应格式**：
+- 认证方式：Bearer Token（`Authorization: Bearer {token}`）
+- Token配置：通过环境变量 `BRAND_API_TOKEN` 配置
+- 响应格式：
+```json
+{
+  "total": 1,
+  "last_updated": "2025-12-30T11:28:40.738185",
+  "has_more": 0,
+  "data": [
+    {"industry_id": 20, "industry_name": "母婴", "brand_id": 533661, "brand_name": "Giving/启初"}
+  ]
+}
+```
+- 解析方式：从 `data[0].brand_name` 获取品牌名称
+<!-- NEW END -->
+
+<!-- ITER: 2026-01-28 - 新增巨量云图API和Cookie池API -->
+<!-- ITER: 2026-01-28 - 修复API参数格式问题 -->
+<!-- NEW START -->
+**Cookie池API详情**：
+- 接口地址：`/v1/yuntu/get_cookie`
+- 请求方式：GET
+- 认证方式：Bearer Token（`Authorization: Bearer {YUNTU_API_TOKEN}`）
+- 用途：获取巨量云图认证信息列表（aadvid + auth_token）
+- **使用方式**：随机选取任意一组 aadvid/auth_token，避免限流
+- 示例：
+```bash
+curl -X 'GET' \
+  'https://api.internal.intelligrow.cn/v1/yuntu/get_cookie?page=1&page_size=100' \
+  -H 'Authorization: Bearer {YUNTU_API_TOKEN}'
+```
+- 响应关键字段：
+  - `data[].aadvid` - 云图API的URL参数
+  - `data[].auth_token` - Cookie头完整值（格式：`sessionid=xxx`）
+
+**巨量云图API详情**：
+- 接口地址：`POST /yuntu_common/api/content/trigger_analysis/GetContentMaterialAnalysisInfo?aadvid={AADVID}`
+- 基础URL：`https://yuntu.oceanengine.com`
+- 认证方式：Cookie头直接使用 `auth_token` 完整值
+- 用途：获取视频触达、A3、搜索、费用等分析数据
+- 请求参数：
+```json
+{
+  "is_my_video": "0",
+  "object_id": "{item_id}",
+  "object_type": 2,
+  "start_date": "{YYYYMMDD格式}",
+  "end_date": "{start_date+30天,YYYYMMDD格式}",
+  "assist_type": 3,
+  "assist_video_type": 3,
+  "industry_id_list": ["{数据库中视频的industry_id,字符串格式}"],
+  "trigger_point_id_list": ["610000", "610300", "610301"]
+}
+```
+- **⚠️ 参数格式要求**：
+  - 日期格式必须为 `YYYYMMDD`（如 `20251014`），不是 `YYYY-MM-DD`
+  - `industry_id_list` 使用数据库中视频的 industry_id，传字符串数组
+  - Cookie 头直接使用 `auth_token` 值（已包含 `sessionid=xxx`）
+- 关键响应字段：
+  - `data.a3_increase_cnt` - 新增A3（字符串类型）
+  - `data.ad_a3_increase_cnt` - 加热新增A3（字符串类型）
+  - `data.natural_a3_increase_cnt` - 自然新增A3（字符串类型）
+  - `data.cost` - 总花费（单位可能是分）
+<!-- NEW END -->
+
 ### 6.2 内部接口

 <!-- MODIFIED: 补充核心API端点，改用 FastAPI RESTful 风格 -->
@@ -247,6 +345,7 @@ KOL Insight
 |------|------|------|------|
 | /api/v1/query | POST | 批量查询KOL视频数据 | FastAPI 后端服务提供 |
 | /api/v1/export | GET | 导出查询结果为Excel/CSV | FastAPI 后端服务提供 |
+| /api/v1/videos/{item_id}/analysis | GET | 获取单个视频分析数据 | FastAPI 后端服务提供 (NEW) |

 <!-- NEW START -->
 **API 架构说明**：
@@ -7,25 +7,25 @@
 | 版本 | v1.0 |
 | 创建日期 | 2026-01-28 |
 | 来源文档 | DevelopmentPlan.md, PRD.md, FeatureSummary.md |
-| 品牌主体 | 麦秒思AI制作 |
+| 品牌主体 | 秒思AI制作 |

 ## 1. 设计概述

 ### 1.1 设计原则

-**麦秒思AI设计语言**
+**秒思AI设计语言**

 | 原则 | 说明 | 应用 |
 |------|------|------|
 | 优雅简洁 | 去除冗余元素,聚焦核心功能 | 单页应用,扁平化设计 |
 | 专业可信 | 体现数据分析的专业性 | 稳重色系,清晰的信息层级 |
 | 高效直观 | 减少用户学习成本 | 明确的操作流程,即时反馈 |
-| 品牌一致 | 强化麦秒思AI品牌形象 | 统一使用品牌标识和色彩 |
+| 品牌一致 | 强化秒思AI品牌形象 | 统一使用品牌标识和色彩 |

 **品牌元素**

- **Logo**: doc/ui/muse.svg (麦秒思AI品牌标识)
- **Slogan**: "麦秒思AI制作" (展示在关键位置)
+- **Logo**: doc/ui/muse.svg (秒思AI品牌标识)
+- **Slogan**: "秒思AI制作" (展示在关键位置)
 - **色调**: 专业、现代、科技感

 ### 1.2 页面总览
@@ -76,7 +76,7 @@
 ┌────────────────────────────────────────────────────────────────────────────┐
 │  ┌──────────────────────────────────────────────────────────────────────┐  │
 │  │                           Header (品牌头部)                           │  │
-│  │  ┌──────┐                                              [麦秒思AI制作] │  │
+│  │  ┌──────┐                                              [秒思AI制作] │  │
 │  │  │ MUSE │  KOL Insight - 云图数据查询分析                            │  │
 │  │  │ Logo │  (品牌标识 + 产品名称)                                      │  │
 │  │  └──────┘                                                             │  │
@@ -123,7 +123,7 @@
 ├────────────────────────────────────────────────────────────────────────────┤
 │  ┌──────────────────────────────────────────────────────────────────────┐  │
 │  │                            Footer                                     │  │
-│  │              © 2026 麦秒思AI制作 | KOL Insight v1.0                   │  │
+│  │              © 2026 秒思AI制作 | KOL Insight v1.0                   │  │
 │  └──────────────────────────────────────────────────────────────────────┘  │
 └────────────────────────────────────────────────────────────────────────────┘
 ```
@@ -132,7 +132,7 @@

 | 组件ID | 组件名称 | 类型 | 说明 | 交互 |
 |--------|----------|------|------|------|
-| C-001 | 品牌头部 | Header | 展示麦秒思AI品牌Logo和产品名称 | 静态展示 |
+| C-001 | 品牌头部 | Header | 展示秒思AI品牌Logo和产品名称 | 静态展示 |
 | C-002 | 查询方式选择器 | Radio Group | 三种查询方式单选 | 点击切换查询方式 |
 | C-003 | 查询输入框 | Textarea | 批量输入或昵称输入 | 文本输入 |
 | C-004 | 查询按钮组 | Button Group | 清空、开始查询 | 点击执行操作 |
@@ -523,7 +523,7 @@

 ### 5.1 色彩规范

-**麦秒思AI品牌色系**
+**秒思AI品牌色系**

 | 用途 | 色值 | 示例 | 说明 |
 |------|------|------|------|
@@ -665,21 +665,21 @@ Mobile (< 768px):

 | 位置 | 尺寸 | 说明 |
 |------|------|------|
-| Header 左侧 | 高度 40px | 麦秒思AI Logo (doc/ui/muse.svg) |
+| Header 左侧 | 高度 40px | 秒思AI Logo (doc/ui/muse.svg) |
 | Favicon | 32x32px | 简化版 Logo 图标 |
 | 加载动画 | - | 可选:Logo 动效 |

 **品牌声明位置**

- Header 右上角:"麦秒思AI制作"
- Footer 中央:"© 2026 麦秒思AI制作 | KOL Insight v1.0"
+- Header 右上角:"秒思AI制作"
+- Footer 中央:"© 2026 秒思AI制作 | KOL Insight v1.0"

 **Header 品牌区域详细设计**

 ```
 ┌────────────────────────────────────────────────────────────────┐
 │  ┌──────┐                                                      │
-│  │      │  KOL Insight                        麦秒思AI制作     │
+│  │      │  KOL Insight                        秒思AI制作     │
 │  │ MUSE │  云图数据查询分析                                    │
 │  │ Logo │  (产品名称 + Slogan)              (品牌声明)         │
 │  │      │                                                      │
@@ -838,7 +838,7 @@ Mobile (< 768px):
 **关键设计决策**

 - **单页应用**: 简化交互流程,提升用户体验
- **品牌强化**: 多处展示"麦秒思AI制作",建立品牌认知
+- **品牌强化**: 多处展示"秒思AI制作",建立品牌认知
 - **数据优先**: 核心是数据展示,UI 简洁不干扰
 - **响应式**: 支持桌面/平板/移动端访问

@@ -846,5 +846,5 @@ Mobile (< 768px):

 **文档版本**: v1.0
 **最后更新**: 2026-01-28
-**设计团队**: 麦秒思AI
+**设计团队**: 秒思AI
 **审核状态**: 待审核 (建议运行 `/ru` 进行评审)
@@ -57,7 +57,7 @@
 | 布局风格统一 | ✅ | 垂直布局，从上到下：Header → 查询区 → 结果区 → Footer |
 | 交互模式一致 | ✅ | 查询 → 展示 → 导出流程清晰 |
 | 状态覆盖完整 | ✅ | 默认态、输入态、查询中、结果态、空结果态、错误态 |
-| 品牌元素应用 | ✅ | 麦秒思AI Logo、Slogan、品牌色系统一应用 |
+| 品牌元素应用 | ✅ | 秒思AI Logo、Slogan、品牌色系统一应用 |
 | 设计规范完整 | ✅ | 色彩、字体、间距、圆角、阴影规范完整 |
 | 响应式设计 | ✅ | 考虑了 Mobile/Tablet/Desktop 三种断点 |

@@ -143,7 +143,7 @@
 | 交互说明清晰 | ✅ | 8种交互场景全部说明 |
 | 用户流程图 | ✅ | 核心流程、辅助流程、异常流程全部包含 |
 | 设计规范统一 | ✅ | 色彩、字体、间距、圆角、阴影规范完整 |
-| 品牌元素应用 | ✅ | 麦秒思AI Logo、Slogan、品牌色完整应用 |
+| 品牌元素应用 | ✅ | 秒思AI Logo、Slogan、品牌色完整应用 |
 | 数据展示规范 | ✅ | 26个字段完整列出，格式化规则明确 |
 | 响应式设计 | ✅ | Mobile/Tablet/Desktop 三种断点考虑 |

@@ -155,7 +155,7 @@
   - 符合开发计划的技术架构（Next.js App Router）

 2. **品牌一致性强** ⭐⭐⭐
-   - 麦秒思AI品牌元素贯穿整个设计
+   - 秒思AI品牌元素贯穿整个设计
   - Logo、Slogan、品牌色系统一应用
   - Header 和 Footer 强化品牌认知

@@ -193,7 +193,7 @@
 | 操作效率 | ⭐⭐⭐⭐⭐ | 批量查询、一键导出，效率高 |
 | 错误提示 | ⭐⭐⭐⭐ | 错误态有明确提示和重试引导 |
 | 视觉层次 | ⭐⭐⭐⭐⭐ | 查询区 → 结果区层次清晰 |
-| 品牌认知 | ⭐⭐⭐⭐⭐ | 多处展示麦秒思AI品牌元素 |
+| 品牌认知 | ⭐⭐⭐⭐⭐ | 多处展示秒思AI品牌元素 |
 | 响应式体验 | ⭐⭐⭐⭐ | 考虑了移动端适配 |

 ## 评审结论
@@ -211,7 +211,7 @@ UIDesign 文档整体质量优秀，设计完整、规范统一、品牌一致

 **优点总结**：
 - ✅ 单页应用设计合理，操作流程简洁高效
- ✅ 品牌元素应用完整，强化麦秒思AI品牌认知
+- ✅ 品牌元素应用完整，强化秒思AI品牌认知
 - ✅ 设计规范详细，便于开发实现
 - ✅ 状态覆盖全面，用户体验考虑周到
 - ✅ 与开发计划高度契合
@@ -4,751 +4,72 @@

 | 项目 | 内容 |
 |------|------|
-| 评审时间 | 2026-01-28 15:30 |
-| 目标文档 | [doc/tasks.md](doc/tasks.md) |
-| 参照文档 | [doc/UIDesign.md](doc/UIDesign.md), [doc/DevelopmentPlan.md](doc/DevelopmentPlan.md) |
-| 问题统计 | **4 个严重 / 6 个一般 / 5 个建议** |
-| 评审结论 | 🟡 **需修改后通过** |
+| 评审时间 | 2026-01-28 17:35 |
+| 目标文档 | doc/tasks.md |
+| 参照文档 | doc/UIDesign.md, doc/DevelopmentPlan.md |
+| 问题统计 | 0 个严重 / 4 个一般 / 2 个建议 |

 ## 覆盖度分析

 ### DevelopmentPlan 覆盖

-#### Phase 1: 基础架构搭建
-
-| 开发项 (DevelopmentPlan) | 对应任务 (tasks.md) | 状态 | 说明 |
-|---------------------------|---------------------|------|------|
-| T-001 前端项目初始化 + T-002 后端项目初始化 | **T-001 项目初始化** | ⚠️ | **合并为一个任务,粒度过大** |
-| T-003 数据库配置 | T-002 数据库配置 | ✅ | 完全覆盖,含TDD要求 |
-| T-004 基础 UI 框架 | T-003 基础 UI 框架 | ✅ | 完全覆盖,含品牌元素 |
-| T-005 环境变量配置 | T-004 环境变量配置 | ✅ | 完全覆盖 |
-
-#### Phase 2: 核心功能开发
-
-| 开发项 (DevelopmentPlan) | 对应任务 (tasks.md) | 状态 | 说明 |
-|---------------------------|---------------------|------|------|
-| T-006 查询 API 开发 (后端) | **T-005 查询 API 开发** | ✅ | 含TDD要求和100%覆盖率 |
-| T-007 计算逻辑实现 (后端) | **T-006 计算逻辑实现** | ✅ | 含TDD要求和100%覆盖率 |
-| T-008 品牌 API 批量集成 (后端) | **T-007 品牌 API 批量集成** | ✅ | 含TDD要求和100%覆盖率 |
-| T-009 导出 API 开发 (后端) | **T-010 导出 API 开发** | ⚠️ | **依赖T-009前端组件,不合理** |
-| T-010 查询表单组件 (前端) | T-008 查询表单组件 | ✅ | 标注"粗略实现" |
-| T-011 结果表格组件 (前端) | T-009 结果表格组件 | ✅ | 标注"粗略实现" |
-| T-012 导出按钮组件 (前端) | T-011 导出按钮组件 | ✅ | 标注"粗略实现" |
-| **(未在 DevelopmentPlan 中)** | **T-012 主页面集成** | ⚠️ | **新增任务,导致编号错位** |
-
-#### Phase 3: 优化与测试
-
-| 开发项 (DevelopmentPlan) | 对应任务 (tasks.md) | 状态 | 说明 |
-|---------------------------|---------------------|------|------|
-| T-013 错误处理 (前后端) | **T-013 错误处理** | ❌ | **编号错位** |
-| T-014 性能优化 (后端) | **T-014 性能优化** | ❌ | **编号错位** |
-| T-015 视频链接跳转 (前端) | **T-015 视频链接跳转** | ❌ | **编号错位** |
-| T-016 部署配置 (前后端) | **T-016 部署配置** | ❌ | **编号错位** |
-| T-017 集成测试 | **T-017 集成测试** | ❌ | **编号错位** |
-
-**总覆盖率**: 17/16 (tasks.md 新增1个任务)
-
-**关键问题**:
-1. ❌ **任务编号不一致**: Phase 3 的5个任务编号都向后偏移一位
-2. ⚠️ **T-001 粒度过大**: 前后端初始化合并为一个任务
-3. ⚠️ **T-010 依赖错误**: 后端 API 不应依赖前端组件 T-009
-4. ⚠️ **T-012 新增任务**: DevelopmentPlan 中没有对应项
-
---
+| 开发项 | 对应任务 | 状态 |
+|--------|----------|------|
+| T-001 前端项目初始化 | T-001A | ✅ |
+| T-002 后端项目初始化 | T-001B | ✅ |
+| T-003 数据库配置 | T-002 | ✅ |
+| T-004 基础 UI 框架 | T-003 | ✅ |
+| T-005 环境变量配置 | T-004 | ✅ |
+| T-006 查询 API 开发 | T-005 | ✅ |
+| T-007 计算逻辑实现 | T-006 | ✅ |
+| T-008 品牌 API 批量集成 | T-007 | ✅ |
+| T-009 导出 API 开发 | T-010 | ✅ |
+| T-010 查询表单组件 | T-008 | ✅ |
+| T-011 结果表格组件 | T-009 | ✅ |
+| T-012 导出按钮组件 | T-011 | ✅ |
+| T-013 错误处理 | T-013 | ✅ |
+| T-014 性能优化 | T-014 | ✅ |
+| T-015 视频链接跳转 | T-015 | ✅ |
+| T-016 部署配置 | T-016 | ✅ |
+| T-017 集成测试 | T-017 | ✅ |

 ### UIDesign 覆盖

-| UI 页面/组件 | 对应任务 | 状态 | 说明 |
-|-------------|----------|------|------|
-| **P-001: 数据查询主页** | T-012 主页面集成 | ✅ | 单页应用集成 |
-| **组件覆盖** | | | |
-| C-001: 品牌头部 | T-003 基础 UI 框架 | ✅ | 包含 Logo 和品牌声明 |
-| C-002: 查询方式选择器 | T-008 查询表单组件 | ✅ | Radio Group |
-| C-003: 查询输入框 | T-008 查询表单组件 | ✅ | Textarea |
-| C-004: 查询按钮组 | T-008 查询表单组件 | ✅ | 清空/开始查询 |
-| C-005: 结果表格 | T-009 结果表格组件 | ✅ | 26字段表格 |
-| C-006: 导出按钮组 | T-011 导出按钮组件 | ✅ | Excel/CSV 导出 |
-| C-007: 分页器 | T-009 结果表格组件 | ✅ | 验收标准第9条 |
-| C-008: 视频链接 | T-015 视频链接跳转 | ✅ | 新窗口打开 |
-| C-009: Footer | T-003 基础 UI 框架 | ✅ | 版权信息 |
-| **页面状态** | | | |
-| 6种状态 | T-012 主页面集成 | ✅ | 验收标准第6-8条 |
+| UI 页面 | 对应任务 | 状态 |
+|---------|----------|------|
+| P-001 数据查询主页 | T-011A (集成), T-008/009/011/015 | ✅ |

-**总覆盖率**: 10/10 (100%)
-
-**UI覆盖评价**: ✅ 所有 UI 页面、组件、状态都有对应任务
-
---
+**总覆盖率**: 1/1

 ## 任务质量分析

-| 检查项 | 通过数 | 总数 | 通过率 |
-|--------|--------|------|--------|
-| 有明确描述 | 17 | 17 | 100% |
-| 有验收标准 | 17 | 17 | 100% |
-| 验收标准清晰 | 17 | 17 | 100% |
-| 依赖关系明确 | 16 | 17 | 94% |
-| 粒度合适 | 16 | 17 | 94% |
-| TDD 要求明确 | 7 | 12 | 58% |
-| 测试覆盖率要求 | 7 | 12 | 58% |
-
-**质量问题**:
- ⚠️ **T-001 粒度过大**: 前后端初始化合并,无法并行开发
- ⚠️ **后端任务 TDD 覆盖不全**: 仅 7/12 的后端任务有明确 TDD 要求
- ❌ **缺少测试独立任务**: 100% 覆盖率嵌入开发任务,难以单独验收
-
---
+| 检查项 | 通过数 | 总数 |
+|--------|--------|------|
+| 有明确描述 | 27 | 27 |
+| 有验收标准 | 27 | 27 |
+| 粒度合适 | 25 | 27 |

 ## 问题清单

 ### 严重问题 (Critical)
-
-#### C-1: T-001 任务粒度过大,前后端无法并行
-**位置**: [doc/tasks.md:43](doc/tasks.md:43)
-
-**问题描述**:
-```markdown
-| T-001 | 项目初始化 | 前后端分离架构:前端 Next.js,后端 FastAPI,配置 TypeScript、ESLint、Prettier | P0 | - |
-```
-
-T-001 包含:
-1. 前端 Next.js 14.x 项目创建
-2. 后端 FastAPI 0.104+ 项目创建
-3. 前端 TypeScript、ESLint、Prettier 配置
-4. 后端 Python 依赖管理配置
-5. 验收标准6条(前端3条+后端3条)
-
-**影响**:
- 🚫 **无法并行开发**: 前端和后端开发者可能是不同人员,合并为一个任务导致无法同时开工
- 🚫 **验收标准过多**: 6条验收标准涉及不同技术栈,验收时需要同时检查前后端
- 🚫 **依赖关系不清晰**: T-002 数据库配置依赖 T-001,但实际只依赖后端部分
-
-**建议修复**:
-拆分为两个独立任务:
- **T-001A: 前端项目初始化** (依赖: 无)
-  - 创建 Next.js 14.x 项目
-  - 配置 TypeScript、ESLint、Prettier
-  - 验收: 可运行 `pnpm dev`
-
- **T-001B: 后端项目初始化** (依赖: 无)
-  - 创建 FastAPI 0.104+ 项目
-  - 配置 Poetry/pip
-  - 验收: 可运行 `uvicorn main:app --reload`
-
-**优点**:
- ✅ 前后端可并行开发,节省时间
- ✅ 验收标准更聚焦
- ✅ 依赖关系更清晰(T-002 只依赖 T-001B)
-
---
-
-#### C-2: T-010 依赖关系错误
-**位置**: [doc/tasks.md:67](doc/tasks.md:67)
-
-**问题描述**:
-```markdown
-| T-010 | 导出 API 开发 | ... | P1 | T-006, T-007, T-009 | ...
-```
-
-T-010 (后端导出 API) 依赖 T-009 (前端结果表格组件),这是**逻辑错误**。
-
-**分析**:
- T-010 是**后端 FastAPI** 接口,负责生成 Excel/CSV 文件
- T-009 是**前端 React** 组件,负责展示表格
- 后端 API 不应该依赖前端组件的实现
-
-**实际依赖**:
- T-010 应该依赖 **T-006 (计算逻辑实现)** 和 **T-007 (品牌API集成)**
- 因为导出的数据需要包含计算后的指标和品牌名称
-
-**验收标准第5条**:
-```
-5. 使用中文列名作为表头 **(与 T-009 ResultTable 字段一致)**
-```
-这说明是要求"字段一致性",而不是"依赖关系"。
-
-**影响**:
- 🚫 **执行顺序混乱**: 开发者可能误以为要先完成前端表格才能开发后端导出API
- 🚫 **前后端耦合**: 后端依赖前端,违反分离架构原则
-
-**建议修复**:
-1. 修改依赖: `T-010 依赖: T-006, T-007` (移除 T-009)
-2. 修改验收标准第5条: "使用中文列名作为表头 **(字段顺序和命名与前端 ResultTable 保持一致,参考共享的字段定义)**"
-3. 建议: 创建共享的字段定义文件(如 `types/fields.ts`),前后端都引用
-
---
-
-#### C-3: 缺少单元测试独立任务
-**位置**: 整个 tasks.md
-
-**问题描述**:
-tasks.md 中有 **7个任务** 要求 TDD 和 100% 测试覆盖率:
- T-002: 数据库配置 (验收标准 7-8 条)
- T-005: 查询 API 开发 (验收标准 9-10 条)
- T-006: 计算逻辑实现 (验收标准 7-8 条)
- T-007: 品牌 API 批量集成 (验收标准 8-9 条)
- T-010: 导出 API 开发 (验收标准 10-11 条)
- T-013: 错误处理 (验收标准 8-9 条)
- T-017: 集成测试 (验收标准 9-11 条)
-
-但**没有单独的测试任务**,所有测试要求都嵌入在开发任务中。
-
-**影响**:
- 🚫 **测试容易被忽略**: 开发进度紧张时,测试可能被压缩或跳过
- 🚫 **无法单独追踪测试进度**: 测试覆盖率没有独立的验收里程碑
- 🚫 **100% 覆盖率难以保证**: 嵌入在开发任务中,验收时可能只检查功能,不检查覆盖率
- 🚫 **测试报告缺失**: T-017 要求生成覆盖率报告,但其他任务没有明确要求
-
-**建议修复**:
-在 Phase 3 增加测试里程碑任务:
-
-**方案A: 增加独立测试任务**
-```markdown
-| T-018 | 测试覆盖率验收 | 验证所有后端代码测试覆盖率 ≥ 100% | P1 | T-002, T-005~007, T-010, T-013 |
-验收标准:
-1. 数据库操作测试覆盖率 100% (T-002)
-2. API集成测试覆盖率 100% (T-005)
-3. 计算逻辑单元测试覆盖率 100% (T-006)
-4. 品牌API单元测试覆盖率 100% (T-007)
-5. 导出功能单元测试覆盖率 100% (T-010)
-6. 错误处理分支覆盖率 100% (T-013)
-7. 使用 pytest-cov 生成覆盖率报告
-8. 覆盖率报告上传到 CI/CD
-```
-
-**方案B: 在每个 Phase 结束增加测试验收点**
-```markdown
-## 3. Phase 2 任务 - 核心功能开发
-
-### 3.3 测试验收
-| ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 |
-|----|------|------|--------|------|----------|
-| T-012A | Phase 2 测试验收 | 验证 Phase 2 所有后端任务测试覆盖率 | P0 | T-005~007, T-010 | 1. 所有后端代码覆盖率 ≥ 100%<br>2. 生成覆盖率报告 |
-```
-
---
-
-#### C-4: 任务编号与 DevelopmentPlan 不一致
-**位置**: Phase 3 所有任务 ([doc/tasks.md:88-101](doc/tasks.md))
-
-**问题描述**:
-tasks.md 新增了 T-012 (主页面集成),导致 Phase 3 的所有任务编号向后偏移一位:
-
-| DevelopmentPlan | tasks.md | 差异 |
-|-----------------|----------|------|
-| T-013 错误处理 | **T-013 错误处理** | ❌ 编号错位 |
-| T-014 性能优化 | **T-014 性能优化** | ❌ 编号错位 |
-| T-015 视频链接跳转 | **T-015 视频链接跳转** | ❌ 编号错位 |
-| T-016 部署配置 | **T-016 部署配置** | ❌ 编号错位 |
-| T-017 集成测试 | **T-017 集成测试** | ❌ 编号错位 |
-
-**影响**:
- 🚫 **文档引用混乱**: 在 DevelopmentPlan 中看到的 T-013 和 tasks.md 中的 T-013 不是同一个任务
- 🚫 **沟通成本高**: 开发人员需要在两个文档之间切换时手动对照编号
- 🚫 **代码注释/提交信息错误**: Git 提交信息中的任务 ID 可能指向错误的任务
-
-**建议修复**:
-
-**方案A (推荐): 将 T-012 改为 T-008A**
-```markdown
-| T-008 | 查询表单组件 | ... | P0 | T-003 |
-| T-008A | 主页面集成 | ... | P0 | T-008, T-009, T-011 |
-| T-009 | 结果表格组件 | ... | P1 | T-003, T-006, T-007 |
-```
- 优点: Phase 3 编号与 DevelopmentPlan 完全一致
- 缺点: 引入子编号
-
-**方案B: 更新 DevelopmentPlan.md**
-在 DevelopmentPlan.md 的 Phase 2 增加 T-012 任务
- 优点: 保持 tasks.md 不变
- 缺点: 需要修改 DevelopmentPlan.md
-
-**方案C: 在 tasks.md 增加对照表**
-```markdown
-## 附录: 与 DevelopmentPlan 任务编号对照
-
-| tasks.md | DevelopmentPlan | 任务名称 |
-|----------|-----------------|----------|
-| T-013 | T-013 | 错误处理 |
-| T-014 | T-014 | 性能优化 |
-...
-```
- 优点: 不修改编号,只增加对照表
- 缺点: 需要手动查表,增加认知负担
-
---
+无。

 ### 一般问题 (Major)
-
-#### M-1: T-002 真实数据库测试要求缺少环境准备说明
-**位置**: [doc/tasks.md:46](doc/tasks.md:46)
-
-**问题描述**:
-```markdown
-6. **真实数据库测试**: 使用 .env 中的连接字符串连接真实数据库并验证
-```
-
-验收标准要求连接"真实数据库",但没有说明:
- 真实数据库是否已经准备好?
- 数据库中是否有测试数据?
- 需要什么权限?
-
-**影响**:
- 开发者执行到 T-002 时可能发现数据库环境未就绪
- 导致任务阻塞,无法继续
-
-**建议修复**:
-1. 在 T-002 依赖中增加: `依赖: T-001B (后端初始化), 数据库环境准备 (DBA)`
-2. 在 T-004 环境变量配置中增加验收标准: "数据库连接字符串配置完成,数据库可访问"
-3. 或在任务描述中明确标注: "需提前准备测试数据库环境,包含表结构和测试数据"
-
---
-
-#### M-2: T-012 主页面集成缺少状态管理方案说明
-**位置**: [doc/tasks.md:85](doc/tasks.md:85)
-
-**问题描述**:
-```markdown
-6. 页面状态管理: 默认态/输入态/查询中/结果态/空结果态/错误态
-```
-
-验收标准提到"页面状态管理",但没有说明使用何种状态管理方案:
- React useState?
- Zustand?
- Redux Toolkit?
- Context API?
-
-**影响**:
- 前端开发者需要自行决定状态管理方案
- 可能导致过度设计(引入 Redux)或过于简单(难以维护)
-
-**建议修复**:
-在验收标准第6条补充说明:
-```markdown
-6. 页面状态管理: 默认态/输入态/查询中/结果态/空结果态/错误态 **(使用 React useState 管理,无需第三方库)**
-```
-
---
-
-#### M-3: T-007 品牌API并发限制和超时参数硬编码
-**位置**: [doc/tasks.md:64](doc/tasks.md:64)
-
-**问题描述**:
-```markdown
-3. 使用 asyncio.gather 批量并发请求(限制 10 并发)
-6. 超时设置: 3秒
-```
-
-验收标准硬编码了"10 并发"和"3 秒",未说明这些参数是否可配置。
-
-**影响**:
- 生产环境可能需要调整并发数(如品牌API限流时降低并发)
- 超时时间可能需要根据网络环境调整
- 硬编码参数难以适应不同环境
-
-**建议修复**:
-1. 将并发限制和超时时间配置到环境变量或配置文件
-2. 修改验收标准:
-```markdown
-3. 使用 asyncio.gather 批量并发请求,并发数可配置(默认 10)
-6. 超时时间可配置(默认 3 秒)
-7. 从环境变量读取配置: BRAND_API_CONCURRENCY, BRAND_API_TIMEOUT
-```
-
---
-
-#### M-4: T-009 与 T-010 字段一致性验证缺失
-**位置**: [doc/tasks.md:76](doc/tasks.md:76)
-
-**问题描述**:
-T-009 (前端表格) 和 T-010 (后端导出) 都要求"使用中文列名",但没有明确如何保证字段一致性。
-
-**当前状态**:
- T-009 验收标准: "展示 26 个字段,使用中文列名"
- T-010 验收标准: "使用中文列名作为表头 **(与 T-009 ResultTable 字段一致)**"
-
-**问题**:
- "字段一致"如何验证?
- 前端和后端是否共享字段定义?
-
-**影响**:
- 前端展示和导出文件的列名可能不一致
- 导致用户混淆
-
-**建议修复**:
-1. 创建共享的字段定义文件:
-```typescript
-// shared/types/fields.ts
-export const VIDEO_FIELDS = [
-  { key: 'item_id', label: '视频ID', width: 120 },
-  { key: 'title', label: '视频标题', width: 200 },
-  // ... 24 more fields
-] as const;
-```
-
-2. 修改 T-009 验收标准:
-```markdown
-2. 展示 26 个字段,使用共享字段定义文件 (shared/types/fields.ts)
-```
-
-3. 修改 T-010 验收标准:
-```markdown
-5. 使用共享字段定义文件作为表头,保证与前端表格字段顺序和命名完全一致
-```
-
---
-
-#### M-5: T-014 性能优化缺少性能测试脚本
-**位置**: [doc/tasks.md:96](doc/tasks.md:96)
-
-**问题描述**:
-T-014 定义了明确的性能指标:
- 查询响应时间 ≤ 3秒 (100条)
- 页面加载时间 ≤ 2秒
- 导出响应时间 ≤ 5秒 (1000条)
-
-但验收标准只有"验证索引已创建",没有要求编写性能测试脚本。
-
-**影响**:
- 性能指标难以自动化验证
- 依赖人工测试,可能遗漏
- 回归测试时无法快速验证性能
-
-**建议修复**:
-增加验收标准:
-```markdown
-6. **后端性能测试**: 编写性能测试脚本,验证响应时间指标
-7. **真实数据库测试**: 使用真实数据库和测试数据进行性能测试
-8. 性能测试报告: 生成性能测试报告,记录实际响应时间
-```
-
---
-
-#### M-6: T-017 集成测试缺少性能测试用例
-**位置**: [doc/tasks.md:101](doc/tasks.md:101)
-
-**问题描述**:
-T-017 集成测试有 8 个功能测试用例,但未包含 T-014 定义的性能指标验证。
-
-**建议修复**:
-在验收标准中增加性能测试用例:
-```markdown
-9. 测试用例: 性能指标验证 (查询≤3秒、导出≤5秒)
-10. **真实数据库集成测试**: 使用 .env 中的真实数据库连接进行完整集成测试
-11. **后端测试覆盖率验证**: 确认所有后端代码测试覆盖率 ≥ 100%
-12. **测试报告生成**: 使用 pytest-cov 生成覆盖率报告
-```
-(注: 验收标准 10-12 已存在,只需增加第9条)
-
---
+1. 任务统计与优先级说明与实际任务清单不一致，且缺少迭代任务计数，导致计划与执行口径不统一，影响排期与资源分配。参考: doc/tasks.md:29-35, doc/tasks.md:189-201, doc/tasks.md:337-357
+2. 依赖图、执行检查清单、里程碑均未覆盖 T-019~T-026 迭代任务，迭代工作缺少清晰执行路径与交付节点，容易被遗漏或排期错误。参考: doc/tasks.md:113-187, doc/tasks.md:337-357
+3. 迭代任务（T-019~T-026）未在上游 DevelopmentPlan/UIDesign 中体现，且 T-026 为新页面无 UI 设计依据，存在范围漂移与验收依据不一致风险。参考: doc/tasks.md:337-357, doc/DevelopmentPlan.md:246-318, doc/UIDesign.md:31-128
+4. 多处任务要求真实数据库/性能/覆盖率验证，但未定义数据准备与测试环境前置条件，可能导致 T-002/T-014/T-017/T-018 无法直接执行。参考: doc/tasks.md:49, doc/tasks.md:103, doc/tasks.md:108-110

 ### 改进建议 (Minor)
-
-#### S-1: 前端"粗略实现"说明不够具体
-**位置**: [doc/tasks.md:74, 76, 78, 85](doc/tasks.md)
-
-**问题描述**:
-T-008/T-009/T-011/T-012 都标注了"粗略实现说明",但"粗略"的标准不明确。
-
-**建议**:
-在任务总览或关键技术点章节定义"粗略实现"标准:
-```markdown
-## 前端"粗略实现"标准
-
-本项目前端采用"功能优先、样式从简"的开发策略:
- ✅ **功能完整**: 所有功能可用,交互流程完整
- ✅ **样式简洁**: 使用 Tailwind 默认样式,无需过度美化
- ✅ **品牌元素保留**: Logo、品牌色、品牌声明必须体现
- ❌ **暂不支持**: 响应式适配、动画效果、深度优化
-```
-
---
-
-#### S-2: 建议增加任务估时
-**位置**: 整个 tasks.md
-
-**问题描述**:
-所有任务都没有工作量估时,无法评估项目整体时间和关键路径。
-
-**建议**:
-在任务总览表格增加"估时"列:
-```markdown
-| ID | 任务 | 描述 | 优先级 | 依赖 | 估时 | 验收标准 |
-|----|------|------|--------|------|------|----------|
-| T-001 | 项目初始化 | ... | P0 | - | 1天 | ... |
-```
-
-**参考估时** (仅供参考):
- T-001: 1天 (前后端分离后: 0.5天 × 2)
- T-002: 1天
- T-005: 2天 (含 TDD)
- T-009: 2天
- T-012: 2天
-
---
-
-#### S-3: T-016 部署配置缺少监控和日志方案
-**位置**: [doc/tasks.md:99](doc/tasks.md:99)
-
-**问题描述**:
-T-016 部署配置只涉及 Docker 和环境变量,未涉及生产环境监控和日志收集。
-
-**建议**:
-增加验收标准:
-```markdown
-8. 日志配置: 前端 console 输出,后端使用 Python logging 模块输出到文件
-9. (可选) 监控配置: 接入 Sentry 或 Prometheus 进行错误监控
-```
-
---
-
-#### S-4: 任务依赖图与实际任务ID不一致
-**位置**: [doc/tasks.md:105](doc/tasks.md:105)
-
-**问题描述**:
-第5节"任务依赖图"仍使用 DevelopmentPlan 的任务编号,与 tasks.md 实际任务ID不一致。
-
-**建议修复**:
-更新任务依赖图,使用 tasks.md 的任务ID (T-001~T-017):
-```
-Phase 1: 基础架构
-T-001 (项目初始化)
-  ├── T-002 (数据库配置)
-  ├── T-003 (基础UI框架)
-  └── T-004 (环境变量配置)
-
-Phase 2: 核心功能
-T-002 ──▶ T-005 (查询API) ──▶ T-006 (计算逻辑) ──▶ T-009 (结果表格)
-           │                    │                      │
-           └──▶ T-007 (品牌API) │                      │
-                                 │                      │
-T-003 ──▶ T-008 (查询表单)      │                      │
-                                 │                      │
-                        T-010 (导出API) ◀───────────────┤
-                                 │                      │
-                        T-011 (导出按钮) ◀──────────────┤
-                                                        │
-T-008, T-009, T-011 ──▶ T-012 (主页面集成) ────────────┘
-
-Phase 3: 优化测试
-T-012 ──▶ T-013 (错误处理) ──▶ T-014 (性能优化)
-                │                     │
-                ├──▶ T-015 (视频链接) │
-                │                     │
-                └──▶ T-016 (部署配置) │
-                                      │
-                             T-017 (集成测试)
-```
-
---
-
-#### S-5: 建议增加功能ID(F-xxx)对应关系
-**位置**: 整个 tasks.md
-
-**建议**:
-在"关联功能"列增加功能ID引用,便于追溯需求:
-```markdown
-| ID | 任务 | 描述 | 优先级 | 依赖 | 关联功能 | 验收标准 |
-|----|------|------|--------|------|----------|----------|
-| T-005 | 查询 API 开发 | ... | P0 | T-002 | F-001, F-002, F-003 | ... |
-| T-006 | 计算逻辑实现 | ... | P0 | T-005 | F-004, F-005, F-006 | ... |
-```
-
---
-
-## 依赖关系分析
-
-### 关键路径
-
-```
-T-001 (项目初始化)
-  │
-  ├─→ T-002 (数据库配置)
-  │     │
-  │     └─→ T-005 (查询API)
-  │           │
-  │           ├─→ T-006 (计算逻辑)
-  │           │     │
-  │           │     └─→ T-010 (导出API)
-  │           │
-  │           └─→ T-007 (品牌API)
-  │                 │
-  │                 └─→ T-009 (结果表格)
-  │                       │
-  │                       └─→ T-012 (主页面集成)
-  │                             │
-  │                             └─→ T-013 (错误处理)
-  │                                   │
-  │                                   └─→ T-017 (集成测试)
-  │
-  └─→ T-003 (基础UI)
-        │
-        └─→ T-008 (查询表单)
-              │
-              └─→ T-012 (主页面集成)
-```
-
-**关键路径**:
-T-001 → T-002 → T-005 → T-007 → T-009 → T-012 → T-013 → T-017
-
-**可并行任务**:
- T-002 (数据库) 和 T-003 (基础UI) 可并行
- T-006 (计算逻辑) 和 T-007 (品牌API) 可并行
- T-013/T-014/T-015 可并行
-
---
+1. 主页面标题与 UIDesign 头部文案不一致（缺少“云图数据查询分析”），建议补齐以满足品牌一致性。参考: doc/tasks.md:91, doc/UIDesign.md:80-82
+2. 覆盖率验收任务 T-018 同时包含指标定义、报告产出、CI 集成，建议拆分为“覆盖率验收”与“CI 集成”以降低任务粒度。参考: doc/tasks.md:110

 ## 评审结论

-### 评审结果
+需修改后通过。

-🟡 **需修改后通过**
-
---
-
-### 主要优点
-
-✅ **覆盖度完整**:
- 所有 DevelopmentPlan (16个任务) 和 UIDesign (10个组件) 都有对应任务
- 新增 T-012 主页面集成任务是合理补充
-
-✅ **验收标准详细**:
- 每个任务平均 6.2 条验收标准
- 验收标准具体可操作,便于验收
- T-006/T-014/T-017 的验收标准特别优秀
-
-✅ **TDD 要求明确**:
- 7个关键后端任务都要求先写测试再写代码
- 明确要求 100% 测试覆盖率和真实数据库测试
-
-✅ **架构更新到位**:
- 任务描述已完全更新为前后端分离架构 (FastAPI + Next.js)
- 品牌元素(麦秒思AI)在任务中明确体现
-
---
-
-### 关键问题
-
-❌ **严重问题** (必须修复):
-1. **C-1: T-001 粒度过大** - 前后端初始化应拆分,支持并行开发
-2. **C-2: T-010 依赖错误** - 后端 API 不应依赖前端组件 T-009
-3. **C-3: 缺少测试独立任务** - 100% 覆盖率需要独立验收里程碑
-4. **C-4: 任务编号不一致** - Phase 3 任务编号与 DevelopmentPlan 错位
-
-⚠️ **一般问题** (建议修复):
-1. **M-1: T-002 数据库环境准备** - 需明确数据库环境前置条件
-2. **M-2: T-012 状态管理方案** - 建议使用 React useState
-3. **M-3: T-007 参数硬编码** - 并发和超时应可配置
-4. **M-4: T-009/T-010 字段一致性** - 建议共享字段定义文件
-5. **M-5: T-014 性能测试脚本** - 需编写自动化性能测试
-6. **M-6: T-017 性能测试用例** - 集成测试应包含性能验证
-
---
-
-### 影响评估
-
-**阻塞性问题**:
- 🚫 **C-1 (T-001 粒度过大)**: 导致前后端无法并行开发,延长项目周期
- 🚫 **C-2 (T-010 依赖错误)**: 导致执行顺序混乱,前后端耦合
-
-**质量风险**:
- ⚠️ **C-3 (缺少测试任务)**: 100% 覆盖率难以保证,可能降低代码质量
- ⚠️ **M-5/M-6 (性能测试缺失)**: 性能指标无法自动化验证
-
-**进度风险**:
- ⚠️ **M-1 (数据库环境未就绪)**: 可能导致 T-002 阻塞
- ⚠️ **无任务估时**: 难以评估项目整体进度和关键路径
-
---
-
-## 下一步行动
-
-### 必须修改 (Critical) - 预估 1.5 小时
-
- [ ] **C-1: 拆分 T-001** 为 T-001A (前端初始化) 和 T-001B (后端初始化)
-  - 预估时间: 30分钟
-  - 影响范围: tasks.md, DevelopmentPlan.md
-
- [ ] **C-2: 修正 T-010 依赖** 移除 T-009,改为 `T-006, T-007`
-  - 预估时间: 10分钟
-  - 影响范围: tasks.md:67
-
- [ ] **C-3: 增加测试任务** 在 Phase 3 增加 T-018 测试覆盖率验收
-  - 预估时间: 20分钟
-  - 影响范围: tasks.md Phase 3
-
- [ ] **C-4: 统一任务编号** 选择方案A/B/C 修复编号不一致问题
-  - 预估时间: 30分钟
-  - 影响范围: tasks.md 或 DevelopmentPlan.md
-
---
-
-### 建议修改 (Major) - 预估 1 小时
-
- [ ] **M-1: T-002 数据库环境说明** 明确数据库准备前置条件
-  - 预估时间: 10分钟
-
- [ ] **M-2: T-012 状态管理说明** 补充 React useState 方案
-  - 预估时间: 5分钟
-
- [ ] **M-3: T-007 参数配置化** 并发和超时改为可配置
-  - 预估时间: 15分钟
-
- [ ] **M-4: T-009/T-010 字段一致性** 增加共享字段定义要求
-  - 预估时间: 15分钟
-
- [ ] **M-5: T-014 性能测试脚本** 增加性能测试验收标准
-  - 预估时间: 10分钟
-
- [ ] **M-6: T-017 性能测试用例** 增加性能测试用例
-  - 预估时间: 5分钟
-
---
-
-### 可选优化 (Minor) - 预估 1 小时
-
- [ ] **S-1: 定义"粗略实现"标准** 增加前端开发标准说明
- [ ] **S-2: 增加任务估时** 为每个任务增加工作量估时(人天)
- [ ] **S-3: T-016 监控配置** 增加日志和监控验收标准
- [ ] **S-4: 更新依赖图** 使用 tasks.md 的实际任务ID
- [ ] **S-5: 增加功能ID** 在关联功能列增加 F-xxx 引用
-
---
-
-### 修复优先级汇总
-
-| 优先级 | 问题ID | 问题描述 | 预估时间 | 阻塞风险 |
-|--------|--------|----------|----------|----------|
-| P0 | C-1 | T-001 拆分 | 30分钟 | ⚠️ 高 |
-| P0 | C-2 | T-010 依赖修正 | 10分钟 | ⚠️ 高 |
-| P0 | C-3 | 增加测试任务 | 20分钟 | ⚠️ 中 |
-| P0 | C-4 | 统一任务编号 | 30分钟 | ⚠️ 中 |
-| P1 | M-1~M-6 | 6个一般问题 | 60分钟 | ⚠️ 低 |
-| P2 | S-1~S-5 | 5个改进建议 | 60分钟 | ✅ 无 |
-
-**预计修复总时间**: 约 3.5 小时 (P0-P2 全部)
-
---
-
-## 参考信息
-
-### 文档链接
-
- 目标文档: [doc/tasks.md](doc/tasks.md)
- 上游文档1: [doc/UIDesign.md](doc/UIDesign.md) - UI 设计文档
- 上游文档2: [doc/DevelopmentPlan.md](doc/DevelopmentPlan.md) - 开发计划
-
-### 修改建议操作
-
-建议使用 `/mt` 命令根据本评审报告的问题清单进行增量修改:
-```bash
-/mt  # 增量修改 tasks.md
-```
-
---
-
-**评审人**: Claude Sonnet 4.5
-**评审日期**: 2026-01-28 15:30
-**评审版本**: tasks.md v1.0
-**评审耗时**: 45 分钟
-**评审方法**: 基于 `/rt` 评审技能,对比 UIDesign.md 和 DevelopmentPlan.md
+### 下一步行动
+- [ ] 对齐任务总数与优先级统计，补充迭代任务到依赖图/清单/里程碑
+- [ ] 将 T-019~T-026 同步到 DevelopmentPlan/UIDesign（或明确为独立迭代范围）
+- [ ] 增加真实数据库与测试数据准备任务（含环境获取方式）
+- [ ] 修正页面头部文案与 UIDesign 一致
@@ -26,12 +26,12 @@

 ## 1. 任务总览

-<!-- MODIFIED: 更新任务统计,T-001拆分+T-018新增 -->
+<!-- MODIFIED: 更新任务统计,T-001拆分+T-018新增+T-019~T-027迭代任务 -->
 | 统计项 | 数量 |
 |--------|------|
-| 总任务数 | 18 |
-| P0 任务 | 10 |
-| P1 任务 | 7 |
+| 总任务数 | 27 |
+| P0 任务 | 17 |
+| P1 任务 | 9 |
 | P2 任务 | 1 |

 ## 2. Phase 1 任务 - 基础架构搭建
@@ -48,7 +48,7 @@
 <!-- MODIFIED: 依赖改为 T-001B (后端初始化) -->
 | T-002 | 数据库配置 | 配置 SQLAlchemy,定义数据模型,连接 PostgreSQL | P0 | T-001B | 1. SQLAlchemy 2.0+ 和 asyncpg 安装完成<br>2. 定义 KolVideo 模型(使用 SQLAlchemy ORM)<br>3. 数据库异步连接成功<br>4. 索引创建: star_id, star_unique_id, star_nickname<br>5. Alembic 迁移工具配置完成<br><!-- NEW START -->6. **真实数据库测试**: 使用 .env 中的连接字符串连接真实数据库并验证<br>7. **TDD要求**: 编写数据库连接测试,模型测试,CRUD测试<br>8. **测试覆盖率**: 数据库操作测试覆盖率 ≥ 100%<!-- NEW END --> |
 <!-- MODIFIED: 依赖改为 T-001A (前端初始化) -->
-| T-003 | 基础 UI 框架 | 安装 Tailwind CSS,创建基础布局组件 | P0 | T-001A | 1. Tailwind CSS 配置完成<br>2. 品牌色系配置 (#4F46E5等)<br>3. 基础布局组件创建 (Header/Footer)<br>4. 麦秒思AI Logo 集成 (doc/ui/muse.svg) |
+| T-003 | 基础 UI 框架 | 安装 Tailwind CSS,创建基础布局组件 | P0 | T-001A | 1. Tailwind CSS 配置完成<br>2. 品牌色系配置 (#4F46E5等)<br>3. 基础布局组件创建 (Header/Footer)<br>4. 秒思AI Logo 集成 (doc/ui/muse.svg) |
 <!-- MODIFIED: 依赖改为 T-001A, T-001B (前后端都需要环境变量) -->
 | T-004 | 环境变量配置 | 配置开发/生产环境变量,数据库连接字符串 | P0 | T-001A, T-001B | 1. 前后端 .env.example 创建<br>2. 后端 DATABASE_URL 配置<br>3. 后端品牌 API 地址配置<br>4. 前端 NEXT_PUBLIC_API_URL 配置<br>5. .env 文件创建并添加到 .gitignore |

@@ -88,7 +88,7 @@
 |----|------|------|--------|------|----------|
 <!-- MODIFIED: 简化前端实现要求 -->
 <!-- MODIFIED: 任务编号改为 T-011A,统一与 DevelopmentPlan 编号体系 (根据评审报告 C-4) -->
-| T-011A | 主页面集成 | 集成查询表单、结果表格和导出按钮,完成单页应用 **(前端粗略实现)** | P0 | T-008, T-009, T-011 | 1. page.tsx 创建单页应用<br>2. 品牌头部: Logo + "KOL Insight" + "麦秒思AI制作"<br>3. 查询区域集成 QueryForm<br>4. 结果区域集成 ResultTable 和 ExportButton<br>5. Footer: "© 2026 麦秒思AI制作"<br>6. 页面状态管理: 默认态/输入态/查询中/结果态/空结果态/错误态<br>7. 空状态组件: 引导文案 + 空盒子图标<br>8. 错误状态组件: 错误提示 + 重试按钮<br><!-- NEW START -->9. **粗略实现说明**: 重点在功能集成,UI可简化,品牌元素必须保留<!-- NEW END --> |
+| T-011A | 主页面集成 | 集成查询表单、结果表格和导出按钮,完成单页应用 **(前端粗略实现)** | P0 | T-008, T-009, T-011 | 1. page.tsx 创建单页应用<br>2. 品牌头部: Logo + "KOL Insight" + "秒思AI制作"<br>3. 查询区域集成 QueryForm<br>4. 结果区域集成 ResultTable 和 ExportButton<br>5. Footer: "© 2026 秒思AI制作"<br>6. 页面状态管理: 默认态/输入态/查询中/结果态/空结果态/错误态<br>7. 空状态组件: 引导文案 + 空盒子图标<br>8. 错误状态组件: 错误提示 + 重试按钮<br><!-- NEW START -->9. **粗略实现说明**: 重点在功能集成,UI可简化,品牌元素必须保留<!-- NEW END --> |

 ## 4. Phase 3 任务 - 优化与测试

@@ -334,6 +334,34 @@ async with httpx.AsyncClient() as client:

 ---

+<!-- ITER: 2026-01-28 - 修复品牌API响应解析+添加认证 -->
+## 12. 迭代任务
+
+### 12.1 Bug 修复
+
+| ID | 任务 | 描述 | 依赖 | 优先级 | 验收标准 |
+|----|------|------|------|--------|----------|
+| T-019 | 修复品牌API响应解析 | 品牌API返回的data是数组结构,当前代码按字典解析导致取不到brand_name | T-007 | P0 | 1. 正确解析 `data[0].brand_name` 获取品牌名称<br>2. 处理 data 数组为空的边界情况<br>3. 更新测试用例的 mock 数据结构 |
+| T-020 | 添加品牌API认证 | 品牌API需要Bearer Token认证,当前代码未配置 | T-019 | P0 | 1. 新增环境变量 `BRAND_API_TOKEN`<br>2. 请求时添加 `Authorization: Bearer {token}` 头<br>3. 更新 `.env.example` 配置示例<br>4. 更新测试用例验证认证头 |
+<!-- ITER: 2026-01-28 - 修复巨量云图API调用参数问题 -->
+| T-027 | 修复巨量云图API调用参数 | API调用不通,日期格式/Cookie头/industry_id等参数错误 | T-023 | P0 | 1. **日期格式**: 从 `YYYY-MM-DD` 改为 `YYYYMMDD`<br>2. **Cookie头**: 直接使用 `auth_token` 完整值(已含sessionid=xxx)<br>3. **industry_id**: 使用数据库中视频的industry_id,传字符串格式 `["12"]`<br>4. **Cookie获取**: 随机选取任意一组aadvid/auth_token,不按brand_id匹配<br>5. 更新测试用例验证参数格式<br>6. **TDD要求**: 测试实际API调用成功返回数据 |
+
+<!-- ITER: 2026-01-28 - 新增巨量云图视频分析功能 -->
+### 12.2 功能迭代 - 视频分析模块
+
+| ID | 任务 | 描述 | 依赖 | 优先级 | 验收标准 |
+|----|------|------|------|--------|----------|
+| T-021 | SessionID池服务 | 实现从内部API获取Cookie列表,随机选取sessionid | T-004 | P0 | 1. 调用 `/v1/yuntu/get_cookie` 获取100个sessionid<br>2. 随机选取机制实现<br>3. 环境变量 `YUNTU_API_TOKEN` 配置<br>4. **TDD要求**: 先写测试用例(mock API响应) |
+| T-022 | SessionID自动重试 | sessionid失效时自动切换到下一个重试 | T-021 | P0 | 1. 检测401/403状态码触发重试<br>2. 最多重试3次<br>3. 重试日志记录<br>4. **TDD要求**: 测试覆盖重试场景 |
+| T-023 | 巨量云图API封装 | 封装GetContentMaterialAnalysisInfo接口调用 | T-022 | P0 | 1. 正确构造请求参数(object_id/start_date/end_date/industry_id_list)<br>2. end_date = start_date + 30天<br>3. Cookie头设置sessionid<br>4. 超时10秒<br>5. **TDD要求**: 测试参数构造和响应解析 |
+| T-024 | 视频分析数据接口 | 实现 GET /api/v1/videos/{item_id}/analysis | T-023 | P0 | 1. 从数据库获取基础信息<br>2. 调用巨量云图API获取实时数据<br>3. 返回6大类指标结构<br>4. 计算成本指标(CPM/CPA3/CPsearch等)<br>5. 除零检查返回null<br>6. **TDD要求**: 测试覆盖率100% |
+| T-025 | 数据库A3指标更新 | 从API获取数据后更新数据库对应字段 | T-024 | P1 | 1. 更新 total_new_a3_cnt<br>2. 更新 heated_new_a3_cnt<br>3. 更新 natural_new_a3_cnt<br>4. 更新 total_cost<br>5. **TDD要求**: 测试数据库更新逻辑 |
+| T-026 | 视频分析前端页面 | 前端展示6大类25+指标(粗略实现) | T-024 | P1 | 1. 基础信息展示(8字段)<br>2. 触达指标展示(7字段)<br>3. A3指标展示(3字段)<br>4. 搜索指标展示(5字段)<br>5. 费用指标展示(3字段)<br>6. 成本指标展示(6字段)<br>7. 数值格式化(千分位/2位小数)<br>8. **粗略实现**: 功能可用即可 |
+
+---
+
 **文档状态**: 待执行
-**建议下一步**: 按顺序执行 Phase 1 任务,完成基础架构搭建
+**建议下一步**:
+- **最高优先级**: 执行 T-027 修复巨量云图API调用参数问题
+- 然后验证视频分析功能 T-021~T-026 是否正常工作
 **评审建议**: 可运行 `/rt` 对任务列表进行评审