104 lines
2.8 KiB
Markdown
104 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. 接口分组
|
||
|
||
OpenAPI 中已按 `tags` 分组：
|
||
|
||
- `Device`：设备注册与查询
|
||
- `Crypto`：授权加解密与二维码数据处理
|
||
- `Report`：报告签名打包
|
||
- `Task`：任务保存与状态管理
|
||
|
||
## 3. 核心接口一览
|
||
|
||
### Device
|
||
|
||
- `POST /api/device/register`
|
||
- 操作名：`deviceRegister`
|
||
- 说明：注册设备，UX 计算并存储 fingerprint
|
||
- `POST /api/device/get`
|
||
- 操作名：`deviceGet`
|
||
- 说明：按 `id` 或 `licence` 查询设备
|
||
|
||
### Crypto
|
||
|
||
- `POST /api/crypto/encrypt-device-info`
|
||
- 操作名：`encryptDeviceInfo`
|
||
- 说明：生成设备授权二维码密文
|
||
- `POST /api/crypto/decrypt-task`
|
||
- 操作名：`decryptTask`
|
||
- 说明：解密任务二维码数据
|
||
- `POST /api/crypto/encrypt-summary`
|
||
- 操作名：`encryptSummary`
|
||
- 说明：加密摘要并返回二维码内容
|
||
- `POST /api/crypto/sign-and-pack-report`
|
||
- 操作名：`signAndPackReport`
|
||
- 说明：上传原始 ZIP，返回签名后 ZIP
|
||
|
||
### Task
|
||
|
||
- `POST /api/task/save`
|
||
- 操作名：`taskSave`
|
||
- `POST /api/task/list`
|
||
- 操作名：`taskList`
|
||
- `POST /api/task/update-status`
|
||
- 操作名：`taskUpdateStatus`
|
||
|
||
## 4. 字段说明来源
|
||
|
||
每个接口的字段定义、必填/可选、类型、以及业务描述，均在 OpenAPI 中由 oRPC 合约的 Zod schema 自动生成。
|
||
|
||
你可以在 `/api/docs` 页面直接查看：
|
||
|
||
1. 接口名称（operationId）
|
||
2. 接口摘要（summary）
|
||
3. 详细说明（description）
|
||
4. 请求字段（含描述）
|
||
5. 响应字段（含描述）
|
||
|
||
## 5. 文件上传接口注意事项
|
||
|
||
`signAndPackReport` 使用 `multipart/form-data`，文件字段名为 `rawZip`。
|
||
|
||
- 文件类型：`application/zip` 或 `application/x-zip-compressed`
|
||
- 其他业务字段（如 `deviceId`、`taskId`）与文件一起提交
|
||
- 接口响应为 JSON，其中 `signedZipBase64` 为签名后 ZIP 的 Base64 编码
|
||
|
||
示例（curl）：
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:3000/api/crypto/sign-and-pack-report" \
|
||
-F "deviceId=dev_xxx" \
|
||
-F "taskId=TASK-20260115-4875" \
|
||
-F "enterpriseId=1173040813421105152" \
|
||
-F "inspectionId=702286470691215417" \
|
||
-F "summary=检查摘要信息" \
|
||
-F "rawZip=@./report-raw.zip;type=application/zip"
|
||
```
|
||
|
||
响应中的 `signedZipBase64` 可按以下方式还原为 ZIP：
|
||
|
||
```bash
|
||
# jq -r '.signedZipBase64' response.json | base64 -d > signed-report.zip
|
||
```
|
||
|
||
## 6. 推荐接入方式
|
||
|
||
第三方如需代码生成，建议直接消费 `/api/spec.json`：
|
||
|
||
- Java：OpenAPI Generator
|
||
- C#：NSwag / OpenAPI Generator
|
||
- TypeScript：openapi-typescript / Orval
|