v0.4.1 发布说明
v0.4.1 是一次纯修复版本,把 v0.4.0 之后端到端走查中暴露的四个缺陷补掉,其中第一个是阻断性的:手工创建的分镜会永久卡在 pending,无法进入任何后续环节。
Highlights
- 手工创建分镜(
POST /api/v1/studio/shots)现在会同时落下配套的shot_details行,分镜不再永久卡在pending。 - 文件列表在包含音频文件时不再整表返回 400。
- 非法的
order查询参数不再静默回落,而是明确返回 400 并列出允许的字段。 - 未执行信息提取的分镜,就绪文案不再自相矛盾地提示「仍有待确认项:资产 0 项,对白 0 项」。
Fixed
手工创建的分镜永久卡在 pending(阻断)
症状:通过 POST /api/v1/studio/shots 创建的分镜,以下三个端点全部返回 404:
GET /api/v1/studio/shot-details/{shot_id}GET /api/v1/studio/shots/{shot_id}/preparation-statePATCH /api/v1/studio/shots/{shot_id}/skip-extraction
其中 PATCH 是写操作,404 之外还会让整个事务被 get_db() 回滚,因此 skip_extraction 与 last_extracted_at 都不会落库,分镜没有任何路径离开 pending。
根因:Shot 与 ShotDetail 是一对一的同主键关联(shot_details.id 是 shots.id 的外键)。但两条创建路径不对称:
backend/app/services/studio/script_division.py(一键提取)会额外插入一行ShotDetail(camera_shot=MS, angle=EYE_LEVEL, movement=STATIC, follow_atmosphere=True, vfx_type=NONE, duration=4);backend/app/services/studio/shots.py的create()只执行return await create_and_refresh(db, Shot(**body.model_dump())),从不创建ShotDetail。
结果是只有「一键提取」产出的分镜带 shot_details,手工创建的分镜没有。
修复:把默认值收敛成单一工厂,消除两份会漂移的常量:
# backend/app/services/studio/shot_details.py
DEFAULT_SHOT_CAMERA_SHOT = CameraShotType.ms
DEFAULT_SHOT_ANGLE = CameraAngle.eye_level
DEFAULT_SHOT_MOVEMENT = CameraMovement.static
DEFAULT_SHOT_DURATION = 4
def build_default_shot_detail(shot_id: str) -> ShotDetail:
...shots.create() 与 script_division 现在都调用 build_default_shot_detail(),并在同一事务里 db.add(...) + await db.flush()。create_and_refresh 只做 add/flush/refresh、不 commit,因此调用方可以在其后继续追加同事务的写入。
注意枚举值的大小写:
CameraShotType/CameraAngle/CameraMovement的值是大写(MS/EYE_LEVEL/STATIC),Python 属性名是小写(ms/eye_level/static)。接口传小写值会得到 422。
文件列表遇到音频行整表 400
症状:只要库中存在 type='audio' 的文件,GET /api/v1/studio/files 就整体返回 400:
1 validation error for FileRead
type
Input should be 'image' or 'video' [type=enum, input_value='audio', input_type=str]根因:响应模型 FileTypeEnum(backend/app/schemas/studio/files.py)只有 image / video,而数据库侧 FileType(backend/app/models/types.py)在 v0.4.0 引入音频对白后已经包含 audio。响应按整表序列化,任何一行失败会导致整个响应失败——不是跳过该行。音频是在 v0.4.0 落地的,因此这是 v0.4.0 引入的回归。
修复:FileTypeEnum 补上 audio,并新增一致性测试锁定两处枚举不再分叉。
非法 order 参数静默回落
症状:GET /api/v1/studio/shots?order=DROP 返回 200。apply_order(backend/app/api/utils.py)对不在允许清单里的字段静默改用默认排序,前端一旦拼错字段名,会拿到看似正常、实则排序错误的结果。
修复:未知字段直接抛 ValueError,由已注册的 value_error_handler 映射为 400 并列出允许字段:
{"code": 400, "message": "Unsupported order field: DROP. Allowed fields: created_at, index, status, title, updated_at"}空字符串仍按「未传」处理,不触发报错。改动前已核对前端实际只会发送 updated_at 与 index,两者都在允许清单内。
未提取分镜的就绪文案自相矛盾
症状:分镜尚未执行信息提取时,视频就绪检查会提示「仍有待确认项:资产 0 项,对白 0 项」——但这正是未提取的必然结果,把「还没提取」说成了「有待确认项」。
修复:在 shot_video_readiness.py 中新增分支,last_extracted_at is None 时给出可执行提示:「尚未执行信息提取,请先提取或将该镜头标记为无需提取」。
Known Issues
- 时间线 / 导出仍是占位:
backend/app/api/v1/routes/studio/timeline.py只有路由壳,没有 CRUD 端点,产品工作流第 ⑥ 步仍不可用。 video_prompt模板类别未播种:一旦库中存在该行,视频预览会走模板分支并绕过 IR → H3 渲染器,因此有意留空。- 首次参考图模式的端到端验证依赖真实对象存储:
file_id_to_data_url需要能从存储下载到内容,纯 DB 造数无法覆盖。 - 遗留前端服务调用已不存在的旧路径:
front/src/services/aiStudioApi.ts请求的是不带/api/v1/studio前缀的旧地址(/projects、/agents、/assets、/files、/prompts/templates、/chapters/{id}/shots、/projects/{id}/timeline等),在当前 API 下全部 404。它的消费方是 4 个仍注册在front/src/App.tsx的页面(files、agents、agents/:id/edit、projects/:projectId/editor)。这些入口没有出现在侧边栏导航(front/src/layouts/MainLayout.tsx的menuItems只含 项目列表 / 资产管理 / 提示词模板 / 模型管理 / 设置),因此只能靠直接输入 URL 到达;属上游遗留脚手架,与当前工作流无关。是否重写或移除待定。 - 工作流预检尚未覆盖「图片格式」:开工预检(
GET /api/v1/studio/projects/{project_id}/production-readiness)已覆盖模型可用性、项目风格、视频比例、角色音色、参考帧与信息提取,但「图片格式 / 输出分辨率」在契约层就缺失,无对应检查项。
Validation Commands
# 后端全量测试(期望 389 passed, 2 deselected)
cd backend && .venv/bin/python -m pytest tests -q
# 前端类型检查
cd front && pnpm run typecheck
# 健康检查与 spec 路径数(期望 200 / 107)
curl -s http://127.0.0.1:8000/health
curl -s http://127.0.0.1:8000/openapi.json | python3 -c "import sys,json;print(len(json.load(sys.stdin)['paths']))"四项修复的线上验证:
# P0:创建分镜后 shot-details / preparation-state / skip-extraction 应为 200(修复前均为 404)
curl -s -X POST http://127.0.0.1:8000/api/v1/studio/shots \
-H 'Content-Type: application/json' \
-d '{"id":"demo-shot","chapter_id":"<chapter>","index":1,"title":"演示"}'
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/api/v1/studio/shot-details/demo-shot
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/api/v1/studio/shots/demo-shot/preparation-state
curl -s -X PATCH http://127.0.0.1:8000/api/v1/studio/shots/demo-shot/skip-extraction \
-H 'Content-Type: application/json' -d '{"skip":true}'
# P1:含音频行时文件列表应为 200(修复前 400)
curl -s -o /dev/null -w '%{http_code}\n' 'http://127.0.0.1:8000/api/v1/studio/files?page_size=5'
# P2:非法 order 应为 400 并列出允许字段(修复前 200)
curl -s 'http://127.0.0.1:8000/api/v1/studio/shots?order=DROP&page_size=5'
ShotSkipExtractionUpdate的字段名是skip(不是skip_extraction)。章节通过POST /api/v1/studio/chapters创建,不嵌在项目路径下。
Upgrade Checklist
- 重建
backend与celery-worker镜像并重启(后端代码烘进镜像,无 bind mount)。 - 确认
GET /api/v1/studio/files在含音频行时返回 200。 - 手工创建一个分镜,确认
shot-details与preparation-state返回 200 而非 404。 - 确认
?order=<非法值>返回 400 并列出允许字段。
Notes for Contributors
- 新增任何与
Shot一对一的附属行时,请走build_default_shot_detail()这类单一工厂,不要在两条创建路径各写一份默认值——v0.4.1修复的正是这种漂移。 - 响应模型里的枚举必须与
app/models/types.py的数据库枚举保持一一对应;序列化失败是整表失败,不是跳过单行。 - 枚举的值通常是全大写,Python 属性名是小写;写接口测试时留意大小写。