@djvlc/openapi-user-client 1.7.14 → 1.8.0

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: 灰度匹配信息（可选，用于调试）
@@ -223,14 +215,20 @@ ResolvePageResponse:
                           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
@@ -337,7 +335,7 @@ ResourceManifests:
 
 ComponentManifest:
   type: object
-  required: [componentType, version, entryUrl]
+  required: [componentType, version, source]
   properties:
     componentType:
       type: string
@@ -345,10 +343,14 @@ ComponentManifest:
     version:
       type: string
       description: 组件版本
+    source:
+      type: string
+      enum: [bundled, remote]
+      description: '组件来源：bundled = 内置组件（随 Runtime 打包），remote = 远程组件（从 CDN 加载）'
     entryUrl:
       type: string
       format: uri
-      description: 组件入口 URL
+      description: '组件入口 URL（source 为 remote 时必填）'
     styleUrl:
       type: string
       format: uri
@@ -395,33 +397,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 +507,7 @@ ExecuteActionRequest:
       additionalProperties: true
       description: 动作参数（Record<string, JsonValue>）
     context:
-      $ref: '#/ActionContext'
+      $ref: '#/ActionClientContext'
       description: 客户端上下文（ActionClientContext，必填）
     idempotencyKey:
       type: string
@@ -452,7 +515,7 @@ ExecuteActionRequest:
       maxLength: 128
       description: 幂等键（部分策略需要客户端提供，防重复提交）
 
-ActionContext:
+ActionClientContext:
   type: object
   description: 动作执行上下文（ActionClientContext，问题追溯必须字段）
   required: [pageVersionId]
@@ -527,6 +590,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 +857,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 +880,12 @@ PaginationMeta:
       type: integer
       minimum: 0
       description: 总页数
+    hasNext:
+      type: boolean
+      description: 是否有下一页
+    hasPrev:
+      type: boolean
+      description: 是否有上一页
 
 # ============================================================================
 # Tenant 租户相关
@@ -920,6 +1004,33 @@ HealthResponse:
 # Activity 用户活动相关
 # ============================================================================
 
+ActivityStatus:
+  type: object
+  required: [activityUid, name, type, isInProgress, startAt, endAt]
+  description: 活动状态信息（与 docs ActivityStatusVo 对齐）
+  properties:
+    activityUid:
+      type: string
+      description: 活动 UID
+    name:
+      type: string
+      description: 活动名称
+    type:
+      type: string
+      description: 活动类型
+      enum: [claim, signin]
+    isInProgress:
+      type: boolean
+      description: 是否进行中
+    startAt:
+      type: string
+      format: date-time
+      description: 开始时间（ISODateTime）
+    endAt:
+      type: string
+      format: date-time
+      description: 结束时间（ISODateTime）
+
 PublicActivityInfo:
   type: object
   required: [id, name, type, status]

package/openapi/src/openapi.yaml

@@ -49,6 +49,10 @@ paths:
   # 页面解析（根据设计总纲 V2）
   /page/resolve:
     $ref: './paths/pages.yaml#/resolve'
+  /page/manifest:
+    $ref: './paths/pages.yaml#/manifest'
+  /page/config:
+    $ref: './paths/pages.yaml#/config'
   
   # Action Gateway（统一入口）
   /actions/execute:
@@ -77,6 +81,12 @@ paths:
     $ref: './paths/activities.yaml#/claimRecords'
   /activities/{activityId}/lottery:
     $ref: './paths/activities.yaml#/lotteryRecords'
+  /activities/{activityId}/status:
+    $ref: './paths/activities.yaml#/activityStatus'
+  /activities/{activityId}/claim/status:
+    $ref: './paths/activities.yaml#/claimStatus'
+  /activities/{activityId}/signin/status:
+    $ref: './paths/activities.yaml#/signinStatus'
   
   # 埋点上报
   /track:

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/activities.yaml

@@ -153,6 +153,107 @@ claimRecords:
     security:
       - BearerAuth: []
 
+activityStatus:
+  get:
+    tags:
+      - Activities
+    summary: 获取活动状态（兼容）
+    operationId: getActivityStatus
+    description: |
+      获取活动的当前状态信息，包括是否进行中、时间范围等。
+      不需要登录，可用于前端判断活动是否在有效期内。
+    parameters:
+      - name: activityId
+        in: path
+        required: true
+        schema:
+          type: string
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  $ref: '../components/schemas/_index.yaml#/ActivityStatus'
+      '404':
+        $ref: '../components/responses/_index.yaml#/NotFound'
+    security: []
+
+claimStatus:
+  get:
+    tags:
+      - Activities
+    summary: 获取领取状态
+    operationId: getClaimStatus
+    description: 获取用户在指定活动中的领取状态
+    parameters:
+      - name: activityId
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: uid
+        in: query
+        required: true
+        schema:
+          type: string
+        description: 用户 UID
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  type: object
+                  description: 领取状态数据
+    security:
+      - BearerAuth: []
+
+signinStatus:
+  get:
+    tags:
+      - Activities
+    summary: 获取签到状态
+    operationId: getSigninStatus
+    description: 获取用户在指定活动中的签到状态
+    parameters:
+      - name: activityId
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: uid
+        in: query
+        required: true
+        schema:
+          type: string
+        description: 用户 UID
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  type: object
+                  description: 签到状态数据
+    security:
+      - BearerAuth: []
+
 lotteryRecords:
   get:
     tags:

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
@@ -74,3 +80,93 @@ resolve:
         $ref: '../components/responses/_index.yaml#/NotFound'
       '503':
         $ref: '../components/responses/_index.yaml#/ServiceUnavailable'
+
+manifest:
+  get:
+    tags: [Pages]
+    operationId: getPageManifest
+    summary: 获取组件清单
+    description: |
+      返回页面的组件锁定清单（manifest），包含所有引用的组件版本和资源信息。
+      
+      用途：
+      - Runtime 根据 manifest 预加载组件资源
+      - Editor 根据 manifest 展示组件依赖
+    parameters:
+      - name: X-Trace-Id
+        in: header
+        required: false
+        schema:
+          type: string
+        description: 链路追踪 ID（OTel，全链路透传）
+      - name: pageId
+        in: query
+        required: true
+        schema:
+          type: string
+        description: 页面 ID
+      - name: env
+        in: query
+        required: false
+        schema:
+          type: string
+          enum: [prod, preview, staging]
+          default: prod
+        description: 环境（prod/preview/staging）
+    responses:
+      '200':
+        description: 获取成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  $ref: '../components/schemas/_index.yaml#/ResourceManifests'
+      '400':
+        $ref: '../components/responses/_index.yaml#/BadRequest'
+      '404':
+        $ref: '../components/responses/_index.yaml#/NotFound'
+
+config:
+  get:
+    tags: [Pages]
+    operationId: getPageConfig
+    summary: 获取运维配置
+    description: |
+      返回当前运维配置（killSwitch、blockedComponents、featureFlags 等）。
+      
+      用途：
+      - Runtime 启动时获取全局运维配置
+      - 判断是否有组件被阻断或功能被关闭
+    parameters:
+      - name: X-Trace-Id
+        in: header
+        required: false
+        schema:
+          type: string
+        description: 链路追踪 ID（OTel，全链路透传）
+      - name: env
+        in: query
+        required: false
+        schema:
+          type: string
+          enum: [prod, preview, staging]
+          default: prod
+        description: 环境（prod/preview/staging）
+    responses:
+      '200':
+        description: 获取成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  $ref: '../components/schemas/_index.yaml#/OpsConfig'
+      '503':
+        $ref: '../components/responses/_index.yaml#/ServiceUnavailable'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djvlc/openapi-user-client",
-  "version": "1.7.14",
+  "version": "1.8.0",
   "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.13"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",