85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
# 第三方 OpenAPI 对接指南
|
||
|
||
本文档用于第三方系统对接 UX 底层能力服务。
|
||
|
||
## 1. 文档入口
|
||
|
||
- OpenAPI 文档（Scalar）：`/api/docs`
|
||
- OpenAPI 规范（JSON）：`/api/spec.json`
|
||
|
||
本地开发环境示例：
|
||
|
||
- `http://localhost:3000/api/docs`
|
||
- `http://localhost:3000/api/spec.json`
|
||
|
||
## 2. 服务边界
|
||
|
||
UX 仅提供底层加密/解密/签名能力，不维护业务实体（设备、任务、组织等）。
|
||
|
||
- 调用方负责提供业务上下文与必要签名材料（如 `platformPublicKey`、`pgpPrivateKey`）
|
||
- 调用方负责业务字段定义与存储
|
||
|
||
## 3. 核心接口
|
||
|
||
- `POST /api/config/get`
|
||
- operationId: `configGet`
|
||
- 作用：读取 UX 本地 `licence` 与 `fingerprint`
|
||
|
||
- `POST /api/config/set-licence`
|
||
- operationId: `configSetLicence`
|
||
- 作用：设置 UX 本地 `licence`（`fingerprint` 由 UX 本机计算并持久化）
|
||
|
||
- `POST /api/crypto/encrypt-device-info`
|
||
- operationId: `encryptDeviceInfo`
|
||
- 作用：使用本地身份（licence/fingerprint）与输入 `platformPublicKey` 生成授权密文
|
||
|
||
- `POST /api/crypto/decrypt-task`
|
||
- operationId: `decryptTask`
|
||
- 作用：基于 `SHA256(licence+fingerprint)` 解密 AES-GCM 密文
|
||
|
||
- `POST /api/crypto/encrypt-summary`
|
||
- operationId: `encryptSummary`
|
||
- 作用：基于 HKDF + AES-GCM 加密任意明文
|
||
|
||
- `POST /api/crypto/sign-and-pack-report`
|
||
- operationId: `signAndPackReport`
|
||
- 作用：上传原始 ZIP，生成 `summary.json` + `META-INF/manifest.json` + `META-INF/signature.asc`，返回签名后 ZIP 文件（二进制）
|
||
|
||
## 4. 文件上传接口（signAndPackReport）
|
||
|
||
调用顺序建议：
|
||
|
||
1. 先调用 `POST /api/config/set-licence` 写入本地 `licence`
|
||
2. 调用 `POST /api/config/get` 确认 `fingerprint` 已存在
|
||
3. 再调用各 `crypto/*` 能力接口
|
||
|
||
请求使用 `multipart/form-data`：
|
||
|
||
- `rawZip`：原始 ZIP 文件（`application/zip` / `application/x-zip-compressed`）
|
||
- `pgpPrivateKey`：签名材料
|
||
- `signingContext`：签名上下文字符串
|
||
- `summaryJson`：`summary.json` 的 JSON 文本
|
||
- `outputFileName`：可选，输出文件名
|
||
|
||
响应：
|
||
|
||
- `application/zip` 二进制文件（签名后 ZIP）
|
||
|
||
说明：响应 ZIP 中 `summary.json` 会包含 `timestamp`（服务端生成，毫秒时间戳）。
|
||
|
||
示例（curl）：
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:3000/api/crypto/sign-and-pack-report" \
|
||
-F "pgpPrivateKey=-----BEGIN PGP PRIVATE KEY BLOCK-----..." \
|
||
-F "signingContext=TASK-20260115-4875|702286470691215417" \
|
||
-F "summaryJson={\"summary\":\"检查摘要\"}" \
|
||
-F "outputFileName=signed-report.zip" \
|
||
-F "rawZip=@./report-raw.zip;type=application/zip" \
|
||
--output signed-report.zip
|
||
```
|
||
|
||
## 5. 字段说明来源
|
||
|
||
所有接口名称、字段类型、必填项、描述均以 `/api/docs` 与 `/api/spec.json` 为准。
|