52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
# APS Provider（平台侧适配器）
|
||
|
||
把 APS 的能力翻译成平台契约：声明能力、转发调用、归一化回执。不判断权限（归 APS）、不碰模型上下文。
|
||
|
||
## 能力的权威来源
|
||
|
||
**APS 的 `GET /api/manifest` 是唯一权威**（A5.1）。平台启动注册时拉一次，不在平台侧手抄能力清单；
|
||
`capabilities/*.capability.json` 是从那份 manifest 生成的人审阅副本，`scripts/aps-provider.test.mjs`
|
||
里有一条「不漂移」用例：起真 APS 服务后逐条比对用途与副作用。
|
||
|
||
`describe()` 连不上 APS 就直接失败——注册不上比"注册上了但能力是旧的"安全。
|
||
|
||
## 注册到哪里
|
||
|
||
平台按配置动态加载，代码里不静态依赖本包（依赖方向检查不允许 `@aps/server` → 具体 Provider）：
|
||
|
||
```bash
|
||
# 开发期最省事的写法：给个地址就注册
|
||
APS_PROVIDER_APS_URL=http://127.0.0.1:8000 pnpm dev
|
||
```
|
||
|
||
或在 `~/.aps/config.json` 里写 `providers: [{ "module": "@aps/provider-aps", "baseUrl": "http://aps.internal:8000" }]`。
|
||
APS 没起来时平台照常启动，只是能力清单里没有 `aps.*`——不会因为一个业务系统挂了就整个平台起不来。
|
||
|
||
## 字段、单位与时区映射（A5.3）
|
||
|
||
平台与 APS 之间**不翻译字段名**：APS 的能力输入输出 schema 就是契约（`aps.orders.query` 的 `items[]` 就是 APS 的订单结构）。
|
||
需要映射的只有三样，都写在能力描述里让模型看见：
|
||
|
||
| 项 | APS 侧 | 平台/界面侧 | 处理 |
|
||
| --- | --- | --- | --- |
|
||
| 订单号 | `orderNo`，如 `SO20260930001` | 原样展示 | 不加工；检索时按字符串包含匹配 |
|
||
| 状态 | `APPROVED` / `PENDING` / … 大写英文枚举 | 中文标签 | 映射表放在界面层（B6），平台不拦不改 |
|
||
| 数量与单位 | `quantity` + `unit`（如 `件`） | 原样展示，单位随数量一起显示 | 不做单位换算；换算是 APS 的事 |
|
||
| 时间 | `orderDate` / `deliveryDate`：`YYYY-MM-DD`（车间本地日期，无时区） | 原样展示 | **按日期处理，不做 UTC 转换**——制造日期是本地日历日，转时区会整体差一天 |
|
||
| 时间戳 | `createdAt` / `updatedAt`：`YYYY-MM-DD HH:mm`（本地时间） | 原样展示 | 同上 |
|
||
|
||
这条规则的理由：APS 的数据是"工厂日历"语义，不是"绝对时刻"语义。平台若把它当 UTC，
|
||
跨时区部署时会看到订单日期整体偏移。
|
||
|
||
## 实例路由（A5.4）
|
||
|
||
首版一个 Provider 实例对应一个 APS 部署（一个 `baseUrl`）。多工厂/多租户路由（哪个租户连哪个 APS 实例）
|
||
在 A7 的 Provider 套件管理里做，届时按 `tenantId` 选择实例；现在写死在配置里。
|
||
|
||
## 现在支持到什么程度
|
||
|
||
| 项 | 状态 |
|
||
| --- | --- |
|
||
| 只读能力（9 个） | 已接通真实 APS 服务，端到端用例在 `scripts/aps-provider.test.mjs` |
|
||
| 写能力（`aps.schedule.preview` / `publish`） | 只有契约草案，APS 侧尚未实现 |
|
||
| 账号绑定（ADR-0012） | 平台侧按人绑定已在 A4.1 落地；APS 侧的登录换取流程待 A5.7 | |