meijiaka-zy/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

美家卡智影 - AI 视频创作桌面应用，采用 Python FastAPI 后端 + Tauri (Rust + React) 前端的混合架构。

核心功能: AI 脚本生成、TTS 语音合成、声音克隆、对口型 (Vidu)、字幕生成、视频合成、项目本地持久化

项目结构

.
├── python-api/          # Python 后端 API (FastAPI)
├── tauri-app/           # Tauri 桌面前端 (Rust + React 19)
├── docs/                # 架构文档
└── AGENTS.md            # AI Agent 专用详细文档

后端 (python-api/)

python-api/
├── app/
│   ├── api/v1/          # API 路由 (按领域拆分: auth, script, voice, vidu, caption, tasks, upload, materials, system)
│   ├── core/            # 核心工具 (配置、异常、Redis、健康检查)
│   ├── db/              # 数据库配置 (SQLAlchemy 2.0 async)
│   ├── models/          # ORM 模型 (BaseModel: UUID 主键 + 时间戳)
│   ├── schemas/         # Pydantic Schema (请求/响应校验)
│   ├── services/        # 业务逻辑层
│   ├── scheduler/       # Async Engine 异步任务调度
│   ├── ai/              # AI 模型封装 (providers, adapters, gateways)
│   └── platform_gateway.py  # 第三方平台统一调用网关
├── config/              # 运行时配置 (platform-config.yaml, materials.json)
├── alembic/             # 数据库迁移
└── Makefile             # 开发命令

前端 (tauri-app/)

tauri-app/
├── src/
│   ├── api/
│   │   ├── client.ts    # 智能路由客户端 (HTTP/IPC 自动选择, camelCase ↔ snake_case)
│   │   ├── modules/     # 按领域拆分的 API 模块
│   │   └── generated/   # OpenAPI 生成类型
│   ├── components/      # 可复用组件 (PascalCase 文件夹)
│   ├── pages/           # 页面组件 (PascalCase 文件夹)
│   ├── store/           # Zustand 状态管理
│   ├── hooks/           # 自定义 Hooks
│   └── styles/          # CSS 变量与全局样式
├── src-tauri/src/
│   ├── commands/        # Tauri IPC 命令 (按领域拆分)
│   ├── storage/         # 本地存储引擎
│   ├── ffmpeg_cmd.rs    # FFmpeg 命令封装
│   └── lib.rs           # Tauri Builder、Command 定义
└── package.json

混合通信架构

1. 纯数据 API (脚本、TTS、字幕、视频生成、任务查询等) → 前端通过 HTTP 直连 Python 后端

   • 使用 tauri-app/src/api/client.ts 的 client.get/post/put/delete
   • 异步任务统一走 POST /tasks/{task_type} + 轮询 /tasks/{task_id}

2. 本地系统能力 (FFmpeg 合成、文件系统、项目持久化) → 走 Tauri IPC → Rust 层

   • 使用 invoke() 调用 src-tauri/src/commands/ 中的 #[tauri::command]
   • 命令参数用 snake_case，前端用 camelCase，通过 #[serde(rename_all = "camelCase")] 转换

新增纯数据 API 时: 只需在 tauri-app/src/api/modules/ 使用 client 调用，无需修改 Rust 代码。

新增本地能力时: 在 src-tauri/src/commands/ 添加 #[tauri::command]，并在 lib.rs 的 invoke_handler 中注册。

常用命令

后端 (cd python-api)

# 安装依赖
make dev

# 启动服务 (需两个终端)
make run              # FastAPI 开发服务器 (8000)
make scheduler        # Async Engine 调度器

# 代码质量
make lint             # ruff + mypy
make format           # black + ruff --fix
make lint-semantic    # 语义层禁词检查 (防止供应商术语泄漏)
make ci               # format-check + lint + lint-semantic + test + security

# 测试
make test             # pytest
make test-cov         # 覆盖率报告

# 安全扫描
make security         # bandit + pip-audit

# Docker
make docker-run       # 启动 api + scheduler (共享外部 db/redis)
make docker-rebuild   # 强制重建
make docker-logs      # 查看日志

# 数据库迁移
alembic revision --autogenerate -m "描述"
alembic upgrade head

前端 (cd tauri-app)

# 开发
npm run dev           # Vite 前端服务器 (1420)
npm run tauri dev     # Tauri 完整开发模式

# 构建
npm run build         # tsc + vite build
npm run tauri build   # Tauri 打包

# 测试
npm run test          # Vitest
npm run test:ui       # Vitest UI
npm run test:coverage # 覆盖率

# 代码质量
npm run lint          # ESLint
npm run lint:fix      # ESLint --fix
npm run format        # Prettier
npm run stylelint     # Stylelint

# API 类型生成
npm run gen:api       # 从 openapi.json 生成 TypeScript 类型

代码规范

命名约定

• 组件/页面文件夹: PascalCase (VideoCreation/, ErrorBoundary/)
• Store/Hooks/API 文件: camelCase (authStore.ts, useProjectData.ts)
• Python 模块/函数: snake_case (script_handler.py, get_settings())
• Python 类: PascalCase (AsyncEngine, BaseModel)
• 常量: UPPER_SNAKE_CASE (PYTHON_API_BASE_URL)

注释语言

• 统一使用中文注释
• 关键架构决策需用多行注释说明

Python 代码质量

• 格式化: black (line-length: 100)
• 检查: ruff (E, F, I, N, W, UP, B, C4, SIM)
• 类型检查: mypy (新代码 app.schemas.*, app.crud.*, app.scheduler.handlers.* 严格模式)
• 依赖管理: uv (requirements.lock 必须与 pyproject.toml 同步)
• 安全: bandit + pip-audit

TypeScript 配置

• strict: true 已开启
• jsx: "react-jsx"，无需手动引入 React
• 路径别名 @/ → ./src

语义层防护 (Makefile lint-semantic)

• API 层禁止 element_id 作为字段名 (应使用 provider_element_id)
• Scheduler 层统一使用 task 命名 (TaskRegistry, task_id, task: Redis key 前缀)，禁止混用 job

关键架构组件

Async Engine (异步任务调度)

• 位置: python-api/app/scheduler/
• 核心组件:
  • AsyncEngine: 主调度器，驱动 Tick 循环
  • TaskRegistry: Redis 任务注册表 (running/pending/finished)
  • SlotManager: 并发槽位管理 (按 task_type 限制并发数)
  • handlers/: 各领域处理器 (script, tts, subtitle, video)
• 启动: make scheduler 或 python -m app.scheduler.main
• Tick 间隔: 5 秒 (可配置)

Platform Gateway (第三方平台统一调用)

• 位置: python-api/app/platform_gateway.py
• 功能: 统一调用所有第三方平台 (Vidu、火山方舟、火山字幕)
• 方法:
  • call_sync(): 同步调用
  • submit_task(): 异步任务提交
  • query_task(): 任务状态查询
  • handle_webhook(): 回调处理 (含签名验证 + nonce 防重放)

Model Router (AI 模型路由)

• 位置: python-api/app/ai/model_router.py
• 功能: 从 YAML 配置文件加载平台/模型配置，支持模型自动选择
• 配置文件: python-api/config/platform-config.yaml

状态管理 (前端)

• Zustand + Immer: 不可变更新
• projectStore: 自定义 persist 存储，通过 Tauri IPC 持久化到本地文件系统 (app_config_dir/current_project.json)
• 其他 Store: 使用 localStorage 持久化

环境变量 (后端)

关键配置见 python-api/.env.example:

变量	说明
DATABASE_URL	PostgreSQL 连接字符串
REDIS_HOST / REDIS_PORT / REDIS_DB	Redis 连接信息
SECRET_KEY	JWT 签名密钥 (生产环境必须设置)
CORS_ORIGINS	允许的跨域来源
VOLCENGINE_API_KEY	火山方舟 API Key
VIDU_API_KEY	Vidu API Key
QINIU_ACCESS_KEY / QINIU_SECRET_KEY	七牛云存储密钥
APP_BASE_URL	应用公网地址 (第三方回调用)

部署

测试环境 (GitLab CI)

• 触发条件: master 分支
• 流程: 拉取代码 → 构建 api + scheduler → 启动服务 → 健康检查 (/health)
• 清理: 删除 7 天前的旧镜像

生产环境

cd python-api
docker compose -f docker-compose.prod.yml up -d --build

数据库

• ORM: SQLAlchemy 2.0 (asyncpg 驱动)
• 迁移: Alembic
• 基础模型: app.models.base.BaseModel (UUID 主键、created_at、updated_at)

安全注意事项

• JWT SECRET_KEY 生产环境必须设置强随机字符串
• 依赖安全: aiohttp>=3.13.4 和 orjson>=3.11.0 为强制最低版本
• 输入验证: 所有 API 入参通过 Pydantic Schema 校验
• 数据库: 使用参数化查询 (SQLAlchemy ORM)

开发注意事项

1. 修改 pyproject.toml 后必须运行 make update-lock 更新 requirements.lock
2. 新增组件遵循 PascalCase 文件夹约定
3. 语义层禁词检查 (make lint-semantic) 必须通过
4. Tauri 配置变更后需重新 tauri dev
5. projectStore 的 partialize 字段决定哪些状态被保存到本地文件
6. 前端测试在 src/__tests__/setup.ts 中已全局 mock localStorage 和 Tauri API