🔌 接口说明

这里提供给程序调用方的接口（简道云插件、智能助手、其他系统）。网页上手工使用的，不用看这一页。

1. 健康检查（探活用）

GET /api/v1/health

返回：{"ok": true, "service": "研发助手", "version": "1.0.0"}

2. 原料清单导入模板生成

传一份业务数据 Excel（base64），返回成品模板（base64）和校验结果。

POST /api/v1/tools/material-import/run
请求头：Content-Type: application/json
        X-API-Token: <平台令牌>      ← 服务端配置了令牌才需要

请求体：
{
  "filename": "业务数据.xlsx",
  "content_b64": "<Excel 文件内容的 base64 字符串>"
}

返回：
{
  "ok": true,
  "sheet": "业务填写",                  // 实际识别的工作表
  "stats": {"rows": 63, "groups": 46, "errors": 0, "warns": 0},
  "problems": [ ["错误","行12","RA0000xxx","字段","问题描述"], ... ],
  "filename": "原料清单-导入模板.xlsx",
  "file_b64": "<成品 xlsx 的 base64>"
}

调用示例（命令行）：

curl -s -X POST https://cos-dev-assist.flagwhale.com/api/v1/tools/material-import/run \
  -H "Content-Type: application/json" \
  -H "X-API-Token: 你的令牌" \
  -d "{\"content_b64\": $(base64 -i 业务数据.xlsx)}"

3. 函数统一调用入口（给插件/智能助手用）

在开发工作台里发布的函数，都可以通过这个统一入口调用；参数即函数里配置的请求参数。

POST /api/v1/fn/<函数ID>/run
请求头：Content-Type: application/json
        X-API-Token: <平台令牌>      ← 服务端配置了令牌才需要

请求体：
{
  "params": { "参数ID": "值", ... }
}

返回：
{
  "ok": true,
  "result": { ...函数返回的字典... },
  "stdout": "运行日志（尾部）",
  "duration_ms": 42
}

失败时 ok=false，error 里带错误堆栈；函数未发布返回 404。

4. 后续会上线的接口

原料合规查询、配方拆分计算、哈希值计算等会陆续在工作台上架，接口风格与上面一致；
所有接口统一用 X-API-Token 令牌鉴权，返回结构统一带 ok 字段；
接入前联系管理员开通令牌。