第三方 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）

调用顺序建议：

先调用 POST /api/config/set-licence 写入本地 licence
调用 POST /api/config/get 确认 fingerprint 已存在
再调用各 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）：

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 为准。

2.8 KiB Raw Blame History Unescape Escape