5.2 KiB
5.2 KiB
APS 对平台的契约草案（B0.2 → B5 输入）
两侧唯一的界面就是这份契约：平台通过
providers/aps的适配器调它，APS 不 import 平台代码。首版只读优先——写能力先列出来定形状，实现放在 A6/B6 之后。能力描述七要素见
docs/spec/capability-description.md（平台侧同一份规范）。
1 传输形状
| 项 | 约定 |
|---|---|
| 端点 | POST /api/capabilities/{capabilityId} |
| 请求体 | { "params": {}, "executionId": "...", "idempotencyKey": "...", "deadlineAt": 0, "identity": { "accountId": "..." } } |
| 响应体 | 与平台 contracts/schemas/receipt.schema.json 的 ExecutionReceipt 同形：{ executionId, status, result?, errorKind?, approvalId? } |
| 健康 | GET /api/health → `{ status: "ok" |
| 清单 | GET /api/manifest → ProviderManifest（id / displayName / version / platformVersion / requiresIdentity / auth / capabilities） |
| 鉴权 | 服务间令牌 + 身份透传（identity.accountId）。权限由 APS 自己校验（D9：权限归业务系统），平台放行不代表 APS 放行 |
| 超时 | deadlineAt 由平台给，APS 尽力遵守；超时不等于失败，平台按「结果未知」处理 |
| 版本 | platformVersion: 1；能力 schema 只加不改，改语义换 capabilityId |
2 只读能力（B5 首批实现）
| capabilityId | 一句话用途（≤40 字） | effect | mode | 幂等 | 何时不用 | 同义词 |
|---|---|---|---|---|---|---|
aps.master.query |
查物料、工序、设备等主数据 | read | sync | none | 要改主数据请用主数据维护流程 | 主数据、基础资料、物料表 |
aps.orders.query |
查订单与交期承诺状态 | read | sync | none | 要看排产结果用 aps.schedule.query |
订单、交期、承诺日期 |
aps.capacity.query |
查产能池与负荷分布 | read | sync | none | 要看某版方案的负荷用 aps.schedule.query |
产能、负荷、能力池 |
aps.calendar.query |
查工厂日历、班次与换型字典 | read | sync | none | 不用于查排产结果 | 日历、班次、换型、setup |
aps.routing.query |
查工艺路线模板与工序顺序 | read | sync | none | 图纸解析在 aps.drawing.parse |
工艺路线、工序、路线模板 |
aps.schedule.query |
查现有排产方案与执行结果 | read | sync | none | 要新算一版用 aps.schedule.preview |
排产结果、计划、方案 |
aps.exceptions.query |
查缺料、冲突与超期等异常 | read | sync | none | 要看某个订单细节用 aps.orders.query |
异常、冲突、缺料、超期 |
参数 schema 一律：{ "project": string(必填，默认当前项目), "filters": object(可选) }，把枚举与单位写进描述；返回 { items: [], total: number, asOf: string }（asOf 是数据时点，供界面显示"数据截至"）。
3 草稿与写能力（形状先定，实现后置）
| capabilityId | 用途 | effect | mode | 幂等 | 说明 |
|---|---|---|---|---|---|
aps.schedule.preview |
按当前数据试排一版，只出结果不发布 | draft | async | natural | 返回 jobId；结果进隔离草稿，不碰 APS 生产数据 |
aps.schedule.publish |
把指定版本方案发布到 APS | write | async | key | 必须带 revision（目标数据版本）；平台侧先出确认卡（A4.4） |
aps.orders.upsert |
新增或修改订单 | write | sync | key | 需要业务系统的写权限；平台不代替它判断 |
aps.drawing.parse |
把图纸解析成工艺信息 | draft | async | natural | 入参是平台上传后的文件引用，APS 不接收文件本身 |
draft 与 write 的关键区别：draft 只写隔离草稿、不碰生产数据，因此不走确认卡；write 一律走确认卡（平台策略层已实现）。
4 错误映射
| APS 侧情况 | errorKind |
|---|---|
| 参数缺失、类型错、枚举越界 | invalid_argument |
| 当前账号在该 APS 里没有这个权限 | forbidden |
| 版本冲突、并发修改 | conflict |
| 求解器等资源排队 | rate_limited |
| APS 不可用、依赖系统不可用 | unavailable |
| 超时、部分完成、无法判断 | unknown_result |
只有 rate_limited 与 unavailable 允许平台自动重试；其余一律不重试（平台 Core 已按此实现）。
5 与平台侧的对齐检查
| 检查 | 方式 |
|---|---|
| 清单形状 | GET /api/manifest 的返回能通过平台 ProviderManifest 类型校验 |
| 能力描述七要素 | 跑平台 pnpm check:capabilities 同一套规则（B5 时把规则提到契约里，两侧共用） |
| 契约测试 | 平台 runProviderContract 对 APS 适配器跑一遍（A2.4 已实现） |
| 只读验收 | A5.6 在真实 APS 上完成一次查询并留证 |
6 待定
| 项 | 说明 | 定的时机 |
|---|---|---|
| 契约用 HTTP 还是进程内 | 首版 Provider 可跑在平台信任域内（实施设计 5），跨进程是外部团队接入的形态 | B5 实现时按部署形态定 |
aps.schedule.preview 的结果存放 |
方案结果落 APS 库还是平台产物区 | B5 |
| 图纸文件引用形式 | 平台产物 id 还是 URL | 与 drawing.parse 一起定 |