# 美家卡智影 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 路由

### 已实现

| 方法 | 路径 | 说明 |
|------|------|------|
| 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` |

## 开发规范

### 代码风格

```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