{
  "openapi": "3.0.3",
  "info": {
    "title": "Reality3D LX Queue API",
    "version": "1.0.0",
    "description": "局域网 LX 工程单任务队列。ZIP 必须保留完整采集目录并含唯一 .lx。pointcloud、mesh、3dgs 均允许完整工程没有额外全景图片。写操作要求 X-LX-Request: 1。若配置服务 token，除 health 外的 API 还需 Authorization: Bearer <token>。平台密码只在服务端配置。"
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "健康与版本",
        "responses": {
          "200": {
            "description": "服务在线，含 authRequired"
          }
        }
      }
    },
    "/api/v1/tasks": {
      "get": {
        "summary": "任务列表、等待顺序、当前任务及存储错误",
        "responses": {
          "200": {
            "description": "tasks、queue、activeId、storageError"
          }
        }
      },
      "post": {
        "summary": "上传 ZIP 工程并创建任务（独立上传接口）",
        "parameters": [
          {
            "name": "X-LX-Request",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "pointcloud",
                "mesh",
                "3dgs"
              ]
            }
          },
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "paused",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "true 时上传成功后保持等待暂停，可由 resume 入队执行"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "一个 ZIP，不接受额外 multipart 字段"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "工程已落盘，返回任务 id 和状态；实际解压/处理异步执行"
          },
          "400": {
            "description": "上传格式/大小错误"
          },
          "429": {
            "description": "同时上传数量已满"
          },
          "503": {
            "description": "存储不可用"
          }
        }
      }
    },
    "/api/v1/tasks/{id}": {
      "get": {
        "summary": "查询单个任务",
        "parameters": [
          {
            "$ref": "#/components/parameters/id"
          }
        ],
        "responses": {
          "200": {
            "description": "任务记录，含结果平台 taskId"
          },
          "404": {
            "description": "不存在"
          }
        }
      }
    },
    "/api/v1/tasks/{id}/logs": {
      "get": {
        "summary": "当前尝试的最近 64 KiB 处理日志",
        "parameters": [
          {
            "$ref": "#/components/parameters/id"
          }
        ],
        "responses": {
          "200": {
            "description": "text、attempt"
          }
        }
      }
    },
    "/api/v1/tasks/{id}/derive": {
      "post": {
        "summary": "使用已完成任务的原始工程排队处理另一种成果",
        "description": "type 选择与来源不同的处理类型。返回独立任务及 sourceTaskId，处理成功后自动上传。同一来源和类型的未结束任务会被复用。",
        "parameters": [
          {"$ref": "#/components/parameters/id"},
          {"name": "type", "in": "query", "required": true, "schema": {"type": "string", "enum": ["pointcloud", "mesh", "3dgs"]}},
          {"name": "X-LX-Request", "in": "header", "required": true, "schema": {"type": "string", "enum": ["1"]}}
        ],
        "responses": {
          "202": {"description": "已接收，返回后续任务"},
          "400": {"description": "处理类型错误"},
          "404": {"description": "来源任务不存在"},
          "409": {"description": "来源未完成、来源与目标同类型或 ZIP 无法复用"}
        }
      }
    },
    "/api/v1/tasks/{id}/{action}": {
      "post": {
        "summary": "暂停/继续/取消/置顶/重试",
        "description": "pause 真正挂起运行进程树，仍占执行位；resume 继续。top 仅调整等待顺序。cancel 不删除已上传的平台内容。retry 从工程包重新处理，可能产生新的平台任务。",
        "parameters": [
          {
            "$ref": "#/components/parameters/id"
          },
          {
            "name": "action",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "pause",
                "resume",
                "cancel",
                "top",
                "retry"
              ]
            }
          },
          {
            "name": "X-LX-Request",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "操作成功"
          },
          "409": {
            "description": "状态不允许或进程操作失败"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[a-f0-9]{32}$"
        }
      }
    }
  }
}
