kol-insight/doc/tasks.md

# KOL Insight - 任务列表

## 文档信息

| 项目 | 内容 |
|------|------|
| 版本 | v1.0 |
| 创建日期 | 2026-01-28 |
| 来源文档 | UIDesign.md, DevelopmentPlan.md, FeatureSummary.md, PRD.md |

<!-- NEW START -->
## 架构说明

**前后端分离架构**:
- **前端**: 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 异步库
<!-- NEW END -->

## 1. 任务总览

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

## 2. Phase 1 任务 - 基础架构搭建

### 2.1 项目初始化与配置

| ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 |
|----|------|------|--------|------|----------|
<!-- MODIFIED: 拆分为前后端独立任务,支持并行开发 (根据评审报告 C-1) -->
| T-001A | 前端项目初始化 | 创建 Next.js 14.x 项目,配置 TypeScript、ESLint、Prettier | P0 | - | 1. Next.js 14.x 项目创建成功<br>2. TypeScript 配置完成 (tsconfig.json)<br>3. ESLint 配置完成 (.eslintrc.json)<br>4. Prettier 配置完成 (.prettierrc)<br>5. 可运行 `pnpm dev` 启动开发服务器<br>6. 可运行 `pnpm build` 构建生产版本 |
| T-001B | 后端项目初始化 | 创建 FastAPI 0.104+ 项目,配置 Python 依赖管理 | P0 | - | 1. FastAPI 0.104+ 项目创建成功<br>2. Python 依赖管理配置完成 (Poetry 或 requirements.txt)<br>3. 项目结构创建 (app/, tests/, alembic/)<br>4. main.py 应用入口文件创建<br>5. 可运行 `uvicorn main:app --reload` 启动开发服务器<br>6. 访问 http://localhost:8000/docs 可看到 API 文档 |
<!-- MODIFIED: 改为 SQLAlchemy + asyncpg -->
<!-- MODIFIED: 添加真实数据库测试要求和 TDD 要求 -->
<!-- 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) |
<!-- 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 |

## 3. Phase 2 任务 - 核心功能开发

### 3.1 后端 API 开发

| ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 |
|----|------|------|--------|------|----------|
<!-- MODIFIED: 改为 FastAPI 实现 -->
<!-- MODIFIED: 增加 TDD 要求和测试覆盖率 -->
| T-005 | 查询 API 开发 | 实现 POST /api/v1/query 接口(FastAPI),支持三种查询方式 | P0 | T-002 | 1. FastAPI POST /api/v1/query 路由实现<br>2. Pydantic 模型验证请求参数(type: star_id/unique_id/nickname)<br>3. 星图ID: 使用 SQLAlchemy 异步查询 WHERE star_id IN (...)<br>4. 达人ID: WHERE star_unique_id IN (...)<br>5. 昵称: WHERE star_nickname LIKE '%...%'<br>6. 返回完整视频数据列表(JSON 格式)<br>7. 限制单次查询最大 1000 条<br>8. CORS 配置支持前端跨域请求<br><!-- NEW START -->9. **TDD要求**: 先编写API测试用例(三种查询方式),再实现路由<br>10. **测试覆盖率**: API集成测试覆盖率 ≥ 100% (包含成功/失败/边界场景)<!-- NEW END --> |
<!-- MODIFIED: 改为 Python 后端实现 -->
<!-- MODIFIED: 增加 TDD 要求和测试覆盖率 -->
| T-006 | 计算逻辑实现 | 在 Python 后端实现 CPM、看后搜人数、成本计算 | P0 | T-005 | 1. 预估自然CPM = estimated_video_cost / natural_play_cnt * 1000<br>2. 预估自然看后搜人数 = natural_play_cnt / total_play_cnt * after_view_search_uv<br>3. 预估看后搜人数成本 = estimated_video_cost / 预估自然看后搜人数<br>4. 除零检查,返回 None<br>5. 结果保留 2 位小数(使用 round())<br>6. 批量计算使用列表推导式或 map()<br><!-- NEW START -->7. **TDD要求**: 先编写计算函数的单元测试(包含除零场景),再实现函数<br>8. **测试覆盖率**: 计算逻辑单元测试覆盖率 ≥ 100% (所有分支覆盖)<!-- NEW END --> |
<!-- MODIFIED: 明确使用 httpx 异步库,去除可选项 -->
<!-- MODIFIED: 删除"可选"验收标准,增加 TDD 要求和测试覆盖率 -->
| T-007 | 品牌 API 批量集成 | 后端使用 httpx 批量调用品牌API获取品牌名称,支持并发控制和降级 | P0 | T-005 | 1. 使用 httpx.AsyncClient 实现 GET /v1/yuntu/brands/{brand_id} 调用<br>2. 从查询结果提取唯一 brand_id(去重)<br>3. 使用 asyncio.gather 批量并发请求(限制 10 并发)<br>4. 构建 brand_id → brand_name 映射字典<br>5. 单个 API 调用失败时降级显示 brand_id<br>6. 超时设置: 3秒<br>7. 错误日志记录<br><!-- NEW START -->8. **TDD要求**: 先编写测试用例(模拟API响应),再实现功能<br>9. **测试覆盖率**: 单元测试覆盖率 ≥ 100% (包含成功/失败/超时/并发场景)<!-- NEW END --> |
<!-- MODIFIED: 改为 FastAPI + Python 导出库实现 -->
<!-- MODIFIED: 修正依赖关系,移除 T-009 前端组件依赖 (根据评审报告 C-2) -->
| T-010 | 导出 API 开发 | 实现 GET /api/v1/export 接口(FastAPI),生成 Excel/CSV | P1 | T-006, T-007 | 1. FastAPI GET /api/v1/export 路由实现<br>2. 支持 format=xlsx/csv 查询参数<br>3. 使用 openpyxl 或 xlsxwriter 库生成 Excel<br>4. CSV 使用 Python csv 模块,处理逗号转义<br>5. 使用中文列名作为表头 **(字段顺序和命名需与前端 ResultTable 保持一致)**<br>6. 文件名: kol_data_{timestamp}.xlsx<br>7. 响应头设置 Content-Disposition: attachment<br>8. 使用 StreamingResponse 返回文件<br>9. 限制单次导出最大 1000 条<br><!-- NEW START -->10. **TDD要求**: 先编写测试用例(生成文件验证),再实现功能<br>11. **测试覆盖率**: 单元测试覆盖率 ≥ 100% (包含 Excel/CSV 生成,字段一致性验证)<!-- NEW END --> |

### 3.2 前端组件开发

| ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 |
|----|------|------|--------|------|----------|
<!-- MODIFIED: 简化前端实现要求 -->
| T-008 | 查询表单组件 | 开发查询输入表单,支持方式切换 **(前端粗略实现)** | P0 | T-003 | 1. QueryForm 组件创建<br>2. Radio 单选器: 星图ID/达人unique_id/达人昵称<br>3. Textarea 输入框,支持批量输入<br>4. 根据查询方式动态更新输入提示<br>5. 输入验证 (实时)<br>6. 清空和提交按钮<br>7. 加载态: 按钮禁用,显示 Loading<br><!-- NEW START -->8. **粗略实现说明**: 基础表单功能可用,样式简洁即可<!-- NEW END --> |
<!-- MODIFIED: 明确分页器组件,简化前端实现要求 -->
| T-009 | 结果表格组件 | 开发数据展示表格,显示 26 个字段 **(前端粗略实现)** | P1 | T-003, T-006, T-007 | 1. ResultTable 组件创建<br>2. 展示 26 个字段,使用中文列名<br>3. 表格列宽按 UIDesign 规范<br>4. 数字格式化: 千分位分隔<br>5. 大数值使用 K/M 缩写<br>6. 空值显示 "-"<br>7. 支持横向滚动<br>8. 支持列排序<br>9. **包含分页器组件**: 每页 20 条,支持翻页<br>10. 品牌名称由后端返回,直接展示<br><!-- NEW START -->11. **粗略实现说明**: 基础功能可用即可,样式可简化<!-- NEW END --> |
<!-- MODIFIED: 简化前端实现要求 -->
| T-011 | 导出按钮组件 | 开发导出按钮,触发文件下载 **(前端粗略实现)** | P1 | T-009, T-010 | 1. ExportButton 组件创建<br>2. 导出 Excel 按钮<br>3. 导出 CSV 按钮<br>4. 点击触发 /api/export 调用<br>5. 浏览器下载文件<br>6. 无数据时提示 "无数据可导出"<br>7. 导出中显示 Loading<br><!-- NEW START -->8. **粗略实现说明**: 基础导出功能可用即可<!-- NEW END --> |

### 3.3 页面集成

| ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 |
|----|------|------|--------|------|----------|
<!-- 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 --> |

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

### 4.1 错误处理与优化

| ID | 任务 | 描述 | 优先级 | 依赖 | 验收标准 |
|----|------|------|--------|------|----------|
<!-- MODIFIED: 增加后端 TDD 要求和测试覆盖率 -->
<!-- MODIFIED: 依赖改为 T-011A -->
| T-013 | 错误处理 | 完善错误处理,添加用户友好提示 | P1 | T-011A | 1. API 错误处理: try-catch 包裹<br>2. 数据库连接失败提示<br>3. 品牌 API 失败降级处理<br>4. 网络超时提示<br>5. 输入验证错误提示<br>6. 空结果友好提示<br>7. 错误日志记录 (后端)<br><!-- NEW START -->8. **后端TDD要求**: 编写异常场景测试用例,验证错误处理逻辑<br>9. **后端测试覆盖率**: 错误处理分支覆盖率 ≥ 100%<br>10. **前端粗略实现**: 基础错误提示可用即可<!-- NEW END --> |
<!-- MODIFIED: 增加后端性能测试要求 -->
| T-014 | 性能优化 | 数据库索引优化,查询性能调优 | P1 | T-013 | 1. 验证索引已创建: star_id, star_unique_id, star_nickname<br>2. 查询响应时间 ≤ 3秒 (100条)<br>3. 页面加载时间 ≤ 2秒<br>4. 导出响应时间 ≤ 5秒 (1000条)<br>5. 品牌 API 并发控制 (限制 10 并发)<br><!-- NEW START -->6. **后端性能测试**: 编写性能测试脚本,验证响应时间指标<br>7. **真实数据库测试**: 使用真实数据库进行性能测试<!-- NEW END --> |
| T-015 | 视频链接跳转 | 实现视频链接点击跳转功能 | P2 | T-009 | 1. 视频链接列展示为链接按钮<br>2. 使用 `<a target="_blank" rel="noopener noreferrer">`<br>3. 链接为空时显示 "-"<br>4. 新窗口打开视频页面 |
<!-- MODIFIED: 改为前后端分离的 Docker 配置 -->
| T-016 | 部署配置 | Docker 配置前后端分离部署 | P1 | T-013 | 1. 前端 Dockerfile 创建(Node.js + Next.js)<br>2. 后端 Dockerfile 创建(Python + FastAPI + Uvicorn)<br>3. docker-compose.yml 配置前端、后端、PostgreSQL<br>4. 前端构建: pnpm build<br>5. 后端启动: uvicorn main:app --host 0.0.0.0 --port 8000<br>6. 生产环境可访问<br>7. 环境变量配置(.env) |
<!-- MODIFIED: 增加真实数据库集成测试和100%覆盖率要求 -->
| T-017 | 集成测试 | 端到端功能测试 | P1 | T-013 | 1. 测试用例: 星图ID精准查询<br>2. 测试用例: 达人ID批量查询<br>3. 测试用例: 昵称模糊查询<br>4. 测试用例: 计算指标准确性<br>5. 测试用例: 品牌名称获取<br>6. 测试用例: 数据导出 (Excel/CSV)<br>7. 测试用例: 错误处理 (网络异常/空结果)<br>8. 所有 P0/P1 功能测试通过<br><!-- NEW START -->9. **真实数据库集成测试**: 使用 .env 中的真实数据库连接进行完整集成测试<!-- NEW END --> |
<!-- NEW START: 根据评审报告 C-3 增加独立测试覆盖率验收任务 -->
| T-018 | 测试覆盖率验收 | 验证所有后端代码测试覆盖率 ≥ 100% | P1 | T-002, T-005, T-006, T-007, T-010, T-013, T-017 | 1. 数据库操作测试覆盖率 100% (T-002)<br>2. API集成测试覆盖率 100% (T-005)<br>3. 计算逻辑单元测试覆盖率 100% (T-006)<br>4. 品牌API单元测试覆盖率 100% (T-007)<br>5. 导出功能单元测试覆盖率 100% (T-010)<br>6. 错误处理分支覆盖率 100% (T-013)<br>7. 使用 pytest-cov 生成覆盖率报告<br>8. 覆盖率报告保存到 coverage/ 目录<br>9. CI/CD 集成: 覆盖率未达标时构建失败 |
<!-- NEW END -->

## 5. 任务依赖图

<!-- MODIFIED: 更新任务依赖图,T-001拆分,T-012改为T-011A,新增T-018 -->
```
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. 执行检查清单

<!-- MODIFIED: 更新任务编号,T-001拆分,T-012改为T-011A,新增T-018 -->
### 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. 里程碑与交付物

<!-- MODIFIED: 更新任务编号范围 -->
| 里程碑 | 包含任务 | 交付物 | 预期验收 |
|--------|----------|--------|----------|
| 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. 优先级说明

<!-- MODIFIED: 更新任务编号和数量 -->
**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. 关键技术点

<!-- MODIFIED: 更新为 FastAPI + SQLAlchemy 技术栈 -->
<!-- MODIFIED: T-001 拆分为 T-001A 和 T-001B -->
| 任务 | 关键技术 | 注意事项 |
|------|----------|----------|
| 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% 覆盖率 |

<!-- MODIFIED: 改为 SQLAlchemy 模型定义 -->
## 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'),
    )
```

<!-- MODIFIED: 改为 FastAPI 格式 -->
## 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` 对任务列表进行评审