docs: 新增第三方 OpenAPI 对接指南

docs/第三方-OpenAPI-对接指南.md

@@ -0,0 +1,103 @@
+# 第三方 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