{
  "openapi": "3.0.3",
  "info": {
    "title": "源奥搅拌 · 选型核算 API",
    "version": "1.0.0",
    "description": "搅拌器选型核算。认证：X-Api-Key（源奥发放）+ X-Client-Id（调用方标识）。先调 GET /api/options 取合法取值。详细说明见 https://yuanaoapi.chilintu.com/docs.md"
  },
  "servers": [{ "url": "https://yuanaoapi.chilintu.com" }],
  "components": {
    "securitySchemes": {
      "YaApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" },
      "YaClientId": { "type": "apiKey", "in": "header", "name": "X-Client-Id" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "enum": [false] },
          "error": { "type": "string", "description": "可读错误原因，照做即可" }
        }
      },
      "Impeller": {
        "type": "object",
        "required": ["type", "d_mm", "clearance_mm"],
        "properties": {
          "type": { "type": "string", "description": "桨型，取值见 /api/options，如 YO4" },
          "d_mm": { "type": "number", "description": "桨叶直径 (mm)" },
          "clearance_mm": { "type": "number", "description": "该层离池底距离 (mm)" }
        }
      },
      "PipeSize": {
        "oneOf": [
          { "type": "string", "description": "管规格名（查表），如 150NB SCH 40" },
          {
            "type": "object",
            "description": "手动录入管径（非标管，不查表）",
            "required": ["od_mm", "t_mm"],
            "properties": {
              "od_mm": { "type": "number", "description": "管外径 (mm)" },
              "t_mm": { "type": "number", "description": "管壁厚 (mm)" }
            }
          }
        ]
      },
      "CalcInput": {
        "type": "object",
        "properties": {
          "project_name": { "type": "string", "description": "项目名称，选填" },
          "medium_type": { "type": "string", "description": "介质类型，如 矿浆" },
          "medium": {
            "type": "object",
            "properties": { "sg": { "type": "number", "description": "介质比重，如 1.25" } }
          },
          "material": { "type": "string", "description": "材质，取值见 /api/options，如 304L SS" },
          "service_factor": { "type": "number", "description": "安全系数 Fs，默认 1.5 或省略；只影响径向力→弯矩→最小轴径" },
          "tank": {
            "type": "object",
            "description": "池体。计算只认 overall_height_mm",
            "properties": { "overall_height_mm": { "type": "number", "description": "池深 (mm)" } }
          },
          "tank_dia_mm": { "type": "number", "description": "池内径/边长 (mm)，工艺指标用" },
          "tank_depth_mm": { "type": "number", "description": "池深 (mm)，落库用" },
          "impellers": { "type": "array", "items": { "$ref": "#/components/schemas/Impeller" }, "description": "桨叶层，从上到下" },
          "motor": {
            "type": "object",
            "properties": {
              "power_kw": { "type": "number", "description": "电机功率 (kW)" },
              "motor_rpm": { "type": "number", "description": "电机额定转速 (rpm)，4 极工频约 1470" },
              "output_speed_rpm": { "type": "number", "description": "输出转速 (rpm)" }
            }
          },
          "shaft": {
            "type": "object",
            "properties": {
              "selected_dia_mm": { "type": "number", "description": "驱动轴（上部实心轴）直径 (mm)" },
              "pipe_mount_mm": { "type": "number", "description": "空心管起点深度 (mm)" },
              "pipe_size": { "$ref": "#/components/schemas/PipeSize" }
            }
          },
          "preview_role": {
            "type": "string",
            "enum": ["sales", "dealer"],
            "description": "口径预览，仅核心账号生效。核算放顶层；推荐放 input 里"
          }
        }
      }
    }
  },
  "security": [{ "YaApiKey": [], "YaClientId": [] }],
  "paths": {
    "/api/options": {
      "get": {
        "summary": "取可选清单",
        "description": "返回引擎当前认的合法取值（材质/桨型/机架/减速机/管规格等）。先调这个再拼请求，可避免绝大多数 400。",
        "responses": {
          "200": { "description": "取值清单" },
          "401": { "description": "令牌无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/pick": {
      "post": {
        "summary": "初步方案推荐",
        "description": "注意：输入是嵌套的 —— input 包根输入，output_speed_rpm 在顶层。返回 推荐 + result.tiers（按角色推送的档位数不同：经销商 良+优秀；销售 合格+良+优秀；核心 全部）。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input", "output_speed_rpm"],
                "properties": {
                  "input": { "$ref": "#/components/schemas/CalcInput" },
                  "output_speed_rpm": { "type": "number", "description": "输出转速 (rpm)，必须 > 0" }
                }
              },
              "example": {
                "input": {
                  "medium": { "sg": 1.25 },
                  "material": "304L SS",
                  "service_factor": 1.5,
                  "tank": { "overall_height_mm": 5000 },
                  "impellers": [{ "type": "YO4", "d_mm": 2500, "clearance_mm": 800 }]
                },
                "output_speed_rpm": 63
              }
            }
          }
        },
        "responses": {
          "200": { "description": "推荐配置 + 分档参考" },
          "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/calc": {
      "post": {
        "summary": "核算",
        "description": "注意：输入是平铺的（字段直接在顶层）。返回 result，字段按调用方角色裁剪（前台显示与回调一致）。经销商/销售缺 项目名称·介质类型·池内径或边长 会被 400 拦住并报缺项；核心不卡。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CalcInput" },
              "example": {
                "medium": { "sg": 1.25 },
                "material": "304L SS",
                "service_factor": 1.5,
                "tank": { "overall_height_mm": 5000 },
                "impellers": [{ "type": "YO4", "d_mm": 2500, "clearance_mm": 800 }],
                "motor": { "power_kw": 30, "motor_rpm": 1470, "output_speed_rpm": 63 },
                "shaft": { "selected_dia_mm": 125, "pipe_mount_mm": 800, "pipe_size": "150NB SCH 40" }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "校核结论 + 机械计算数据（按角色裁剪）" },
          "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "超频或额度用尽", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  }
}