# KOL Insight - 任务列表 ## 文档信息 | 项目 | 内容 | |------|------| | 版本 | v1.0 | | 创建日期 | 2026-01-28 | | 来源文档 | UIDesign.md, DevelopmentPlan.md, FeatureSummary.md, PRD.md | ## 架构说明 **前后端分离架构**: - **前端**: Next.js 14.x + React + TypeScript + Tailwind CSS - **后端**: Python FastAPI 0.104+ + SQLAlchemy 2.0+ + asyncpg - **数据库**: PostgreSQL 14.x+ - **部署**: Docker + Uvicorn (ASGI 服务器) **关键技术点**: - 后端使用 FastAPI 异步框架,提供 RESTful API - 前端通过 HTTP 调用后端 API(CORS 配置) - 数据库使用 SQLAlchemy 异步 ORM - 外部 API 调用使用 httpx 异步库 ## 1. 任务总览 | 统计项 | 数量 | |--------|------| | 总任务数 | 18 | | P0 任务 | 10 | | P1 任务 | 7 | | P2 任务 | 1 | ## 2. Phase 1 任务 - 基础架构搭建 ### 2.1 项目初始化与配置 | ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 | |----|------|------|--------|------|----------| | T-001A | 前端项目初始化 | 创建 Next.js 14.x 项目,配置 TypeScript、ESLint、Prettier | P0 | - | 1. Next.js 14.x 项目创建成功
2. TypeScript 配置完成 (tsconfig.json)
3. ESLint 配置完成 (.eslintrc.json)
4. Prettier 配置完成 (.prettierrc)
5. 可运行 `pnpm dev` 启动开发服务器
6. 可运行 `pnpm build` 构建生产版本 | | T-001B | 后端项目初始化 | 创建 FastAPI 0.104+ 项目,配置 Python 依赖管理 | P0 | - | 1. FastAPI 0.104+ 项目创建成功
2. Python 依赖管理配置完成 (Poetry 或 requirements.txt)
3. 项目结构创建 (app/, tests/, alembic/)
4. main.py 应用入口文件创建
5. 可运行 `uvicorn main:app --reload` 启动开发服务器
6. 访问 http://localhost:8000/docs 可看到 API 文档 | | T-002 | 数据库配置 | 配置 SQLAlchemy,定义数据模型,连接 PostgreSQL | P0 | T-001B | 1. SQLAlchemy 2.0+ 和 asyncpg 安装完成
2. 定义 KolVideo 模型(使用 SQLAlchemy ORM)
3. 数据库异步连接成功
4. 索引创建: star_id, star_unique_id, star_nickname
5. Alembic 迁移工具配置完成
6. **真实数据库测试**: 使用 .env 中的连接字符串连接真实数据库并验证
7. **TDD要求**: 编写数据库连接测试,模型测试,CRUD测试
8. **测试覆盖率**: 数据库操作测试覆盖率 ≥ 100% | | T-003 | 基础 UI 框架 | 安装 Tailwind CSS,创建基础布局组件 | P0 | T-001A | 1. Tailwind CSS 配置完成
2. 品牌色系配置 (#4F46E5等)
3. 基础布局组件创建 (Header/Footer)
4. 麦秒思AI Logo 集成 (doc/ui/muse.svg) | | T-004 | 环境变量配置 | 配置开发/生产环境变量,数据库连接字符串 | P0 | T-001A, T-001B | 1. 前后端 .env.example 创建
2. 后端 DATABASE_URL 配置
3. 后端品牌 API 地址配置
4. 前端 NEXT_PUBLIC_API_URL 配置
5. .env 文件创建并添加到 .gitignore | ## 3. Phase 2 任务 - 核心功能开发 ### 3.1 后端 API 开发 | ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 | |----|------|------|--------|------|----------| | T-005 | 查询 API 开发 | 实现 POST /api/v1/query 接口(FastAPI),支持三种查询方式 | P0 | T-002 | 1. FastAPI POST /api/v1/query 路由实现
2. Pydantic 模型验证请求参数(type: star_id/unique_id/nickname)
3. 星图ID: 使用 SQLAlchemy 异步查询 WHERE star_id IN (...)
4. 达人ID: WHERE star_unique_id IN (...)
5. 昵称: WHERE star_nickname LIKE '%...%'
6. 返回完整视频数据列表(JSON 格式)
7. 限制单次查询最大 1000 条
8. CORS 配置支持前端跨域请求
9. **TDD要求**: 先编写API测试用例(三种查询方式),再实现路由
10. **测试覆盖率**: API集成测试覆盖率 ≥ 100% (包含成功/失败/边界场景) | | T-006 | 计算逻辑实现 | 在 Python 后端实现 CPM、看后搜人数、成本计算 | P0 | T-005 | 1. 预估自然CPM = estimated_video_cost / natural_play_cnt * 1000
2. 预估自然看后搜人数 = natural_play_cnt / total_play_cnt * after_view_search_uv
3. 预估看后搜人数成本 = estimated_video_cost / 预估自然看后搜人数
4. 除零检查,返回 None
5. 结果保留 2 位小数(使用 round())
6. 批量计算使用列表推导式或 map()
7. **TDD要求**: 先编写计算函数的单元测试(包含除零场景),再实现函数
8. **测试覆盖率**: 计算逻辑单元测试覆盖率 ≥ 100% (所有分支覆盖) | | T-007 | 品牌 API 批量集成 | 后端使用 httpx 批量调用品牌API获取品牌名称,支持并发控制和降级 | P0 | T-005 | 1. 使用 httpx.AsyncClient 实现 GET /v1/yuntu/brands/{brand_id} 调用
2. 从查询结果提取唯一 brand_id(去重)
3. 使用 asyncio.gather 批量并发请求(限制 10 并发)
4. 构建 brand_id → brand_name 映射字典
5. 单个 API 调用失败时降级显示 brand_id
6. 超时设置: 3秒
7. 错误日志记录
8. **TDD要求**: 先编写测试用例(模拟API响应),再实现功能
9. **测试覆盖率**: 单元测试覆盖率 ≥ 100% (包含成功/失败/超时/并发场景) | | T-010 | 导出 API 开发 | 实现 GET /api/v1/export 接口(FastAPI),生成 Excel/CSV | P1 | T-006, T-007 | 1. FastAPI GET /api/v1/export 路由实现
2. 支持 format=xlsx/csv 查询参数
3. 使用 openpyxl 或 xlsxwriter 库生成 Excel
4. CSV 使用 Python csv 模块,处理逗号转义
5. 使用中文列名作为表头 **(字段顺序和命名需与前端 ResultTable 保持一致)**
6. 文件名: kol_data_{timestamp}.xlsx
7. 响应头设置 Content-Disposition: attachment
8. 使用 StreamingResponse 返回文件
9. 限制单次导出最大 1000 条
10. **TDD要求**: 先编写测试用例(生成文件验证),再实现功能
11. **测试覆盖率**: 单元测试覆盖率 ≥ 100% (包含 Excel/CSV 生成,字段一致性验证) | ### 3.2 前端组件开发 | ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 | |----|------|------|--------|------|----------| | T-008 | 查询表单组件 | 开发查询输入表单,支持方式切换 **(前端粗略实现)** | P0 | T-003 | 1. QueryForm 组件创建
2. Radio 单选器: 星图ID/达人unique_id/达人昵称
3. Textarea 输入框,支持批量输入
4. 根据查询方式动态更新输入提示
5. 输入验证 (实时)
6. 清空和提交按钮
7. 加载态: 按钮禁用,显示 Loading
8. **粗略实现说明**: 基础表单功能可用,样式简洁即可 | | T-009 | 结果表格组件 | 开发数据展示表格,显示 26 个字段 **(前端粗略实现)** | P1 | T-003, T-006, T-007 | 1. ResultTable 组件创建
2. 展示 26 个字段,使用中文列名
3. 表格列宽按 UIDesign 规范
4. 数字格式化: 千分位分隔
5. 大数值使用 K/M 缩写
6. 空值显示 "-"
7. 支持横向滚动
8. 支持列排序
9. **包含分页器组件**: 每页 20 条,支持翻页
10. 品牌名称由后端返回,直接展示
11. **粗略实现说明**: 基础功能可用即可,样式可简化 | | T-011 | 导出按钮组件 | 开发导出按钮,触发文件下载 **(前端粗略实现)** | P1 | T-009, T-010 | 1. ExportButton 组件创建
2. 导出 Excel 按钮
3. 导出 CSV 按钮
4. 点击触发 /api/export 调用
5. 浏览器下载文件
6. 无数据时提示 "无数据可导出"
7. 导出中显示 Loading
8. **粗略实现说明**: 基础导出功能可用即可 | ### 3.3 页面集成 | ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 | |----|------|------|--------|------|----------| | T-011A | 主页面集成 | 集成查询表单、结果表格和导出按钮,完成单页应用 **(前端粗略实现)** | P0 | T-008, T-009, T-011 | 1. page.tsx 创建单页应用
2. 品牌头部: Logo + "KOL Insight" + "麦秒思AI制作"
3. 查询区域集成 QueryForm
4. 结果区域集成 ResultTable 和 ExportButton
5. Footer: "© 2026 麦秒思AI制作"
6. 页面状态管理: 默认态/输入态/查询中/结果态/空结果态/错误态
7. 空状态组件: 引导文案 + 空盒子图标
8. 错误状态组件: 错误提示 + 重试按钮
9. **粗略实现说明**: 重点在功能集成,UI可简化,品牌元素必须保留 | ## 4. Phase 3 任务 - 优化与测试 ### 4.1 错误处理与优化 | ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 | |----|------|------|--------|------|----------| | T-013 | 错误处理 | 完善错误处理,添加用户友好提示 | P1 | T-011A | 1. API 错误处理: try-catch 包裹
2. 数据库连接失败提示
3. 品牌 API 失败降级处理
4. 网络超时提示
5. 输入验证错误提示
6. 空结果友好提示
7. 错误日志记录 (后端)
8. **后端TDD要求**: 编写异常场景测试用例,验证错误处理逻辑
9. **后端测试覆盖率**: 错误处理分支覆盖率 ≥ 100%
10. **前端粗略实现**: 基础错误提示可用即可 | | T-014 | 性能优化 | 数据库索引优化,查询性能调优 | P1 | T-013 | 1. 验证索引已创建: star_id, star_unique_id, star_nickname
2. 查询响应时间 ≤ 3秒 (100条)
3. 页面加载时间 ≤ 2秒
4. 导出响应时间 ≤ 5秒 (1000条)
5. 品牌 API 并发控制 (限制 10 并发)
6. **后端性能测试**: 编写性能测试脚本,验证响应时间指标
7. **真实数据库测试**: 使用真实数据库进行性能测试 | | T-015 | 视频链接跳转 | 实现视频链接点击跳转功能 | P2 | T-009 | 1. 视频链接列展示为链接按钮
2. 使用 ``
3. 链接为空时显示 "-"
4. 新窗口打开视频页面 | | T-016 | 部署配置 | Docker 配置前后端分离部署 | P1 | T-013 | 1. 前端 Dockerfile 创建(Node.js + Next.js)
2. 后端 Dockerfile 创建(Python + FastAPI + Uvicorn)
3. docker-compose.yml 配置前端、后端、PostgreSQL
4. 前端构建: pnpm build
5. 后端启动: uvicorn main:app --host 0.0.0.0 --port 8000
6. 生产环境可访问
7. 环境变量配置(.env) | | T-017 | 集成测试 | 端到端功能测试 | P1 | T-013 | 1. 测试用例: 星图ID精准查询
2. 测试用例: 达人ID批量查询
3. 测试用例: 昵称模糊查询
4. 测试用例: 计算指标准确性
5. 测试用例: 品牌名称获取
6. 测试用例: 数据导出 (Excel/CSV)
7. 测试用例: 错误处理 (网络异常/空结果)
8. 所有 P0/P1 功能测试通过
9. **真实数据库集成测试**: 使用 .env 中的真实数据库连接进行完整集成测试 | | T-018 | 测试覆盖率验收 | 验证所有后端代码测试覆盖率 ≥ 100% | P1 | T-002, T-005, T-006, T-007, T-010, T-013, T-017 | 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. 覆盖率报告保存到 coverage/ 目录
9. CI/CD 集成: 覆盖率未达标时构建失败 | ## 5. 任务依赖图 ``` Phase 1: 基础架构 T-001A (前端初始化) T-001B (后端初始化) │ │ ├── T-003 (基础UI) ├── T-002 (数据库配置) │ │ └────────┬─────────────┘ │ └── 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-011A (主页面集成) ───────────┘ Phase 3: 优化测试 T-011A ──▶ T-013 (错误处理) ──▶ T-014 (性能优化) │ │ ├──▶ T-015 (视频链接) │ │ │ ├──▶ T-016 (部署配置) │ │ │ └──▶ T-017 (集成测试) ─┤ │ │ └──▶ T-018 (测试覆盖率验收) ``` ## 6. 执行检查清单 ### Phase 1 - 基础架构搭建 - [ ] T-001A: 前端项目初始化 - [ ] T-001B: 后端项目初始化 - [ ] T-002: 数据库配置 - [ ] T-003: 基础 UI 框架 - [ ] T-004: 环境变量配置 ### Phase 2 - 核心功能开发 - [ ] T-005: 查询 API 开发 - [ ] T-006: 计算逻辑实现 - [ ] T-007: 品牌 API 批量集成 - [ ] T-008: 查询表单组件 - [ ] T-009: 结果表格组件 - [ ] T-010: 导出 API 开发 - [ ] T-011: 导出按钮组件 - [ ] T-011A: 主页面集成 ### Phase 3 - 优化与测试 - [ ] T-013: 错误处理 - [ ] T-014: 性能优化 - [ ] T-015: 视频链接跳转 - [ ] T-016: 部署配置 - [ ] T-017: 集成测试 - [ ] T-018: 测试覆盖率验收 ## 7. 里程碑与交付物 | 里程碑 | 包含任务 | 交付物 | 预期验收 | |--------|----------|--------|----------| | M1: 基础架构完成 | T-001A, T-001B, T-002~T-004 | 前后端项目骨架、数据库连接、基础UI | 前后端项目可运行,数据库可连接 | | M2: 核心功能完成 | T-005~T-011A | 查询、计算、展示、导出功能 | 所有 P0 功能可用,品牌API集成 | | M3: 优化测试完成 | T-013~T-018 | 错误处理、性能优化、部署配置、测试覆盖率 | 测试通过,性能达标,100%覆盖率,可部署 | | M4: 正式上线 | - | 生产环境部署 | 生产环境可访问,稳定运行 | ## 8. 优先级说明 **P0 任务 (10个)** - MVP 必须完成 - 基础架构: T-001A (前端初始化), T-001B (后端初始化), T-002 (数据库), T-003 (基础UI), T-004 (环境变量) - 核心功能: T-005 (查询API), T-006 (计算逻辑), T-007 (品牌API), T-008 (查询表单), T-011A (主页面集成) **P1 任务 (7个)** - 重要功能 - 展示导出: T-009 (结果表格), T-010 (导出API), T-011 (导出按钮) - 优化测试: T-013 (错误处理), T-014 (性能优化), T-016 (部署配置), T-017 (集成测试), T-018 (测试覆盖率验收) **P2 任务 (1个)** - 次要功能 - 增强体验: T-015 (视频链接跳转) ## 9. 关键技术点 | 任务 | 关键技术 | 注意事项 | |------|----------|----------| | T-001A | Next.js 14.x 项目初始化 | TypeScript + ESLint + Prettier,App Router 模式 | | T-001B | FastAPI 0.104+ 项目初始化 | Poetry/pip 依赖管理,项目结构规划 | | T-002 | SQLAlchemy + asyncpg | 必须创建索引: star_id, star_unique_id, star_nickname,使用异步 ORM | | T-005 | FastAPI + Pydantic | 使用 IN 查询批量匹配,LIKE 模糊匹配,限制最大 1000 条,CORS 配置 | | T-006 | Python 计算 | 除零检查,结果保留 2 位小数,None 值处理 | | T-007 | httpx + asyncio | 批量并发调用 (限制 10 并发),超时 3 秒,降级处理,使用 asyncio.gather | | T-009 | React 表格组件 | 26 个字段展示,数字格式化,横向滚动,分页 | | T-010 | openpyxl/xlsxwriter | Python 库生成 Excel,CSV 逗号转义,中文列名,StreamingResponse | | T-011A | React 状态管理 | 6 种页面状态: 默认/输入/查询中/结果/空结果/错误 | | T-013 | FastAPI 错误处理 | API 错误、数据库连接失败、品牌API降级、网络超时 | | T-014 | 性能优化 | 查询 ≤3秒,页面加载 ≤2秒,导出 ≤5秒,并发控制 | | T-016 | Docker + Uvicorn | 前后端分离部署,Uvicorn ASGI 服务器 | | T-018 | pytest-cov | 测试覆盖率验收,确保所有后端代码 ≥ 100% 覆盖率 | ## 10. 数据库 Schema 参考 ```python # SQLAlchemy 模型定义 from sqlalchemy import Column, String, Integer, Float, DateTime, Index from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() class KolVideo(Base): __tablename__ = "kol_videos" # 主键 item_id = Column(String, primary_key=True) # 基本信息 title = Column(String, nullable=True) viral_type = Column(String, nullable=True) video_url = Column(String, nullable=True) star_id = Column(String, nullable=False) star_unique_id = Column(String, nullable=False) star_nickname = Column(String, nullable=False) publish_time = Column(DateTime, nullable=True) # 曝光指标 natural_play_cnt = Column(Integer, default=0) heated_play_cnt = Column(Integer, default=0) total_play_cnt = Column(Integer, default=0) # 互动指标 total_interact = Column(Integer, default=0) like_cnt = Column(Integer, default=0) share_cnt = Column(Integer, default=0) comment_cnt = Column(Integer, default=0) # 效果指标 new_a3_rate = Column(Float, nullable=True) after_view_search_uv = Column(Integer, default=0) return_search_cnt = Column(Integer, default=0) # 商业信息 industry_id = Column(String, nullable=True) industry_name = Column(String, nullable=True) brand_id = Column(String, nullable=True) estimated_video_cost = Column(Float, default=0) # 索引 __table_args__ = ( Index('idx_star_id', 'star_id'), Index('idx_star_unique_id', 'star_unique_id'), Index('idx_star_nickname', 'star_nickname'), ) ``` ## 11. API 接口参考 ### POST /api/v1/query ```python # FastAPI 路由定义 from pydantic import BaseModel from typing import List, Literal class QueryRequest(BaseModel): type: Literal["star_id", "unique_id", "nickname"] values: List[str] class QueryResponse(BaseModel): success: bool data: List[dict] # 视频数据列表 (含 26 个字段) total: int # 请求示例 { "type": "star_id", "values": ["id1", "id2", ...] } # 响应示例 { "success": true, "data": [...], "total": 100 } ``` ### GET /api/v1/export ```python # FastAPI 路由 @app.get("/api/v1/export") async def export_data(format: Literal["xlsx", "csv"] = "xlsx"): # 返回 StreamingResponse pass # 请求: GET /api/v1/export?format=xlsx # 响应: 文件下载 (Content-Disposition: attachment) ``` ### 外部 API: GET /v1/yuntu/brands/{brand_id} ```python # 使用 httpx.AsyncClient 调用 import httpx async with httpx.AsyncClient() as client: response = await client.get( f"https://api.internal.intelligrow.cn/v1/yuntu/brands/{brand_id}", timeout=3.0 ) # 失败时降级显示 brand_id ``` --- **文档状态**: 待执行 **建议下一步**: 按顺序执行 Phase 1 任务,完成基础架构搭建 **评审建议**: 可运行 `/rt` 对任务列表进行评审