# 第三方 OpenAPI 对接指南

本文档用于第三方系统对接 UX 底层能力服务。

## 1. 文档入口

- OpenAPI 文档（Scalar）：`/api/docs`
- OpenAPI 规范（JSON）：`/api/spec.json`

本地开发环境示例：

- `http://localhost:3000/api/docs`
- `http://localhost:3000/api/spec.json`

## 2. 服务边界

UX 仅提供底层加密/解密/签名能力，不维护业务实体（设备、任务、组织等）。

- 调用方负责提供业务上下文与必要签名材料（如 `platformPublicKey`、`pgpPrivateKey`）
- 调用方负责业务字段定义与存储

## 3. 核心接口

- `POST /api/config/get`
  - operationId: `configGet`
  - 作用：读取 UX 本地 `licence` 与 `fingerprint`

- `POST /api/config/set-licence`
  - operationId: `configSetLicence`
  - 作用：设置 UX 本地 `licence`（`fingerprint` 由 UX 本机计算并持久化）

- `POST /api/crypto/encrypt-device-info`
  - operationId: `encryptDeviceInfo`
  - 作用：使用本地身份（licence/fingerprint）与输入 `platformPublicKey` 生成授权密文

- `POST /api/crypto/decrypt-task`
  - operationId: `decryptTask`
  - 作用：基于 `SHA256(licence+fingerprint)` 解密 AES-GCM 密文

- `POST /api/crypto/encrypt-summary`
  - operationId: `encryptSummary`
  - 作用：基于 HKDF + AES-GCM 加密任意明文

- `POST /api/crypto/sign-and-pack-report`
  - operationId: `signAndPackReport`
  - 作用：上传原始 ZIP，生成 `summary.json` + `META-INF/manifest.json` + `META-INF/signature.asc`，返回签名后 ZIP 文件（二进制）

## 4. 文件上传接口（signAndPackReport）

调用顺序建议：

1. 先调用 `POST /api/config/set-licence` 写入本地 `licence`
2. 调用 `POST /api/config/get` 确认 `fingerprint` 已存在
3. 再调用各 `crypto/*` 能力接口

请求使用 `multipart/form-data`：

- `rawZip`：原始 ZIP 文件（`application/zip` / `application/x-zip-compressed`）
- `pgpPrivateKey`：签名材料
- `signingContext`：签名上下文字符串
- `summaryJson`：`summary.json` 的 JSON 文本
- `outputFileName`：可选，输出文件名

响应：

- `application/zip` 二进制文件（签名后 ZIP）

说明：响应 ZIP 中 `summary.json` 会包含 `timestamp`（服务端生成，毫秒时间戳）。

示例（curl）：

```bash
curl -X POST "http://localhost:3000/api/crypto/sign-and-pack-report" \
  -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
```

## 5. 字段说明来源

所有接口名称、字段类型、必填项、描述均以 `/api/docs` 与 `/api/spec.json` 为准。