@djvlc/openapi-user-client 1.8.0 → 1.8.1

package/openapi/src/openapi.yaml

@@ -1,18 +1,18 @@
 openapi: 3.0.3
 info:
-  title: DJVLC User API
+  title: 平台用户端 API
   version: 1.0.0
   description: |
-    DJVLC 低代码平台用户端 API（数据面）
+    平台用户端 API 文档 (User API)
     
     提供以下功能：
-    - 页面解析（Page Resolve）
-    - 动作执行（Action Gateway - 统一入口）
-    - 数据查询（Data Proxy - 统一入口）
-    - 活动状态查询
-    - 埋点上报（Track）
-    - 租户解析（Tenant Resolver）
-    - 健康检查（Health）
+    - 页面运行时（Pages）- 页面解析与渲染
+    - 动作网关（Actions）- 统一动作执行入口
+    - 数据查询（Queries）- 数据代理查询
+    - 活动运行时（Activities）- 活动状态查询
+    - 埋点追踪（Track）- 用户行为追踪
+    - 租户解析（Tenant）- 多租户解析
+    - 健康检查（Health）- 服务健康状态
     
     核心原则：
     - 所有业务动作只走 Action Gateway（鉴权/风控/幂等/审计/签名）
@@ -31,22 +31,22 @@ servers:
 
 tags:
   - name: Pages
-    description: 页面解析（Page Resolve）
+    description: 页面运行时 - 页面解析与渲染
   - name: Actions
-    description: 动作执行（Action Gateway）
+    description: 动作网关 - 统一动作执行入口
   - name: Queries
-    description: 数据查询（Data Proxy）
+    description: 数据查询 - 数据代理查询
   - name: Activities
-    description: 活动状态查询
+    description: 活动运行时 - 活动状态查询
   - name: Track
-    description: 埋点上报
+    description: 埋点追踪 - 用户行为追踪
   - name: Tenant
-    description: 租户解析
+    description: 租户解析 - 多租户解析
   - name: Health
-    description: 健康检查
+    description: 健康检查 - 服务健康状态
 
 paths:
-  # 页面解析（根据设计总纲 V2）
+  # 页面解析
   /page/resolve:
     $ref: './paths/pages.yaml#/resolve'
   /page/manifest:
@@ -103,10 +103,10 @@ paths:
   # 健康检查
   /health:
     $ref: './paths/health.yaml#/health'
-  /health/ready:
-    $ref: './paths/health.yaml#/ready'
   /health/live:
     $ref: './paths/health.yaml#/live'
+  /health/ready:
+    $ref: './paths/health.yaml#/ready'
 
 components:
   schemas:
@@ -118,7 +118,7 @@ components:
       type: http
       scheme: bearer
       bearerFormat: JWT
-      description: JWT 认证令牌（可选）
+      description: 请输入 JWT 访问令牌
     ApiKey:
       type: apiKey
       in: header

package/openapi/src/paths/actions.yaml

@@ -4,9 +4,9 @@ execute:
   post:
     tags: [Actions]
     operationId: executeAction
-    summary: 执行动作（统一入口）
+    summary: 执行动作
     description: |
-      Action Gateway 唯一入口，所有业务动作都通过此接口执行。
+      统一的动作执行入口，支持领取、签到等业务动作。
       
       执行流程（Pipeline）：
       1. Auth（登录态/票据/签名）
@@ -15,36 +15,6 @@ execute:
       4. Execute（执行器：Claim/Signin/Lottery...）
       5. Audit（审计落库 + outbox）
       6. Normalize（统一错误码/返回）
-      
-      支持的动作类型：
-      - claim: 领取
-      - signin: 签到
-      - lottery: 抽奖
-      - reserve: 预约
-      - bind: 绑定
-      - task_complete: 任务完成
-      - vote: 投票
-      - share: 分享
-      - form_submit: 表单提交
-      - navigate: 页面跳转（内置）
-      - 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:
@@ -53,7 +23,7 @@ execute:
             $ref: '../components/schemas/_index.yaml#/ExecuteActionRequest'
     responses:
       '200':
-        description: 执行成功
+        description: 执行结果
         content:
           application/json:
             schema:
@@ -62,29 +32,19 @@ execute:
         $ref: '../components/responses/_index.yaml#/BadRequest'
       '401':
         $ref: '../components/responses/_index.yaml#/Unauthorized'
-      '403':
-        $ref: '../components/responses/_index.yaml#/Forbidden'
-      '409':
-        description: 幂等冲突（重复请求）
-        content:
-          application/json:
-            schema:
-              $ref: '../components/schemas/_index.yaml#/IdempotencyConflictResponse'
-      '422':
-        $ref: '../components/responses/_index.yaml#/UnprocessableEntity'
       '429':
         $ref: '../components/responses/_index.yaml#/TooManyRequests'
       '500':
         $ref: '../components/responses/_index.yaml#/InternalError'
+    security:
+      - BearerAuth: []
 
 validate:
   post:
     tags: [Actions]
     operationId: validateActionParams
     summary: 验证动作参数
-    description: |
-      验证动作参数是否符合 Schema 定义（不执行动作）。
-      用于前端表单提交前的预校验。
+    description: 验证参数是否符合 Schema 定义，不执行动作
     requestBody:
       required: true
       content:
@@ -100,26 +60,31 @@ validate:
               $ref: '../components/schemas/_index.yaml#/ValidateActionResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
+    security:
+      - BearerAuth: []
 
 definitions:
   get:
     tags: [Actions]
     operationId: getActionDefinition
     summary: 获取动作定义
-    description: 获取指定动作定义版本的详细信息（用于 Runtime 渲染动作配置）
+    description: 按版本 ID 获取动作定义详情
     parameters:
       - name: actionDefinitionVersionId
         in: query
         required: true
+        description: 动作定义版本 ID
         schema:
           type: string
-        description: 动作定义版本 ID
+          example: 202401efgh87654321
     responses:
       '200':
-        description: 成功
+        description: 动作定义版本信息
         content:
           application/json:
             schema:
-              $ref: '../components/schemas/_index.yaml#/ActionDefinitionResponse'
+              $ref: '../components/schemas/_index.yaml#/ActionDefinitionVersionResponse'
       '404':
         $ref: '../components/responses/_index.yaml#/NotFound'
+    security:
+      - BearerAuth: []

package/openapi/src/paths/activities.yaml

@@ -1,18 +1,11 @@
 # Activities 活动状态 API（User 端）
 
-activityState:
+activityInfo:
   get:
-    tags:
-      - Activities
-    summary: 获取用户活动状态
-    operationId: getActivityState
-    description: |
-      查询用户在指定活动中的参与状态。
-      
-      返回内容包括：
-      - 是否可参与
-      - 剩余次数
-      - 类型特定状态（领取/签到/抽奖等）
+    tags: [Activities]
+    operationId: getActivityInfo
+    summary: 获取活动信息（公开）
+    description: 获取活动的公开信息，不需要登录
     parameters:
       - name: activityId
         in: path
@@ -25,100 +18,117 @@ activityState:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/UserActivityState'
+              $ref: '../components/schemas/_index.yaml#/ActivityInfoResponse'
       '404':
         $ref: '../components/responses/_index.yaml#/NotFound'
-    security:
-      - BearerAuth: []
+    security: []
 
-activityInfo:
+activityState:
   get:
-    tags:
-      - Activities
-    summary: 获取活动信息（公开）
-    operationId: getActivityInfo
-    description: |
-      获取活动的公开信息，不需要登录。
-      
-      返回内容包括：
-      - 活动基本信息
-      - 时间范围
-      - 奖品列表（脱敏）
+    tags: [Activities]
+    operationId: getActivityState
+    summary: 获取用户活动状态
+    description: 查询用户在指定活动中的参与状态
     parameters:
       - name: activityId
         in: path
         required: true
         schema:
           type: string
+      - name: uid
+        in: query
+        required: false
+        description: 用户 UID
+        schema:
+          type: string
     responses:
       '200':
         description: 成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/PublicActivityInfo'
+              $ref: '../components/schemas/_index.yaml#/ActivityStatusResponse'
       '404':
         $ref: '../components/responses/_index.yaml#/NotFound'
-    security: []
 
 signinCalendar:
   get:
-    tags:
-      - Activities
-    summary: 获取签到日历
+    tags: [Activities]
     operationId: getSigninCalendar
-    description: |
-      获取用户的签到日历数据。
-      
-      返回内容包括：
-      - 当前周期的签到记录
-      - 连续签到天数
-      - 累计签到天数
-      - 奖励进度
+    summary: 获取签到日历
+    description: 获取用户的签到日历数据
     parameters:
       - name: activityId
         in: path
         required: true
         schema:
           type: string
+      - name: uid
+        in: query
+        required: true
+        description: 用户 UID
+        schema:
+          type: string
       - name: month
         in: query
-        description: 月份（YYYY-MM），默认当前月
+        required: false
+        description: 月份（YYYY-MM）
         schema:
           type: string
-          pattern: '^\d{4}-\d{2}$'
+          example: '2024-01'
     responses:
       '200':
         description: 成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/SigninCalendar'
-    security:
-      - BearerAuth: []
+              $ref: '../components/schemas/_index.yaml#/SigninCalendarResponse'
 
 claimRecords:
   get:
-    tags:
-      - Activities
-    summary: 获取领取记录
+    tags: [Activities]
     operationId: getClaimRecords
+    summary: 获取领取记录
     description: 获取用户在指定活动中的领取记录
+    parameters:
+      - name: activityId
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: pageToken
+        in: query
+        required: false
+        description: 分页游标
+        schema:
+          type: string
+      - name: pageSize
+        in: query
+        required: false
+        description: 每页条数
+        schema:
+          type: number
+          example: 20
+      - name: uid
+        in: query
+        required: false
+        description: 用户 UID，不传则返回空
+        schema:
+          type: string
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/_index.yaml#/PaginatedRecordsResponse'
+
+lotteryRecords:
+  get:
+    tags: [Activities]
+    operationId: getLotteryRecords
+    summary: 获取抽奖记录
+    description: 获取用户在指定活动中的抽奖记录
     parameters:
       - name: activityId
         in: path
@@ -127,11 +137,16 @@ claimRecords:
           type: string
       - name: pageSize
         in: query
+        required: false
+        description: 每页条数
         schema:
-          type: integer
+          type: number
           default: 20
+          example: 20
       - name: pageToken
         in: query
+        required: false
+        description: 分页游标
         schema:
           type: string
     responses:
@@ -140,28 +155,14 @@ claimRecords:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  type: array
-                  items:
-                    $ref: '../components/schemas/_index.yaml#/ClaimRecordInfo'
-                meta:
-                  $ref: '../components/schemas/_index.yaml#/PaginationMeta'
-    security:
-      - BearerAuth: []
+              $ref: '../components/schemas/_index.yaml#/PaginatedRecordsResponse'
 
 activityStatus:
   get:
-    tags:
-      - Activities
-    summary: 获取活动状态（兼容）
+    tags: [Activities]
     operationId: getActivityStatus
-    description: |
-      获取活动的当前状态信息，包括是否进行中、时间范围等。
-      不需要登录，可用于前端判断活动是否在有效期内。
+    summary: 获取活动状态（兼容）
+    description: 获取活动的当前状态信息
     parameters:
       - name: activityId
         in: path
@@ -174,22 +175,16 @@ activityStatus:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  $ref: '../components/schemas/_index.yaml#/ActivityStatus'
+              $ref: '../components/schemas/_index.yaml#/ActivityStatusResponse'
       '404':
         $ref: '../components/responses/_index.yaml#/NotFound'
     security: []
 
 claimStatus:
   get:
-    tags:
-      - Activities
-    summary: 获取领取状态
+    tags: [Activities]
     operationId: getClaimStatus
+    summary: 获取领取状态
     description: 获取用户在指定活动中的领取状态
     parameters:
       - name: activityId
@@ -200,31 +195,22 @@ claimStatus:
       - name: uid
         in: query
         required: true
+        description: 用户 UID
         schema:
           type: string
-        description: 用户 UID
     responses:
       '200':
         description: 成功
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  type: object
-                  description: 领取状态数据
-    security:
-      - BearerAuth: []
+              $ref: '../components/schemas/_index.yaml#/ClaimStatusResponse'
 
 signinStatus:
   get:
-    tags:
-      - Activities
-    summary: 获取签到状态
+    tags: [Activities]
     operationId: getSigninStatus
+    summary: 获取签到状态
     description: 获取用户在指定活动中的签到状态
     parameters:
       - name: activityId
@@ -235,45 +221,7 @@ signinStatus:
       - 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:
-      - Activities
-    summary: 获取抽奖记录
-    operationId: getLotteryRecords
-    description: 获取用户在指定活动中的抽奖记录
-    parameters:
-      - name: activityId
-        in: path
-        required: true
-        schema:
-          type: string
-      - name: pageSize
-        in: query
-        schema:
-          type: integer
-          default: 20
-      - name: pageToken
-        in: query
         schema:
           type: string
     responses:
@@ -282,15 +230,4 @@ lotteryRecords:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                success:
-                  type: boolean
-                data:
-                  type: array
-                  items:
-                    $ref: '../components/schemas/_index.yaml#/LotteryRecordInfo'
-                meta:
-                  $ref: '../components/schemas/_index.yaml#/PaginationMeta'
-    security:
-      - BearerAuth: []
+              $ref: '../components/schemas/_index.yaml#/SigninStatusResponse'

package/openapi/src/paths/health.yaml

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