chore(backend): 迁移包管理工具从 pip 到 uv

- 新增 pyproject.toml 替代 requirements.txt，合并 pytest.ini 配置
- 添加 greenlet、httpx[socks] 依赖修复运行时错误
- 添加 basedpyright + ruff 开发工具及配置
- 更新 Dockerfile 使用 uv 安装依赖
- 更新 CLAUDE.md 所有后端命令为 uv 前缀
- 删除 requirements.txt 和 pytest.ini

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -15,6 +15,7 @@ KOL Insight 是一个 KOL（关键意见领袖）数据查询与分析工具，
 - **前端**: Next.js 14.x (App Router) + React + TypeScript + Tailwind CSS
 - **后端**: Python FastAPI 0.104+ + SQLAlchemy 2.0+ (异步 ORM) + asyncpg
 - **数据库**: PostgreSQL 14.x+
+- **包管理**: uv (pyproject.toml)
 - **部署**: Docker + Uvicorn (ASGI 服务器)
 
 ## 常用命令
@@ -44,28 +45,49 @@ pnpm type-check  # 如果配置了此脚本
 ### 后端开发
 
 ```bash
-# 安装依赖
+# 安装依赖（使用 uv）
-pip install -r requirements.txt
+uv sync
-# 或使用 Poetry
+
-poetry install
+# 仅安装生产依赖
+uv sync --no-dev
 
 # 开发模式运行（热重载）
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 # 生产模式运行
-uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
+uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
 
 # 运行测试（TDD 必须）
-pytest
+uv run pytest
 
 # 运行测试并生成覆盖率报告
-pytest --cov=app --cov-report=html
+uv run pytest --cov=app --cov-report=html
 
 # 运行特定测试文件
-pytest tests/test_query_service.py
+uv run pytest tests/test_query_service.py
 
 # 运行特定测试函数
-pytest tests/test_query_service.py::test_query_by_star_id
+uv run pytest tests/test_query_service.py::test_query_by_star_id
+
+# 添加新依赖
+uv add <package-name>
+
+# 添加开发依赖
+uv add --group dev <package-name>
+
+# 类型检查（修改后端代码后必须执行）
+uv run basedpyright
+
+# 代码风格检查（修改后端代码后必须执行）
+uv run ruff check app/
+```
+
+### 后端代码质量检查
+
+**修改后端 Python 文件后，必须执行以下检查：**
+
+```bash
+uv run basedpyright && uv run ruff check app/
 ```
 
 ### 数据库操作
@@ -75,13 +97,13 @@ pytest tests/test_query_service.py::test_query_by_star_id
 psql "postgresql://user:password@host:5432/yuntu_kol"
 
 # 创建迁移
-alembic revision --autogenerate -m "description"
+uv run alembic revision --autogenerate -m "description"
 
 # 执行迁移
-alembic upgrade head
+uv run alembic upgrade head
 
 # 回滚迁移
-alembic downgrade -1
+uv run alembic downgrade -1
 ```
 
 ### Docker 部署
@@ -403,7 +425,7 @@ kol-insight/
 │   │   ├── api/v1/              # API 路由
 │   │   └── services/            # 业务逻辑
 │   ├── tests/                   # 测试文件（TDD 必须）
-│   └── requirements.txt
+│   └── pyproject.toml
 │
 ├── doc/                         # 项目文档
 │   ├── PRD.md                   # 产品需求文档
@@ -450,12 +472,12 @@ kol-insight/
 
 ### Q: 如何运行单个测试？
 ```bash
-pytest tests/test_calculator.py::test_calculate_natural_cpm -v
+uv run pytest tests/test_calculator.py::test_calculate_natural_cpm -v
 ```
 
 ### Q: 如何查看测试覆盖率？
 ```bash
-pytest --cov=app --cov-report=html
+uv run pytest --cov=app --cov-report=html
 # 打开 htmlcov/index.html 查看详细报告
 ```
 

backend/Dockerfile

@@ -1,5 +1,7 @@
 FROM python:3.11-slim
 
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
 WORKDIR /app
 
 # Install system dependencies
@@ -8,9 +10,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libpq-dev \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy requirements and install Python dependencies
+# Copy dependency files and install
-COPY requirements.txt .
+COPY pyproject.toml uv.lock ./
-RUN pip install --no-cache-dir -r requirements.txt
+RUN uv sync --frozen --no-dev --no-install-project
 
 # Copy application code
 COPY app/ ./app/
@@ -27,4 +29,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:8000/health || exit 1
 
 # Start application
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "kol-insight-backend"
+version = "0.1.0"
+description = "KOL Insight - KOL 数据查询与分析工具后端"
+requires-python = ">=3.11"
+dependencies = [
+    # Web Framework
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    # Database
+    "sqlalchemy>=2.0.0",
+    "asyncpg>=0.29.0",
+    "alembic>=1.12.0",
+    "greenlet>=3.0.0",
+    # HTTP Client
+    "httpx[socks]>=0.25.0",
+    # Data Validation
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    # Excel Export
+    "openpyxl>=3.1.0",
+    # Environment
+    "python-dotenv>=1.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "basedpyright>=1.20.0",
+    "ruff>=0.8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-v --cov=app --cov-report=html --cov-report=term-missing"
+
+[tool.basedpyright]
+typeCheckingMode = "basic"
+pythonVersion = "3.11"
+include = ["app"]
+exclude = [".venv", "**/__pycache__", "alembic", "tests"]
+extraPaths = ["app"]
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportGeneralTypeIssues = false
+reportOptionalMemberAccess = "warning"
+
+[tool.ruff]
+line-length = 150
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle 错误
+    "F",  # Pyflakes 错误（未定义变量、未使用导入等）
+    "B",  # bugbear 安全警告
+    "I",  # import 排序
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"!app/**" = ["E", "F", "B", "I"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"

backend/pytest.ini

@@ -1,5 +0,0 @@
-[pytest]
-testpaths = tests
-asyncio_mode = auto
-asyncio_default_fixture_loop_scope = function
-addopts = -v --cov=app --cov-report=html --cov-report=term-missing

backend/requirements.txt

@@ -1,27 +0,0 @@
-# Web Framework
-fastapi>=0.104.0
-uvicorn[standard]>=0.24.0
-
-# Database
-sqlalchemy>=2.0.0
-asyncpg>=0.29.0
-alembic>=1.12.0
-
-# HTTP Client
-httpx>=0.25.0
-
-# Data Validation
-pydantic>=2.0.0
-pydantic-settings>=2.0.0
-
-# Excel Export
-openpyxl>=3.1.0
-
-# Testing
-pytest>=7.4.0
-pytest-asyncio>=0.21.0
-pytest-cov>=4.1.0
-httpx>=0.25.0
-
-# Development
-python-dotenv>=1.0.0