小鱼开发
30536276ba
核心变更：
- 统一第三方接口架构：所有服务走 PlatformGateway（call_sync/submit_task/query_task/handle_webhook）
- 视频生成（Vidu 对口型）纳入 Async Engine，与 script/subtitle/tts 统一为 POST /tasks/{task_type} 模式
- 新增 VideoHandler、TTSHandler，完善 ScriptHandler/SubtitleHandler
- PlatformGateway 生成 internal_task_id，建立 Redis 双向映射，callback 场景传入 Async Engine task_id 保证映射一致
- SlotManager 新增 acquire_ctx 上下文管理器，所有 Handler 统一使用
- ViduAdapter 状态映射归一化（normalize_state/denormalize_state）
- 移除 ViduService Semaphore 和 tenacity 重试，并发控制完全交予 SlotManager
- nonce 防重放下沉到 CallbackCapable 协议
- Service 层错误统一为 PlatformError，路由层错误信息脱敏
- 废弃 /voice/lip-sync，清理 vidu.py 遗留路由
Bug 修复：
- VideoHandler 轮询阶段后添加 continue，防止已提交任务重复创建
- voice.py synthesize_to_file 变量名冲突（request vs request_body）
- PlatformGateway.submit_task 空 data 防护
- ScriptHandler 动态导入 asyncio 改为模块级导入
- SubtitleHandler 完成时补充 progress=100
文档：
- 更新 AGENTS.md 核心功能、运行时架构、异步调度描述
美家卡智影 API
美家卡智影后端服务 - 基于 FastAPI + Redis 的 AI 视频创作 API。
技术栈
| 组件 | 技术 | 版本 |
|---|---|---|
| Web 框架 | FastAPI | ^0.110.0 |
| 数据库 | PostgreSQL | 15+ |
| ORM | SQLAlchemy | 2.0+ (异步) |
| 缓存/状态 | Redis | 7.x |
| 异步调度 | Async Engine (Slot Scheduler) | Python asyncio |
| 部署 | Docker + Docker Compose | - |
快速开始
1. 环境准备
确保已安装：
- Python 3.11+
- Docker & Docker Compose（推荐）
- 或本地 PostgreSQL + Redis
2. 使用 Docker Compose 启动（推荐）
# 1. 克隆项目后进入目录
cd python-api
# 2. 复制环境变量配置
cp .env.example .env
# 3. 启动所有服务
docker-compose up -d
# 4. 查看日志
docker-compose logs -f api
# 5. 服务地址
# API: http://localhost:8080
# 文档: http://localhost:8080/docs
3. 本地开发
# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 2. 安装依赖
pip install -e ".[dev]"
# 3. 配置环境变量
cp .env.example .env
# 编辑 .env，修改数据库连接等配置
# 4. 启动 PostgreSQL 和 Redis（Docker）
docker-compose up -d db redis
# 5. 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 7. 启动 Async Engine Scheduler（另开终端）
python -m app.scheduler.main
项目结构
python-api/
├── app/ # 主应用代码
│ ├── api/v1/ # API 路由
│ ├── core/ # 核心工具（安全、异常）
│ ├── db/ # 数据库配置
│ ├── models/ # SQLAlchemy 模型
│ ├── schemas/ # Pydantic Schema
│ ├── services/ # 业务逻辑
│ ├── scheduler/ # Async Engine 异步任务调度
│ ├── ai/ # AI 模型相关
│ ├── utils/ # 工具函数
│ ├── config.py # 配置管理
│ └── main.py # FastAPI 入口
├── docker-compose.yml # Docker 编排
├── Dockerfile # Docker 镜像
├── pyproject.toml # 项目依赖
└── README.md # 本文档
数据模型
核心实体
- User - 用户/设备（设备 ID + JWT 认证）
- Project - 视频创作项目
- ScriptSegment - 脚本分镜
- MediaAsset - 媒体元数据（音频/视频/封面）
- TaskQueue - 异步任务队列
API 路由
已实现
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/auth/login |
设备登录/注册 |
| GET | /api/v1/auth/me |
获取当前用户 |
| GET | /api/v1/system/health |
健康检查 |
| GET | /api/v1/system/version |
版本信息 |
待实现（M2-M5）
/api/v1/script/*- 脚本生成（SSE 流式）/api/v1/voice/*- 语音合成（TTS）/api/v1/video/*- 数字人视频（异步任务）/api/v1/project/*- 项目云同步/api/v1/parser/*- 视频链接解析（预留）
环境变量
见 .env.example，主要配置项：
| 变量 | 说明 | 默认值 |
|---|---|---|
DATABASE_URL |
PostgreSQL 连接字符串 | postgresql+asyncpg://postgres:postgres@localhost:5432/meijiaka_zy |
REDIS_URL |
Redis 连接字符串 | redis://localhost:6379/0 |
SECRET_KEY |
JWT 签名密钥 | 必须修改 |
OPENAI_API_KEY |
OpenAI API Key | - |
CORS_ORIGINS |
允许的跨域来源 | http://localhost:1420 |
开发规范
代码风格
# 格式化
black app/
# 检查
ruff check app/
mypy app/
# 测试
pytest
提交规范
feat:新功能fix:修复docs:文档refactor:重构test:测试
与前端集成
Tauri 前端默认连接 http://127.0.0.1:8080/api/v1。
云端部署后：
- 修改前端
src/api/client.ts中的PYTHON_API_BASE_URL - 更新
tauri.conf.jsonCSP 配置，添加云端域名到connect-src
许可
MIT