From 86754f73c100596c0902234b602baeaa88b3ea35 Mon Sep 17 00:00:00 2001 From: imbytecat Date: Fri, 6 Mar 2026 14:30:09 +0800 Subject: [PATCH] =?UTF-8?q?docs(contract):=20=E4=BC=98=E5=8C=96=20API=20su?= =?UTF-8?q?mmary/description=EF=BC=8C=E5=AF=B9=E9=BD=90=E5=B7=A5=E5=85=B7?= =?UTF-8?q?=E7=AE=B1=E7=AB=AF=E5=AF=B9=E6=8E=A5=E6=8C=87=E5=8D=97=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/server/api/contracts/config.contract.ts | 10 ++++++---- .../src/server/api/contracts/crypto.contract.ts | 16 ++++++++-------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/apps/server/src/server/api/contracts/config.contract.ts b/apps/server/src/server/api/contracts/config.contract.ts index 0d79be6..b305580 100644 --- a/apps/server/src/server/api/contracts/config.contract.ts +++ b/apps/server/src/server/api/contracts/config.contract.ts @@ -11,8 +11,9 @@ export const get = oc method: 'POST', path: '/config/get', operationId: 'configGet', - summary: '读取 UX 本地身份配置', - description: '返回 UX 当前存储的 licence 与本机 fingerprint。', + summary: '读取本机身份配置', + description: + '返回 UX 本地持久化的 licence 和本机计算的设备特征码（fingerprint）。工具箱端可据此判断是否已完成本地身份初始化。', tags: ['Config'], }) .input(z.object({})) @@ -23,8 +24,9 @@ export const setLicence = oc method: 'POST', path: '/config/set-licence', operationId: 'configSetLicence', - summary: '设置本地 licence', - description: '写入或更新 UX 本地 licence。fingerprint 始终由 UX 本机计算。', + summary: '写入本地 licence', + description: + '写入或更新本机持久化的 licence。设备特征码（fingerprint）始终由 UX 本机自动计算，无需外部传入。此接口应在设备授权流程前调用。', tags: ['Config'], }) .input( diff --git a/apps/server/src/server/api/contracts/crypto.contract.ts b/apps/server/src/server/api/contracts/crypto.contract.ts index 0650f39..5e61b13 100644 --- a/apps/server/src/server/api/contracts/crypto.contract.ts +++ b/apps/server/src/server/api/contracts/crypto.contract.ts @@ -6,9 +6,9 @@ export const encryptDeviceInfo = oc method: 'POST', path: '/crypto/encrypt-device-info', operationId: 'encryptDeviceInfo', - summary: '加密设备信息', + summary: '生成设备授权二维码密文', description: - '读取 UX 本地存储的 licence 与 fingerprint，组装为 UTF-8 JSON 字符串后，使用平台公钥执行 RSA-OAEP 加密并返回 Base64 密文。', + '将本机 licence 与 fingerprint 组装为 JSON，使用平台 RSA 公钥（RSA-OAEP + SHA-256）加密后返回 Base64 密文，供工具箱生成设备授权二维码。参见《工具箱端 - 设备授权二维码生成指南》。', tags: ['Crypto'], }) .input( @@ -27,9 +27,9 @@ export const decryptTask = oc method: 'POST', path: '/crypto/decrypt-task', operationId: 'decryptTask', - summary: '解密 AES-GCM 密文', + summary: '解密任务二维码数据', description: - '读取 UX 本地存储的 licence 与 fingerprint，UTF-8 直接拼接（无分隔符）后取 SHA256 作为 AES-256-GCM 密钥，解密 Base64 密文。', + '使用本机 licence 与 fingerprint 派生 AES-256-GCM 密钥（SHA-256），解密 App 任务二维码中的 Base64 密文，返回任务信息明文。参见《工具箱端 - 任务二维码解密指南》。', tags: ['Crypto'], }) .input( @@ -48,9 +48,9 @@ export const encryptSummary = oc method: 'POST', path: '/crypto/encrypt-summary', operationId: 'encryptSummary', - summary: '加密文本内容', + summary: '加密摘要信息', description: - '读取 UX 本地存储的 licence 与 fingerprint，使用 HKDF-SHA256 + AES-256-GCM 加密明文文本，返回 Base64 密文。', + '使用本机 licence 与 fingerprint 通过 HKDF-SHA256 派生密钥，以 AES-256-GCM 加密检查摘要明文并返回 Base64 密文，供工具箱生成摘要信息二维码。参见《工具箱端 - 摘要信息二维码生成指南》。', tags: ['Crypto'], }) .input( @@ -70,9 +70,9 @@ export const signAndPackReport = oc method: 'POST', path: '/crypto/sign-and-pack-report', operationId: 'signAndPackReport', - summary: '签名并打包 ZIP', + summary: '签名并打包检查报告', description: - '读取 UX 本地存储的 licence 与 fingerprint，结合签名材料处理原始 ZIP，生成 summary.json、META-INF/manifest.json、META-INF/signature.asc，并返回签名后 ZIP 二进制文件。', + '对原始报告 ZIP 执行设备签名（HKDF + HMAC-SHA256）与 OpenPGP 分离式签名，生成含 summary.json、META-INF/manifest.json、META-INF/signature.asc 的签名报告 ZIP 文件。参见《工具箱端 - 报告加密与签名生成指南》。', tags: ['Crypto', 'Report'], }) .input(