From 095e203fe60f738e3dd90e1e31a1a5d7d807021e Mon Sep 17 00:00:00 2001
From: Jerry Yan <792602257@qq.com>
Date: Sat, 17 Jan 2026 16:22:01 +0800
Subject: [PATCH] =?UTF-8?q?feat(task):=20=E5=A2=9E=E5=BC=BA=E7=B4=A0?=
 =?UTF-8?q?=E6=9D=90URL=E5=A4=84=E7=90=86=E5=92=8C=E9=AA=8C=E8=AF=81?=
 =?UTF-8?q?=E9=80=BB=E8=BE=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加详细的get_material_url方法文档说明优先级逻辑
- 新增get_source_ref方法用于获取素材源引用
- 新增get_bound_material_url方法用于获取绑定素材URL
- 在视频渲染处理器中添加HTTP URL格式验证检查
- 当素材URL格式无效时返回详细错误信息和调试日志
- 验证失败时返回E_SPEC_INVALID错误码并提示服务器需提供有效的boundMaterialUrl
---
 domain/task.py           | 18 +++++++++++++++++-
 handlers/render_video.py | 15 +++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/domain/task.py b/domain/task.py
index b23134c..7cac821 100644
--- a/domain/task.py
+++ b/domain/task.py
@@ -350,9 +350,25 @@ class Task:
         return int(self.payload.get('durationMs', 5000))
 
     def get_material_url(self) -> Optional[str]:
-        """获取素材 URL"""
+        """
+        获取素材 URL
+
+        优先使用 boundMaterialUrl（实际可下载的 HTTP URL），
+        如果不存在则回退到 sourceRef（可能是 slot 引用）。
+
+        Returns:
+            素材 URL，如果都不存在返回 None
+        """
         return self.payload.get('boundMaterialUrl') or self.payload.get('sourceRef')
 
+    def get_source_ref(self) -> Optional[str]:
+        """获取素材源引用（slot 标识符，如 device:xxx）"""
+        return self.payload.get('sourceRef')
+
+    def get_bound_material_url(self) -> Optional[str]:
+        """获取绑定的素材 URL（实际可下载的 HTTP URL）"""
+        return self.payload.get('boundMaterialUrl')
+
     def get_render_spec(self) -> RenderSpec:
         """获取渲染规格"""
         return RenderSpec.from_dict(self.payload.get('renderSpec'))
diff --git a/handlers/render_video.py b/handlers/render_video.py
index acc4e98..de3dd98 100644
--- a/handlers/render_video.py
+++ b/handlers/render_video.py
@@ -46,6 +46,21 @@ class RenderSegmentVideoHandler(BaseHandler):
                     "Missing material URL (boundMaterialUrl or sourceRef)"
                 )
 
+            # 检查 URL 格式：必须是 HTTP/HTTPS 协议
+            if not material_url.startswith(('http://', 'https://')):
+                source_ref = task.get_source_ref()
+                bound_url = task.get_bound_material_url()
+                logger.error(
+                    f"[task:{task.task_id}] Invalid material URL format: '{material_url}'. "
+                    f"boundMaterialUrl={bound_url}, sourceRef={source_ref}. "
+                    f"Server should provide boundMaterialUrl with HTTP URL."
+                )
+                return TaskResult.fail(
+                    ErrorCode.E_SPEC_INVALID,
+                    f"Invalid material URL: '{material_url}' is not a valid HTTP URL. "
+                    f"Server must provide boundMaterialUrl."
+                )
+
             render_spec = task.get_render_spec()
             output_spec = task.get_output_spec()
             duration_ms = task.get_duration_ms()