docs(contract): 为所有 API 的 input/output 添加 OpenAPI examples，便于厂商测试

2026-03-06 14:37:50 +08:00
parent 86754f73c1
commit ec41a4cfc7
2 changed files with 132 additions and 32 deletions
--- a/apps/server/src/server/api/contracts/config.contract.ts
+++ b/apps/server/src/server/api/contracts/config.contract.ts
@@ -1,9 +1,22 @@
 import { oc } from '@orpc/contract'
 import { z } from 'zod'

-const configOutput = z.object({
+const configOutput = z
+  .object({
    licence: z.string().nullable().describe('当前本地 licence，未设置时为 null'),
-  fingerprint: z.string().describe('UX 本机计算得到的 fingerprint'),
+    fingerprint: z.string().describe('UX 本机计算得到的设备特征码（SHA-256）'),
+  })
+  .meta({
+    examples: [
+      {
+        licence: 'LIC-8F2A-XXXX',
+        fingerprint: '9a3b7c1d2e4f5a6b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b',
+      },
+      {
+        licence: null,
+        fingerprint: '9a3b7c1d2e4f5a6b8c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b',
+      },
+    ],
  })

 export const get = oc
@@ -30,8 +43,12 @@ export const setLicence = oc
    tags: ['Config'],
  })
  .input(
-    z.object({
+    z
+      .object({
        licence: z.string().min(1).describe('本地持久化的 licence'),
+      })
+      .meta({
+        examples: [{ licence: 'LIC-8F2A-XXXX' }],
      }),
  )
  .output(configOutput)
--- a/apps/server/src/server/api/contracts/crypto.contract.ts
+++ b/apps/server/src/server/api/contracts/crypto.contract.ts
@@ -12,13 +12,30 @@ export const encryptDeviceInfo = oc
    tags: ['Crypto'],
  })
  .input(
-    z.object({
+    z
+      .object({
        platformPublicKey: z.string().min(1).describe('平台公钥（Base64，SPKI DER）'),
+      })
+      .meta({
+        examples: [
+          {
+            platformPublicKey:
+              'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzDlZvMDVaL+fjl05Hi182JOAUAaN4gh9rOF+1NhKfO4J6e0HLy8lBuylp3A4xoTiyUejNm22h0dqAgDSPnY/xZR76POFTD1soHr2LaFCN8JAbQ96P8gE7wC9qpoTssVvIVRH7QbVd260J6eD0Szwcx9cg591RSN69pMpe5IVRi8T99Hhql6/wnZHORPr18eESLOY93jRskLzc0q18r68RRoTJiQf+9YC8ub5iKp7rCjVnPi1UbIYmXmL08tk5mksYA0NqWQAa1ofKxx/9tQtB9uTjhTxuTu94XU9jlGU87qaHZs+kpqa8CAbYYJFbSP1xHwoZzpU2jpw2aF22HBYxwIDAQAB',
+          },
+        ],
      }),
  )
  .output(
-    z.object({
+    z
+      .object({
        encrypted: z.string().describe('Base64 密文（用于设备授权二维码）'),
+      })
+      .meta({
+        examples: [
+          {
+            encrypted: 'dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIFJTQS1PQUVQIGVuY3J5cHRlZCBkZXZpY2UgaW5mby4uLg==',
+          },
+        ],
      }),
  )

@@ -33,13 +50,30 @@ export const decryptTask = oc
    tags: ['Crypto'],
  })
  .input(
-    z.object({
-      encryptedData: z.string().min(1).describe('Base64 密文'),
+    z
+      .object({
+        encryptedData: z.string().min(1).describe('Base64 编码的 AES-256-GCM 密文（来自任务二维码扫描结果）'),
+      })
+      .meta({
+        examples: [
+          {
+            encryptedData: 'uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nug==',
+          },
+        ],
      }),
  )
  .output(
-    z.object({
-      decrypted: z.string().describe('解密后的 UTF-8 明文字符串'),
+    z
+      .object({
+        decrypted: z.string().describe('解密后的任务信息 JSON 字符串'),
+      })
+      .meta({
+        examples: [
+          {
+            decrypted:
+              '{"taskId":"TASK-20260115-4875","enterpriseId":"1173040813421105152","orgName":"超艺科技有限公司","inspectionId":"702286470691215417","inspectionPerson":"警务通","issuedAt":1734571234567}',
+          },
+        ],
      }),
  )

@@ -54,14 +88,32 @@ export const encryptSummary = oc
    tags: ['Crypto'],
  })
  .input(
-    z.object({
-      salt: z.string().min(1).describe('HKDF salt（例如 taskId）'),
-      plaintext: z.string().min(1).describe('待加密明文'),
+    z
+      .object({
+        salt: z.string().min(1).describe('HKDF salt（即 taskId，从任务二维码中获取）'),
+        plaintext: z.string().min(1).describe('待加密的摘要信息 JSON 明文'),
+      })
+      .meta({
+        examples: [
+          {
+            salt: 'TASK-20260115-4875',
+            plaintext:
+              '{"enterpriseId":"1173040813421105152","inspectionId":"702286470691215417","summary":"检查摘要信息：发现3个高危漏洞，5个中危漏洞","timestamp":1734571234567}',
+          },
+        ],
      }),
  )
  .output(
-    z.object({
-      encrypted: z.string().describe('Base64 密文'),
+    z
+      .object({
+        encrypted: z.string().describe('Base64 密文（用于摘要信息二维码）'),
+      })
+      .meta({
+        examples: [
+          {
+            encrypted: 'uWUcAmp6UQd0w3G3crdsd4613QCxGLoEgslgXJ4G2hQhpQdjtghtQjCBUZwB/JO+NRgH1vSTr8dqBJRq7Qh4nug==',
+          },
+        ],
      }),
  )

@@ -77,14 +129,45 @@ export const signAndPackReport = oc
  })
  .input(
    z.object({
-      pgpPrivateKey: z.string().min(1).describe('OpenPGP 私钥（ASCII armored）'),
-      signingContext: z.string().min(1).describe('签名上下文字符串（由调用方定义）'),
-      summaryJson: z.string().min(1).describe('summary.json 的完整 JSON 文本'),
-      outputFileName: z.string().min(1).optional().describe('返回 ZIP 文件名（可选）'),
+      pgpPrivateKey: z
+        .string()
+        .min(1)
+        .describe('OpenPGP 私钥（ASCII armored）')
+        .meta({
+          examples: ['-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcMGBGd...\n-----END PGP PRIVATE KEY BLOCK-----'],
+        }),
+      signingContext: z
+        .string()
+        .min(1)
+        .describe('签名上下文字符串（通常为 taskId + inspectionId 拼接）')
+        .meta({
+          examples: ['TASK-20260115-4875702286470691215417'],
+        }),
+      summaryJson: z
+        .string()
+        .min(1)
+        .describe('summary.json 的完整 JSON 文本（包含 orgId、checkId、taskId 等业务字段）')
+        .meta({
+          examples: [
+            '{"orgId":1173040813421105152,"checkId":702286470691215417,"taskId":"TASK-20260115-4875","summary":"检查摘要信息"}',
+          ],
+        }),
+      outputFileName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('返回 ZIP 文件名（可选，默认 signed-report.zip）')
+        .meta({ examples: ['signed-report.zip'] }),
      rawZip: z
        .file()
        .mime(['application/zip', 'application/x-zip-compressed'])
-        .describe('原始报告 ZIP 文件（multipart/form-data 字段）'),
+        .describe(
+          '原始报告 ZIP 文件（multipart/form-data 字段，应包含 assets.json、vulnerabilities.json、weakPasswords.json、漏洞评估报告.html）',
+        ),
    }),
  )
-  .output(z.file().describe('签名后报告 ZIP 文件（二进制响应）'))
+  .output(
+    z
+      .file()
+      .describe('签名后报告 ZIP 文件（二进制响应，包含 summary.json、META-INF/manifest.json、META-INF/signature.asc）'),
+  )