项目管理 API

项目模块共 7 个接口，含单并发锁、创建时快照与删除级联。

接口一览

#	方法	路径	说明
10	POST	`/api/projects`	创建项目（写 projects 表，status=等待）
11	POST	`/api/projects/{id}/generate`	开始生成（单并发锁，占用中返回 400）
12	GET	`/api/projects/{id}/status`	查询状态（status 读库 + 内存进度）
13	GET	`/api/projects/{id}`	项目详情（配置 + scenes 分镜 + final_video_url）
14	GET	`/api/projects`	项目列表（分页 / 状态筛选 / 关键词 / cover_url）
15	DELETE	`/api/projects/{id}`	删除（级联 scenes + output 目录 + freed_mb）
16	GET	`/api/projects/{id}/download`	下载成片（.mp4）

创建项目

curl -X POST http://localhost:8000/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的视频",
    "topic": "中国茶文化宣传片",
    "config": {
      "ratio": "16:9",
      "resolution": "高清720p",
      "fps": 24,
      "style": "写实",
      "voice": "温柔女声",
      "targetDuration": 30
    }
  }'

响应：{"project_id": "proj_20260820_120000", "status": "等待"}

注意：config 键保持 camelCase（targetDuration）；后端映射为 target_duration。

查询进度

curl http://localhost:8000/api/projects/proj_20260820_120000/status

响应：{"project_id": "...", "status": "进行中", "current_step": "videos", "progress_percent": 40, "error_msg": ""}

列表分页

GET /api/projects?page=1&page_size=12&status=进行中&keyword=茶

响应：{"items": [...], "total": n, "page": 1, "page_size": 12, "has_more": bool}；items 含 cover_url（第 1 分镜图片）。

删除级联

curl -X DELETE http://localhost:8000/api/projects/proj_20260820_120000

删除 projects 行 + 全部 scenes 行 + output/{project_id}/ 整目录；
响应：{"message": "已删除", "freed_mb": 12.3}；
删除前校验 project_id 格式（proj_\d+_\d+），防路径穿越。

单并发说明

全局生成互斥锁：同一时间仅 1 个项目处于「进行中」；
重复触发 → 400「当前已有项目正在创作中」；
开发期生成类接口免鉴权，正式版统一鉴权。