fix(ai-avatar): 契约文档标题字段纠正 + script_id 改为可选

- 文档 §5/§6：标题是单个 title_config dict（非 titles[] 数组），字段以 build_title_drawtext_filter() 为准：text/content、font_size/size、 font_color/color、position(top/center/bottom/custom)、pos_x/pos_y、bold、 stroke、shadow、enabled；删除不存在的 titles[]/fontSize/frame/start/end 描述 - script_id 改为可选：手动输入文案/TTS 直生场景不关联文案库条目，留空不校验，避免手动文案用户被 ScriptNotFound 卡住；选了文案库时仍做归属校验 - 迁移 074：ai_avatar_render_jobs.script_id 默认空串 - 新增 schema 单测（script_id 空/空白/title_config 单 dict），94 测试全绿 Refs #1797 #1826
2026-09-09 19:55:01 +08:00
parent 8052f245ec
commit 4d09bd630e
6 changed files with 130 additions and 47 deletions
@@ -0,0 +1,36 @@
+"""ai_avatar_render_jobs.script_id 放宽为可空串（手动文案直生场景不关联文案库）
+
+Revision ID: 074_render_script_id_optional
+Revises: 073_add_lipsync_tts_fields
+Create Date: 2026-09-09
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "074_render_script_id_optional"
+down_revision = "073_add_lipsync_tts_fields"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 列保持 NOT NULL（空串占位），仅应用层允许不传；这里显式补 server_default 防止历史约束歧义
+    with op.batch_alter_table("ai_avatar_render_jobs") as batch:
+        batch.alter_column(
+            "script_id",
+            existing_type=sa.String(length=36),
+            nullable=False,
+            server_default="",
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("ai_avatar_render_jobs") as batch:
+        batch.alter_column(
+            "script_id",
+            existing_type=sa.String(length=36),
+            nullable=False,
+            server_default=None,
+        )
@@ -50,7 +50,7 @@ class CreateAiAvatarRenderRequest(BaseModel):
    """创建渲染任务请求."""

    lipsync_job_id: str = Field(..., description="对口型任务 ID")
-    script_id: str = Field(..., description="文案 ID")
+    script_id: str = Field("", description="文案 ID（选自文案库时传；手动输入文案直生场景可留空）")
    b_roll_segments: list[BRollSegment] = Field(default_factory=list, description="B-roll 片段列表")
    title_config: dict[str, Any] = Field(default_factory=dict, description="标题配置")
    cover_config: dict[str, Any] = Field(default_factory=dict, description="封面配置")
@@ -67,10 +67,8 @@ class CreateAiAvatarRenderRequest(BaseModel):
    @field_validator("script_id")
    @classmethod
    def validate_script_id(cls, v: str) -> str:
-        v = v.strip()
-        if not v:
-            raise ValueError("script_id 不能为空")
-        return v
+        # script_id 可选：手动输入文案（TTS 直生）场景不关联文案库条目
+        return (v or "").strip()


 class AiAvatarRenderJobResponse(BaseModel):
@@ -80,7 +78,7 @@ class AiAvatarRenderJobResponse(BaseModel):
    user_id: str
    project_id: str
    lipsync_job_id: str
-    script_id: str
+    script_id: str = ""
    b_roll_segments: list[dict[str, Any]]
    title_config: dict[str, Any]
    cover_config: dict[str, Any]
@@ -53,8 +53,8 @@ class AiAvatarRenderService:
        *,
        user_id: str,
        lipsync_job_id: str,
-        script_id: str,
-        b_roll_segments: list[dict[str, Any]],
+        script_id: str = "",
+        b_roll_segments: list[dict[str, Any]] | None = None,
        title_config: dict[str, Any],
        cover_config: dict[str, Any],
        project_id: str = "",
@@ -83,17 +83,19 @@ class AiAvatarRenderService:
        if not lipsync_job.output_video_url:
            raise AiAvatarRenderError("对口型任务输出视频 URL 为空", code="LipsyncJobNoOutput")

-        # 2. 验证文案归属
-        script = (
-            self.db.query(ScriptModel)
-            .filter(
-                ScriptModel.id == script_id,
-                ScriptModel.user_id == user_id,
+        # 2. 验证文案归属（仅当选了文案库条目时；手动输入文案直生场景 script_id 可空）
+        script_id = (script_id or "").strip()
+        if script_id:
+            script = (
+                self.db.query(ScriptModel)
+                .filter(
+                    ScriptModel.id == script_id,
+                    ScriptModel.user_id == user_id,
+                )
+                .first()
            )
-            .first()
-        )
-        if script is None:
-            raise AiAvatarRenderError("文案不存在或无权访问", code="ScriptNotFound")
+            if script is None:
+                raise AiAvatarRenderError("文案不存在或无权访问", code="ScriptNotFound")

        # 3. 创建渲染任务
        job_id = str(uuid.uuid4())
@@ -103,7 +105,7 @@ class AiAvatarRenderService:
            project_id=project_id,
            lipsync_job_id=lipsync_job_id,
            script_id=script_id,
-            b_roll_segments=[s if isinstance(s, dict) else s.model_dump() for s in b_roll_segments],
+            b_roll_segments=[s if isinstance(s, dict) else s.model_dump() for s in (b_roll_segments or [])],
            title_config=title_config,
            cover_config=cover_config,
            status="pending",
@@ -107,40 +107,63 @@

 ---

-## 5. 标题配置 `title_config` 字段清单（build_title_drawtext_filter）
+## 5. 渲染接口 `POST /api/v1/ai-avatar/render`

-AI 数字人渲染请求 `titles[]` 每项结构，字段名与类型如下：
+```jsonc
+{
+  "lipsync_job_id": "7c29a3b2-...",     // 必填，已 completed 的对口型任务
+  "script_id": "",                       // 可选！见下方说明
+  "b_roll_segments": [],                 // 可选，B-roll 片段
+  "title_config": { ... },               // 可选，单个标题配置 dict（见 §6）
+  "cover_config": { ... },               // 可选，封面配置（建议改用 smart-cover）
+  "project_id": ""
+}
+```

-| 字段 | 类型 | 必填 | 默认 | 说明 |
-|------|------|------|------|------|
-| `text` | string | ✅ | — | 标题文本。**多行用 `\n` 分隔**；内部统一把 `/` 替换为 `／`（drawtext 转义保护） |
-| `start` | float | ✅ | — | 出现时间（秒） |
-| `end` | float | ✅ | — | 消失时间（秒），须 > start |
-| `fontSize` | number | ❌ | 48 | 字号（像素），范围建议 12~200 |
-| `color` | string | ❌ | `white` | 文字颜色，CSS/FFmpeg 颜色名或 `0xRRGGBB`（如 `red`、`0xFF5733`） |
-| `fontPath` | string | ❌ | 内置思源黑体 | 字体文件绝对路径（通常不传，用默认中文字体） |
-| `backgroundColor` | string | ❌ | 黑色 | 背景框颜色 |
-| `borderColor` | string | ❌ | 白色 | 边框颜色 |
-| `borderWidth` | int | ❌ | 2 | 边框宽度（像素） |
-| `backgroundOpacity` | float | ❌ | 0.5 | 背景框不透明度 0~1 |
-| `frame` | object | ❌ | 居中底部 | 画面内位置，见下 |
-| `frame.x` | float | ❌ | `null` | 框中心 X 比例 0~1；null=水平居中 |
-| `frame.y` | float | ❌ | `null` | 框中心 Y 比例 0~1；null=底部（0.75） |
-| `frame.widthRatio` | float | ❌ | 0.9 | 框宽占画面比例 0~1 |
-| `frame.heightRatio` | float | ❌ | 0.2 | 框高占画面比例 0~1 |
-| `z_index` | int | ❌ | 0 | 层级（预留，当前标题在 B-roll 之后） |
-
-**前端注意事项**
- 多行标题直接在 `text` 里写 `\n`，后端按行处理 drawtext 的 `textfile` 换行，无需手工拆滤镜。
- 颜色建议固定传英文颜色名（`white`/`black`/`red`…）或 `0xRRGGBB`，不要传 `#RRGGBB`（`#` 会被滤镜解析干扰）。
- 位置不传 frame 时标题在画面居中偏下（y≈0.75），这是常见口播标题位置。
+**`script_id` 是否必填：可选。**
+- 从文案库选了文案时传对应文案 ID（后端做归属校验）。
+- **手动输入文案、走 TTS 直生模式时不传（留空）即可**——渲染管线不依赖文案内容，`script_id` 仅用于归属校验。留空不会卡手动文案用户。

 ---

-## 6. 前端对接清单
+## 6. 标题配置 `title_config` 字段清单（以 build_title_drawtext_filter 为准）
+
+渲染请求收的是**单个 `title_config` dict**（不是 `titles[]` 数组），字段与 `packages/domain/video_filter_builder.py` 的 `build_title_drawtext_filter()` 完全对齐：
+
+| 字段 | 别名 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|------|
+| `text` | `content` | string | ✅ | — | 标题文字；为空或 `enabled=false` 时不渲染标题 |
+| `enabled` | — | bool | ❌ | `true` | 是否启用标题；false 跳过 |
+| `font` | `font_preset` | string | ❌ | 思源黑体 | 字体名（后端按名字解析字体文件） |
+| `font_size` | `size` | int | ❌ | 36 | 字号（像素） |
+| `font_color` | `color` | string | ❌ | `#ffffff` | 文字颜色，`#RRGGBB`；后端自动去掉 `#`，也可传 `RRGGBB` 或颜色名 |
+| `position` | — | string | ❌ | `top` | 预设位置：`top`(y=50) / `center`(垂直居中) / `bottom`(底部上移50px) / `custom` |
+| `pos_x` | — | int/float | ❌ | — | 自定义 X 坐标（像素），仅 `position=custom` 生效 |
+| `pos_y` | — | int/float | ❌ | — | 自定义 Y 坐标（像素），仅 `position=custom` 生效 |
+| `bold` | — | bool | ❌ | `true` | 粗体（Bold 字体变体，回退 borderw 模拟） |
+| `stroke` | — | bool/object | ❌ | — | 描边。`true`=黑描边宽2；object 见下 |
+| `stroke.enabled` | — | bool | ❌ | true | 是否描边 |
+| `stroke.width` | — | int | ❌ | 2 | 描边宽度 |
+| `stroke.color` | — | string | ❌ | `#000000` | 描边颜色 |
+| `shadow` | — | bool/object | ❌ | — | 阴影。`true`=黑色阴影偏移2px；object 见下 |
+| `shadow.enabled` | — | bool | ❌ | true | 是否阴影 |
+| `shadow.color` | — | string | ❌ | `#000000` | 阴影颜色 |
+| `shadow.offset_x` | — | int | ❌ | 2 | 阴影 X 偏移 |
+| `shadow.offset_y` | — | int | ❌ | 2 | 阴影 Y 偏移 |
+
+**前端注意事项**
+- 标题是**整条成片一个标题**（单个 dict），不是按时间段的标题数组；没有 `start`/`end`/`frame`/`fontSize` 这些字段。
+- 位置用 `position` 四档枚举；自由摆放用 `position="custom"` + `pos_x`/`pos_y`（像素坐标，非比例）。
+- 颜色统一传 `#RRGGBB` 即可，后端会处理 `#`；三档预设位置下标题始终水平居中。
+- `stroke`/`shadow` 传 `true` 用默认样式，或传 object 精细控制颜色/宽度/偏移。
+
+---
+
+## 7. 前端对接清单

 1. 对口型：改用**模式 A**（voice_id + script_text + speed + emotion），不要再先调 TTS 拿 audio_url。
 2. 音色 ID：`voice_id` 可直接传克隆音色的 profile UUID，后端会解析为 CosyVoice voice_id（与 /tts 一致）。
 3. 情绪下拉：自然/兴奋/沉稳/亲切 → natural/excited/calm/friendly。
 4. 封面：点「智能获取封面」→ POST `/ai-avatar/render/smart-cover`，用返回的 `cover_url`。
-5. 轮询：识别 `running` 等中间态，不要只认 `submitted`。
+5. 渲染：手动文案直生场景 `script_id` 留空；标题传**单个** `title_config` dict（字段见 §6）。
+6. 轮询：识别 `running` 等中间态，不要只认 `submitted`。
@@ -721,7 +721,8 @@ class AiAvatarRenderJob(Base):

    # 输入参数
    lipsync_job_id = Column(String(36), nullable=False)
-    script_id = Column(String(36), nullable=False)
+    # 文案 ID 可选：手动输入文案（TTS 直生）场景不关联文案库条目
+    script_id = Column(String(36), nullable=False, default="")
    b_roll_segments = Column(JSON, nullable=False, default=list)
    # b_roll_segments 格式: [{"script_segment_index": 0, "asset_url": "...", "mode": "fullscreen|pip", "start_time": 5.0, "end_time": 10.0}, ...]
    title_config = Column(JSON, nullable=False, default=dict)
@@ -259,3 +259,26 @@ def test_smart_cover_returns_empty_when_mediakit_unavailable():
        mk_patch.return_value = mk
        url = cov.generate_smart_cover("https://oss/avatar.mp4")
    assert url == ""
+
+
+# ── 渲染 script_id 可选（手动文案直生场景）──────────────────────────────
+
+def test_render_request_script_id_optional():
+    import sys, os
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "apps", "api"))
+    from app.schemas.ai_avatar_render import CreateAiAvatarRenderRequest
+
+    # 手动文案直生：不传 script_id 也合法
+    req = CreateAiAvatarRenderRequest(lipsync_job_id="j-1")
+    assert req.script_id == ""
+
+    # 空白被 strip
+    req2 = CreateAiAvatarRenderRequest(lipsync_job_id="j-1", script_id="   ")
+    assert req2.script_id == ""
+
+    # title_config 是单个 dict
+    req3 = CreateAiAvatarRenderRequest(
+        lipsync_job_id="j-1",
+        title_config={"text": "标题", "position": "top", "font_size": 40},
+    )
+    assert req3.title_config["position"] == "top"