@djvlc/openapi-user-client 1.7.14 → 1.8.0

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
@@ -124,6 +130,102 @@ paths:
           $ref: '#/components/responses/NotFound'
         '503':
           $ref: '#/components/responses/ServiceUnavailable'
+  /page/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/ResourceManifests'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /page/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/OpsConfig'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailable'
   /actions/execute:
     post:
       tags:
@@ -155,6 +257,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:
@@ -518,6 +635,104 @@ paths:
                     $ref: '#/components/schemas/PaginationMeta'
       security:
         - BearerAuth: []
+  /activities/{activityId}/status:
+    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/ActivityStatus'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      security: []
+  /activities/{activityId}/claim/status:
+    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: []
+  /activities/{activityId}/signin/status:
+    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: []
   /track:
     post:
       tags:
@@ -822,36 +1037,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 +1181,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: 灰度匹配信息（可选，用于调试）
@@ -954,14 +1243,22 @@ components:
                               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
@@ -1076,7 +1373,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 +1391,109 @@ components:
           type: string
           example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
           description: 链路追踪 ID（可选，用于分布式追踪）
-    ActionContext:
+    ComponentManifest:
+      type: object
+      required:
+        - componentType
+        - version
+        - source
+      properties:
+        componentType:
+          type: string
+          description: 组件类型
+        version:
+          type: string
+          description: 组件版本
+        source:
+          type: string
+          enum:
+            - bundled
+            - remote
+          description: 组件来源：bundled = 内置组件（随 Runtime 打包），remote = 远程组件（从 CDN 加载）
+        entryUrl:
+          type: string
+          format: uri
+          description: 组件入口 URL（source 为 remote 时必填）
+        styleUrl:
+          type: string
+          format: uri
+          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:
+          type: boolean
+          description: 是否内置动作
+    QueryManifest:
+      type: object
+      required:
+        - queryId
+        - queryVersionId
+      properties:
+        queryId:
+          type: string
+          description: 查询 ID
+        queryVersionId:
+          type: string
+          description: 查询定义版本 ID
+        cacheTtl:
+          type: integer
+          description: 缓存 TTL（秒）
+    ResourceManifests:
+      type: object
+      properties:
+        components:
+          type: array
+          items:
+            $ref: '#/components/schemas/ComponentManifest'
+          description: 组件资源清单
+        actions:
+          type: array
+          items:
+            $ref: '#/components/schemas/ActionManifest'
+          description: 动作资源清单
+        queries:
+          type: array
+          items:
+            $ref: '#/components/schemas/QueryManifest'
+          description: 查询资源清单
+    ActionClientContext:
       type: object
       description: 动作执行上下文（ActionClientContext，问题追溯必须字段）
       required:
@@ -1160,7 +1559,7 @@ components:
           additionalProperties: true
           description: 动作参数（Record<string, JsonValue>）
         context:
-          $ref: '#/components/schemas/ActionContext'
+          $ref: '#/components/schemas/ActionClientContext'
           description: 客户端上下文（ActionClientContext，必填）
         idempotencyKey:
           type: string
@@ -1230,6 +1629,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 +2169,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 +2193,12 @@ components:
           type: integer
           minimum: 0
           description: 总页数
+        hasNext:
+          type: boolean
+          description: 是否有下一页
+        hasPrev:
+          type: boolean
+          description: 是否有上一页
     LotteryRecordInfo:
       type: object
       required:
@@ -1823,6 +2244,40 @@ components:
           type: string
           format: date-time
           description: 领取时间
+    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）
     TrackRequest:
       type: object
       required:
@@ -1991,99 +2446,6 @@ components:
               message:
                 type: string
           description: 依赖服务状态
-    ComponentManifest:
-      type: object
-      required:
-        - componentType
-        - version
-        - entryUrl
-      properties:
-        componentType:
-          type: string
-          description: 组件类型
-        version:
-          type: string
-          description: 组件版本
-        entryUrl:
-          type: string
-          format: uri
-          description: 组件入口 URL
-        styleUrl:
-          type: string
-          format: uri
-          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:
-          type: boolean
-          description: 是否内置动作
-    QueryManifest:
-      type: object
-      required:
-        - queryId
-        - queryVersionId
-      properties:
-        queryId:
-          type: string
-          description: 查询 ID
-        queryVersionId:
-          type: string
-          description: 查询定义版本 ID
-        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'
@@ -2114,24 +2476,6 @@ components:
                 integrity:
                   type: string
                   description: 完整性哈希
-    ResourceManifests:
-      type: object
-      properties:
-        components:
-          type: array
-          items:
-            $ref: '#/components/schemas/ComponentManifest'
-          description: 组件资源清单
-        actions:
-          type: array
-          items:
-            $ref: '#/components/schemas/ActionManifest'
-          description: 动作资源清单
-        queries:
-          type: array
-          items:
-            $ref: '#/components/schemas/QueryManifest'
-          description: 查询资源清单
   responses:
     BadRequest:
       description: 请求参数错误
@@ -2144,9 +2488,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