feat: expose signed platform health status

openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: 数据采集终端—云端系统 API
-  version: 0.64.0
+  version: 0.65.0
   description: 工程框架、SaaS核心业务、设备v2能力协商与智能体启动状态查询、首次通话就绪与最低固件门禁、背景资料准备失败闭环、活动通话授权撤回安全停止、语音内容闭环、终端终稿补传、批量设备遥测、录音上传队列、隐私对账、固件、双轨录音、状态事件、具体资源分享、受控运营配置、Agent组合组件引用、质量证据门禁、运营自定义版本族投放、新通话运行时冻结与供应商启动传递、带并发版本校验的配置投放暂停恢复、带严重度和验收证据门禁的联调问题闭环、含阻断告警定位证据的发布候选技术验收快照、绑定候选版本与构建摘要并按业务时区生成的可审计试点日/周运行证据、可审计且不生成正式告警的接收器联通测试、外部依赖预检台账、证书到期清单，以及带价格版本冻结、供应商用量去重和硬额度控制的费用治理接口。
 servers:
   - url: http://localhost:58080
@@ -241,6 +241,17 @@ paths:
       responses:
         '200': { description: 平台外部依赖预检状态, content: { application/json: { schema: { $ref: '#/components/schemas/OpsExternalDependencyListResponse' } } } }
         '403': { $ref: '#/components/responses/AccessDeniedError' }
+  /api/v1/ops/diagnostics/platform-health:
+    get:
+      operationId: getOpsPlatformHealth
+      tags: [operations]
+      description: 查询云端主机最近一次签名健康快照；仅返回脱敏检查名、状态和短值，不返回密钥、证书正文或业务数据。
+      security: [{ oidcBearer: [] }]
+      parameters: [{ $ref: '#/components/parameters/RequiredTenantSelectionHeader' }]
+      responses:
+        '200': { description: 云端主机最新健康快照, content: { application/json: { schema: { $ref: '#/components/schemas/PlatformHealthSnapshotResponse' } } } }
+        '403': { $ref: '#/components/responses/AccessDeniedError' }
+        '404': { $ref: '#/components/responses/NotFoundError' }
   /api/v1/ops/diagnostics/jobs:
     get:
       operationId: listOpsDiagnosticJobs
@@ -2644,6 +2655,27 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
+  /callbacks/v1/platform-health:
+    post:
+      operationId: receivePlatformHealthReport
+      tags: [callback, operations]
+      description: 接收云端主机五分钟一次的脱敏健康快照；Unix时间戳和原始正文使用独立HMAC-SHA256密钥签名，完全重复的正文幂等返回原记录。
+      security:
+        - platformHealthSignature: []
+      parameters:
+        - $ref: '#/components/parameters/PlatformTimestampHeader'
+        - $ref: '#/components/parameters/PlatformSignatureHeader'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PlatformHealthReport' }
+      responses:
+        '201': { description: 新健康快照已保存, content: { application/json: { schema: { $ref: '#/components/schemas/PlatformHealthReceiptResponse' } } } }
+        '200': { description: 完全重复的健康快照已幂等确认, content: { application/json: { schema: { $ref: '#/components/schemas/PlatformHealthReceiptResponse' } } } }
+        '400': { $ref: '#/components/responses/ValidationError' }
+        '401': { description: 签名无效或时间窗已过, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
+        '503': { description: 健康快照暂时无法保存, content: { application/json: { schema: { $ref: '#/components/schemas/ErrorResponse' } } } }
 components:
   securitySchemes:
     oidcBearer:
@@ -2659,6 +2691,11 @@ components:
       in: header
       name: X-Provider-Signature
       description: 供应商回调正文摘要和时间戳的HMAC-SHA256签名。
+    platformHealthSignature:
+      type: apiKey
+      in: header
+      name: X-Platform-Signature
+      description: 使用独立密钥对Unix时间戳、点号和原始健康报告正文计算的HMAC-SHA256十六进制签名，格式为sha256=摘要。
   headers:
     StrongETag:
       description: 资源强版本标签，例如"v2"。
@@ -2755,6 +2792,16 @@ components:
       in: header
       required: true
       schema: { type: string }
+    PlatformTimestampHeader:
+      name: X-Platform-Timestamp
+      in: header
+      required: true
+      schema: { type: string, pattern: '^[0-9]{10}$' }
+    PlatformSignatureHeader:
+      name: X-Platform-Signature
+      in: header
+      required: true
+      schema: { type: string, pattern: '^sha256=[a-f0-9]{64}$' }
   schemas:
     CreateOpsConfigVersionRequest:
       type: object
@@ -3086,6 +3133,54 @@ components:
       properties:
         request_id: { type: string }
         data: { $ref: '#/components/schemas/OpsExternalDependencyListData' }
+    PlatformHealthCheck:
+      type: object
+      additionalProperties: false
+      required: [name, status, value]
+      properties:
+        name: { type: string, pattern: '^[a-z][a-z0-9_.-]{1,79}$' }
+        status: { type: string, enum: [healthy, warning, critical] }
+        value: { type: string, maxLength: 256 }
+    PlatformHealthReport:
+      type: object
+      additionalProperties: false
+      required: [schema, status, observed_at, checks]
+      properties:
+        schema: { type: string, const: platform-server-health-v1 }
+        status: { type: string, enum: [healthy, warning, critical] }
+        observed_at: { type: string, format: date-time }
+        checks: { type: array, minItems: 1, maxItems: 64, items: { $ref: '#/components/schemas/PlatformHealthCheck' } }
+    PlatformHealthSnapshot:
+      type: object
+      additionalProperties: false
+      required: [id, schema, status, observed_at, received_at, checks]
+      properties:
+        id: { type: string, format: uuid }
+        schema: { type: string, const: platform-server-health-v1 }
+        status: { type: string, enum: [healthy, warning, critical] }
+        observed_at: { type: string, format: date-time }
+        received_at: { type: string, format: date-time }
+        checks: { type: array, minItems: 1, maxItems: 64, items: { $ref: '#/components/schemas/PlatformHealthCheck' } }
+    PlatformHealthSnapshotResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/PlatformHealthSnapshot' }
+    PlatformHealthReceipt:
+      type: object
+      additionalProperties: false
+      required: [id, status, duplicate]
+      properties:
+        id: { type: string, format: uuid }
+        status: { type: string, enum: [healthy, warning, critical] }
+        duplicate: { type: boolean }
+    PlatformHealthReceiptResponse:
+      type: object
+      required: [request_id, data]
+      properties:
+        request_id: { type: string }
+        data: { $ref: '#/components/schemas/PlatformHealthReceipt' }
     OpsDiagnosticAction:
       type: object
       additionalProperties: false