小鱼开发
7550559aa0
- 删除8个未使用IPC命令，保留validate_media_path - file.rs返回类型优化为ApiResponse<()> - point_service.consume()注释与签名一致 - VideoGeneration改为拼接成功后扣费 - 添加漏扣费风险注释 - 删除过时测试文件 - 修复camelToSnake连续大写字母问题 - vidu.py import移至模块顶层 Refs: P1-1~P1-6 技术债务清理
188 lines
5.2 KiB
Markdown
188 lines
5.2 KiB
Markdown
# 美家卡智影 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 启动（推荐）
|
||
|
||
```bash
|
||
# 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. 本地开发
|
||
|
||
```bash
|
||
# 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 路由
|
||
|
||
| 模块 | 接口 | 说明 |
|
||
|------|------|------|
|
||
| **auth** | `POST /auth/send-code` | 发送验证码 |
|
||
| | `POST /auth/login` | 登录 |
|
||
| | `POST /auth/refresh` | 刷新 Token |
|
||
| | `POST /auth/logout` | 登出 |
|
||
| | `GET /auth/me` | 获取用户信息 |
|
||
| | `PATCH /auth/me` | 更新用户信息 |
|
||
| **system** | `GET /system/version` | 版本信息 |
|
||
| **events** | `GET /events` | SSE 事件流 |
|
||
| **tasks** | `POST /tasks/{type}` | 创建异步任务 |
|
||
| | `GET /tasks` | 任务列表 |
|
||
| | `GET /tasks/{id}` | 任务状态 |
|
||
| | `GET /tasks/{id}/result` | 任务结果 |
|
||
| **script** | `GET /script/categories` | 脚本分类 |
|
||
| | `POST /script/polish` | 文案润色 |
|
||
| | `POST /script/generate-title` | 生成标题 |
|
||
| **voice** | `GET /voice/voices` | 音色列表 |
|
||
| | `POST /voice/synthesize` | TTS 合成 |
|
||
| | `POST /voice/clone/submit` | 提交声音复刻 |
|
||
| | `GET /voice/clone/query/{id}` | 查询复刻状态 |
|
||
| **caption** | `POST /caption/ata/align` | 自动字幕打轴 |
|
||
| **upload** | `POST /upload/video` | 上传视频 |
|
||
| | `POST /upload/audio` | 上传音频 |
|
||
| **vidu** | `POST /vidu/callback` | Vidu 回调 |
|
||
| **materials** | `POST /materials/match` | 素材匹配 |
|
||
| | `POST /materials/batch-match` | 批量素材匹配 |
|
||
| **cover** | `GET /cover-backgrounds` | 封面背景图 |
|
||
| **points** | `GET /points/balance` | 积分余额 |
|
||
| | `GET /points/transactions` | 积分流水 |
|
||
| | `POST /points/recharge` | 创建充值订单 |
|
||
| | `POST /points/recharge/notify` | 微信支付回调 |
|
||
| | `GET /points/recharge/query/{id}` | 查询充值订单 |
|
||
| | `GET /points/recharge-options` | 充值档位 |
|
||
| | `GET /points/chargeable-types` | 扣费业务类型 |
|
||
| | `GET /points/rules` | 积分计费规则 |
|
||
| | `POST /points/consume` | 消费积分 |
|
||
|
||
## 环境变量
|
||
|
||
见 `.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` |
|
||
|
||
## 开发规范
|
||
|
||
### 代码风格
|
||
|
||
```bash
|
||
# 格式化
|
||
black app/
|
||
|
||
# 检查
|
||
ruff check app/
|
||
mypy app/
|
||
|
||
# 测试
|
||
pytest
|
||
```
|
||
|
||
### 提交规范
|
||
|
||
- `feat:` 新功能
|
||
- `fix:` 修复
|
||
- `docs:` 文档
|
||
- `refactor:` 重构
|
||
- `test:` 测试
|
||
|
||
## 与前端集成
|
||
|
||
Tauri 前端默认连接 `http://127.0.0.1:8080/api/v1`。
|
||
|
||
云端部署后：
|
||
1. 修改前端 `src/api/client.ts` 中的 `PYTHON_API_BASE_URL`
|
||
2. 更新 `tauri.conf.json` CSP 配置，添加云端域名到 `connect-src`
|
||
|
||
## 许可
|
||
|
||
MIT
|