kol-insight/doc/tasks.md

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. 使用 <a target="_blank" rel="noopener noreferrer">
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 参考

# 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

# 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

# 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}

# 使用 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 对任务列表进行评审