更新canvas 3d接口 ,使用异步mq队列处理

src/routers/generate_3D.py

@@ -114,33 +114,124 @@ async def img_to_3D(request_data: ImageTo3DRequest):
 
 @router.post("/img_to_3D_mq")
 async def img_to_3d_endpoint(request_data: ImageTo3DRequest):
-    result = submit_img_to_3d_task(
+    """
-        input_images=request_data.input_images,
+    ### 接口说明:
-        model=request_data.model
+    将图片转换为3D模型（异步处理）。接口接收请求后立即返回任务ID，后台通过 Celery 处理，处理完成后结果会通过 RabbitMQ 发送。
-    )
 
-    return result
+    ### 参数说明:
+    - **input_images**: 输入图片路径列表（支持单张或多张）
+    - **model**: 推理模式，`single` 表示单张图片，`multi` 表示多张图片融合
+
+    ### 请求体示例:
+    **单张图片模式:**
+    ```json
+    {
+        "input_images": ["test/img_to_3d_data/example/character_1.png"],
+        "model": "single"
+    }
+    **多张图片模式:**
+    ```json
+    {
+        "input_images": [
+            "test/img_to_3d_data/example_multi_image/character_1.png",
+            "test/img_to_3d_data/example_multi_image/character_2.png",
+            "test/img_to_3d_data/example_multi_image/character_3.png"
+        ],
+        "model": "multi"
+    }
+
+    ### 输出示例:
+    ```json
+    {
+        "code": 200,
+        "message": "ok",
+        "data": {
+            "job_id": "b2c3d4e5-f6g7-8901-hijk-lm2345678901",
+            "status": "queued",
+            "message": "任务已进入后台处理"
+        }
+    }
+    ```json
+    {
+        "code": 429,
+        "message": "ok",
+        "data": {
+            "status": "queue_full",
+            "message": "当前 3D 生成请求较多，请稍后重试。",
+            "queue_length": 10,
+            "max_length": 10
+        }
+    }
+    ```json
+    {
+        "code": 500,
+        "message": "ok",
+        "data": {
+            "status": "fail",
+            "message": "提交失败，请稍后重试。",
+            "error": str(e)
+        }
+    }
+
+
+    --------------------------------------------------------------------
+    RabbitMQ 结果消息说明:
+    处理完成后，结果会通过 RabbitMQ 发送到以下位置：
+    Queue: img_to_3d_results
+
+    消息格式:
+    ```json
+    {
+        "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "status": "completed",           // 或 "failed"
+        "timestamp": "2026-04-01T14:35:22.456789",
+        "timestamp_unix": 1743510922,
+        "task_type": "img_to_3d_results",
+        "result": {
+            "glb_path": "test/3d_result/glb/5ebe2fe118c94946bdc379e4d44799d2.glb",
+            "glb_static_img_path": "test/3d_result/png/19c4b60ab7594e3f84e58d0169739bd1.png",
+            "glb_info": {
+                "file_format": ".glb",
+                "vertex_count": 7312,
+                "centroid": [0.001, -0.108, 0.075],
+                "size": [0.468, 0.761, 0.999]
+            }
+        }
+    }
+    status 说明:
+        completed: 处理成功，result 中包含 3D 模型相关路径和信息
+        failed: 处理失败，result 中会包含 error 字段
+    """
+    result = submit_img_to_3d_task(input_images=request_data.input_images, model=request_data.model)
+    if result.get("state") == "success":
+        state_code = 200
+    elif result.get("state") == "queue_full":
+        state_code = 429
+    else:
+        state_code = 500
+
+    return ResponseModel(data=result, code=state_code)
 
 
 @router.post("/3d_to_3views")
 async def to_3views(request_data: ToSVGRequest):
     """
-        ### 参数说明:
+    ### 参数说明:
-            - **minio_glb_path**:glb文件路径
+        - **minio_glb_path**:glb文件路径
 
-        ### 请求体示例:
+    ### 请求体示例:
-        ```json
+    ```json
-            {
+        {
-                "minio_glb_path": "test/3d_result/glb/543570111d344552b080ff6f875e4e83.glb"
+            "minio_glb_path": "test/3d_result/glb/543570111d344552b080ff6f875e4e83.glb"
-            }
+        }
-        ```
+    ```
-        ### 输出示例:
+    ### 输出示例:
-        ```json
+    ```json
-            {
+        {
-                "minio_svg_path": "test/3d_result/svg/bbcd534cffa143bba418148a0db80ad0.svg"
+            "minio_svg_path": "test/3d_result/svg/bbcd534cffa143bba418148a0db80ad0.svg"
-            }
+        }
-        ```
+    ```
-        """
+    """
     try:
         logger.info(
             f"img_to_3D request: {json.dumps(request_data.dict(), indent=4)}"
@@ -168,5 +259,90 @@ async def to_3views(request_data: ToSVGRequest):
 
 @router.post("/3d_to_3views_mq")
 async def to_3views(request_data: ToSVGRequest):
+    """
+    ### 接口说明:
+    将 GLB 3D 模型文件转换为 3 个视图图片（3-views），异步处理。
+
+    ### 参数说明:
+    - **minio_glb_path**: MinIO 中 GLB 文件的完整路径
+
+    ### 请求体示例:
+    ```json
+    {
+        "minio_glb_path": "test/3d_result/glb/543570111d344552b080ff6f875e4e83.glb"
+    }
+
+    ### 输出示例:
+    ```json
+    {
+        "code": 200,
+        "message": "任务已提交",
+        "data": {
+            "job_id": "b2c3d4e5-f6g7-8901-hijk-lm2345678901",
+            "status": "queued",
+            "message": "任务已进入后台处理"
+        }
+    }
+
+     ### 输出示例:
+    ```json
+    {
+        "code": 200,
+        "message": "ok",
+        "data": {
+            "job_id": "b2c3d4e5-f6g7-8901-hijk-lm2345678901",
+            "status": "queued",
+            "message": "任务已进入后台处理"
+        }
+    }
+    ```json
+    {
+        "code": 429,
+        "message": "ok",
+        "data": {
+            "status": "queue_full",
+            "message": "当前 3D 生成请求较多，请稍后重试。",
+            "queue_length": 10,
+            "max_length": 10
+        }
+    }
+    ```json
+    {
+        "code": 500,
+        "message": "ok",
+        "data": {
+            "status": "fail",
+            "message": "提交失败，请稍后重试。",
+            "error": str(e)
+        }
+    }
+    --------------------------------------------------------------------
+    RabbitMQ 结果消息说明:
+    Queue: three_d_to_3views_results
+    消息格式:
+    ```json
+    {
+        "job_id": "b2c3d4e5-f6g7-8901-hijk-lm2345678901",
+        "status": "completed",           // completed 或 failed
+        "timestamp": "2026-04-01T14:36:15.789012",
+        "timestamp_unix": 1743510975,
+        "task_type": "three_d_to_3views_results",
+        "result": {
+            "minio_svg_path": "test/3d_result/svg/bbcd534cffa143bba418148a0db80ad0.svg",
+            "views": ["front", "side", "top"],
+            "status": "success"
+        }
+    }
+    status 说明:
+        completed: 处理成功，result 中包含转换后的视图图片路径
+        failed: 处理失败，result 中会包含 "error" 字段
+    """
     result = submit_three_d_to_3views_task(minio_glb_path=request_data.minio_glb_path)
-    return result
+    if result.get("state") == "success":
+        state_code = 200
+    elif result.get("state") == "queue_full":
+        state_code = 429
+    else:
+        state_code = 500
+
+    return ResponseModel(data=result, code=state_code)