# 源奥搅拌 · 选型核算 API

给 agent 的接入说明。**本页自包含**：读完即可调用，不需要额外文档。
机器可读规格：`/openapi.json`　｜　索引：`/llms.txt`

---

## 1. 认证

所有接口都要两个请求头：

| 请求头 | 说明 |
|---|---|
| `X-Api-Key` | 你的令牌。由源奥发放，不要外传、不要写进代码仓库 |
| `X-Client-Id` | 调用方标识，自定义字符串（如 `my-agent-01`），用于留痕 |

缺令牌／令牌无效 → `401`。令牌未绑定设备时首次调用即绑定；要换设备需先解绑。

**正式环境**：`https://yuanaoapi.chilintu.com`

---

## 2. 接口一览

| 方法 | 路径 | 用途 | 输入形态 |
|---|---|---|---|
| GET | `/api/options` | 取可选清单（材质 / 桨型 / 机架 / 减速机 / 管规格等） | 无 |
| POST | `/api/pick` | 初步方案推荐：给根输入 + 目标转速 → 推荐配置 + 分档参考 | **嵌套**：`{"input": {...}, "output_speed_rpm": 63}` |
| POST | `/api/calc` | 核算：给完整输入 → 校核结论 + 机械计算数据 | **平铺**：所有字段在顶层 |

### 先取清单再调用

`/api/options` 返回的全部是**当前引擎认的合法取值**，先取一次再拼请求，能避免 90% 的 400。

```bash
curl -s https://yuanaoapi.chilintu.com/api/options \
  -H "X-Api-Key: $YA_KEY" -H "X-Client-Id: my-agent-01"
```

---

## 3. 输入字段

`/api/calc` 平铺写法（`/api/pick` 把同样的内容放进 `input` 里）：

```json
{
  "project_name": "某某项目",
  "medium_type": "矿浆",
  "medium": { "sg": 1.25 },
  "material": "304L SS",
  "service_factor": 1.5,
  "tank": { "overall_height_mm": 5000 },
  "tank_dia_mm": 6500,
  "tank_depth_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" }
}
```

| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
| `project_name` | string | — | 项目名称。选填；填了会记进核验书，便于回溯 |
| `medium_type` | string | — | 介质类型，如 `矿浆` |
| `medium.sg` | number | — | 介质比重（相对水），如 `1.25` |
| `material` | string | — | 材质，取值见 `/api/options`（如 `304L SS`） |
| `service_factor` | number | — | 安全系数 Fs。只放大径向力→弯矩→最小轴径；**不影响扭矩和临界转速**。默认 1.5 |
| `tank.overall_height_mm` | number | mm | 池深（有效水深）。**计算只用这一个池体尺寸** |
| `tank_dia_mm` | number | mm | 池内径／边长／长。工艺指标用；核算页对经销商、销售必填 |
| `tank_depth_mm` | number | mm | 池深（与 `tank.overall_height_mm` 同义，落库用） |
| `impellers` | array | — | 桨叶层，**从上到下**排列。每层一个对象 |
| `impellers[].type` | string | — | 桨型，如 `YO4` |
| `impellers[].d_mm` | number | mm | 桨叶直径 |
| `impellers[].clearance_mm` | number | mm | 该层离池底距离 |
| `motor.power_kw` | number | kW | 电机功率 |
| `motor.motor_rpm` | number | rpm | 电机额定转速（4 极工频约 1470） |
| `motor.output_speed_rpm` | number | rpm | 输出转速（搅拌轴转速） |
| `shaft.selected_dia_mm` | number | mm | 驱动轴（上部实心轴）直径 |
| `shaft.pipe_mount_mm` | number | mm | 空心管起点深度 |
| `shaft.pipe_size` | string \| object | — | 空心管规格。**两种写法见下** |

### 空心管规格的两种写法

```json
"pipe_size": "150NB SCH 40"
```
从 `/api/options` 的管规格清单里选（按名称查表）。

```json
"pipe_size": { "od_mm": 168.3, "t_mm": 7.1 }
```
**手动录入管径**：给外径和壁厚即可，用于非标管。内核按圆环截面直接算，不查表。

---

## 4. 输出

### `/api/pick` 返回

```json
{
  "ok": true, "engine": "mixer_pick", "ms": 42,
  "推荐": { "电机功率_kw": 30.0, "减速机型号": "RF147", "输出转速_rpm": 63.0, "...": "..." },
  "result": { "tiers": { "空心支": {...}, "实心支": {...} }, "...": "..." }
}
```

- **`推荐`** —— 推荐配置清单（扁平键值）
- **`result.tiers`** —— 分档参考。两个支系（`空心支` 实心轴+空心管 / `实心支` 全实心轴），每支若干档（`临界档` / `优选档` / `土豪档` / `内部保留档`）
- 每档含 `verdict`：`{ "总体档": "合格", "结论": [ { "项": "驱动轴强度", "档": "合格" }, ... ] }`

**按角色推送的档位数量不同**（见第 6 节）。

### `/api/calc` 返回

```json
{ "ok": true, "engine": "mixercalc", "algo_fp": "...", "result": { "...": "..." } }
```

`result` 里是校核结论与机械计算数据。**字段随调用方角色裁剪**（见第 6 节）。

---

## 5. 错误码

| 状态码 | 含义 | 处理 |
|---|---|---|
| `401` | 令牌无效（缺失或不对） | 检查 `X-Api-Key` |
| `403` | 令牌绑定到别的设备 | 联系源奥解绑 |
| `400` | 参数错误 | 响应 `error` 里有具体原因，如「材质无效」「核算必填项缺失：…」 |
| `429` | 调用超频或当日额度用尽 | 按限制降速；响应里有原因 |
| `500` | 内部错误 | 已留痕；重试或联系源奥 |

`400` 一律附可读原因，**照做即可**。

---

## 6. 各角色可见范围

角色线性嵌套：**核心 > 销售 > 经销商**。同一接口，不同角色拿到的东西不同。

| 场景 | 核心 | 销售 | 经销商 |
|---|---|---|---|
| 推荐页可推档位 | 全部（临界档 / 优选档 / 土豪档 / 内部保留档） | 合格 + 良 + 优秀（不含内部保留档） | **仅 良 + 优秀** |
| 机械校核原始量（弯矩 / 最小轴径 / 截面模数 / 临界转速及其比值 / 等效重量 / 轴向力 / 候选表） | ✅ | ❌ | ❌ |
| 重量数据 | ✅ | ✅ | ❌ |
| 核算页必填项 | 不卡 | 卡（项目名称 / 介质类型 / 池内径或边长） | 卡（同左） |

**口径预览**：核心账号可带 `"preview_role": "sales"` 或 `"dealer"` 预演对方看到的范围 —— **只改可见范围，不改真实角色、不提权**。该参数在 `/api/calc` 放顶层，在 `/api/pick` 放 `input` 里。

**永不返回**：`steps`、`k_force`（任何角色、任何情况）。

---

## 7. 最小可跑示例

### curl

```bash
export YA_KEY="<你的令牌>"

# 1) 取清单
curl -s https://yuanaoapi.chilintu.com/api/options \
  -H "X-Api-Key: $YA_KEY" -H "X-Client-Id: my-agent-01"

# 2) 推荐（注意：是嵌套 input）
curl -s https://yuanaoapi.chilintu.com/api/pick \
  -H "X-Api-Key: $YA_KEY" -H "X-Client-Id: my-agent-01" \
  -H "Content-Type: application/json" \
  -d '{"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}'

# 3) 核算（注意：是平铺）
curl -s https://yuanaoapi.chilintu.com/api/calc \
  -H "X-Api-Key: $YA_KEY" -H "X-Client-Id: my-agent-01" \
  -H "Content-Type: application/json" \
  -d '{"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"}}'
```

### Python

```python
import requests

BASE = "https://yuanaoapi.chilintu.com"
H = {"X-Api-Key": YA_KEY, "X-Client-Id": "my-agent-01"}

opts = requests.get(f"{BASE}/api/options", headers=H, timeout=30).json()

r = requests.post(f"{BASE}/api/calc", headers=H, timeout=60, json={
    "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"},
}).json()
if not r.get("ok"):
    raise RuntimeError(r.get("error"))
result = r["result"]
```

---

## 8. 给 agent 的接入检查单

1. `GET /api/options` —— 拿到合法取值表（材质 / 桨型 / 机架 / 管规格）
2. 组装输入 —— 池深用 `tank.overall_height_mm`；桨叶**从上到下**；空心管可用名称或 `{od_mm, t_mm}`
3. `POST /api/pick` —— 注意 `input` 嵌套；拿 `推荐` + `result.tiers`
4. `POST /api/calc` —— 注意平铺；拿 `result`
5. 按第 6 节判断本角色能看到哪些字段，**不要把看不到的字段名写进你的流程**

排错优先看响应里的 `error` 字段（`400` / `429` 都带可读原因）。

---

*本页由源奥研发侧维护。接口变更时同步更新此页，无需另行通知。*