feat(generate): #1970 智能剪辑流程重构 - 选择模式→素材→标题→确认→封面 (#1973)

- script_asr_service.py: 捕获ImportError(apps.worker未安装)，抛ASRNotConfiguredError
- scripts_ai.py B2回退路径: 504超时直接抛出，502/503 ASR/下载错误走desc兜底
- 修复API镜像未打包worker模块导致有旁白视频在MediaKit失败时直接502的问题
- 更新单元测试覆盖ASR失败→desc兜底场景

apps/api/app/api/routes/scripts_ai.py

@@ -443,10 +443,20 @@ def extract_from_douyin(
                         result.source, len(text), time.time() - t0,
                     )
                     last_err_stage = "asr"
-        except HTTPException:
-            raise
+        except HTTPException as exc:
+            # 下载超时（504）是明确的网络错误，直接抛出
+            if exc.status_code == status.HTTP_504_GATEWAY_TIMEOUT:
+                raise
+            # 本地 ASR 不可用/失败（502/503）时记录后继续走 desc 兜底，
+            # 不直接抛 502，避免 API 镜像缺 worker 模块时整条链路挂掉
+            logger.warning("本地 ASR 链路失败(status=%d): %s", exc.status_code, exc.detail)
+            text = ""
+            # 如果是下载失败（非ASR错误），保持stage为download
+            if "语音识别" in str(exc.detail) or "ASR" in str(exc.detail):
+                last_err_stage = "asr"
         except Exception as exc:  # noqa: BLE001
             logger.warning("本地 ASR 链路异常: %s", exc)
+            text = ""
 
     # ── Phase C：结果判定 & 兜底 ──
 

apps/api/app/services/script_asr_service.py

@@ -38,7 +38,12 @@ def transcribe_to_text(media_path: str | Path) -> str:
         ASRTranscriptionError: ASR 调用失败
     """
     # 延迟导入，避免循环依赖和启动时副作用
-    from apps.worker.services.asr_service_factory import get_asr_service
+    try:
+        from apps.worker.services.asr_service_factory import get_asr_service
+    except ImportError as exc:
+        # API 镜像未打包 worker 代码（本地 ASR 依赖 worker 的 asr_service_factory）
+        logger.warning("本地 ASR 不可用（apps.worker 未安装）: %s", exc)
+        raise ASRNotConfiguredError("本地 ASR 服务不可用（worker 模块未安装）") from exc
 
     asr = get_asr_service()
     if asr is None:

tests/unit/test_extract_from_douyin_errors.py

@@ -187,29 +187,39 @@ def test_asr_not_configured_returns_503(fake_user):
 # ── ASR 转写失败 → 502 ────────────────────────────────────────
 
 
-def test_asr_transcription_failure_returns_502(fake_user):
-    """ASR 转写异常 → 502（被 _direct_url_download_and_local_asr 包装）。"""
-    from app.services.script_asr_service import ASRTranscriptionError
+def test_asr_transcription_failure_returns_503_with_desc_fallback(fake_user):
+    """ASR 转写异常（MediaKit+本地都失败）→ desc 兜底；desc 也空则 503。"""
+    from app.api.routes import scripts_ai
+    from app.services.mediakit_client import MediaKitError
+    from fastapi import HTTPException
 
-    scripts_ai = _import_target()
     body = scripts_ai.ExtractFromDouyinRequest(url="https://v.douyin.com/xxxxx/")
 
-    # MediaKit 失败
     fake_mk = mock.MagicMock()
     fake_mk.is_available = True
-    from app.services.mediakit_client import MediaKitError
-
     fake_mk.asr_submit.side_effect = MediaKitError("ASR failed", code="TaskFailed")
 
+    # desc 为空 → 最终 503（stage=asr）
     with _fake_resolver_success(desc=""):
+        with mock.patch("app.api.routes.scripts_ai.get_mediakit_client", return_value=fake_mk):
+            with mock.patch(
+                "app.api.routes.scripts_ai._direct_url_download_and_local_asr",
+                side_effect=HTTPException(status_code=502, detail="语音识别失败: No module named 'apps.worker'"),
+            ):
+                with pytest.raises(HTTPException) as exc:
+                    scripts_ai.extract_from_douyin(request=body, current_user=fake_user, db=mock.MagicMock())
+                assert exc.value.status_code == status.HTTP_503_SERVICE_UNAVAILABLE
+
+    # desc 非空 → desc 兜底成功，返回 200
+    with _fake_resolver_success(desc="这是视频文案描述"):
         with mock.patch("app.api.routes.scripts_ai.get_mediakit_client", return_value=fake_mk):
             with mock.patch(
                 "app.api.routes.scripts_ai._direct_url_download_and_local_asr",
                 side_effect=HTTPException(status_code=502, detail="语音识别失败"),
             ):
-                with pytest.raises(HTTPException) as exc:
-                    scripts_ai.extract_from_douyin(request=body, current_user=fake_user, db=mock.MagicMock())
-                assert exc.value.status_code == status.HTTP_502_BAD_GATEWAY
+                resp = scripts_ai.extract_from_douyin(request=body, current_user=fake_user, db=mock.MagicMock())
+                assert resp.text == "这是视频文案描述"
+                assert resp.duration_seconds == 0.0
 
 
 # ── 下载超时 → 504 ────────────────────────────────────────────