feat(core): 完成 Phase 2 核心功能开发

- 实现查询API (query.py): 支持star_id/unique_id/nickname三种查询方式 - 实现计算模块 (calculator.py): CPM/自然搜索UV/搜索成本计算 - 实现品牌API集成 (brand_api.py): 批量并发调用，10并发限制 - 实现导出服务 (export_service.py): Excel/CSV导出 - 前端组件: QueryForm/ResultTable/ExportButton - 主页面集成: 支持6种页面状态 - 测试: 44个测试全部通过，覆盖率88% Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 14:38:38 +08:00 · 2026-01-28 14:38:38 +08:00 · 8fbcb72a3f
commit 8fbcb72a3f
parent ac0f086821
21 changed files with 1677 additions and 100 deletions
--- a/backend/app/api/v1/export.py
+++ b/backend/app/api/v1/export.py
@ -0,0 +1,59 @@
+from datetime import datetime
+from typing import Literal
+
+from fastapi import APIRouter, Query
+from fastapi.responses import StreamingResponse
+from io import BytesIO
+
+from app.services.export_service import generate_excel, generate_csv
+
+router = APIRouter()
+
+# 存储最近的查询结果 (简化实现, 生产环境应使用 Redis 等缓存)
+_cached_data: list = []
+
+
+def set_export_data(data: list):
+    """设置导出数据缓存."""
+    global _cached_data
+    _cached_data = data
+
+
+def get_export_data() -> list:
+    """获取导出数据缓存."""
+    return _cached_data
+
+
+@router.get("/export")
+async def export_data(
+    format: Literal["xlsx", "csv"] = Query("xlsx", description="导出格式"),
+):
+    """
+    导出查询结果.
+
+    Args:
+        format: 导出格式 (xlsx 或 csv)
+
+    Returns:
+        文件下载响应
+    """
+    data = get_export_data()
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+    if format == "xlsx":
+        content = generate_excel(data)
+        media_type = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+        filename = f"kol_data_{timestamp}.xlsx"
+    else:
+        content = generate_csv(data)
+        media_type = "text/csv; charset=utf-8"
+        filename = f"kol_data_{timestamp}.csv"
+
+    return StreamingResponse(
+        BytesIO(content),
+        media_type=media_type,
+        headers={
+            "Content-Disposition": f'attachment; filename="{filename}"',
+        },
+    )
--- a/backend/app/api/v1/query.py
+++ b/backend/app/api/v1/query.py
@ -0,0 +1,66 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.schemas.query import QueryRequest, QueryResponse, VideoData
+from app.services.query_service import query_videos
+from app.services.calculator import calculate_metrics
+from app.services.brand_api import get_brand_names
+from app.api.v1.export import set_export_data
+
+router = APIRouter()
+
+
+@router.post("/query", response_model=QueryResponse)
+async def query(
+    request: QueryRequest,
+    db: AsyncSession = Depends(get_db),
+) -> QueryResponse:
+    """
+    批量查询 KOL 视频数据.
+
+    支持三种查询方式:
+    - star_id: 按星图ID精准匹配
+    - unique_id: 按达人unique_id精准匹配
+    - nickname: 按达人昵称模糊匹配
+    """
+    try:
+        # 1. 查询数据库
+        videos = await query_videos(db, request.type, request.values)
+
+        if not videos:
+            return QueryResponse(success=True, data=[], total=0)
+
+        # 2. 提取品牌ID并批量获取品牌名称
+        brand_ids = [v.brand_id for v in videos if v.brand_id]
+        brand_map = await get_brand_names(brand_ids) if brand_ids else {}
+
+        # 3. 转换为响应模型并计算指标
+        data = []
+        for video in videos:
+            video_data = VideoData.model_validate(video)
+
+            # 填充品牌名称
+            if video.brand_id:
+                video_data.brand_name = brand_map.get(video.brand_id, video.brand_id)
+
+            # 计算预估指标
+            metrics = calculate_metrics(
+                estimated_video_cost=video.estimated_video_cost,
+                natural_play_cnt=video.natural_play_cnt,
+                total_play_cnt=video.total_play_cnt,
+                after_view_search_uv=video.after_view_search_uv,
+            )
+            video_data.estimated_natural_cpm = metrics["estimated_natural_cpm"]
+            video_data.estimated_natural_search_uv = metrics["estimated_natural_search_uv"]
+            video_data.estimated_natural_search_cost = metrics["estimated_natural_search_cost"]
+
+            data.append(video_data)
+
+        # 缓存数据供导出使用
+        set_export_data([d.model_dump() for d in data])
+
+        return QueryResponse(success=True, data=data, total=len(data))
+
+    except Exception as e:
+        return QueryResponse(success=False, data=[], total=0, error=str(e))
--- a/backend/app/main.py
+++ b/backend/app/main.py
@ -2,6 +2,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware

 from app.config import settings
+from app.api.v1 import query, export

 app = FastAPI(
    title="KOL Insight API",
@ -18,6 +19,10 @@ app.add_middleware(
    allow_headers=["*"],
 )

+# 注册 API 路由
+app.include_router(query.router, prefix="/api/v1", tags=["Query"])
+app.include_router(export.router, prefix="/api/v1", tags=["Export"])
+

@app.get("/")
 async def root():
--- a/backend/app/schemas/query.py
+++ b/backend/app/schemas/query.py
@ -0,0 +1,67 @@
+from pydantic import BaseModel, ConfigDict, Field
+from typing import List, Literal, Optional
+from datetime import datetime
+
+
+class QueryRequest(BaseModel):
+    """查询请求模型."""
+
+    type: Literal["star_id", "unique_id", "nickname"] = Field(
+        ..., description="查询类型: star_id, unique_id, nickname"
+    )
+    values: List[str] = Field(
+        ..., description="查询值列表 (批量ID 或单个昵称)", min_length=1
+    )
+
+
+class VideoData(BaseModel):
+    """视频数据模型."""
+
+    # 基础信息
+    item_id: str
+    title: Optional[str] = None
+    viral_type: Optional[str] = None
+    video_url: Optional[str] = None
+    star_id: str
+    star_unique_id: str
+    star_nickname: str
+    publish_time: Optional[datetime] = None
+
+    # 曝光指标
+    natural_play_cnt: int = 0
+    heated_play_cnt: int = 0
+    total_play_cnt: int = 0
+
+    # 互动指标
+    total_interact: int = 0
+    like_cnt: int = 0
+    share_cnt: int = 0
+    comment_cnt: int = 0
+
+    # 效果指标
+    new_a3_rate: Optional[float] = None
+    after_view_search_uv: int = 0
+    return_search_cnt: int = 0
+
+    # 商业信息
+    industry_id: Optional[str] = None
+    industry_name: Optional[str] = None
+    brand_id: Optional[str] = None
+    brand_name: Optional[str] = None  # 从品牌 API 获取
+    estimated_video_cost: float = 0
+
+    # 计算字段
+    estimated_natural_cpm: Optional[float] = None
+    estimated_natural_search_uv: Optional[float] = None
+    estimated_natural_search_cost: Optional[float] = None
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class QueryResponse(BaseModel):
+    """查询响应模型."""
+
+    success: bool = True
+    data: List[VideoData] = []
+    total: int = 0
+    error: Optional[str] = None
--- a/backend/app/services/brand_api.py
+++ b/backend/app/services/brand_api.py
@ -0,0 +1,83 @@
+import asyncio
+from typing import Dict, List, Tuple
+import httpx
+import logging
+
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_brand_name(
+    brand_id: str,
+    semaphore: asyncio.Semaphore,
+) -> Tuple[str, str]:
+    """
+    获取单个品牌名称.
+
+    Args:
+        brand_id: 品牌ID
+        semaphore: 并发控制信号量
+
+    Returns:
+        (brand_id, brand_name) 元组, 失败时 brand_name 为 brand_id
+    """
+    async with semaphore:
+        try:
+            async with httpx.AsyncClient(
+                timeout=settings.BRAND_API_TIMEOUT
+            ) as client:
+                response = await client.get(
+                    f"{settings.BRAND_API_BASE_URL}/v1/yuntu/brands/{brand_id}"
+                )
+                if response.status_code == 200:
+                    data = response.json()
+                    # 尝试从响应中获取品牌名称
+                    if isinstance(data, dict):
+                        name = data.get("data", {}).get("name") or data.get("name")
+                        if name:
+                            return brand_id, name
+        except httpx.TimeoutException:
+            logger.warning(f"Brand API timeout for brand_id: {brand_id}")
+        except httpx.RequestError as e:
+            logger.warning(f"Brand API request error for brand_id: {brand_id}, error: {e}")
+        except Exception as e:
+            logger.error(f"Unexpected error fetching brand {brand_id}: {e}")
+
+        # 失败时降级返回 brand_id
+        return brand_id, brand_id
+
+
+async def get_brand_names(brand_ids: List[str]) -> Dict[str, str]:
+    """
+    批量获取品牌名称.
+
+    Args:
+        brand_ids: 品牌ID列表
+
+    Returns:
+        brand_id -> brand_name 映射字典
+    """
+    # 过滤空值并去重
+    unique_ids = list(set(filter(None, brand_ids)))
+
+    if not unique_ids:
+        return {}
+
+    # 创建并发控制信号量
+    semaphore = asyncio.Semaphore(settings.BRAND_API_CONCURRENCY)
+
+    # 批量并发请求
+    tasks = [fetch_brand_name(brand_id, semaphore) for brand_id in unique_ids]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    # 构建映射表
+    brand_map: Dict[str, str] = {}
+    for result in results:
+        if isinstance(result, tuple):
+            brand_id, brand_name = result
+            brand_map[brand_id] = brand_name
+        elif isinstance(result, Exception):
+            logger.error(f"Error in batch brand fetch: {result}")
+
+    return brand_map
--- a/backend/app/services/calculator.py
+++ b/backend/app/services/calculator.py
@ -0,0 +1,102 @@
+from typing import Optional, Dict
+
+
+def calculate_natural_cpm(
+    estimated_video_cost: float,
+    natural_play_cnt: int,
+) -> Optional[float]:
+    """
+    计算预估自然CPM.
+
+    公式: estimated_video_cost / natural_play_cnt * 1000
+
+    Args:
+        estimated_video_cost: 预估视频成本
+        natural_play_cnt: 自然播放量
+
+    Returns:
+        预估自然CPM (元/千次曝光), 除零时返回 None
+    """
+    if natural_play_cnt <= 0:
+        return None
+    return round((estimated_video_cost / natural_play_cnt) * 1000, 2)
+
+
+def calculate_natural_search_uv(
+    natural_play_cnt: int,
+    total_play_cnt: int,
+    after_view_search_uv: int,
+) -> Optional[float]:
+    """
+    计算预估自然看后搜人数.
+
+    公式: natural_play_cnt / total_play_cnt * after_view_search_uv
+
+    Args:
+        natural_play_cnt: 自然播放量
+        total_play_cnt: 总播放量
+        after_view_search_uv: 看后搜人数
+
+    Returns:
+        预估自然看后搜人数, 除零时返回 None
+    """
+    if total_play_cnt <= 0:
+        return None
+    return round((natural_play_cnt / total_play_cnt) * after_view_search_uv, 2)
+
+
+def calculate_natural_search_cost(
+    estimated_video_cost: float,
+    estimated_natural_search_uv: Optional[float],
+) -> Optional[float]:
+    """
+    计算预估自然看后搜人数成本.
+
+    公式: estimated_video_cost / 预估自然看后搜人数
+
+    Args:
+        estimated_video_cost: 预估视频成本
+        estimated_natural_search_uv: 预估自然看后搜人数
+
+    Returns:
+        预估自然看后搜人数成本 (元/人), 除零时返回 None
+    """
+    if estimated_natural_search_uv is None or estimated_natural_search_uv <= 0:
+        return None
+    return round(estimated_video_cost / estimated_natural_search_uv, 2)
+
+
+def calculate_metrics(
+    estimated_video_cost: float,
+    natural_play_cnt: int,
+    total_play_cnt: int,
+    after_view_search_uv: int,
+) -> Dict[str, Optional[float]]:
+    """
+    批量计算所有预估指标.
+
+    Args:
+        estimated_video_cost: 预估视频成本
+        natural_play_cnt: 自然播放量
+        total_play_cnt: 总播放量
+        after_view_search_uv: 看后搜人数
+
+    Returns:
+        包含所有计算结果的字典
+    """
+    # 计算 CPM
+    cpm = calculate_natural_cpm(estimated_video_cost, natural_play_cnt)
+
+    # 计算看后搜人数
+    search_uv = calculate_natural_search_uv(
+        natural_play_cnt, total_play_cnt, after_view_search_uv
+    )
+
+    # 计算看后搜成本
+    search_cost = calculate_natural_search_cost(estimated_video_cost, search_uv)
+
+    return {
+        "estimated_natural_cpm": cpm,
+        "estimated_natural_search_uv": search_uv,
+        "estimated_natural_search_cost": search_cost,
+    }
--- a/backend/app/services/export_service.py
+++ b/backend/app/services/export_service.py
@ -0,0 +1,97 @@
+import csv
+from io import BytesIO, StringIO
+from typing import List, Dict, Any, Tuple
+from openpyxl import Workbook
+
+# 列定义: (中文名, 字段名)
+COLUMN_HEADERS: List[Tuple[str, str]] = [
+    ("视频ID", "item_id"),
+    ("视频标题", "title"),
+    ("爆文类型", "viral_type"),
+    ("视频链接", "video_url"),
+    ("新增A3率", "new_a3_rate"),
+    ("看后搜人数", "after_view_search_uv"),
+    ("回搜次数", "return_search_cnt"),
+    ("自然曝光数", "natural_play_cnt"),
+    ("加热曝光数", "heated_play_cnt"),
+    ("总曝光数", "total_play_cnt"),
+    ("总互动", "total_interact"),
+    ("点赞", "like_cnt"),
+    ("转发", "share_cnt"),
+    ("评论", "comment_cnt"),
+    ("合作行业ID", "industry_id"),
+    ("合作行业", "industry_name"),
+    ("合作品牌ID", "brand_id"),
+    ("合作品牌", "brand_name"),
+    ("发布时间", "publish_time"),
+    ("达人昵称", "star_nickname"),
+    ("达人unique_id", "star_unique_id"),
+    ("预估视频价格", "estimated_video_cost"),
+    ("预估自然CPM", "estimated_natural_cpm"),
+    ("预估自然看后搜人数", "estimated_natural_search_uv"),
+    ("预估自然看后搜人数成本", "estimated_natural_search_cost"),
+]
+
+
+def format_value(value: Any) -> Any:
+    """格式化导出值."""
+    if value is None:
+        return ""
+    return value
+
+
+def generate_excel(data: List[Dict[str, Any]]) -> bytes:
+    """
+    生成 Excel 文件.
+
+    Args:
+        data: 数据列表
+
+    Returns:
+        Excel 文件的字节内容
+    """
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "KOL数据"
+
+    # 写入表头
+    headers = [col[0] for col in COLUMN_HEADERS]
+    ws.append(headers)
+
+    # 写入数据
+    for row in data:
+        row_data = [format_value(row.get(col[1])) for col in COLUMN_HEADERS]
+        ws.append(row_data)
+
+    # 保存到内存
+    output = BytesIO()
+    wb.save(output)
+    output.seek(0)
+    return output.read()
+
+
+def generate_csv(data: List[Dict[str, Any]]) -> bytes:
+    """
+    生成 CSV 文件.
+
+    Args:
+        data: 数据列表
+
+    Returns:
+        CSV 文件的字节内容 (UTF-8 BOM 编码)
+    """
+    output = StringIO()
+    writer = csv.writer(output, quoting=csv.QUOTE_MINIMAL)
+
+    # 写入表头
+    headers = [col[0] for col in COLUMN_HEADERS]
+    writer.writerow(headers)
+
+    # 写入数据
+    for row in data:
+        row_data = [format_value(row.get(col[1])) for col in COLUMN_HEADERS]
+        writer.writerow(row_data)
+
+    # 返回 UTF-8 BOM 编码的内容 (Excel 可正确识别中文)
+    content = output.getvalue()
+    return ("\ufeff" + content).encode("utf-8")
--- a/backend/app/services/query_service.py
+++ b/backend/app/services/query_service.py
@ -0,0 +1,42 @@
+from typing import List, Literal
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import KolVideo
+from app.config import settings
+
+
+async def query_videos(
+    session: AsyncSession,
+    query_type: Literal["star_id", "unique_id", "nickname"],
+    values: List[str],
+) -> List[KolVideo]:
+    """
+    查询 KOL 视频数据.
+
+    Args:
+        session: 数据库会话
+        query_type: 查询类型 (star_id, unique_id, nickname)
+        values: 查询值列表
+
+    Returns:
+        匹配的视频列表
+    """
+    stmt = select(KolVideo)
+
+    if query_type == "star_id":
+        # 精准匹配 star_id
+        stmt = stmt.where(KolVideo.star_id.in_(values))
+    elif query_type == "unique_id":
+        # 精准匹配 star_unique_id
+        stmt = stmt.where(KolVideo.star_unique_id.in_(values))
+    elif query_type == "nickname":
+        # 模糊匹配 star_nickname (使用第一个值)
+        if values:
+            stmt = stmt.where(KolVideo.star_nickname.like(f"%{values[0]}%"))
+
+    # 限制返回数量
+    stmt = stmt.limit(settings.MAX_QUERY_LIMIT)
+
+    result = await session.execute(stmt)
+    return list(result.scalars().all())
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@ -1,8 +1,9 @@
 import pytest
 from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker

-from app.database import Base
+from app.database import Base, get_db
 from app.models import KolVideo
+from app.main import app


@pytest.fixture
@ -47,12 +48,29 @@ async def test_engine():


@pytest.fixture
-async def test_session(test_engine):
-    """Create a test database session."""
-    async_session = async_sessionmaker(
+async def async_session_factory(test_engine):
+    """Create async session factory."""
+    return async_sessionmaker(
        test_engine,
        class_=AsyncSession,
        expire_on_commit=False,
    )
-    async with async_session() as session:
+
+
+@pytest.fixture
+async def test_session(async_session_factory):
+    """Create a test database session."""
+    async with async_session_factory() as session:
        yield session
+
+
+@pytest.fixture
+async def override_get_db(async_session_factory):
+    """Override get_db dependency for testing."""
+    async def _get_db():
+        async with async_session_factory() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
--- a/backend/tests/test_brand_api.py
+++ b/backend/tests/test_brand_api.py
@ -0,0 +1,117 @@
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, patch
+import httpx
+
+from app.services.brand_api import get_brand_names, fetch_brand_name
+
+
+class TestBrandAPI:
+    """Tests for Brand API integration."""
+
+    async def test_get_brand_names_success(self):
+        """Test successful brand name fetching."""
+        with patch("app.services.brand_api.fetch_brand_name") as mock_fetch:
+            mock_fetch.side_effect = [
+                ("brand_001", "品牌A"),
+                ("brand_002", "品牌B"),
+            ]
+
+            result = await get_brand_names(["brand_001", "brand_002"])
+
+            assert result["brand_001"] == "品牌A"
+            assert result["brand_002"] == "品牌B"
+
+    async def test_get_brand_names_empty_list(self):
+        """Test with empty brand ID list."""
+        result = await get_brand_names([])
+        assert result == {}
+
+    async def test_get_brand_names_with_none_values(self):
+        """Test filtering out None values."""
+        with patch("app.services.brand_api.fetch_brand_name") as mock_fetch:
+            mock_fetch.return_value = ("brand_001", "品牌A")
+
+            result = await get_brand_names(["brand_001", None, ""])
+
+            assert "brand_001" in result
+            assert len(result) == 1
+
+    async def test_get_brand_names_deduplication(self):
+        """Test that duplicate brand IDs are deduplicated."""
+        with patch("app.services.brand_api.fetch_brand_name") as mock_fetch:
+            mock_fetch.return_value = ("brand_001", "品牌A")
+
+            result = await get_brand_names(["brand_001", "brand_001", "brand_001"])
+
+            # Should only call once due to deduplication
+            assert mock_fetch.call_count == 1
+
+    async def test_get_brand_names_partial_failure(self):
+        """Test that partial failures don't break the whole batch."""
+        with patch("app.services.brand_api.fetch_brand_name") as mock_fetch:
+            mock_fetch.side_effect = [
+                ("brand_001", "品牌A"),
+                ("brand_002", "brand_002"),  # Fallback to ID
+                ("brand_003", "品牌C"),
+            ]
+
+            result = await get_brand_names(["brand_001", "brand_002", "brand_003"])
+
+            assert result["brand_001"] == "品牌A"
+            assert result["brand_002"] == "brand_002"  # Fallback
+            assert result["brand_003"] == "品牌C"
+
+    async def test_fetch_brand_name_success(self):
+        """Test successful single brand fetch via get_brand_names."""
+        # 使用更高层的 mock，测试整个流程
+        with patch("app.services.brand_api.fetch_brand_name") as mock_fetch:
+            mock_fetch.return_value = ("test_id", "测试品牌")
+
+            result = await get_brand_names(["test_id"])
+
+            assert result["test_id"] == "测试品牌"
+
+    async def test_fetch_brand_name_failure(self):
+        """Test brand fetch failure returns ID as fallback."""
+        mock_client = AsyncMock()
+        mock_client.get.side_effect = httpx.TimeoutException("Timeout")
+        mock_client.__aenter__.return_value = mock_client
+        mock_client.__aexit__.return_value = None
+
+        with patch("httpx.AsyncClient", return_value=mock_client):
+            semaphore = asyncio.Semaphore(10)
+            brand_id, brand_name = await fetch_brand_name("test_id", semaphore)
+
+            assert brand_id == "test_id"
+            assert brand_name == "test_id"  # Fallback to ID
+
+    async def test_fetch_brand_name_404(self):
+        """Test brand fetch with 404 returns ID as fallback."""
+        mock_response = AsyncMock()
+        mock_response.status_code = 404
+
+        mock_client = AsyncMock()
+        mock_client.get.return_value = mock_response
+        mock_client.__aenter__.return_value = mock_client
+        mock_client.__aexit__.return_value = None
+
+        with patch("httpx.AsyncClient", return_value=mock_client):
+            semaphore = asyncio.Semaphore(10)
+            brand_id, brand_name = await fetch_brand_name("nonexistent", semaphore)
+
+            assert brand_id == "nonexistent"
+            assert brand_name == "nonexistent"
+
+    async def test_concurrency_limit(self):
+        """Test that concurrency is limited."""
+        with patch("app.services.brand_api.fetch_brand_name") as mock_fetch:
+            # 创建 15 个品牌 ID
+            brand_ids = [f"brand_{i:03d}" for i in range(15)]
+            mock_fetch.side_effect = [(id, f"名称_{id}") for id in brand_ids]
+
+            result = await get_brand_names(brand_ids)
+
+            assert len(result) == 15
+            # 验证所有调用都完成了
+            assert mock_fetch.call_count == 15
--- a/backend/tests/test_calculator.py
+++ b/backend/tests/test_calculator.py
@ -0,0 +1,99 @@
+import pytest
+from app.services.calculator import (
+    calculate_natural_cpm,
+    calculate_natural_search_uv,
+    calculate_natural_search_cost,
+    calculate_metrics,
+)
+
+
+class TestCalculator:
+    """Tests for calculator functions."""
+
+    def test_calculate_natural_cpm_normal(self):
+        """Test normal CPM calculation."""
+        result = calculate_natural_cpm(10000.0, 100000)
+        assert result == 100.0  # 10000 / 100000 * 1000 = 100
+
+    def test_calculate_natural_cpm_zero_play(self):
+        """Test CPM with zero plays returns None."""
+        result = calculate_natural_cpm(10000.0, 0)
+        assert result is None
+
+    def test_calculate_natural_cpm_decimal(self):
+        """Test CPM returns 2 decimal places."""
+        result = calculate_natural_cpm(1234.56, 50000)
+        assert result == 24.69  # round(1234.56 / 50000 * 1000, 2)
+
+    def test_calculate_natural_search_uv_normal(self):
+        """Test normal search UV calculation."""
+        result = calculate_natural_search_uv(100000, 150000, 500)
+        expected = round((100000 / 150000) * 500, 2)
+        assert result == expected
+
+    def test_calculate_natural_search_uv_zero_total(self):
+        """Test search UV with zero total plays returns None."""
+        result = calculate_natural_search_uv(100000, 0, 500)
+        assert result is None
+
+    def test_calculate_natural_search_uv_zero_natural(self):
+        """Test search UV with zero natural plays."""
+        result = calculate_natural_search_uv(0, 150000, 500)
+        assert result == 0.0
+
+    def test_calculate_natural_search_cost_normal(self):
+        """Test normal search cost calculation."""
+        result = calculate_natural_search_cost(10000.0, 333.33)
+        assert result == 30.0  # round(10000 / 333.33, 2)
+
+    def test_calculate_natural_search_cost_zero_uv(self):
+        """Test search cost with zero UV returns None."""
+        result = calculate_natural_search_cost(10000.0, 0)
+        assert result is None
+
+    def test_calculate_natural_search_cost_none_uv(self):
+        """Test search cost with None UV returns None."""
+        result = calculate_natural_search_cost(10000.0, None)
+        assert result is None
+
+    def test_calculate_metrics_all_normal(self):
+        """Test calculate_metrics with all normal values."""
+        result = calculate_metrics(
+            estimated_video_cost=10000.0,
+            natural_play_cnt=100000,
+            total_play_cnt=150000,
+            after_view_search_uv=500,
+        )
+
+        assert result["estimated_natural_cpm"] == 100.0
+        assert result["estimated_natural_search_uv"] == round((100000 / 150000) * 500, 2)
+        expected_cost = round(10000.0 / result["estimated_natural_search_uv"], 2)
+        assert result["estimated_natural_search_cost"] == expected_cost
+
+    def test_calculate_metrics_zero_plays(self):
+        """Test calculate_metrics with zero plays."""
+        result = calculate_metrics(
+            estimated_video_cost=10000.0,
+            natural_play_cnt=0,
+            total_play_cnt=0,
+            after_view_search_uv=500,
+        )
+
+        assert result["estimated_natural_cpm"] is None
+        assert result["estimated_natural_search_uv"] is None
+        assert result["estimated_natural_search_cost"] is None
+
+    def test_calculate_metrics_partial_zero(self):
+        """Test calculate_metrics with partial zero values."""
+        result = calculate_metrics(
+            estimated_video_cost=10000.0,
+            natural_play_cnt=100000,
+            total_play_cnt=0,  # Zero total plays
+            after_view_search_uv=500,
+        )
+
+        # CPM can still be calculated
+        assert result["estimated_natural_cpm"] == 100.0
+        # But search UV and cost cannot
+        assert result["estimated_natural_search_uv"] is None
+        assert result["estimated_natural_search_cost"] is None
--- a/backend/tests/test_export_api.py
+++ b/backend/tests/test_export_api.py
@ -0,0 +1,169 @@
+import pytest
+from io import BytesIO
+from openpyxl import load_workbook
+
+from app.services.export_service import generate_excel, generate_csv, COLUMN_HEADERS
+
+
+class TestExportService:
+    """Tests for Export Service."""
+
+    @pytest.fixture
+    def sample_export_data(self):
+        """Sample data for export testing."""
+        return [
+            {
+                "item_id": "item_001",
+                "title": "测试视频1",
+                "viral_type": "爆款",
+                "video_url": "https://example.com/1",
+                "star_id": "star_001",
+                "star_unique_id": "unique_001",
+                "star_nickname": "测试达人1",
+                "publish_time": "2026-01-28T10:00:00",
+                "natural_play_cnt": 100000,
+                "heated_play_cnt": 50000,
+                "total_play_cnt": 150000,
+                "total_interact": 5000,
+                "like_cnt": 3000,
+                "share_cnt": 1000,
+                "comment_cnt": 1000,
+                "new_a3_rate": 0.05,
+                "after_view_search_uv": 500,
+                "return_search_cnt": 200,
+                "industry_id": "ind_001",
+                "industry_name": "美妆",
+                "brand_id": "brand_001",
+                "brand_name": "测试品牌",
+                "estimated_video_cost": 10000.0,
+                "estimated_natural_cpm": 100.0,
+                "estimated_natural_search_uv": 333.33,
+                "estimated_natural_search_cost": 30.0,
+            }
+        ]
+
+    def test_generate_excel_success(self, sample_export_data):
+        """Test Excel generation."""
+        content = generate_excel(sample_export_data)
+
+        assert content is not None
+        assert len(content) > 0
+
+        # 验证可以被 openpyxl 读取
+        wb = load_workbook(BytesIO(content))
+        ws = wb.active
+
+        # 验证表头
+        assert ws.cell(row=1, column=1).value == "视频ID"
+        assert ws.cell(row=1, column=2).value == "视频标题"
+
+        # 验证数据行
+        assert ws.cell(row=2, column=1).value == "item_001"
+        assert ws.cell(row=2, column=2).value == "测试视频1"
+
+    def test_generate_excel_empty_data(self):
+        """Test Excel generation with empty data."""
+        content = generate_excel([])
+
+        assert content is not None
+        wb = load_workbook(BytesIO(content))
+        ws = wb.active
+
+        # 应该只有表头
+        assert ws.max_row == 1
+
+    def test_generate_csv_success(self, sample_export_data):
+        """Test CSV generation."""
+        content = generate_csv(sample_export_data)
+
+        assert content is not None
+        assert len(content) > 0
+
+        # 验证 CSV 内容
+        lines = content.decode("utf-8-sig").split("\n")
+        assert len(lines) >= 2  # 表头 + 至少一行数据
+
+        # 验证表头
+        assert "视频ID" in lines[0]
+        assert "视频标题" in lines[0]
+
+    def test_generate_csv_empty_data(self):
+        """Test CSV generation with empty data."""
+        content = generate_csv([])
+
+        assert content is not None
+        lines = content.decode("utf-8-sig").split("\n")
+
+        # 应该只有表头
+        assert len(lines) == 2  # 表头 + 空行
+
+    def test_generate_csv_comma_escape(self):
+        """Test CSV properly escapes commas."""
+        data = [
+            {
+                "item_id": "item_001",
+                "title": "标题,包含,逗号",
+                "viral_type": None,
+                "video_url": None,
+                "star_id": "star_001",
+                "star_unique_id": "unique_001",
+                "star_nickname": "测试达人",
+                "publish_time": None,
+                "natural_play_cnt": 0,
+                "heated_play_cnt": 0,
+                "total_play_cnt": 0,
+                "total_interact": 0,
+                "like_cnt": 0,
+                "share_cnt": 0,
+                "comment_cnt": 0,
+                "new_a3_rate": None,
+                "after_view_search_uv": 0,
+                "return_search_cnt": 0,
+                "industry_id": None,
+                "industry_name": None,
+                "brand_id": None,
+                "brand_name": None,
+                "estimated_video_cost": 0,
+                "estimated_natural_cpm": None,
+                "estimated_natural_search_uv": None,
+                "estimated_natural_search_cost": None,
+            }
+        ]
+        content = generate_csv(data)
+        csv_text = content.decode("utf-8-sig")
+
+        # 包含逗号的字段应该被引号包裹
+        assert '"标题,包含,逗号"' in csv_text
+
+    def test_column_headers_complete(self):
+        """Test that all required columns are defined."""
+        expected_columns = [
+            "视频ID",
+            "视频标题",
+            "爆文类型",
+            "视频链接",
+            "新增A3率",
+            "看后搜人数",
+            "回搜次数",
+            "自然曝光数",
+            "加热曝光数",
+            "总曝光数",
+            "总互动",
+            "点赞",
+            "转发",
+            "评论",
+            "合作行业ID",
+            "合作行业",
+            "合作品牌ID",
+            "合作品牌",
+            "发布时间",
+            "达人昵称",
+            "达人unique_id",
+            "预估视频价格",
+            "预估自然CPM",
+            "预估自然看后搜人数",
+            "预估自然看后搜人数成本",
+        ]
+
+        for col in expected_columns:
+            assert col in [h[0] for h in COLUMN_HEADERS], f"Missing column: {col}"
--- a/backend/tests/test_query_api.py
+++ b/backend/tests/test_query_api.py
@ -0,0 +1,139 @@
+import pytest
+from httpx import AsyncClient, ASGITransport
+from unittest.mock import patch, AsyncMock
+
+from app.main import app
+from app.models import KolVideo
+from app.database import get_db
+
+
+class TestQueryAPI:
+    """Tests for Query API."""
+
+    @pytest.fixture
+    async def client(self, override_get_db):
+        """Create test client with dependency override."""
+        transport = ASGITransport(app=app)
+        async with AsyncClient(transport=transport, base_url="http://test") as ac:
+            yield ac
+
+    @pytest.fixture
+    async def seed_data(self, test_session, sample_video_data):
+        """Seed test data."""
+        videos = []
+        for i in range(3):
+            data = sample_video_data.copy()
+            data["item_id"] = f"item_{i:03d}"
+            data["star_id"] = f"star_{i:03d}"
+            data["star_unique_id"] = f"unique_{i:03d}"
+            data["star_nickname"] = f"测试达人{i}"
+            videos.append(KolVideo(**data))
+        test_session.add_all(videos)
+        await test_session.commit()
+        return videos
+
+    @patch("app.api.v1.query.get_brand_names", new_callable=AsyncMock)
+    async def test_query_by_star_id_success(
+        self, mock_brand, client, test_session, seed_data
+    ):
+        """Test querying by star_id returns correct results."""
+        mock_brand.return_value = {}
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "star_id", "values": ["star_000", "star_001"]},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["success"] is True
+        assert data["total"] == 2
+
+    @patch("app.api.v1.query.get_brand_names", new_callable=AsyncMock)
+    async def test_query_by_unique_id_success(
+        self, mock_brand, client, test_session, seed_data
+    ):
+        """Test querying by unique_id returns correct results."""
+        mock_brand.return_value = {}
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "unique_id", "values": ["unique_000"]},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["success"] is True
+        assert data["total"] == 1
+
+    @patch("app.api.v1.query.get_brand_names", new_callable=AsyncMock)
+    async def test_query_by_nickname_like(
+        self, mock_brand, client, test_session, seed_data
+    ):
+        """Test querying by nickname using fuzzy match."""
+        mock_brand.return_value = {}
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "nickname", "values": ["测试达人"]},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["success"] is True
+        assert data["total"] == 3  # 所有包含 "测试达人" 的记录
+
+    async def test_query_empty_values(self, client):
+        """Test querying with empty values returns error."""
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "star_id", "values": []},
+        )
+        assert response.status_code == 422  # Validation error
+
+    async def test_query_invalid_type(self, client):
+        """Test querying with invalid type returns error."""
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "invalid_type", "values": ["test"]},
+        )
+        assert response.status_code == 422
+
+    @patch("app.api.v1.query.get_brand_names", new_callable=AsyncMock)
+    async def test_query_no_results(self, mock_brand, client, test_session, seed_data):
+        """Test querying with no matching results."""
+        mock_brand.return_value = {}
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "star_id", "values": ["nonexistent_id"]},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["success"] is True
+        assert data["total"] == 0
+        assert data["data"] == []
+
+    @patch("app.api.v1.query.get_brand_names", new_callable=AsyncMock)
+    async def test_query_limit_enforcement(self, mock_brand, client, test_session):
+        """Test that query limit is enforced."""
+        mock_brand.return_value = {}
+        # 创建超过 1000 条记录的情况在测试中略过
+        # 这里只测试 API 能正常工作
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "star_id", "values": ["star_000"]},
+        )
+        assert response.status_code == 200
+
+    @patch("app.api.v1.query.get_brand_names", new_callable=AsyncMock)
+    async def test_query_returns_calculated_fields(
+        self, mock_brand, client, test_session, seed_data
+    ):
+        """Test that calculated fields are returned."""
+        mock_brand.return_value = {}
+        response = await client.post(
+            "/api/v1/query",
+            json={"type": "star_id", "values": ["star_000"]},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        if data["total"] > 0:
+            video = data["data"][0]
+            # 检查计算字段存在
+            assert "estimated_natural_cpm" in video
+            assert "estimated_natural_search_uv" in video
+            assert "estimated_natural_search_cost" in video
--- a/frontend/src/app/page.tsx
+++ b/frontend/src/app/page.tsx
@ -1,101 +1,111 @@
-import Image from "next/image";
+'use client';
+
+import { useState } from 'react';
+import { QueryForm, ResultTable, ExportButton } from '@/components';
+import { QueryType, VideoData, PageState } from '@/types';
+import { queryVideos } from '@/lib/api';

 export default function Home() {
-  return (
-    <div className="grid grid-rows-[20px_1fr_20px] items-center justify-items-center min-h-screen p-8 pb-20 gap-16 sm:p-20 font-[family-name:var(--font-geist-sans)]">
-      <main className="flex flex-col gap-8 row-start-2 items-center sm:items-start">
-        <Image
-          className="dark:invert"
-          src="https://nextjs.org/icons/next.svg"
-          alt="Next.js logo"
-          width={180}
-          height={38}
-          priority
-        />
-        <ol className="list-inside list-decimal text-sm text-center sm:text-left font-[family-name:var(--font-geist-mono)]">
-          <li className="mb-2">
-            Get started by editing{" "}
-            <code className="bg-black/[.05] dark:bg-white/[.06] px-1 py-0.5 rounded font-semibold">
-              src/app/page.tsx
-            </code>
-            .
-          </li>
-          <li>Save and see your changes instantly.</li>
-        </ol>
+  const [pageState, setPageState] = useState<PageState>('default');
+  const [data, setData] = useState<VideoData[]>([]);
+  const [total, setTotal] = useState(0);
+  const [error, setError] = useState<string | null>(null);

-        <div className="flex gap-4 items-center flex-col sm:flex-row">
-          <a
-            className="rounded-full border border-solid border-transparent transition-colors flex items-center justify-center bg-foreground text-background gap-2 hover:bg-[#383838] dark:hover:bg-[#ccc] text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5"
-            href="https://vercel.com/new?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <Image
-              className="dark:invert"
-              src="https://nextjs.org/icons/vercel.svg"
-              alt="Vercel logomark"
-              width={20}
-              height={20}
-            />
-            Deploy now
-          </a>
-          <a
-            className="rounded-full border border-solid border-black/[.08] dark:border-white/[.145] transition-colors flex items-center justify-center hover:bg-[#f2f2f2] dark:hover:bg-[#1a1a1a] hover:border-transparent text-sm sm:text-base h-10 sm:h-12 px-4 sm:px-5 sm:min-w-44"
-            href="https://nextjs.org/docs?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            Read our docs
-          </a>
-        </div>
-      </main>
-      <footer className="row-start-3 flex gap-6 flex-wrap items-center justify-center">
-        <a
-          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
-          href="https://nextjs.org/learn?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="https://nextjs.org/icons/file.svg"
-            alt="File icon"
-            width={16}
-            height={16}
-          />
-          Learn
-        </a>
-        <a
-          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
-          href="https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="https://nextjs.org/icons/window.svg"
-            alt="Window icon"
-            width={16}
-            height={16}
-          />
-          Examples
-        </a>
-        <a
-          className="flex items-center gap-2 hover:underline hover:underline-offset-4"
-          href="https://nextjs.org?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          <Image
-            aria-hidden
-            src="https://nextjs.org/icons/globe.svg"
-            alt="Globe icon"
-            width={16}
-            height={16}
-          />
-          Go to nextjs.org →
-        </a>
-      </footer>
+  const handleQuery = async (type: QueryType, values: string[]) => {
+    setPageState('loading');
+    setError(null);
+
+    try {
+      const response = await queryVideos({ type, values });
+
+      if (response.success) {
+        setData(response.data);
+        setTotal(response.total);
+        setPageState(response.total > 0 ? 'result' : 'empty');
+      } else {
+        setError(response.error || '查询失败');
+        setPageState('error');
+      }
+    } catch (err) {
+      console.error('Query error:', err);
+      setError(err instanceof Error ? err.message : '网络错误，请检查后端服务是否正常');
+      setPageState('error');
+    }
+  };
+
+  const handleRetry = () => {
+    setPageState('default');
+    setError(null);
+    setData([]);
+    setTotal(0);
+  };
+
+  return (
+    <div className="max-w-7xl mx-auto px-4 py-8">
+      {/* 查询区域 */}
+      <section className="mb-8">
+        <QueryForm onSubmit={handleQuery} isLoading={pageState === 'loading'} />
+      </section>
+
+      {/* 结果区域 */}
+      <section>
+        {/* 默认态 */}
+        {pageState === 'default' && (
+          <div className="bg-white rounded-lg shadow-sm p-12 text-center">
+            <div className="text-gray-400 text-6xl mb-4">🔍</div>
+            <p className="text-gray-500">请选择查询方式并输入查询条件</p>
+          </div>
+        )}
+
+        {/* 加载态 */}
+        {pageState === 'loading' && (
+          <div className="bg-white rounded-lg shadow-sm p-12 text-center">
+            <div className="animate-spin text-primary text-4xl mb-4">⟳</div>
+            <p className="text-gray-500">正在查询数据，请稍候...</p>
+          </div>
+        )}
+
+        {/* 结果态 */}
+        {pageState === 'result' && (
+          <div>
+            <div className="flex justify-between items-center mb-4">
+              <h2 className="text-lg font-medium text-gray-900">查询结果</h2>
+              <ExportButton hasData={total > 0} />
+            </div>
+            <ResultTable data={data} total={total} />
+          </div>
+        )}
+
+        {/* 空结果态 */}
+        {pageState === 'empty' && (
+          <div className="bg-white rounded-lg shadow-sm p-12 text-center">
+            <div className="text-gray-400 text-6xl mb-4">📦</div>
+            <p className="text-gray-700 mb-2">未找到匹配数据</p>
+            <p className="text-gray-500 text-sm mb-4">请调整查询条件后重新尝试</p>
+            <button
+              onClick={handleRetry}
+              className="px-4 py-2 text-sm font-medium text-primary border border-primary rounded hover:bg-primary hover:text-white"
+            >
+              修改查询条件
+            </button>
+          </div>
+        )}
+
+        {/* 错误态 */}
+        {pageState === 'error' && (
+          <div className="bg-white rounded-lg shadow-sm p-12 text-center">
+            <div className="text-error text-6xl mb-4">⚠</div>
+            <p className="text-gray-700 mb-2">查询失败，请重试</p>
+            <p className="text-gray-500 text-sm mb-4">{error || '可能原因：网络异常或数据库连接失败'}</p>
+            <button
+              onClick={handleRetry}
+              className="px-4 py-2 text-sm font-medium text-white bg-primary rounded hover:bg-primary-dark"
+            >
+              重新查询
+            </button>
+          </div>
+        )}
+      </section>
    </div>
  );
 }
--- a/frontend/src/components/ExportButton.tsx
+++ b/frontend/src/components/ExportButton.tsx
@ -0,0 +1,63 @@
+'use client';
+
+import { useState } from 'react';
+
+interface ExportButtonProps {
+  hasData: boolean;
+}
+
+const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api/v1';
+
+export default function ExportButton({ hasData }: ExportButtonProps) {
+  const [isExporting, setIsExporting] = useState(false);
+
+  const handleExport = async (format: 'xlsx' | 'csv') => {
+    if (!hasData) {
+      alert('无数据可导出');
+      return;
+    }
+
+    setIsExporting(true);
+    try {
+      const response = await fetch(`${API_BASE_URL}/export?format=${format}`);
+
+      if (!response.ok) {
+        throw new Error('导出失败');
+      }
+
+      const blob = await response.blob();
+      const url = window.URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `kol_data_${new Date().toISOString().slice(0, 10)}.${format}`;
+      document.body.appendChild(a);
+      a.click();
+      window.URL.revokeObjectURL(url);
+      document.body.removeChild(a);
+    } catch (error) {
+      console.error('Export error:', error);
+      alert('导出失败，请重试');
+    } finally {
+      setIsExporting(false);
+    }
+  };
+
+  return (
+    <div className="flex gap-2">
+      <button
+        onClick={() => handleExport('xlsx')}
+        disabled={!hasData || isExporting}
+        className="px-3 py-1.5 text-sm font-medium text-white bg-success rounded hover:bg-green-600 disabled:opacity-50 disabled:cursor-not-allowed"
+      >
+        {isExporting ? '导出中...' : '导出 Excel'}
+      </button>
+      <button
+        onClick={() => handleExport('csv')}
+        disabled={!hasData || isExporting}
+        className="px-3 py-1.5 text-sm font-medium text-white bg-success rounded hover:bg-green-600 disabled:opacity-50 disabled:cursor-not-allowed"
+      >
+        {isExporting ? '导出中...' : '导出 CSV'}
+      </button>
+    </div>
+  );
+}
--- a/frontend/src/components/QueryForm.tsx
+++ b/frontend/src/components/QueryForm.tsx
@ -0,0 +1,81 @@
+'use client';
+
+import { useState } from 'react';
+import { QueryType, QUERY_TYPE_OPTIONS, QUERY_PLACEHOLDER } from '@/types';
+
+interface QueryFormProps {
+  onSubmit: (type: QueryType, values: string[]) => void;
+  isLoading: boolean;
+}
+
+export default function QueryForm({ onSubmit, isLoading }: QueryFormProps) {
+  const [queryType, setQueryType] = useState<QueryType>('star_id');
+  const [inputValue, setInputValue] = useState('');
+
+  const handleSubmit = () => {
+    const values = inputValue
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+
+    if (values.length === 0) {
+      return;
+    }
+
+    onSubmit(queryType, values);
+  };
+
+  const handleClear = () => {
+    setInputValue('');
+  };
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm p-6">
+      <div className="mb-4">
+        <label className="block text-sm font-medium text-gray-700 mb-2">查询方式</label>
+        <div className="flex gap-4">
+          {QUERY_TYPE_OPTIONS.map((option) => (
+            <label key={option.value} className="flex items-center cursor-pointer">
+              <input
+                type="radio"
+                name="queryType"
+                value={option.value}
+                checked={queryType === option.value}
+                onChange={(e) => setQueryType(e.target.value as QueryType)}
+                className="w-4 h-4 text-primary border-gray-300 focus:ring-primary"
+              />
+              <span className="ml-2 text-sm text-gray-700">{option.label}</span>
+            </label>
+          ))}
+        </div>
+      </div>
+
+      <div className="mb-4">
+        <textarea
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          placeholder={QUERY_PLACEHOLDER[queryType]}
+          className="w-full h-32 px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent resize-none"
+          disabled={isLoading}
+        />
+      </div>
+
+      <div className="flex justify-end gap-2">
+        <button
+          onClick={handleClear}
+          disabled={isLoading || !inputValue}
+          className="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          清空
+        </button>
+        <button
+          onClick={handleSubmit}
+          disabled={isLoading || !inputValue.trim()}
+          className="px-4 py-2 text-sm font-medium text-white bg-primary rounded-md hover:bg-primary-dark disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {isLoading ? '查询中...' : '开始查询'}
+        </button>
+      </div>
+    </div>
+  );
+}
--- a/frontend/src/components/ResultTable.tsx
+++ b/frontend/src/components/ResultTable.tsx
@ -0,0 +1,195 @@
+'use client';
+
+import { useState } from 'react';
+import { VideoData } from '@/types';
+import { formatNumber, formatLargeNumber, formatPercent, formatCurrency, formatDate } from '@/lib/utils';
+
+interface ResultTableProps {
+  data: VideoData[];
+  total: number;
+}
+
+// 表格列定义
+const columns = [
+  { key: 'item_id', label: '视频ID', width: 120 },
+  { key: 'title', label: '视频标题', width: 200 },
+  { key: 'viral_type', label: '爆文类型', width: 100 },
+  { key: 'video_url', label: '视频链接', width: 100 },
+  { key: 'star_nickname', label: '达人昵称', width: 120 },
+  { key: 'star_unique_id', label: '达人unique_id', width: 150 },
+  { key: 'natural_play_cnt', label: '自然曝光数', width: 120 },
+  { key: 'heated_play_cnt', label: '加热曝光数', width: 120 },
+  { key: 'total_play_cnt', label: '总曝光数', width: 120 },
+  { key: 'total_interact', label: '总互动', width: 100 },
+  { key: 'like_cnt', label: '点赞', width: 100 },
+  { key: 'share_cnt', label: '转发', width: 100 },
+  { key: 'comment_cnt', label: '评论', width: 100 },
+  { key: 'new_a3_rate', label: '新增A3率', width: 100 },
+  { key: 'after_view_search_uv', label: '看后搜人数', width: 120 },
+  { key: 'return_search_cnt', label: '回搜次数', width: 100 },
+  { key: 'industry_name', label: '合作行业', width: 120 },
+  { key: 'brand_name', label: '合作品牌', width: 150 },
+  { key: 'publish_time', label: '发布时间', width: 120 },
+  { key: 'estimated_video_cost', label: '预估视频价格', width: 120 },
+  { key: 'estimated_natural_cpm', label: '预估自然CPM', width: 120 },
+  { key: 'estimated_natural_search_uv', label: '预估自然看后搜人数', width: 150 },
+  { key: 'estimated_natural_search_cost', label: '预估看后搜成本', width: 150 },
+];
+
+const PAGE_SIZE = 20;
+
+export default function ResultTable({ data, total }: ResultTableProps) {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [sortKey, setSortKey] = useState<string | null>(null);
+  const [sortOrder, setSortOrder] = useState<'asc' | 'desc'>('desc');
+
+  // 排序
+  const sortedData = [...data].sort((a, b) => {
+    if (!sortKey) return 0;
+    const aVal = a[sortKey as keyof VideoData];
+    const bVal = b[sortKey as keyof VideoData];
+    if (aVal === null || aVal === undefined) return 1;
+    if (bVal === null || bVal === undefined) return -1;
+    if (typeof aVal === 'number' && typeof bVal === 'number') {
+      return sortOrder === 'asc' ? aVal - bVal : bVal - aVal;
+    }
+    return sortOrder === 'asc'
+      ? String(aVal).localeCompare(String(bVal))
+      : String(bVal).localeCompare(String(aVal));
+  });
+
+  // 分页
+  const totalPages = Math.ceil(sortedData.length / PAGE_SIZE);
+  const paginatedData = sortedData.slice(
+    (currentPage - 1) * PAGE_SIZE,
+    currentPage * PAGE_SIZE
+  );
+
+  const handleSort = (key: string) => {
+    if (sortKey === key) {
+      setSortOrder(sortOrder === 'asc' ? 'desc' : 'asc');
+    } else {
+      setSortKey(key);
+      setSortOrder('desc');
+    }
+  };
+
+  const renderCell = (row: VideoData, key: string) => {
+    const value = row[key as keyof VideoData];
+
+    switch (key) {
+      case 'video_url':
+        return value ? (
+          <a
+            href={value as string}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-primary hover:underline"
+          >
+            查看
+          </a>
+        ) : (
+          '-'
+        );
+      case 'natural_play_cnt':
+      case 'heated_play_cnt':
+      case 'total_play_cnt':
+        return formatLargeNumber(value as number);
+      case 'total_interact':
+      case 'like_cnt':
+      case 'share_cnt':
+      case 'comment_cnt':
+      case 'after_view_search_uv':
+      case 'return_search_cnt':
+        return formatNumber(value as number);
+      case 'new_a3_rate':
+        return formatPercent(value as number);
+      case 'estimated_video_cost':
+      case 'estimated_natural_search_cost':
+        return formatCurrency(value as number);
+      case 'estimated_natural_cpm':
+      case 'estimated_natural_search_uv':
+        return value !== null && value !== undefined ? (value as number).toFixed(2) : '-';
+      case 'publish_time':
+        return formatDate(value as string);
+      case 'title':
+        const title = value as string;
+        return title && title.length > 20 ? (
+          <span title={title}>{title.slice(0, 20)}...</span>
+        ) : (
+          title || '-'
+        );
+      default:
+        return value !== null && value !== undefined ? String(value) : '-';
+    }
+  };
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm">
+      <div className="p-4 border-b border-gray-200 flex justify-between items-center">
+        <span className="text-sm text-gray-600">查询结果 (共 {total} 条)</span>
+      </div>
+
+      <div className="overflow-x-auto">
+        <table className="min-w-full divide-y divide-gray-200">
+          <thead className="bg-gray-50">
+            <tr>
+              {columns.map((col) => (
+                <th
+                  key={col.key}
+                  onClick={() => handleSort(col.key)}
+                  className="px-3 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer hover:bg-gray-100"
+                  style={{ minWidth: col.width }}
+                >
+                  <div className="flex items-center gap-1">
+                    {col.label}
+                    {sortKey === col.key && (
+                      <span>{sortOrder === 'asc' ? '↑' : '↓'}</span>
+                    )}
+                  </div>
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody className="bg-white divide-y divide-gray-200">
+            {paginatedData.map((row, idx) => (
+              <tr key={row.item_id} className={idx % 2 === 0 ? 'bg-white' : 'bg-gray-50'}>
+                {columns.map((col) => (
+                  <td
+                    key={col.key}
+                    className="px-3 py-2 text-sm text-gray-900 whitespace-nowrap"
+                  >
+                    {renderCell(row, col.key)}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {/* 分页 */}
+      {totalPages > 1 && (
+        <div className="px-4 py-3 border-t border-gray-200 flex justify-center items-center gap-2">
+          <button
+            onClick={() => setCurrentPage((p) => Math.max(1, p - 1))}
+            disabled={currentPage === 1}
+            className="px-3 py-1 text-sm border border-gray-300 rounded hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            上一页
+          </button>
+          <span className="text-sm text-gray-600">
+            {currentPage} / {totalPages}
+          </span>
+          <button
+            onClick={() => setCurrentPage((p) => Math.min(totalPages, p + 1))}
+            disabled={currentPage === totalPages}
+            className="px-3 py-1 text-sm border border-gray-300 rounded hover:bg-gray-50 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            下一页
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
--- a/frontend/src/components/index.ts
+++ b/frontend/src/components/index.ts
@ -1,2 +1,5 @@
 export { default as Header } from './Header';
 export { default as Footer } from './Footer';
+export { default as QueryForm } from './QueryForm';
+export { default as ResultTable } from './ResultTable';
+export { default as ExportButton } from './ExportButton';
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@ -0,0 +1,29 @@
+import { QueryRequest, QueryResponse } from '@/types';
+
+const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api/v1';
+
+export async function queryVideos(request: QueryRequest): Promise<QueryResponse> {
+  const response = await fetch(`${API_BASE_URL}/query`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) {
+    throw new Error(`查询失败: ${response.statusText}`);
+  }
+
+  return response.json();
+}
+
+export async function exportData(format: 'xlsx' | 'csv'): Promise<Blob> {
+  const response = await fetch(`${API_BASE_URL}/export?format=${format}`);
+
+  if (!response.ok) {
+    throw new Error(`导出失败: ${response.statusText}`);
+  }
+
+  return response.blob();
+}
--- a/frontend/src/lib/utils.ts
+++ b/frontend/src/lib/utils.ts
@ -0,0 +1,70 @@
+/**
+ * 格式化数字为千分位分隔
+ */
+export function formatNumber(num: number | null | undefined): string {
+  if (num === null || num === undefined) {
+    return '-';
+  }
+  return num.toLocaleString('zh-CN');
+}
+
+/**
+ * 格式化大数值 (K/M 缩写)
+ */
+export function formatLargeNumber(num: number | null | undefined): string {
+  if (num === null || num === undefined) {
+    return '-';
+  }
+  if (num >= 1000000) {
+    return `${(num / 1000000).toFixed(1)}M`;
+  }
+  if (num >= 1000) {
+    return `${(num / 1000).toFixed(1)}K`;
+  }
+  return num.toString();
+}
+
+/**
+ * 格式化百分比
+ */
+export function formatPercent(num: number | null | undefined): string {
+  if (num === null || num === undefined) {
+    return '-';
+  }
+  return `${(num * 100).toFixed(2)}%`;
+}
+
+/**
+ * 格式化金额
+ */
+export function formatCurrency(num: number | null | undefined): string {
+  if (num === null || num === undefined) {
+    return '-';
+  }
+  return `¥${num.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+/**
+ * 格式化日期
+ */
+export function formatDate(dateStr: string | null | undefined): string {
+  if (!dateStr) {
+    return '-';
+  }
+  const date = new Date(dateStr);
+  return date.toLocaleDateString('zh-CN', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  });
+}
+
+/**
+ * 解析输入文本为数组 (按换行分隔)
+ */
+export function parseInputToArray(input: string): string[] {
+  return input
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@ -0,0 +1,63 @@
+// 查询类型
+export type QueryType = 'star_id' | 'unique_id' | 'nickname';
+
+// 查询请求
+export interface QueryRequest {
+  type: QueryType;
+  values: string[];
+}
+
+// 视频数据
+export interface VideoData {
+  item_id: string;
+  title: string | null;
+  viral_type: string | null;
+  video_url: string | null;
+  star_id: string;
+  star_unique_id: string;
+  star_nickname: string;
+  publish_time: string | null;
+  natural_play_cnt: number;
+  heated_play_cnt: number;
+  total_play_cnt: number;
+  total_interact: number;
+  like_cnt: number;
+  share_cnt: number;
+  comment_cnt: number;
+  new_a3_rate: number | null;
+  after_view_search_uv: number;
+  return_search_cnt: number;
+  industry_id: string | null;
+  industry_name: string | null;
+  brand_id: string | null;
+  brand_name: string | null;
+  estimated_video_cost: number;
+  estimated_natural_cpm: number | null;
+  estimated_natural_search_uv: number | null;
+  estimated_natural_search_cost: number | null;
+}
+
+// 查询响应
+export interface QueryResponse {
+  success: boolean;
+  data: VideoData[];
+  total: number;
+  error?: string;
+}
+
+// 页面状态
+export type PageState = 'default' | 'input' | 'loading' | 'result' | 'empty' | 'error';
+
+// 查询方式选项
+export const QUERY_TYPE_OPTIONS = [
+  { value: 'star_id' as QueryType, label: '星图ID' },
+  { value: 'unique_id' as QueryType, label: '达人unique_id' },
+  { value: 'nickname' as QueryType, label: '达人昵称' },
+];
+
+// 查询方式对应的提示文本
+export const QUERY_PLACEHOLDER: Record<QueryType, string> = {
+  star_id: '请输入星图ID，每行一个...',
+  unique_id: '请输入达人unique_id，每行一个...',
+  nickname: '请输入达人昵称关键词...',
+};