2.7 KiB
2.7 KiB
第三方 OpenAPI 对接指南
本文档用于第三方系统快速接入 UX 授权服务。
1. 文档入口
- OpenAPI 文档（Scalar）：
/api/docs - OpenAPI 规范（JSON）：
/api/spec.json
例如本地开发环境：
http://localhost:3000/api/docshttp://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 页面直接查看：
- 接口名称（operationId）
- 接口摘要（summary）
- 详细说明（description）
- 请求字段（含描述）
- 响应字段（含描述）
5. 文件上传接口注意事项
signAndPackReport 使用 multipart/form-data，文件字段名为 rawZip。
- 文件类型：
application/zip或application/x-zip-compressed - 其他业务字段（如
deviceId、taskId）与文件一起提交 - 接口响应为签名后 ZIP 文件（
application/zip）
示例（curl）：
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" \
--output signed-report.zip
6. 推荐接入方式
第三方如需代码生成，建议直接消费 /api/spec.json：
- Java：OpenAPI Generator
- C#：NSwag / OpenAPI Generator
- TypeScript：openapi-typescript / Orval