@djvlc/openapi-user-client 1.7.13 → 1.7.15

package/openapi/dist/user-api.yaml

@@ -69,6 +69,12 @@ paths:
         - cacheTtlSeconds: 缓存 TTL（建议 10~30 秒）
         - snapshot: 完整快照（仅当 includeSnapshot=1 时返回）
       parameters:
+        - name: X-Trace-Id
+          in: header
+          required: false
+          schema:
+            type: string
+          description: 链路追踪 ID（OTel，全链路透传）
         - name: pageId
           in: query
           required: true
@@ -155,6 +161,21 @@ paths:
         - setState: 状态更新（内置）
         - showToast: 提示消息（内置）
         - custom: 自定义动作
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: false
+          schema:
+            type: string
+            minLength: 16
+            maxLength: 128
+          description: 幂等键（与 body.idempotencyKey 二选一，推荐 header 传递）
+        - name: X-Trace-Id
+          in: header
+          required: false
+          schema:
+            type: string
+          description: 链路追踪 ID（OTel，全链路透传）
       requestBody:
         required: true
         content:
@@ -822,36 +843,103 @@ components:
           type: string
           example: uuid-string
           description: 请求 ID（可选）
+    KillSwitchItem:
+      type: object
+      required:
+        - targetType
+        - targetId
+        - enabled
+      description: Kill-Switch 条目
+      properties:
+        targetType:
+          type: string
+          enum:
+            - action
+            - component
+            - feature
+            - page
+            - query
+          description: 目标类型
+        targetId:
+          type: string
+          description: 目标 ID（actionType/componentName/featureKey/pageId/queryId）
+        enabled:
+          type: boolean
+          description: 是否启用（true = 被关闭）
+        reason:
+          type: string
+          description: 关闭原因
+        enabledAt:
+          type: string
+          format: date-time
+          description: 关闭时间（ISO8601）
+        enabledBy:
+          type: string
+          description: 关闭操作者
+        userMessage:
+          type: string
+          description: 用户提示消息
+    BlockedComponentItem:
+      type: object
+      required:
+        - name
+        - reason
+      description: 被阻断的组件条目
+      properties:
+        name:
+          type: string
+          description: 组件名称
+        version:
+          type: string
+          pattern: ^\d+\.\d+\.\d+$
+          description: 组件版本（可选，不指定则阻断所有版本）
+        reason:
+          type: string
+          description: 阻断原因
+        blockedAt:
+          type: string
+          format: date-time
+          description: 阻断时间（ISO8601）
+        blockedBy:
+          type: string
+          description: 阻断操作者
+        fallbackVersion:
+          type: string
+          pattern: ^\d+\.\d+\.\d+$
+          description: 降级版本（可选）
+        urgent:
+          type: boolean
+          description: 是否紧急阻断
     OpsConfig:
       type: object
-      description: 运维配置（运行时下发）
+      description: 运维配置（运行时下发，与 types/page/snapshot.ts OpsConfig 对齐）
       required:
         - killSwitch
         - blockedComponents
         - flags
       properties:
+        configVersionId:
+          type: string
+          description: 配置版本 ID（用于缓存失效）
         killSwitch:
           type: array
           items:
-            type: string
-          description: Kill Switch 列表（被阻断的 actionType/componentType）
+            $ref: '#/components/schemas/KillSwitchItem'
+          description: Kill-Switch 列表（被紧急关闭的功能/动作）
         blockedComponents:
           type: array
           items:
-            type: object
-            properties:
-              componentName:
-                type: string
-              componentVersion:
-                type: string
-              reason:
-                type: string
+            $ref: '#/components/schemas/BlockedComponentItem'
           description: 被阻断的组件列表
         flags:
           type: object
           additionalProperties:
             type: boolean
           description: 功能开关（Feature Flags）
+        expiresAt:
+          type: string
+          format: date-time
+          description: 配置过期时间（ISO8601）
     ResolvePageResponse:
       allOf:
         - $ref: '#/components/schemas/SuccessResponse'
@@ -899,6 +987,13 @@ components:
                   maximum: 300
                   default: 30
                   description: 缓存 TTL（秒），建议 10~30 秒
+                traceId:
+                  type: string
+                  description: 链路追踪 ID（全链路透传，与 types 可观测原则一致）
+                runtimeVersion:
+                  type: string
+                  pattern: ^\d+\.\d+\.\d+$
+                  description: 运行时版本（SemVer，与 manifest.runtime.version 一致）
                 rolloutMatch:
                   type: object
                   description: 灰度匹配信息（可选，用于调试）
@@ -1076,7 +1171,7 @@ components:
         data:
           type: object
           additionalProperties: true
-          description: 错误详情（验证错误时使用 ApiErrorDetail[]，其他情况使用 unknown，放在 data 字段中）
+          description: 错误详情（Record<string, unknown>，与 types ApiErrorResponse.data 一致）
         timestamp:
           type: integer
           format: int64
@@ -1094,7 +1189,7 @@ components:
           type: string
           example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
           description: 链路追踪 ID（可选，用于分布式追踪）
-    ActionContext:
+    ActionClientContext:
       type: object
       description: 动作执行上下文（ActionClientContext，问题追溯必须字段）
       required:
@@ -1160,7 +1255,7 @@ components:
           additionalProperties: true
           description: 动作参数（Record<string, JsonValue>）
         context:
-          $ref: '#/components/schemas/ActionContext'
+          $ref: '#/components/schemas/ActionClientContext'
           description: 客户端上下文（ActionClientContext，必填）
         idempotencyKey:
           type: string
@@ -1230,6 +1325,19 @@ components:
                 retryAfter:
                   type: integer
                   description: 建议重试延迟（毫秒）
+                riskDecision:
+                  type: object
+                  description: 风控决策（可选，风控拒绝时返回）
+                  properties:
+                    allowed:
+                      type: boolean
+                      description: 是否放行
+                    reason:
+                      type: string
+                      description: 拒绝原因（如 RISK_BLOCKED）
+                    code:
+                      type: string
+                      description: 风控错误码
     IdempotencyConflictResponse:
       type: object
       required:
@@ -1757,15 +1865,18 @@ components:
       type: object
       required:
         - page
-        - limit
+        - pageSize
         - total
         - totalPages
+        - hasNext
+        - hasPrev
+      description: 分页元数据（PaginationMeta）
       properties:
         page:
           type: integer
           minimum: 1
           description: 当前页码
-        limit:
+        pageSize:
           type: integer
           minimum: 1
           maximum: 100
@@ -1778,6 +1889,12 @@ components:
           type: integer
           minimum: 0
           description: 总页数
+        hasNext:
+          type: boolean
+          description: 是否有下一页
+        hasPrev:
+          type: boolean
+          description: 是否有上一页
     LotteryRecordInfo:
       type: object
       required:
@@ -2069,21 +2186,6 @@ components:
         cacheTtl:
           type: integer
           description: 缓存 TTL（秒）
-    ErrorDetail:
-      type: object
-      required:
-        - message
-      description: 错误详情（ApiErrorDetail，与 types/src/common/api.ts 保持一致）
-      properties:
-        field:
-          type: string
-          description: 字段路径（可选）
-        message:
-          type: string
-          description: 错误消息（必填）
-        code:
-          type: string
-          description: 错误码（可选）
     PageResponse:
       allOf:
         - $ref: '#/components/schemas/SuccessResponse'
@@ -2144,9 +2246,9 @@ components:
             code: VALIDATION_INVALID_PARAMS
             message: 请求参数无效
             data:
-              - field: pageId
-                message: 页面 ID 不能为空
-                code: REQUIRED
+              field: pageId
+              message: 页面 ID 不能为空
+              code: REQUIRED
             timestamp: 1702300000000
             path: /api/user/pages/resolve
             requestId: uuid-string

package/openapi/src/components/responses/_index.yaml

@@ -11,9 +11,9 @@ BadRequest:
         code: VALIDATION_INVALID_PARAMS
         message: 请求参数无效
         data:
-          - field: pageId
-            message: 页面 ID 不能为空
-            code: REQUIRED
+          field: pageId
+          message: 页面 ID 不能为空
+          code: REQUIRED
         timestamp: 1702300000000
         path: /api/user/pages/resolve
         requestId: uuid-string

package/openapi/src/components/schemas/_index.yaml

@@ -63,7 +63,7 @@ ErrorResponse:
     data:
       type: object
       additionalProperties: true
-      description: 错误详情（验证错误时使用 ApiErrorDetail[]，其他情况使用 unknown，放在 data 字段中）
+      description: 错误详情（Record<string, unknown>，与 types ApiErrorResponse.data 一致）
     timestamp:
       type: integer
       format: int64
@@ -82,21 +82,6 @@ ErrorResponse:
       example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
       description: 链路追踪 ID（可选，用于分布式追踪）
 
-ErrorDetail:
-  type: object
-  required: [message]
-  description: 错误详情（ApiErrorDetail，与 types/src/common/api.ts 保持一致）
-  properties:
-    field:
-      type: string
-      description: 字段路径（可选）
-    message:
-      type: string
-      description: 错误消息（必填）
-    code:
-      type: string
-      description: 错误码（可选）
-
 # ============================================================================
 # 页面相关
 # ============================================================================
@@ -168,6 +153,13 @@ ResolvePageResponse:
               maximum: 300
               default: 30
               description: 缓存 TTL（秒），建议 10~30 秒
+            traceId:
+              type: string
+              description: 链路追踪 ID（全链路透传，与 types 可观测原则一致）
+            runtimeVersion:
+              type: string
+              pattern: '^\d+\.\d+\.\d+$'
+              description: 运行时版本（SemVer，与 manifest.runtime.version 一致）
             rolloutMatch:
               type: object
               description: 灰度匹配信息（可选，用于调试）
@@ -395,33 +387,94 @@ QueryManifest:
       type: integer
       description: 缓存 TTL（秒）
 
+# 与 types/page/snapshot.ts KillSwitchItem 对齐
+KillSwitchItem:
+  type: object
+  required: [targetType, targetId, enabled]
+  description: Kill-Switch 条目
+  properties:
+    targetType:
+      type: string
+      enum: [action, component, feature, page, query]
+      description: 目标类型
+    targetId:
+      type: string
+      description: 目标 ID（actionType/componentName/featureKey/pageId/queryId）
+    enabled:
+      type: boolean
+      description: 是否启用（true = 被关闭）
+    reason:
+      type: string
+      description: 关闭原因
+    enabledAt:
+      type: string
+      format: date-time
+      description: 关闭时间（ISO8601）
+    enabledBy:
+      type: string
+      description: 关闭操作者
+    userMessage:
+      type: string
+      description: 用户提示消息
+
+# 与 types/page/snapshot.ts BlockedComponentItem 对齐
+BlockedComponentItem:
+  type: object
+  required: [name, reason]
+  description: 被阻断的组件条目
+  properties:
+    name:
+      type: string
+      description: 组件名称
+    version:
+      type: string
+      pattern: '^\d+\.\d+\.\d+$'
+      description: 组件版本（可选，不指定则阻断所有版本）
+    reason:
+      type: string
+      description: 阻断原因
+    blockedAt:
+      type: string
+      format: date-time
+      description: 阻断时间（ISO8601）
+    blockedBy:
+      type: string
+      description: 阻断操作者
+    fallbackVersion:
+      type: string
+      pattern: '^\d+\.\d+\.\d+$'
+      description: 降级版本（可选）
+    urgent:
+      type: boolean
+      description: 是否紧急阻断
+
 OpsConfig:
   type: object
-  description: 运维配置（运行时下发）
+  description: 运维配置（运行时下发，与 types/page/snapshot.ts OpsConfig 对齐）
   required: [killSwitch, blockedComponents, flags]
   properties:
+    configVersionId:
+      type: string
+      description: 配置版本 ID（用于缓存失效）
     killSwitch:
       type: array
       items:
-        type: string
-      description: Kill Switch 列表（被阻断的 actionType/componentType）
+        $ref: '#/KillSwitchItem'
+      description: Kill-Switch 列表（被紧急关闭的功能/动作）
     blockedComponents:
       type: array
       items:
-        type: object
-        properties:
-          componentName:
-            type: string
-          componentVersion:
-            type: string
-          reason:
-            type: string
+        $ref: '#/BlockedComponentItem'
       description: 被阻断的组件列表
     flags:
       type: object
       additionalProperties:
         type: boolean
       description: 功能开关（Feature Flags）
+    expiresAt:
+      type: string
+      format: date-time
+      description: 配置过期时间（ISO8601）
 
 # ============================================================================
 # Action Gateway 动作相关
@@ -444,7 +497,7 @@ ExecuteActionRequest:
       additionalProperties: true
       description: 动作参数（Record<string, JsonValue>）
     context:
-      $ref: '#/ActionContext'
+      $ref: '#/ActionClientContext'
       description: 客户端上下文（ActionClientContext，必填）
     idempotencyKey:
       type: string
@@ -452,7 +505,7 @@ ExecuteActionRequest:
       maxLength: 128
       description: 幂等键（部分策略需要客户端提供，防重复提交）
 
-ActionContext:
+ActionClientContext:
   type: object
   description: 动作执行上下文（ActionClientContext，问题追溯必须字段）
   required: [pageVersionId]
@@ -527,6 +580,19 @@ ExecuteActionResponse:
             retryAfter:
               type: integer
               description: 建议重试延迟（毫秒）
+            riskDecision:
+              type: object
+              description: 风控决策（可选，风控拒绝时返回）
+              properties:
+                allowed:
+                  type: boolean
+                  description: 是否放行
+                reason:
+                  type: string
+                  description: 拒绝原因（如 RISK_BLOCKED）
+                code:
+                  type: string
+                  description: 风控错误码
 
 ActionEffect:
   type: object
@@ -781,15 +847,17 @@ BatchQueryResponse:
 # 通用分页
 # ============================================================================
 
+# 与 types/src/common/api.ts PaginationMeta 严格一致
 PaginationMeta:
   type: object
-  required: [page, limit, total, totalPages]
+  required: [page, pageSize, total, totalPages, hasNext, hasPrev]
+  description: 分页元数据（PaginationMeta）
   properties:
     page:
       type: integer
       minimum: 1
       description: 当前页码
-    limit:
+    pageSize:
       type: integer
       minimum: 1
       maximum: 100
@@ -802,6 +870,12 @@ PaginationMeta:
       type: integer
       minimum: 0
       description: 总页数
+    hasNext:
+      type: boolean
+      description: 是否有下一页
+    hasPrev:
+      type: boolean
+      description: 是否有上一页
 
 # ============================================================================
 # Tenant 租户相关

package/openapi/src/paths/actions.yaml

@@ -30,6 +30,21 @@ execute:
       - setState: 状态更新（内置）
       - showToast: 提示消息（内置）
       - custom: 自定义动作
+    parameters:
+      - name: Idempotency-Key
+        in: header
+        required: false
+        schema:
+          type: string
+          minLength: 16
+          maxLength: 128
+        description: 幂等键（与 body.idempotencyKey 二选一，推荐 header 传递）
+      - name: X-Trace-Id
+        in: header
+        required: false
+        schema:
+          type: string
+        description: 链路追踪 ID（OTel，全链路透传）
     requestBody:
       required: true
       content:

package/openapi/src/paths/pages.yaml

@@ -22,6 +22,12 @@ resolve:
       - cacheTtlSeconds: 缓存 TTL（建议 10~30 秒）
       - snapshot: 完整快照（仅当 includeSnapshot=1 时返回）
     parameters:
+      - name: X-Trace-Id
+        in: header
+        required: false
+        schema:
+          type: string
+        description: 链路追踪 ID（OTel，全链路透传）
       - name: pageId
         in: query
         required: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djvlc/openapi-user-client",
-  "version": "1.7.13",
+  "version": "1.7.15",
   "description": "DJV Low-code Platform - User API 客户端（自动生成）",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -25,7 +25,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@djvlc/openapi-client-core": "1.2.11"
+    "@djvlc/openapi-client-core": "1.2.12"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",