API 集成文档

Authorization: Bearer sk_live_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "success": true,
  "data": { ... }
}

{
  "error": "错误描述信息"
}

{
  "type": "lathe",
  "source": "json",
  "data": {
    "sizes": ["S", "M", "L", "XL", "2XL"],
    "colors": ["白色", "黑色", "蓝色"],
    "demand": {
      "白色": { "S": 120, "M": 200, "L": 180, "XL": 150, "2XL": 80 },
      "黑色": { "S": 100, "M": 180, "L": 160, "XL": 120, "2XL": 60 },
      "蓝色": { "S": 80, "M": 150, "L": 140, "XL": 100, "2XL": 50 }
    }
  },
  "params": {
    "method": "auto",
    "max_layers_per_bed": 150,
    "max_pieces_per_layer": 10,
    "tolerance_over": 2,
    "tolerance_under": 2,
    "max_colors_per_bed": 2,
    "time_limit": 5
  }
}

Content-Type: multipart/form-data
Authorization: Bearer sk_live_xxxx_...

FormData:
  file: (订单数据.xlsx, ≤200KB)
  type: "lathe"

{
  "success": true,
  "data": {
    "tempId": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "originalName": "订单数据.xlsx"
  }
}

{
  "type": "lathe",
  "source": "upload",
  "tempId": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "params": {
    "method": "auto",
    "time_limit": 5
  }
}

{ "tempId": "a1b2c3d4-..." }

→ 响应: { "data": { "sizes": [...], "colors": [...], "demand": {...} } }

{
  "success": true,
  "data": {
    "id": 88,
    "jobNumber": "A3K7-LA-260804-0001",
    "status": "pending"
  }
}

// 运行中
{
  "success": true,
  "data": {
    "id": 88,
    "status": "running",
    "progress": {
      "iteration": 5,
      "best_beds": 12,
      "elapsed_sec": 45.2,
      "status": "improving"
    }
  }
}

// 成功
{
  "success": true,
  "data": {
    "id": 88,
    "status": "success",
    "result": {
      "total_beds": 12,
      "status": "optimal",
      "run_time_sec": 193.5,
      "beds": [
        {
          "bed_id": 1,
          "pattern": { "M": 4, "L": 3, "XL": 3 },
          "layers": { "白色": 20, "黑色": 15 },
          "pieces_per_layer": 10
        }
      ],
      "deviation": [
        { "color": "白色", "size": "S", "demand": 120, "produced": 122, "diff": 2 }
      ]
    }
  }
}

{
  "total_beds": 12,
  "status": "optimal",
  "run_time_sec": 193.5,
  "beds": [
    {
      "bed_id": 1,
      "pattern": { "M": 4, "L": 3, "XL": 3 },
      "layers": { "白色": 20, "黑色": 15 },
      "pieces_per_layer": 10
    }
  ],
  "deviation": [
    { "color": "白色", "size": "S", "demand": 120, "produced": 122, "diff": 2 }
  ]
}

响应: .xlsx 文件二进制流
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Excel 包含三个 Sheet:
  - 分床方案: 每床颜色、各尺码件数、层数、总件数
  - 偏差分析: 各颜色尺码的需求 vs 实际产出偏差
  - 汇总: 总床数、方案状态、求解时间

FormData: file (.xlsx, ≤200KB), type = "pcb"

{ "source": "upload", "tempId": "uuid-from-upload" }

{
  "type": "pcb",
  "source": "upload",
  "tempId": "uuid-from-upload",
  "originalName": "PCB订单.xlsx",
  "params": {
    "component_spacing": 1.6,
    "margin": 7.0,
    "min_orders_per_panel": 3,
    "max_extra_qty": 1,
    "max_extra_ratio": 0.1,
    "over_production_ratio": 0.03,
    "panel_sizes": "600 500",
    "time_minutes": 5
  }
}

FormData: file (.plt, ≤10MB), type = "fabric"

{
  "type": "fabric",
  "source": "upload",
  "tempId": "uuid-from-upload",
  "originalName": "裁片.plt",
  "params": {
    "strip_height": 1480,
    "time_minutes": 3
  }
}

FormData: file (.xlsx, ≤10MB, 支持多文件), type = "transaction"

响应: { "data": { "tempIds": ["uuid-1", "uuid-2"], "originalNames": [...] } }

{
  "type": "transaction",
  "source": "upload",
  "tempIds": ["uuid-1", "uuid-2"],
  "params": {
    "target_month": "2026-07",
    "target_mode": "ratio",
    "target_ratio": 0.15,
    "tolerance": 0.10,
    "amount_column": "收款金额",
    "time_column": "收款时间",
    "time_limit": 2
  }
}

方式二: GET /api/transaction/export/:id → 返回 .xlsx 结果文件

响应:
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 88,
        "jobNumber": "A3K7-LA-260804-0001",
        "type": "lathe",
        "status": "success",
        "createdAt": "2026-08-04T10:00:00.000Z",
        "completedAt": "2026-08-04T10:03:15.000Z",
        "totalBeds": 12,
        "runTimeSec": 193.5
      }
    ],
    "total": 15,
    "page": 1,
    "pageSize": 20
  }
}

DELETE /api/jobs/:id

行为:
  pending → 标记为 canceled
  running → 中止进程，标记为 canceled
  其他状态 → 软删除（从列表隐藏）

POST /api/jobs/:id/stop

仅对 running 状态有效。算法会在下一个检查点退出，返回当前最优解。

import requests
import time

BASE_URL = "https://norai.cn/api"
API_KEY = "sk_live_a3k7_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 步骤 1: 直接提交任务 (无需上传文件)
resp = requests.post(f"{BASE_URL}/jobs",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "type": "lathe",
        "source": "json",
        "data": {
            "sizes": ["S", "M", "L", "XL", "2XL"],
            "colors": ["白色", "黑色", "蓝色"],
            "demand": {
                "白色": {"S": 120, "M": 200, "L": 180, "XL": 150, "2XL": 80},
                "黑色": {"S": 100, "M": 180, "L": 160, "XL": 120, "2XL": 60},
                "蓝色": {"S": 80, "M": 150, "L": 140, "XL": 100, "2XL": 50},
            },
        },
        "params": {"method": "auto", "time_limit": 5},
    })
job_id = resp.json()["data"]["id"]

# 步骤 2: 轮询状态
while True:
    resp = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=headers)
    data = resp.json()["data"]
    if data["status"] in ("success", "failure"):
        break
    time.sleep(3)

# 步骤 3: 获取结果
if data["status"] == "success":
    # 方式一: JSON 结果 (已在轮询响应中, 推荐)
    result = data["result"]
    print(f"完成! 总床数: {result['total_beds']}")
    print(f"床方案: {result['beds']}")

    # 方式二: 导出 Excel 文件
    resp = requests.get(f"{BASE_URL}/lathe/export/{job_id}", headers=headers)
    with open("result.xlsx", "wb") as f:
        f.write(resp.content)

# 直接提交 JSON 任务 (推荐, 无需上传文件)
curl -X POST https://norai.cn/api/jobs \
  -H "Authorization: Bearer sk_live_a3k7_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lathe",
    "source": "json",
    "data": {"sizes":["S","M","L"],"colors":["白色"],
             "demand":{"白色":{"S":100,"M":200,"L":150}}},
    "params": {"method":"auto","time_limit":5}
  }'

# 查询状态 (轮询直到 status 为 success/failure)
curl https://norai.cn/api/jobs/88 \
  -H "Authorization: Bearer sk_live_a3k7_xxxx..."

# 导出 Excel (可选, JSON 结果已在上一步响应中)
curl -o result.xlsx https://norai.cn/api/lathe/export/88 \
  -H "Authorization: Bearer sk_live_a3k7_xxxx..."

# --- 若数据来源为 Excel 文件, 使用上传流程 ---
# 上传文件
curl -X POST https://norai.cn/api/upload \
  -H "Authorization: Bearer sk_live_a3k7_xxxx..." \
  -F "file=@订单数据.xlsx" -F "type=lathe"

# 解析数据
curl -X POST https://norai.cn/api/lathe/parse-upload \
  -H "Authorization: Bearer sk_live_a3k7_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{"tempId": "uuid-from-upload"}'

# 提交任务 (source=upload 需要 tempId + data)
curl -X POST https://norai.cn/api/jobs \
  -H "Authorization: Bearer sk_live_a3k7_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "lathe", "source": "upload",
    "tempId": "uuid-from-upload",
    "data": {"sizes":["S","M","L"],"colors":["白色"],
             "demand":{"白色":{"S":100,"M":200,"L":150}}},
    "params": {"method":"auto","time_limit":5}
  }'

const API_KEY = "sk_live_a3k7_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const BASE = "https://norai.cn/api";
const headers = { Authorization: `Bearer ${API_KEY}` };

// 直接提交 JSON 任务
const jobResp = await fetch(`${BASE}/jobs`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "lathe",
    source: "json",
    data: {
      sizes: ["S", "M", "L"],
      colors: ["白色", "黑色"],
      demand: { "白色": { S: 100, M: 200, L: 150 }, "黑色": { S: 80, M: 160, L: 120 } },
    },
    params: { method: "auto", time_limit: 5 },
  }),
});
const { data: job } = await jobResp.json();

// 轮询
let result;
while (true) {
  const resp = await fetch(`${BASE}/jobs/${job.id}`, { headers });
  const { data } = await resp.json();
  if (data.status === "success") { result = data.result; break; }
  if (data.status === "failure") throw new Error(data.errorMessage);
  await new Promise(r => setTimeout(r, 3000));
}
console.log("总床数:", result.total_beds);