# 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"|"degraded"|"down", detail?, checkedAt }` |
| 清单 | `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` 一起定 |