开始之前
- 管理端已创建设备并拿到设备令牌
- 已有供应商门户账号（企业编码 + 账号 + 密码）
- 能访问后端域名
操作步骤
认清两条入口的鉴权差异
设备上报走 /api/iot/*，请求头 X-Device-Token，服务端按 sha256 反查设备，不走 JWT；供应商门户走 /api/supplier-portal/*，先登录换 JWT，token 里带 scope=supplier，只能调用门户接口。两者的令牌不能混用。
设备上报按批次提交
POST /api/iot/ingest，body 里带 device_code、batch_id、ts 与 metrics 数组。batch_id 建议用「设备号 + 时间窗」，同一批次重复提交由服务端幂等处理。单条循环上报在低频场景可用，高频建议合并。
历史数据用 CSV 补
POST /api/iot/ingest/csv 支持批量导入，适合停机改造后补历史。注意时间列要与 metrics 编码对齐，否则会出现「有读数但算不出 OEE」。
供应商登录与调用
POST /api/supplier-portal/auth/login，body 为 tenant_code、username、password，返回 access_token。之后用 Authorization: Bearer 调 /orders、/orders/{id}/accept、/orders/{id}/ship、/delivery-notes、/statements。供应商只能看到自己企业的数据，越权返回 404 而不是 403，避免探测。
其它新增接口按需接
APS：/api/admin/aps/gantt、/api/admin/aps/items/{id}/move；OEE：/api/admin/oee/summary、/trend；安灯：/api/admin/andon/calls；EMS：/api/admin/ems/readings、/summary；成本差异：/api/admin/erp/variance/report；召回：/api/admin/trace/recall/analyze、/recall/tasks；预测维护：/api/admin/maintenance/predictions。全部遵循统一 {code,msg,data} 信封与 offset/limit 分页。
上线前做三件事
① 设备令牌按设备单独发放，不要全厂共用一个；② 供应商账号按供应商单独建，换联系人先停用旧账号；③ 给集成账号最小权限角色，不要用管理员账号换 token。
代码示例
curl -X POST 'https://YOUR_HOST/api/iot/ingest' \
-H 'Content-Type: application/json' \
-H 'X-Device-Token: DEVICE_TOKEN' \
-d '{
"device_code": "C01-CNC-03",
"batch_id": "C01-CNC-03-202611130930",
"metrics": [
{"code": "run_status", "value": "run"},
{"code": "output_count", "value": 128},
{"code": "good_count", "value": 125}
]
}'
# {"code":200,"msg":"","data":{"accepted":3}}# 1) 登录
curl -X POST 'https://YOUR_HOST/api/supplier-portal/auth/login' \
-H 'Content-Type: application/json' \
-d '{"tenant_code":"YOUR_TENANT","username":"supplier01","password":"********"}'
# 2) 接单（TOKEN 为上面返回的 access_token）
curl -X POST 'https://YOUR_HOST/api/supplier-portal/orders/123/accept' \
-H 'Authorization: Bearer TOKEN'示例中的域名、租户编码、密钥请替换成你自己的。生产环境不要把密钥写进前端代码。