# 第三方 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`）与文件一起提交
- 接口响应为签名后 ZIP 文件（`application/zip`）

示例（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" \
  --output signed-report.zip
```

## 6. 推荐接入方式

第三方如需代码生成，建议直接消费 `/api/spec.json`：

- Java：OpenAPI Generator
- C#：NSwag / OpenAPI Generator
- TypeScript：openapi-typescript / Orval