@djvlc/openapi-user-client 1.8.0 → 1.8.2

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

@@ -1,534 +1,323 @@
 # Schema 组件索引
+# 与 docs/user-api/openapi.yaml 保持一致
 
 # ============================================================================
-# 通用
-# ============================================================================
-
-# ============================================================================
-# 统一响应结构（与 platform 仓库保持一致）
+# 统一响应结构
 # ============================================================================
 
 SuccessResponse:
   type: object
   required: [success, code, message, data, timestamp, path]
-  description: 成功响应（ApiSuccessResponse，与 types/src/common/api.ts 保持一致）
+  description: 成功响应（BaseResponseVo）
   properties:
     success:
       type: boolean
-      enum: [true]
+      description: 请求是否成功
       example: true
-      description: 是否成功（固定为 true）
     code:
       type: string
-      example: OK
       description: 业务状态码
+      example: OK
     message:
       type: string
-      example: 操作成功
       description: 响应消息
+      example: 操作成功
     data:
-      description: 响应数据（泛型 T）
+      type: object
+      description: 响应数据
     timestamp:
-      type: integer
-      format: int64
+      type: number
+      description: 响应时间戳
       example: 1702300000000
-      description: 响应时间戳（Unix 毫秒时间戳，number）
     path:
       type: string
-      example: /api/user/pages/resolve
       description: 请求路径
+      example: /api/users
     requestId:
       type: string
+      description: 请求ID
       example: uuid-string
-      description: 请求 ID（可选）
+    traceId:
+      type: string
+      description: 链路追踪ID（用于全链路定位问题）
+      example: trace-uuid-string
 
 ErrorResponse:
   type: object
   required: [success, code, message, timestamp, path]
-  description: 错误响应（ApiErrorResponse，与 types/src/common/api.ts 保持一致）
+  description: 错误响应（ErrorResponseVo）
   properties:
     success:
       type: boolean
-      enum: [false]
+      description: 请求是否成功
       example: false
-      description: 是否成功（固定为 false）
     code:
       type: string
-      example: VALIDATION_INVALID_PARAMS
-      description: 错误码（ErrorCode | string）
+      description: 错误码
+      example: USER_NOT_FOUND
     message:
       type: string
-      example: 请求参数无效
-      description: 错误消息（用户可读）
-    data:
-      type: object
-      additionalProperties: true
-      description: 错误详情（Record<string, unknown>，与 types ApiErrorResponse.data 一致）
+      description: 错误消息
+      example: 用户不存在
     timestamp:
-      type: integer
-      format: int64
+      type: number
+      description: 响应时间戳
       example: 1702300000000
-      description: 响应时间戳（Unix 毫秒时间戳，number）
     path:
       type: string
-      example: /api/user/pages/resolve
       description: 请求路径
+      example: /api/users/123
     requestId:
       type: string
+      description: 请求ID
       example: uuid-string
-      description: 请求 ID（可选）
     traceId:
       type: string
-      example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
-      description: 链路追踪 ID（可选，用于分布式追踪）
+      description: 链路追踪ID（用于全链路定位问题）
+      example: trace-uuid-string
 
 # ============================================================================
-# 页面相关
+# 通用分页
 # ============================================================================
 
-PageResponse:
-  allOf:
-    - $ref: '#/SuccessResponse'
-    - type: object
-      properties:
-        data:
-          type: object
-          required: [pageId, version, meta]
-          properties:
-            pageId:
-              type: string
-              description: 页面 ID
-            version:
-              type: string
-              description: 页面版本
-            meta:
-              type: object
-              properties:
-                title:
-                  type: string
-                  description: 页面标题
-                description:
-                  type: string
-                  description: 页面描述
-            integrity:
-              type: string
-              description: 完整性哈希
+PaginationMeta:
+  type: object
+  required: [page, pageSize, total, totalPages, hasNext, hasPrevious]
+  description: 分页元数据（PageMetaVo）
+  properties:
+    page:
+      type: number
+      description: 当前页码
+      example: 1
+    pageSize:
+      type: number
+      description: 每页条数
+      example: 10
+    total:
+      type: number
+      description: 总条数
+      example: 100
+    totalPages:
+      type: number
+      description: 总页数
+      example: 10
+    hasNext:
+      type: boolean
+      description: 是否有下一页
+      example: true
+    hasPrevious:
+      type: boolean
+      description: 是否有上一页
+      example: false
 
-ResolvePageResponse:
-  allOf:
-    - $ref: '#/SuccessResponse'
-    - type: object
-      properties:
-        data:
-          type: object
-          required: [pageId, resolvedVersionId, cdnBase, snapshotUrl, manifestUrl, ops, etag, cacheTtlSeconds]
-          properties:
-            pageId:
-              type: string
-              description: 页面 ID（UniqueId）
-            resolvedVersionId:
-              type: string
-              description: 解析后的页面版本 ID（考虑灰度/回滚后的实际版本，UniqueId）
-            cdnBase:
-              type: string
-              format: uri
-              description: CDN 基础地址
-            snapshotUrl:
-              type: string
-              format: uri
-              description: snapshot.json 的完整 URL
-            manifestUrl:
-              type: string
-              format: uri
-              description: manifest.json 的完整 URL
-            ops:
-              $ref: '#/OpsConfig'
-              description: 运维配置（killSwitch、blockedComponents、flags）
-            etag:
-              type: string
-              description: 内容哈希（用于缓存验证）
-            cacheTtlSeconds:
-              type: integer
-              minimum: 0
-              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: 灰度匹配信息（可选，用于调试）
-              properties:
-                strategyId:
-                  type: string
-                  description: 匹配的策略 ID
-                strategyName:
-                  type: string
-                  description: 匹配的策略名称
-                isDefault:
-                  type: boolean
-                  description: 是否使用默认版本
-            snapshot:
-              type: object
-              description: 完整快照（仅当 includeSnapshot=1 时返回，CDN 失败保底使用）
-              properties:
-                page:
-                  type: object
-                  description: 页面 Schema（PageSnapshotPage）
-                  properties:
-                    schemaVersion:
-                      type: string
-                    pageId:
-                      type: string
-                    pageVersion:
-                      type: string
-                      pattern: '^\d+\.\d+\.\d+$'
-                    title:
-                      type: string
-                    initialState:
-                      type: object
-                      additionalProperties: true
-                    bindings:
-                      type: array
-                      items:
-                        type: object
-                    root:
-                      type: object
-                    config:
-                      type: object
-                manifest:
-                  type: object
-                  description: 组件锁定清单（PageSnapshotManifest）
-                  properties:
-                    components:
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          name:
-                            type: string
-                          version:
-                            type: string
-                            pattern: '^\d+\.\d+\.\d+$'
-                          source:
-                            type: string
-                            enum: [bundled, remote]
-                            description: '组件来源：bundled = 内置组件，remote = 远程组件'
-                          integrity:
-                            type: string
-                            pattern: '^sha(256|384|512)-'
-                          assetsUrl:
-                            type: string
-                            format: uri
-                            description: 'CDN 资源基础 URL（source 为 remote 时必填）'
-                          entrypoints:
-                            type: object
-                            description: '入口点（source 为 remote 时必填）'
-                            properties:
-                              js:
-                                type: string
-                              css:
-                                type: string
-                              chunks:
-                                type: array
-                                items:
-                                  type: string
-                    runtime:
-                      type: object
-                      properties:
-                        version:
-                          type: string
-                          pattern: '^\d+\.\d+\.\d+$'
-                        minVersion:
-                          type: string
-                          pattern: '^\d+\.\d+\.\d+$'
-                definitionsDigest:
-                  type: object
-                  description: 绑定的 Definition 版本摘要（DefinitionsDigest）
-                  properties:
-                    actions:
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          id:
-                            type: string
-                          name:
-                            type: string
-                          versionId:
-                            type: string
-                          hash:
-                            type: string
-                    queries:
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          id:
-                            type: string
-                          name:
-                            type: string
-                          versionId:
-                            type: string
-                          hash:
-                            type: string
-                meta:
-                  type: object
-                  description: 元数据（PageSnapshotMeta）
-                  properties:
-                    pageId:
-                      type: string
-                    pageVersionId:
-                      type: string
-                    publishId:
-                      type: string
-                    schemaVersion:
-                      type: string
-                    createdAt:
-                      type: string
-                      format: date-time
-                    createdBy:
-                      type: string
-                    contentHash:
-                      type: string
-                    bindings:
-                      type: object
-                      properties:
-                        componentVersions:
-                          type: array
-                          items:
-                            type: string
-                        definitionVersions:
-                          type: array
-                          items:
-                            type: string
-                    runtimeVersion:
-                      type: string
-                      pattern: '^\d+\.\d+\.\d+$'
-                    env:
-                      type: string
-                      enum: [preview, staging, prod]
+CursorPaginationMeta:
+  type: object
+  description: 游标分页元数据（PageRecordsMetaVo）
+  properties:
+    pageSize:
+      type: number
+      description: 每页条数
+    pageToken:
+      type: string
+      description: 下一页游标
+
+# ============================================================================
+# 页面相关
+# ============================================================================
 
-ResourceManifests:
+ResolvePageResponse:
   type: object
+  required: [pageId, resolvedVersionId, cdnBase, snapshotUrl, manifestUrl, ops, etag, cacheTtlSeconds]
+  description: 页面解析响应（PageResolveResponseVo）
   properties:
-    components:
-      type: array
-      items:
-        $ref: '#/ComponentManifest'
-      description: 组件资源清单
-    actions:
-      type: array
-      items:
-        $ref: '#/ActionManifest'
-      description: 动作资源清单
-    queries:
-      type: array
-      items:
-        $ref: '#/QueryManifest'
-      description: 查询资源清单
+    pageId:
+      type: string
+      description: 页面 ID
+      example: page_123456
+    resolvedVersionId:
+      type: string
+      description: 解析后的页面版本 ID
+      example: pv_20240101_abc
+    cdnBase:
+      type: string
+      description: CDN 基础 URL
+      example: https://cdn.example.com
+    snapshotUrl:
+      type: string
+      description: Snapshot URL
+      example: https://cdn.example.com/pages/page_123456/snapshot.json
+    manifestUrl:
+      type: string
+      description: Manifest URL
+      example: https://cdn.example.com/pages/page_123456/manifest.json
+    ops:
+      description: 运维配置
+      allOf:
+        - $ref: '#/OpsConfig'
+    etag:
+      type: string
+      description: ETag（用于缓存）
+      example: '"abc123"'
+    cacheTtlSeconds:
+      type: number
+      description: 缓存 TTL（秒）
+      example: 300
+    traceId:
+      type: string
+      description: 链路追踪 ID
+    runtimeVersion:
+      type: string
+      description: 运行时版本（SemVer）
+      example: 1.0.0
 
-ComponentManifest:
+ManifestComponent:
   type: object
-  required: [componentType, version, source]
+  required: [name, version, source, integrity]
+  description: 组件清单项（ManifestComponentSwaggerVo）
   properties:
-    componentType:
+    name:
       type: string
-      description: 组件类型
+      description: 组件名称（Custom Element 标签名）
+      example: djvlc-button
     version:
       type: string
-      description: 组件版本
+      description: 版本号
+      example: 1.0.0
     source:
       type: string
+      description: 组件来源
       enum: [bundled, remote]
-      description: '组件来源：bundled = 内置组件（随 Runtime 打包），remote = 远程组件（从 CDN 加载）'
-    entryUrl:
+    entry:
       type: string
-      format: uri
-      description: '组件入口 URL（source 为 remote 时必填）'
-    styleUrl:
+      description: 入口 URL（remote 组件必填）
+    styleEntry:
       type: string
-      format: uri
-      description: 样式文件 URL
+      description: 样式入口 URL
     integrity:
       type: string
       description: SRI 完整性哈希
-    blocked:
-      type: boolean
-      description: 是否被阻断
-    fallback:
-      type: string
-      description: 降级组件类型
-
-ActionManifest:
-  type: object
-  required: [actionId, actionDefinitionVersionId]
-  properties:
-    actionId:
-      type: string
-      description: 动作 ID
-    actionDefinitionVersionId:
-      type: string
-      description: 动作定义版本 ID
-    actionType:
-      type: string
-      enum: [claim, signin, lottery, reserve, bind, task_complete, vote, share, form_submit, navigate, setState, showToast, refreshData, custom]
-      description: 动作类型
-    builtin:
+    preload:
       type: boolean
-      description: 是否内置动作
+      description: 是否预加载
 
-QueryManifest:
+ManifestRuntime:
   type: object
-  required: [queryId, queryVersionId]
+  required: [version, minVersion]
+  description: Runtime 版本信息（ManifestRuntimeVo）
   properties:
-    queryId:
+    version:
       type: string
-      description: 查询 ID
-    queryVersionId:
+      description: 版本
+      example: 1.0.0
+    minVersion:
       type: string
-      description: 查询定义版本 ID
-    cacheTtl:
-      type: integer
-      description: 缓存 TTL（秒）
+      description: 最低兼容版本
+      example: 0.9.0
 
-# 与 types/page/snapshot.ts KillSwitchItem 对齐
-KillSwitchItem:
+ManifestResponse:
   type: object
-  required: [targetType, targetId, enabled]
-  description: Kill-Switch 条目
+  required: [pageVersionId, manifestVersion, components, runtime]
+  description: 组件清单响应（ManifestSwaggerVo）
   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:
+    pageVersionId:
       type: string
-      description: 关闭操作者
-    userMessage:
+      description: 页面版本 ID
+    manifestVersion:
       type: string
-      description: 用户提示消息
+      description: 清单版本
+    components:
+      description: 组件列表
+      type: array
+      items:
+        $ref: '#/ManifestComponent'
+    runtime:
+      description: Runtime 版本
+      allOf:
+        - $ref: '#/ManifestRuntime'
 
-# 与 types/page/snapshot.ts BlockedComponentItem 对齐
-BlockedComponentItem:
+BlockedComponent:
   type: object
-  required: [name, reason]
-  description: 被阻断的组件条目
+  required: [name, reason, blockedAt, blockedBy]
+  description: 被阻断的组件（BlockedComponentVo）
   properties:
     name:
       type: string
       description: 组件名称
     version:
       type: string
-      pattern: '^\d+\.\d+\.\d+$'
-      description: 组件版本（可选，不指定则阻断所有版本）
+      description: 组件版本（不填则阻断所有版本）
     reason:
       type: string
       description: 阻断原因
     blockedAt:
       type: string
-      format: date-time
-      description: 阻断时间（ISO8601）
+      description: 阻断时间
     blockedBy:
       type: string
-      description: 阻断操作者
-    fallbackVersion:
-      type: string
-      pattern: '^\d+\.\d+\.\d+$'
-      description: 降级版本（可选）
-    urgent:
+      description: 操作者
+
+DegradeConfig:
+  type: object
+  required: [enabled, mode]
+  description: 降级配置（DegradeConfigVo）
+  properties:
+    enabled:
       type: boolean
-      description: 是否紧急阻断
+      description: 是否启用降级
+    mode:
+      type: string
+      description: 降级模式
+      enum: [fallback, static, error]
+    message:
+      type: string
+      description: 降级消息
 
 OpsConfig:
   type: object
-  description: 运维配置（运行时下发，与 types/page/snapshot.ts OpsConfig 对齐）
-  required: [killSwitch, blockedComponents, flags]
+  required: [killSwitch, blockedComponents, blockedPages, featureFlags, degradeConfig]
+  description: 运维配置（OpsConfigVo）
   properties:
-    configVersionId:
-      type: string
-      description: 配置版本 ID（用于缓存失效）
     killSwitch:
+      type: boolean
+      description: 全局 kill-switch
+    blockedComponents:
+      description: 被阻断的组件列表
       type: array
       items:
-        $ref: '#/KillSwitchItem'
-      description: Kill-Switch 列表（被紧急关闭的功能/动作）
-    blockedComponents:
+        $ref: '#/BlockedComponent'
+    blockedPages:
+      description: 被阻断的页面列表
       type: array
       items:
-        $ref: '#/BlockedComponentItem'
-      description: 被阻断的组件列表
-    flags:
+        type: string
+    featureFlags:
       type: object
+      description: 功能开关
       additionalProperties:
         type: boolean
-      description: 功能开关（Feature Flags）
-    expiresAt:
-      type: string
-      format: date-time
-      description: 配置过期时间（ISO8601）
+    degradeConfig:
+      description: 降级配置
+      allOf:
+        - $ref: '#/DegradeConfig'
 
 # ============================================================================
 # Action Gateway 动作相关
 # ============================================================================
 
-ExecuteActionRequest:
-  type: object
-  required: [actionType, params, context]
-  description: 动作执行请求（ActionExecuteRequest）
-  properties:
-    actionType:
-      type: string
-      enum: [claim, signin, lottery, reserve, bind, task_complete, vote, share, form_submit, navigate, setState, showToast, refreshData, custom]
-      description: 动作类型（ActionType | string）
-    actionDefinitionVersionId:
-      type: string
-      description: 动作定义版本 ID（可选，不提供则使用最新稳定版，UniqueId）
-    params:
-      type: object
-      additionalProperties: true
-      description: 动作参数（Record<string, JsonValue>）
-    context:
-      $ref: '#/ActionClientContext'
-      description: 客户端上下文（ActionClientContext，必填）
-    idempotencyKey:
-      type: string
-      minLength: 16
-      maxLength: 128
-      description: 幂等键（部分策略需要客户端提供，防重复提交）
-
 ActionClientContext:
   type: object
-  description: 动作执行上下文（ActionClientContext，问题追溯必须字段）
   required: [pageVersionId]
+  description: 动作执行上下文（ActionContextDto）
   properties:
     pageVersionId:
       type: string
-      description: 页面版本 ID（不可变，UniqueId）
+      description: 页面版本 ID
     componentVersionId:
       type: string
-      description: 组件版本 ID（UniqueId）
+      description: 组件版本 ID
     componentInstanceId:
       type: string
-      description: 组件实例 ID（UniqueId）
+      description: 组件实例 ID
     triggerEvent:
       type: string
       description: 触发事件名
@@ -537,477 +326,346 @@ ActionClientContext:
       description: 设备 ID
     channel:
       type: string
-      description: 渠道标识
+      description: 渠道
     clientTimestamp:
       type: string
-      format: date-time
-      description: 客户端时间戳（ISODateTime）
+      description: 客户端时间戳（ISO 8601）
     extra:
       type: object
+      description: 扩展数据
       additionalProperties: true
-      description: 扩展数据（Record<string, JsonValue>）
-
-ExecuteActionResponse:
-  allOf:
-    - $ref: '#/SuccessResponse'
-    - type: object
-      properties:
-        data:
-          type: object
-          properties:
-            actionId:
-              type: string
-              description: 动作执行 ID（UniqueId，用于审计追溯）
-            result:
-              description: 执行结果（泛型 T）
-            effects:
-              type: array
-              items:
-                $ref: '#/ActionEffect'
-              description: 副作用列表
-            errorCode:
-              type: string
-              description: 错误码（失败时）
-            errorMessage:
-              type: string
-              description: 错误消息（失败时，用户可见）
-            errorDetails:
-              type: object
-              additionalProperties: true
-              description: 错误详情（失败时，调试用）
-            requestId:
-              type: string
-              description: 请求 ID
-            traceId:
-              type: string
-              description: 链路追踪 ID
-            duration:
-              type: integer
-              description: 执行耗时（毫秒）
-            retryable:
-              type: boolean
-              description: 是否可重试
-            retryAfter:
-              type: integer
-              description: 建议重试延迟（毫秒）
-            riskDecision:
-              type: object
-              description: 风控决策（可选，风控拒绝时返回）
-              properties:
-                allowed:
-                  type: boolean
-                  description: 是否放行
-                reason:
-                  type: string
-                  description: 拒绝原因（如 RISK_BLOCKED）
-                code:
-                  type: string
-                  description: 风控错误码
 
-ActionEffect:
+ExecuteActionRequest:
   type: object
-  required: [type]
+  required: [actionType, params, context]
+  description: 动作执行请求（ActionExecuteDto）
   properties:
-    type:
+    actionType:
+      type: string
+      description: 动作类型
+      example: claim
+    actionDefinitionVersionId:
       type: string
-      enum: [setState, navigate, showToast, refreshData, openDialog, closeDialog, custom]
-      description: 副作用类型
-    payload:
+      description: 动作定义版本 ID（不提供则使用最新稳定版）
+    params:
       type: object
+      description: 动作参数
       additionalProperties: true
-      description: 副作用参数
+      example:
+        couponId: '12345'
+        quantity: 1
+      default: {}
+    idempotencyKey:
+      type: string
+      description: 幂等键
+    context:
+      description: 客户端上下文
+      allOf:
+        - $ref: '#/ActionClientContext'
 
-IdempotencyConflictResponse:
+ExecuteActionResponse:
   type: object
-  required: [success, data]
+  required: [success, requestId, traceId, actionId, duration]
+  description: 动作执行响应（ActionExecuteVo）
   properties:
     success:
       type: boolean
-      example: true
+      description: 是否成功
     data:
       type: object
-      properties:
-        idempotent:
-          type: boolean
-          example: true
-        originalActionId:
-          type: string
-          description: 原始动作执行 ID
-        originalResult:
-          description: 原始执行结果
-        originalExecutedAt:
-          type: string
-          format: date-time
-          description: 原始执行时间
+      description: 业务数据
+      additionalProperties: true
+      example:
+        couponId: '12345'
+        claimedAt: '2024-01-01T00:00:00Z'
+    errorCode:
+      type: string
+      description: 错误码
+    errorMessage:
+      type: string
+      description: 错误信息（用户可见）
+    errorDetails:
+      type: object
+      description: 错误详情（调试用）
+      additionalProperties: true
+    requestId:
+      type: string
+      description: 请求 ID
+    traceId:
+      type: string
+      description: 链路追踪 ID
+    actionId:
+      type: string
+      description: 动作 ID（用于审计追溯）
+    duration:
+      type: number
+      description: 执行耗时（毫秒）
+    retryable:
+      type: boolean
+      description: 是否可重试
+    retryAfter:
+      type: number
+      description: 建议重试延迟（毫秒）
 
 ValidateActionRequest:
   type: object
-  required: [actionType, params]
+  required: [actionDefinitionVersionId, params]
+  description: 动作参数验证请求（ActionValidateDto）
   properties:
-    actionType:
-      type: string
-      description: 动作类型
     actionDefinitionVersionId:
       type: string
       description: 动作定义版本 ID
     params:
       type: object
+      description: 待验证参数
       additionalProperties: true
-      description: 待验证的参数
+      example:
+        couponId: '12345'
+        quantity: 1
+      default: {}
 
 ValidateActionResponse:
   type: object
-  required: [data]
+  required: [valid]
+  description: 动作参数验证响应（ActionValidateVo）
   properties:
-    data:
-      type: object
-      required: [valid]
-      properties:
-        valid:
-          type: boolean
-          description: 是否有效
-        errors:
-          type: array
-          items:
-            type: object
-            properties:
-              path:
-                type: string
-                description: 参数路径
-              message:
-                type: string
-                description: 错误消息
-              code:
-                type: string
-                description: 错误码
-          description: 验证错误
+    valid:
+      type: boolean
+      description: 是否通过校验
+    errors:
+      description: 校验错误列表
+      type: array
+      items:
+        type: string
 
-ActionDefinitionResponse:
+ActionDefinitionVersionResponse:
   type: object
-  required: [data]
+  required: [uid, definitionUid, versionNumber, spec, status, createdBy, createdByUsername, createdAt]
+  description: 动作定义版本响应（ActionDefinitionVersionVo）
   properties:
-    data:
+    uid:
+      type: string
+      description: 版本 UID
+      example: 202401efgh87654321
+    definitionUid:
+      type: string
+      description: 所属定义 UID
+      example: 202401abcd12345678
+    versionNumber:
+      type: number
+      description: 版本号（递增）
+      example: 1
+    versionLabel:
+      type: string
+      nullable: true
+      description: 版本标签（可选，如 v1.0.0）
+      example: v1.0.0
+    description:
+      type: string
+      nullable: true
+      description: 版本描述
+    spec:
+      description: 规格快照（不可变的 ActionSpec）
       type: object
-      properties:
-        actionDefinitionVersionId:
-          type: string
-        actionType:
-          type: string
-        name:
-          type: string
-        paramsSchema:
-          type: object
-          description: 参数 JSON Schema
-        resultSchema:
-          type: object
-          description: 结果 JSON Schema
+      additionalProperties: true
+    status:
+      type: string
+      description: 版本状态
+      enum: [draft, stable, deprecated, blocked]
+      example: stable
+    createdBy:
+      type: string
+      description: 创建者 UID
+      example: 202401user1234
+    createdByUsername:
+      type: string
+      description: 创建者用户名
+      example: admin
+    createdAt:
+      type: string
+      format: date-time
+      description: 创建时间
 
 # ============================================================================
 # Data Proxy 查询相关
 # ============================================================================
 
+QueryContext:
+  type: object
+  description: 数据查询上下文（DataQueryContextDto）
+  properties:
+    uid:
+      type: string
+      description: 用户 UID
+    pageVersionId:
+      type: string
+      description: 页面版本 ID
+    componentVersionId:
+      type: string
+      description: 组件版本 ID
+
 QueryDataRequest:
   type: object
   required: [queryVersionId]
-  description: 数据查询请求（DataQueryRequest）
+  description: 数据查询请求（DataQueryDto）
   properties:
     queryVersionId:
       type: string
-      description: 查询定义版本 ID（UniqueId）
+      description: 查询版本 ID
     params:
       type: object
+      description: 查询参数
       additionalProperties: true
-      description: 查询参数（Record<string, JsonValue>）
-    cacheControl:
-      type: object
-      description: 缓存策略覆盖
-      properties:
-        noCache:
-          type: boolean
-          description: 是否跳过缓存
-        forceRefresh:
-          type: boolean
-          description: 强制刷新缓存
     context:
-      $ref: '#/QueryContext'
-      description: 客户端上下文（可选）
+      description: 上下文
+      allOf:
+        - $ref: '#/QueryContext'
 
-QueryContext:
+QueryMetadata:
   type: object
-  description: 数据查询上下文（DataQueryRequest.context）
+  description: 查询元数据（DataQueryMetadataVo）
   properties:
-    pageVersionId:
-      type: string
-      description: 页面版本 ID（UniqueId）
-    componentVersionId:
-      type: string
-      description: 组件版本 ID（UniqueId，可选）
+    fromCache:
+      type: boolean
+      description: 是否来自缓存
+    duration:
+      type: number
+      description: 查询耗时（毫秒）
 
 QueryDataResponse:
-  allOf:
-    - $ref: '#/SuccessResponse'
-    - type: object
-      properties:
-        data:
-          description: 查询结果数据（泛型 T）
-        # 错误信息（失败时）
-        errorCode:
-          type: string
-          description: 错误码（失败时）
-        errorMessage:
-          type: string
-          description: 错误消息（失败时）
-        # 缓存信息
-        fromCache:
-          type: boolean
-          description: 是否来自缓存
-        cachedAt:
-          type: string
-          format: date-time
-          description: 缓存时间戳（ISODateTime）
-        age:
-          type: integer
-          description: 数据新鲜度（秒）
-        # 追踪信息
-        requestId:
-          type: string
-          description: 请求 ID
-        traceId:
-          type: string
-          description: 链路追踪 ID
-        duration:
-          type: integer
-          description: 查询耗时（毫秒）
-        # 降级信息
-        degraded:
-          type: boolean
-          description: 是否为降级数据
-        degradedReason:
-          type: string
-          description: 降级原因
-
-QueryDefinitionResponse:
   type: object
-  required: [data]
+  required: [success]
+  description: 数据查询响应（DataQueryVo）
   properties:
+    success:
+      type: boolean
+      description: 是否成功
     data:
       type: object
-      properties:
-        queryVersionId:
-          type: string
-        name:
-          type: string
-        paramsSchema:
-          type: object
-          description: 参数 JSON Schema
-        resultSchema:
-          type: object
-          description: 结果 JSON Schema
-        cacheTtl:
-          type: integer
-          description: 缓存 TTL（秒）
+      description: 数据
+      additionalProperties: true
+    errorCode:
+      type: string
+      description: 错误码
+    errorMessage:
+      type: string
+      description: 错误消息
+    metadata:
+      description: 元数据
+      allOf:
+        - $ref: '#/QueryMetadata'
+
+BatchQueryItemRequest:
+  type: object
+  required: [queryVersionId]
+  description: 批量查询项（DataQueryBatchItemDto）
+  properties:
+    queryVersionId:
+      type: string
+      description: 查询版本 ID
+    params:
+      type: object
+      description: 查询参数
+      additionalProperties: true
 
 BatchQueryRequest:
   type: object
   required: [queries]
+  description: 批量查询请求（DataQueryBatchDto）
   properties:
     queries:
+      description: 查询列表
       type: array
       items:
-        type: object
-        required: [queryVersionId]
-        properties:
-          queryVersionId:
-            type: string
-          params:
-            type: object
-          alias:
-            type: string
-            description: 查询别名（用于结果映射）
-      maxItems: 20
-      description: 查询列表（最多 20 个）
-    context:
-      $ref: '#/QueryContext'
+        $ref: '#/BatchQueryItemRequest'
 
 BatchQueryResponse:
   type: object
-  required: [success, data]
+  required: [results]
+  description: 批量查询响应（DataQueryBatchVo）
   properties:
-    success:
-      type: boolean
-    data:
-      type: object
-      additionalProperties:
-        type: object
-        properties:
-          success:
-            type: boolean
-          data:
-            description: 查询结果
-          error:
-            type: object
-            properties:
-              code:
-                type: string
-              message:
-                type: string
-      description: 按 alias 或 queryVersionId 索引的结果
-
-# ============================================================================
-# 通用分页
-# ============================================================================
+    results:
+      description: 各查询结果列表
+      type: array
+      items:
+        $ref: '#/QueryDataResponse'
 
-# 与 types/src/common/api.ts PaginationMeta 严格一致
-PaginationMeta:
+QueryDefinitionResponse:
   type: object
-  required: [page, pageSize, total, totalPages, hasNext, hasPrev]
-  description: 分页元数据（PaginationMeta）
+  required: [uid, queryUid, versionNumber, spec, status]
+  description: 查询定义响应（DataQueryDefinitionVo）
   properties:
-    page:
-      type: integer
-      minimum: 1
-      description: 当前页码
-    pageSize:
-      type: integer
-      minimum: 1
-      maximum: 100
-      description: 每页数量
-    total:
-      type: integer
-      minimum: 0
-      description: 总记录数
-    totalPages:
-      type: integer
-      minimum: 0
-      description: 总页数
-    hasNext:
-      type: boolean
-      description: 是否有下一页
-    hasPrev:
-      type: boolean
-      description: 是否有上一页
-
-# ============================================================================
-# Tenant 租户相关
-# ============================================================================
-
-TenantInfo:
-  type: object
-  required: [appId, appName, status]
-  properties:
-    appId:
-      type: string
-      description: 应用 ID
-    appName:
-      type: string
-      description: 应用名称
-    status:
+    uid:
       type: string
-      enum: [active, suspended, disabled]
-      description: 应用状态
-    workspaceId:
+      description: 版本 UID
+      example: 202401efgh87654321
+    queryUid:
       type: string
-      description: 工作空间 ID
-    cdnDomain:
-      type: string
-      format: uri
-      description: CDN 域名
-    apiDomain:
-      type: string
-      format: uri
-      description: API 域名
-
-TenantConfig:
-  type: object
-  properties:
-    features:
-      type: object
-      additionalProperties:
-        type: boolean
-      description: 功能开关
-    theme:
+      description: 所属查询 UID
+      example: 202401abcd12345678
+    versionNumber:
+      type: number
+      description: 版本号（递增）
+      example: 1
+    versionLabel:
+      type: string
+      nullable: true
+      description: 版本标签（可选，如 v1.0.0）
+      example: v1.0.0
+    spec:
+      description: 规格快照（不可变的 DataQuerySpec）
       type: object
       additionalProperties: true
-      description: 主题配置
-    cdnDomain:
-      type: string
-      format: uri
-      description: CDN 域名
-    runtimeVersion:
+    status:
       type: string
-      description: 推荐的 Runtime 版本
-    blockedComponents:
-      type: array
-      items:
-        type: object
-        properties:
-          componentType:
-            type: string
-          version:
-            type: string
-          reason:
-            type: string
-      description: 阻断的组件列表
-    killSwitch:
-      type: object
-      properties:
-        enabled:
-          type: boolean
-        pageIds:
-          type: array
-          items:
-            type: string
-          description: 被 Kill 的页面 ID 列表
-        fallbackUrl:
-          type: string
-          format: uri
-      description: Kill Switch 配置
+      description: 版本状态
+      enum: [draft, stable, deprecated, blocked]
+      example: stable
 
 # ============================================================================
-# Health 健康检查相关
+# Activity 活动相关
 # ============================================================================
 
-HealthResponse:
+ActivityInfoData:
   type: object
-  required: [status, version]
+  required: [activityId, name, type, startAt, endAt]
+  description: 活动信息数据（ActivityInfoDataVo）
   properties:
-    status:
+    activityId:
       type: string
-      enum: [healthy, degraded, unhealthy]
-      description: 服务状态
-    version:
+      description: 活动 ID
+    name:
       type: string
-      description: 服务版本
-    uptime:
-      type: integer
-      description: 运行时间（秒）
-    timestamp:
+      description: 活动名称
+    type:
+      type: string
+      description: 活动类型
+    startAt:
       type: string
+      description: 开始时间
+      format: date-time
+    endAt:
+      type: string
+      description: 结束时间
       format: date-time
-      description: 检查时间
-    dependencies:
-      type: object
-      additionalProperties:
-        type: object
-        properties:
-          status:
-            type: string
-            enum: [healthy, degraded, unhealthy]
-          latency:
-            type: integer
-            description: 延迟（毫秒）
-          message:
-            type: string
-      description: 依赖服务状态
 
-# ============================================================================
-# Activity 用户活动相关
-# ============================================================================
+ActivityInfoResponse:
+  type: object
+  required: [success, data]
+  description: 活动信息响应（ActivityInfoVo）
+  properties:
+    success:
+      type: boolean
+      description: 是否成功
+    data:
+      description: 活动数据
+      allOf:
+        - $ref: '#/ActivityInfoData'
 
 ActivityStatus:
   type: object
   required: [activityUid, name, type, isInProgress, startAt, endAt]
-  description: 活动状态信息（与 docs ActivityStatusVo 对齐）
+  description: 活动状态（ActivityStatusVo）
   properties:
     activityUid:
       type: string
@@ -1024,334 +682,464 @@ ActivityStatus:
       description: 是否进行中
     startAt:
       type: string
-      format: date-time
-      description: 开始时间（ISODateTime）
+      description: 开始时间
     endAt:
       type: string
-      format: date-time
-      description: 结束时间（ISODateTime）
+      description: 结束时间
 
-PublicActivityInfo:
+ActivityStatusResponse:
   type: object
-  required: [id, name, type, status]
+  description: 活动状态响应
   properties:
-    id:
+    activityUid:
       type: string
-      description: 活动 ID
+      description: 活动 UID
     name:
       type: string
       description: 活动名称
     type:
       type: string
-      enum: [claim, signin, lottery, reserve, task, vote, share, bind, custom]
       description: 活动类型
-    status:
-      type: string
-      enum: [active, ended]
-      description: 活动状态
-    description:
-      type: string
-      description: 活动描述
-    startTime:
+      enum: [claim, signin]
+    isInProgress:
+      type: boolean
+      description: 是否进行中
+    startAt:
       type: string
-      format: date-time
       description: 开始时间
-    endTime:
+    endAt:
       type: string
-      format: date-time
       description: 结束时间
-    rules:
-      type: object
-      additionalProperties: true
-      description: 活动规则（公开部分）
-    rewards:
-      type: array
-      items:
-        type: object
-        properties:
-          name:
-            type: string
-          description:
-            type: string
-          icon:
-            type: string
-      description: 奖励列表
 
-UserActivityState:
+SigninCalendarData:
   type: object
-  required: [activityId, userId, activityType, canParticipate, typeState]
-  description: 用户活动状态（UserActivityState，根据 types/src/activity/index.ts）
+  required: [activityId, month, signedDates, consecutiveDays, totalDays]
+  description: 签到日历数据（SigninCalendarDataVo）
   properties:
     activityId:
       type: string
-      description: 活动 ID（UniqueId）
-    userId:
-      type: string
-      description: 用户 ID
-    activityType:
+      description: 活动 ID
+    month:
       type: string
-      enum: [claim, signin, lottery, reserve, task, vote, share, bind, custom]
-      description: 活动类型（ActivityType）
-    canParticipate:
+      description: 月份（YYYY-MM）
+      example: '2024-01'
+    signedDates:
+      description: 已签到日期列表
+      example: ['2024-01-01', '2024-01-02']
+      type: array
+      items:
+        type: string
+    consecutiveDays:
+      type: number
+      description: 连续签到天数
+    totalDays:
+      type: number
+      description: 累计签到天数
+
+SigninCalendarResponse:
+  type: object
+  required: [success, data]
+  description: 签到日历响应（SigninCalendarVo）
+  properties:
+    success:
       type: boolean
-      description: 是否可参与
-    notParticipateReason:
-      type: string
-      description: 不可参与原因
-    remainingCount:
-      type: integer
-      description: 剩余参与次数
-    typeState:
-      type: object
-      description: 类型特定状态（ClaimState | SigninState | LotteryState）
-      oneOf:
-        - type: object
-          required: [type, claimed]
-          properties:
-            type:
-              type: string
-              enum: [claim]
-            claimed:
-              type: boolean
-            claimedAt:
-              type: string
-              format: date-time
-            claimedPrizeId:
-              type: string
-            availablePrizes:
-              type: array
-              items:
-                type: object
-                properties:
-                  prizeId:
-                    type: string
-                  name:
-                    type: string
-                  stock:
-                    type: integer
-        - type: object
-          required: [type, signedToday, consecutiveDays, totalDays, cycleRecords, makeupAvailable]
-          properties:
-            type:
-              type: string
-              enum: [signin]
-            signedToday:
-              type: boolean
-            todaySignedAt:
-              type: string
-              format: date-time
-            consecutiveDays:
-              type: integer
-            totalDays:
-              type: integer
-            cycleRecords:
-              type: array
-              items:
-                type: object
-                properties:
-                  dayKey:
-                    type: string
-                  signed:
-                    type: boolean
-                  isMakeup:
-                    type: boolean
-            makeupAvailable:
-              type: integer
-            nextReward:
-              type: object
-              properties:
-                type:
-                  type: string
-                  enum: [consecutive, cumulative]
-                daysNeeded:
-                  type: integer
-                reward:
-                  type: object
-                  additionalProperties: true
-        - type: object
-          required: [type, freeDrawsRemaining, todayDrawCount, totalDrawCount]
-          properties:
-            type:
-              type: string
-              enum: [lottery]
-            freeDrawsRemaining:
-              type: integer
-            todayDrawCount:
-              type: integer
-            totalDrawCount:
-              type: integer
-            pityProgress:
-              type: object
-              properties:
-                current:
-                  type: integer
-                target:
-                  type: integer
-            resources:
-              type: array
-              items:
-                type: object
-                properties:
-                  type:
-                    type: string
-                  amount:
-                    type: integer
+      description: 是否成功
+    data:
+      description: 日历数据
+      allOf:
+        - $ref: '#/SigninCalendarData'
 
-SigninCalendar:
+PaginatedRecordsResponse:
   type: object
-  required: [year, month, records]
+  required: [success, data]
+  description: 分页记录响应（PaginatedRecordsVo）
   properties:
-    year:
-      type: integer
-      description: 年份
-    month:
-      type: integer
-      minimum: 1
-      maximum: 12
-      description: 月份
-    records:
+    success:
+      type: boolean
+      description: 是否成功
+    data:
       type: array
+      description: 记录列表
       items:
         type: object
-        properties:
-          day:
-            type: integer
-            minimum: 1
-            maximum: 31
-          signedIn:
-            type: boolean
-          reward:
-            type: object
-            properties:
-              name:
-                type: string
-              amount:
-                type: number
-      description: 签到记录
-    consecutiveDays:
-      type: integer
-      description: 连续签到天数
-    totalDays:
-      type: integer
-      description: 本月签到总天数
+    meta:
+      description: 分页元数据
+      allOf:
+        - $ref: '#/CursorPaginationMeta'
 
-ClaimRecordInfo:
+RewardInfo:
   type: object
-  required: [id, rewardType, status, createdAt]
+  required: [type, value, description]
+  description: 奖励信息（RewardInfoVo）
   properties:
-    id:
-      type: string
-      description: 记录 ID
-    activityId:
-      type: string
-      description: 活动 ID
-    rewardType:
+    type:
       type: string
       description: 奖励类型
-    rewardName:
-      type: string
-      description: 奖励名称
-    rewardValue:
+    value:
       type: number
       description: 奖励值
-    status:
+    description:
       type: string
-      enum: [pending, claimed, expired]
-      description: 领取状态
-    createdAt:
+      description: 奖励描述
+
+MilestoneInfo:
+  type: object
+  required: [days, reward]
+  description: 里程碑信息（MilestoneInfoVo）
+  properties:
+    days:
+      type: number
+      description: 目标天数
+    reward:
+      description: 里程碑奖励
+      allOf:
+        - $ref: '#/RewardInfo'
+
+ClaimStatusResponse:
+  type: object
+  required: [activityUid, hasClaimed, remainingCount, totalCount]
+  description: 领取状态响应（ClaimStatusVo）
+  properties:
+    activityUid:
       type: string
-      format: date-time
-      description: 创建时间
+      description: 活动 UID
+    hasClaimed:
+      type: boolean
+      description: 是否已领取
     claimedAt:
       type: string
-      format: date-time
       description: 领取时间
-    expiresAt:
-      type: string
-      format: date-time
-      description: 过期时间
+    remainingCount:
+      type: number
+      description: 剩余领取次数
+    totalCount:
+      type: number
+      description: 总领取次数
 
-LotteryRecordInfo:
+SigninStatusResponse:
   type: object
-  required: [id, prizeId, status, createdAt]
+  required: [activityUid, hasSignedToday, consecutiveDays, totalDays, signedDates]
+  description: 签到状态响应（SigninStatusVo）
   properties:
-    id:
-      type: string
-      description: 记录 ID
-    activityId:
-      type: string
-      description: 活动 ID
-    prizeId:
-      type: string
-      description: 奖品 ID
-    prizeName:
-      type: string
-      description: 奖品名称
-    prizeType:
-      type: string
-      enum: [physical, virtual, coupon, points, none]
-      description: 奖品类型
-    status:
-      type: string
-      enum: [won, notWon, claimed, shipped]
-      description: 状态
-    createdAt:
-      type: string
-      format: date-time
-      description: 抽奖时间
-    claimedAt:
+    activityUid:
       type: string
-      format: date-time
-      description: 领取时间
+      description: 活动 UID
+    hasSignedToday:
+      type: boolean
+      description: 今日是否已签到
+    consecutiveDays:
+      type: number
+      description: 连续签到天数
+    totalDays:
+      type: number
+      description: 累计签到天数
+    signedDates:
+      description: 签到日期列表
+      type: array
+      items:
+        type: string
+    todayReward:
+      description: 今日奖励
+      allOf:
+        - $ref: '#/RewardInfo'
+    nextMilestone:
+      description: 下一个里程碑
+      allOf:
+        - $ref: '#/MilestoneInfo'
 
 # ============================================================================
 # Track 埋点相关
 # ============================================================================
 
-TrackRequest:
+TrackEvent:
   type: object
-  required: [eventName]
+  required: [eventType, eventName]
+  description: 埋点事件（TrackEventDto）
   properties:
-    eventName:
-      type: string
-      minLength: 1
-      maxLength: 255
-      description: 事件名称
     eventType:
       type: string
-      enum: [page_view, click, exposure, custom]
-      default: custom
       description: 事件类型
+    eventName:
+      type: string
+      description: 事件名称
     properties:
       type: object
-      additionalProperties: true
       description: 事件属性
     timestamp:
+      type: number
+      description: 事件时间戳（毫秒）
+
+TrackContext:
+  type: object
+  description: 埋点上下文（TrackContextDto）
+  properties:
+    uid:
       type: string
-      format: date-time
-      description: 事件时间（默认为服务器接收时间）
+      description: 用户 UID
+    pageVersionId:
+      type: string
+      description: 页面版本 ID
+    componentVersionId:
+      type: string
+      description: 组件版本 ID
+    deviceId:
+      type: string
+      description: 设备 ID
+    sessionId:
+      type: string
+      description: 会话 ID
+    appId:
+      type: string
+      description: 应用 ID
+
+TrackSingleRequest:
+  type: object
+  required: [event]
+  description: 单个埋点请求（TrackSingleDto）
+  properties:
+    event:
+      description: 事件
+      allOf:
+        - $ref: '#/TrackEvent'
     context:
+      description: 上下文
+      allOf:
+        - $ref: '#/TrackContext'
+
+TrackSingleResponse:
+  type: object
+  required: [success, data]
+  description: 单个埋点响应（TrackSingleResponseVo）
+  properties:
+    success:
+      type: boolean
+      description: 是否成功
+    data:
       type: object
+      required: [eventId]
       properties:
-        pageVersionId:
-          type: string
-        componentVersionId:
-          type: string
-        sessionId:
-          type: string
-        deviceType:
+        eventId:
           type: string
-        traceId:
-          type: string
-      description: 上下文信息
+          description: 事件 ID
 
 TrackBatchRequest:
   type: object
   required: [events]
+  description: 批量埋点请求（TrackBatchDto）
   properties:
     events:
+      description: 事件列表
+      type: array
+      items:
+        $ref: '#/TrackEvent'
+    context:
+      description: 上下文
+      allOf:
+        - $ref: '#/TrackContext'
+
+TrackBatchError:
+  type: object
+  required: [index, reason]
+  description: 批量埋点错误（TrackBatchErrorVo）
+  properties:
+    index:
+      type: number
+      description: 错误索引
+    reason:
+      type: string
+      description: 错误原因
+
+TrackBatchResponse:
+  type: object
+  required: [success, data]
+  description: 批量埋点响应（TrackBatchResponseVo）
+  properties:
+    success:
+      type: boolean
+      description: 是否成功
+    data:
+      type: object
+      required: [accepted, rejected, errors]
+      properties:
+        accepted:
+          type: number
+          description: 接受的事件数量
+        rejected:
+          type: number
+          description: 拒绝的事件数量
+        errors:
+          description: 错误列表
+          type: array
+          items:
+            $ref: '#/TrackBatchError'
+
+# ============================================================================
+# Tenant 租户相关
+# ============================================================================
+
+ResolveTenantRequest:
+  type: object
+  description: 租户解析请求（TenantResolveDto）
+  properties:
+    appKey:
+      type: string
+      description: 应用 Key
+    host:
+      type: string
+      description: 主机/域名
+    channel:
+      type: string
+      description: 渠道
+
+ResolveTenantData:
+  type: object
+  required: [appId, name, status, type]
+  description: 租户解析数据（TenantResolveDataVo）
+  properties:
+    appId:
+      type: string
+      description: 应用 ID
+    name:
+      type: string
+      description: 租户名称
+    status:
+      type: string
+      description: 租户状态
+      example: active
+    type:
+      type: string
+      description: 租户类型
+      example: standard
+    logo:
+      type: string
+      description: 租户 Logo URL
+    config:
+      type: object
+      description: 租户配置
+      additionalProperties: true
+    channel:
+      type: string
+      description: 渠道
+    domain:
+      type: string
+      description: 自定义域名
+
+ResolveTenantResponse:
+  type: object
+  required: [success, data]
+  description: 租户解析响应（TenantResolveVo）
+  properties:
+    success:
+      type: boolean
+      description: 是否成功
+    data:
+      description: 租户数据
+      allOf:
+        - $ref: '#/ResolveTenantData'
+
+TenantConfigData:
+  type: object
+  required: [appId, status]
+  description: 租户配置数据（TenantConfigDataVo）
+  properties:
+    appId:
+      type: string
+      description: 应用 ID
+    status:
+      type: string
+      description: 租户状态
+      example: active
+    featureFlags:
+      type: object
+      description: 功能开关
+      additionalProperties:
+        type: boolean
+    theme:
+      type: object
+      description: 主题配置
+      additionalProperties: true
+    cdnBase:
+      type: string
+      description: CDN 基地址
+    blockedComponents:
+      description: 阻断组件列表
       type: array
       items:
-        $ref: '#/TrackRequest'
-      maxItems: 100
-      description: 事件列表（最多 100 个）
+        type: string
+    killSwitch:
+      type: boolean
+      description: 全局 killSwitch
+
+TenantConfigResponse:
+  type: object
+  required: [success, data]
+  description: 租户配置响应（TenantConfigVo）
+  properties:
+    success:
+      type: boolean
+      description: 是否成功
+    data:
+      description: 配置数据
+      allOf:
+        - $ref: '#/TenantConfigData'
+
+# ============================================================================
+# Health 健康检查相关
+# ============================================================================
+
+HealthCheckResponse:
+  type: object
+  required: [status, timestamp]
+  description: 健康检查响应（HealthCheckVo）
+  properties:
+    status:
+      type: string
+      description: 服务状态
+      example: healthy
+    timestamp:
+      type: string
+      description: 响应时间戳
+      example: '2026-02-04T12:00:00.000Z'
+
+LivenessResponse:
+  type: object
+  required: [status]
+  description: 存活检查响应（LivenessVo）
+  properties:
+    status:
+      type: string
+      description: 服务状态
+      example: alive
+
+HealthCheckItem:
+  type: object
+  description: 健康检查项
+  properties:
+    status:
+      type: string
+      description: 检查状态
+    message:
+      type: string
+      description: 检查消息
+
+ReadinessResponse:
+  type: object
+  required: [status, checks]
+  description: 就绪检查响应（ReadinessVo）
+  properties:
+    status:
+      type: string
+      description: 服务状态
+      example: ready
+    checks:
+      type: object
+      description: 各检查项状态
+      additionalProperties:
+        $ref: '#/HealthCheckItem'
+      example:
+        database:
+          status: healthy
+          message: Connection OK
+        redis:
+          status: healthy
+          message: Connection OK