docs: 更新 UX 本地身份配置流程与对接说明

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

@@ -1,98 +1,84 @@
 # 第三方 OpenAPI 对接指南
 
-本文档用于第三方系统快速接入 UX 授权服务。
+本文档用于第三方系统对接 UX 底层能力服务。
 
 ## 1. 文档入口
 
 - OpenAPI 文档（Scalar）：`/api/docs`
 - OpenAPI 规范（JSON）：`/api/spec.json`
 
-例如本地开发环境：
+本地开发环境示例：
 
 - `http://localhost:3000/api/docs`
 - `http://localhost:3000/api/spec.json`
 
-## 2. 接口分组
+## 2. 服务边界
 
-OpenAPI 中已按 `tags` 分组：
+UX 仅提供底层加密/解密/签名能力，不维护业务实体（设备、任务、组织等）。
 
-- `Device`：设备注册与查询
-- `Crypto`：授权加解密与二维码数据处理
-- `Report`：报告签名打包
-- `Task`：任务保存与状态管理
+- 调用方负责提供业务上下文与必要签名材料（如 `platformPublicKey`、`pgpPrivateKey`）
+- 调用方负责业务字段定义与存储
 
-## 3. 核心接口一览
+## 3. 核心接口
 
-### Device
+- `POST /api/config/get`
+  - operationId: `configGet`
+  - 作用：读取 UX 本地 `licence` 与 `fingerprint`
 
-- `POST /api/device/register`
-  - 操作名：`deviceRegister`
-  - 说明：注册设备，UX 计算并存储 fingerprint
-- `POST /api/device/get`
-  - 操作名：`deviceGet`
-  - 说明：按 `id` 或 `licence` 查询设备
-
-### Crypto
+- `POST /api/config/set-licence`
+  - operationId: `configSetLicence`
+  - 作用：设置 UX 本地 `licence`（`fingerprint` 由 UX 本机计算并持久化）
 
 - `POST /api/crypto/encrypt-device-info`
-  - 操作名：`encryptDeviceInfo`
-  - 说明：生成设备授权二维码密文
+  - operationId: `encryptDeviceInfo`
+  - 作用：使用本地身份（licence/fingerprint）与输入 `platformPublicKey` 生成授权密文
+
 - `POST /api/crypto/decrypt-task`
-  - 操作名：`decryptTask`
-  - 说明：解密任务二维码数据
+  - operationId: `decryptTask`
+  - 作用：基于 `SHA256(licence+fingerprint)` 解密 AES-GCM 密文
+
 - `POST /api/crypto/encrypt-summary`
-  - 操作名：`encryptSummary`
-  - 说明：加密摘要并返回二维码内容
+  - operationId: `encryptSummary`
+  - 作用：基于 HKDF + AES-GCM 加密任意明文
+
 - `POST /api/crypto/sign-and-pack-report`
-  - 操作名：`signAndPackReport`
-  - 说明：上传原始 ZIP，返回签名后 ZIP
+  - operationId: `signAndPackReport`
+  - 作用：上传原始 ZIP，生成 `summary.json` + `META-INF/manifest.json` + `META-INF/signature.asc`，返回签名后 ZIP 文件（二进制）
 
-### Task
+## 4. 文件上传接口（signAndPackReport）
 
-- `POST /api/task/save`
-  - 操作名：`taskSave`
-- `POST /api/task/list`
-  - 操作名：`taskList`
-- `POST /api/task/update-status`
-  - 操作名：`taskUpdateStatus`
+调用顺序建议：
 
-## 4. 字段说明来源
+1. 先调用 `POST /api/config/set-licence` 写入本地 `licence`
+2. 调用 `POST /api/config/get` 确认 `fingerprint` 已存在
+3. 再调用各 `crypto/*` 能力接口
 
-每个接口的字段定义、必填/可选、类型、以及业务描述，均在 OpenAPI 中由 oRPC 合约的 Zod schema 自动生成。
+请求使用 `multipart/form-data`：
 
-你可以在 `/api/docs` 页面直接查看：
+- `rawZip`：原始 ZIP 文件（`application/zip` / `application/x-zip-compressed`）
+- `pgpPrivateKey`：签名材料
+- `signingContext`：签名上下文字符串
+- `summaryJson`：`summary.json` 的 JSON 文本
+- `outputFileName`：可选，输出文件名
 
-1. 接口名称（operationId）
-2. 接口摘要（summary）
-3. 详细说明（description）
-4. 请求字段（含描述）
-5. 响应字段（含描述）
+响应：
 
-## 5. 文件上传接口注意事项
+- `application/zip` 二进制文件（签名后 ZIP）
 
-`signAndPackReport` 使用 `multipart/form-data`，文件字段名为 `rawZip`。
-
-- 文件类型：`application/zip` 或 `application/x-zip-compressed`
-- 其他业务字段（如 `deviceId`、`taskId`）与文件一起提交
-- 接口响应为签名后 ZIP 文件（`application/zip`）
+说明：响应 ZIP 中 `summary.json` 会包含 `timestamp`（服务端生成，毫秒时间戳）。
 
 示例（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 "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
 ```
 
-## 6. 推荐接入方式
+## 5. 字段说明来源
 
-第三方如需代码生成，建议直接消费 `/api/spec.json`：
-
-- Java：OpenAPI Generator
-- C#：NSwag / OpenAPI Generator
-- TypeScript：openapi-typescript / Orval
+所有接口名称、字段类型、必填项、描述均以 `/api/docs` 与 `/api/spec.json` 为准。