@djvlc/openapi-user-client 1.8.0 → 1.8.2

package/openapi/src/paths/health.yaml

@@ -2,87 +2,60 @@
 
 health:
   get:
-    tags:
-      - Health
-    summary: 健康检查
+    tags: [Health]
     operationId: healthCheck
-    description: |
-      综合健康检查，包含所有依赖服务状态。
-      
-      返回：
-      - 服务状态（healthy/degraded/unhealthy）
-      - 版本信息
-      - 运行时间
-      - 依赖服务状态
+    summary: 健康检查
+    description: 综合健康检查，返回服务状态和时间戳
     responses:
       '200':
-        description: 服务健康
-        content:
-          application/json:
-            schema:
-              $ref: '../components/schemas/_index.yaml#/HealthResponse'
-      '503':
-        description: 服务不健康
+        description: 健康
         content:
           application/json:
             schema:
-              $ref: '../components/schemas/_index.yaml#/HealthResponse'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/HealthCheckResponse'
     security: []
 
-ready:
+live:
   get:
-    tags:
-      - Health
-    summary: 就绪检查
-    operationId: readinessCheck
-    description: |
-      Kubernetes readiness probe。
-      检查服务是否准备好接收流量。
+    tags: [Health]
+    operationId: livenessCheck
+    summary: 存活检查
+    description: Kubernetes liveness probe
     responses:
       '200':
-        description: 服务就绪
+        description: 存活
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                ready:
-                  type: boolean
-                  example: true
-      '503':
-        description: 服务未就绪
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                ready:
-                  type: boolean
-                  example: false
-                reason:
-                  type: string
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/LivenessResponse'
     security: []
 
-live:
+ready:
   get:
-    tags:
-      - Health
-    summary: 存活检查
-    operationId: livenessCheck
-    description: |
-      Kubernetes liveness probe。
-      检查服务是否存活。
+    tags: [Health]
+    operationId: readinessCheck
+    summary: 就绪检查
+    description: Kubernetes readiness probe
     responses:
       '200':
-        description: 服务存活
+        description: 就绪
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                alive:
-                  type: boolean
-                  example: true
-      '503':
-        description: 服务不存活
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/ReadinessResponse'
     security: []

package/openapi/src/paths/pages.yaml

@@ -4,76 +4,88 @@ resolve:
   get:
     tags: [Pages]
     operationId: resolvePage
-    summary: 解析页面（Runtime 核心接口）
+    summary: 解析页面
     description: |
-      Runtime 的核心接口，返回渲染所需的完整数据。
+      Runtime 核心接口，返回渲染所需的完整数据。
       
       支持两种模式：
       1. 稳定入口（推荐）：支持灰度/回滚/ops，返回 resolvedVersionId 和 CDN 地址
-      2. 保底模式：当 includeSnapshot=1 时，返回完整 snapshot（CDN 失败时使用）
-      
-      响应包含：
-      - resolvedVersionId: 解析后的页面版本 ID（考虑灰度/回滚）
-      - cdnBase: CDN 基础地址
-      - snapshotUrl: snapshot.json 的完整 URL
-      - manifestUrl: manifest.json 的完整 URL
-      - ops: 运维配置（killSwitch、blockedComponents、flags）
-      - etag: 内容哈希（用于缓存）
-      - cacheTtlSeconds: 缓存 TTL（建议 10~30 秒）
-      - snapshot: 完整快照（仅当 includeSnapshot=1 时返回）
+      2. 保底模式：当 includeSnapshot=true 时，返回完整 snapshot（CDN 失败时使用）
     parameters:
-      - name: X-Trace-Id
-        in: header
-        required: false
-        schema:
-          type: string
-        description: 链路追踪 ID（OTel，全链路透传）
       - name: pageId
         in: query
         required: true
+        description: 页面 ID
         schema:
           type: string
-        description: 页面 ID
+          example: page_123456
       - name: env
         in: query
         required: false
+        description: 环境
         schema:
           type: string
           enum: [prod, preview, staging]
           default: prod
-        description: 环境（prod/preview/staging）
+          example: prod
+      - name: includeSnapshot
+        in: query
+        required: false
+        description: 是否包含完整快照（CDN 失败保底）
+        schema:
+          type: boolean
+          default: false
       - name: uid
         in: query
         required: false
+        description: 用户 ID（契约 query；也可用 Header x-user-id）
         schema:
           type: string
-        description: 用户 ID（用于灰度路由）
+          maxLength: 64
+          example: user_123456
       - name: deviceId
         in: query
         required: false
+        description: 设备 ID（契约 query；也可用 Header x-device-id）
         schema:
           type: string
-        description: 设备 ID
+          maxLength: 64
+          example: device_123456
       - name: channel
         in: query
         required: false
+        description: 渠道（契约 query；也可用 Header x-channel）
         schema:
           type: string
-        description: 渠道标识
-      - name: includeSnapshot
-        in: query
-        required: false
+          maxLength: 64
+          example: wechat
+      - name: x-user-id
+        in: header
+        required: true
         schema:
-          type: boolean
-          default: false
-        description: 是否包含完整 snapshot（CDN 失败保底时使用）
+          type: string
+      - name: x-device-id
+        in: header
+        required: true
+        schema:
+          type: string
+      - name: x-channel
+        in: header
+        required: true
+        schema:
+          type: string
     responses:
       '200':
         description: 解析成功
         content:
           application/json:
             schema:
-              $ref: '../components/schemas/_index.yaml#/ResolvePageResponse'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/ResolvePageResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
       '404':
@@ -86,45 +98,36 @@ manifest:
     tags: [Pages]
     operationId: getPageManifest
     summary: 获取组件清单
-    description: |
-      返回页面的组件锁定清单（manifest），包含所有引用的组件版本和资源信息。
-      
-      用途：
-      - Runtime 根据 manifest 预加载组件资源
-      - Editor 根据 manifest 展示组件依赖
+    description: 返回页面的组件锁定清单
     parameters:
-      - name: X-Trace-Id
-        in: header
-        required: false
-        schema:
-          type: string
-        description: 链路追踪 ID（OTel，全链路透传）
       - name: pageId
         in: query
         required: true
+        description: 页面 ID
         schema:
           type: string
-        description: 页面 ID
+          example: page_123456
       - name: env
         in: query
         required: false
+        description: 环境
         schema:
           type: string
           enum: [prod, preview, staging]
           default: prod
-        description: 环境（prod/preview/staging）
+          example: prod
     responses:
       '200':
         description: 获取成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/ResourceManifests'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/ManifestResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
       '404':
@@ -135,38 +138,28 @@ config:
     tags: [Pages]
     operationId: getPageConfig
     summary: 获取运维配置
-    description: |
-      返回当前运维配置（killSwitch、blockedComponents、featureFlags 等）。
-      
-      用途：
-      - Runtime 启动时获取全局运维配置
-      - 判断是否有组件被阻断或功能被关闭
+    description: 返回当前运维配置（killSwitch、blockedComponents 等）
     parameters:
-      - name: X-Trace-Id
-        in: header
-        required: false
-        schema:
-          type: string
-        description: 链路追踪 ID（OTel，全链路透传）
       - name: env
         in: query
         required: false
+        description: 环境
         schema:
           type: string
           enum: [prod, preview, staging]
           default: prod
-        description: 环境（prod/preview/staging）
+          example: prod
     responses:
       '200':
         description: 获取成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/OpsConfig'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/OpsConfig'
       '503':
         $ref: '../components/responses/_index.yaml#/ServiceUnavailable'

package/openapi/src/paths/queries.yaml

@@ -4,23 +4,8 @@ query:
   post:
     tags: [Queries]
     operationId: queryData
-    summary: 执行数据查询（Data Proxy 统一入口）
-    description: |
-      Data Proxy 统一入口，所有数据查询都通过此接口执行。
-      
-      功能：
-      - 白名单校验（queryVersionId 属于该 app/workspace）
-      - 字段裁剪、脱敏
-      - 缓存（短 TTL）
-      - 失败降级（兜底结构）
-      - 审计（可选，或采样）
-      
-      支持的数据源类型：
-      - http: HTTP 接口
-      - graphql: GraphQL 查询
-      - database: 数据库查询（受限）
-      - internal: 内部服务
-      - aggregation: 聚合查询
+    summary: 执行数据查询
+    description: 通过 queryVersionId 查询数据
     requestBody:
       required: true
       content:
@@ -33,53 +18,27 @@ query:
         content:
           application/json:
             schema:
-              $ref: '../components/schemas/_index.yaml#/QueryDataResponse'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/QueryDataResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
       '401':
         $ref: '../components/responses/_index.yaml#/Unauthorized'
-      '403':
-        $ref: '../components/responses/_index.yaml#/Forbidden'
-      '404':
-        $ref: '../components/responses/_index.yaml#/NotFound'
-      '422':
-        $ref: '../components/responses/_index.yaml#/UnprocessableEntity'
       '500':
         $ref: '../components/responses/_index.yaml#/InternalError'
-      '504':
-        $ref: '../components/responses/_index.yaml#/GatewayTimeout'
-
-definitions:
-  get:
-    tags: [Queries]
-    operationId: getQueryDefinition
-    summary: 获取查询定义
-    description: 获取指定数据查询定义版本的详细信息
-    parameters:
-      - name: queryVersionId
-        in: query
-        required: true
-        schema:
-          type: string
-        description: 查询定义版本 ID
-    responses:
-      '200':
-        description: 成功
-        content:
-          application/json:
-            schema:
-              $ref: '../components/schemas/_index.yaml#/QueryDefinitionResponse'
-      '404':
-        $ref: '../components/responses/_index.yaml#/NotFound'
+    security:
+      - BearerAuth: []
 
 batch:
   post:
     tags: [Queries]
     operationId: batchQueryData
     summary: 批量执行数据查询
-    description: |
-      批量执行多个数据查询，用于页面初始化时预取多个数据源。
-      所有查询并行执行，部分失败不影响其他查询返回。
+    description: 批量执行多个数据查询，所有查询并行执行
     requestBody:
       required: true
       content:
@@ -88,10 +47,46 @@ batch:
             $ref: '../components/schemas/_index.yaml#/BatchQueryRequest'
     responses:
       '200':
-        description: 批量查询结果
+        description: 批量查询成功
         content:
           application/json:
             schema:
-              $ref: '../components/schemas/_index.yaml#/BatchQueryResponse'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/BatchQueryResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
+    security:
+      - BearerAuth: []
+
+definitions:
+  get:
+    tags: [Queries]
+    operationId: getQueryDefinition
+    summary: 获取查询定义
+    description: 按版本 ID 获取数据查询定义
+    parameters:
+      - name: queryVersionId
+        in: query
+        required: true
+        schema:
+          type: string
+    responses:
+      '200':
+        description: 获取查询定义成功
+        content:
+          application/json:
+            schema:
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/QueryDefinitionResponse'
+      '404':
+        $ref: '../components/responses/_index.yaml#/NotFound'
+    security:
+      - BearerAuth: []

package/openapi/src/paths/tenant.yaml

@@ -2,47 +2,28 @@
 
 resolve:
   post:
-    tags:
-      - Tenant
-    summary: 解析租户信息
+    tags: [Tenant]
     operationId: resolveTenant
-    description: |
-      根据 appKey 或 host 解析租户/应用信息。
-      
-      用于：
-      - Runtime 初始化时获取应用配置
-      - 多租户场景下的应用隔离
+    summary: 解析租户信息
+    description: 根据 appKey 或 host 解析租户/应用信息
     requestBody:
       required: true
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              appKey:
-                type: string
-                description: 应用密钥
-              host:
-                type: string
-                description: 请求来源域名
-              channel:
-                type: string
-                description: 渠道标识
-            anyOf:
-              - required: [appKey]
-              - required: [host]
+            $ref: '../components/schemas/_index.yaml#/ResolveTenantRequest'
     responses:
       '200':
         description: 解析成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/TenantInfo'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/ResolveTenantResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
       '404':
@@ -55,38 +36,33 @@ resolve:
 
 config:
   get:
-    tags:
-      - Tenant
-    summary: 获取租户配置
+    tags: [Tenant]
     operationId: getTenantConfig
-    description: |
-      获取当前租户的运行时配置。
-      
-      包括：
-      - 功能开关
-      - 主题配置
-      - CDN 域名
-      - 阻断组件列表
-      - Kill Switch 状态
+    summary: 获取租户配置
+    description: 获取当前租户的运行时配置
     parameters:
+      - name: x-app-id
+        in: header
+        required: true
+        schema:
+          type: string
       - name: X-App-Id
         in: header
         required: true
         schema:
           type: string
-        description: 应用 ID
     responses:
       '200':
-        description: 成功
+        description: 获取成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/TenantConfig'
+              allOf:
+                - $ref: '../components/schemas/_index.yaml#/SuccessResponse'
+                - type: object
+                  properties:
+                    data:
+                      $ref: '../components/schemas/_index.yaml#/TenantConfigResponse'
       '401':
         $ref: '../components/responses/_index.yaml#/Unauthorized'
       '404':

package/openapi/src/paths/track.yaml

@@ -2,55 +2,32 @@
 
 track:
   post:
-    tags:
-      - Track
-    summary: 埋点上报
+    tags: [Track]
     operationId: track
-    description: |
-      接收客户端埋点数据，异步写入 Outbox。
-      
-      特点：
-      - 高性能：不阻塞主链路
-      - 可靠：通过 Outbox 异步持久化
-      - 可追溯：自动关联 pageVersionId/componentVersionId/traceId
+    summary: 单个埋点上报
+    description: 接收客户端埋点数据，异步处理
     requestBody:
       required: true
       content:
         application/json:
           schema:
-            $ref: '../components/schemas/_index.yaml#/TrackRequest'
+            $ref: '../components/schemas/_index.yaml#/TrackSingleRequest'
     responses:
       '202':
         description: 接收成功（异步处理）
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                  example: true
-                data:
-                  type: object
-                  properties:
-                    eventId:
-                      type: string
-                      description: 事件 ID
+              $ref: '../components/schemas/_index.yaml#/TrackSingleResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
 
 trackBatch:
   post:
-    tags:
-      - Track
-    summary: 批量埋点上报
+    tags: [Track]
     operationId: trackBatch
-    description: |
-      批量接收客户端埋点数据，提高上报效率。
-      
-      限制：
-      - 单次最多 100 条
-      - 单条事件不超过 10KB
+    summary: 批量埋点上报
+    description: 批量接收客户端埋点数据，提高上报效率
     requestBody:
       required: true
       content:
@@ -63,27 +40,6 @@ trackBatch:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  type: object
-                  properties:
-                    accepted:
-                      type: integer
-                      description: 接收的事件数量
-                    rejected:
-                      type: integer
-                      description: 拒绝的事件数量
-                    errors:
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          index:
-                            type: integer
-                          reason:
-                            type: string
+              $ref: '../components/schemas/_index.yaml#/TrackBatchResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'