@djvlc/openapi-user-client 1.7.1 → 1.7.2

package/openapi/src/openapi.yaml

@@ -1,14 +1,23 @@
 openapi: 3.0.3
 info:
   title: DJVLC User API
-  version: 1.0.0
+  version: 2.0.0
   description: |
-    DJVLC 低代码平台用户端 API
+    DJVLC 低代码平台用户端 API（数据面）
     
     提供以下功能：
-    - 页面获取（解析页面 Schema）
-    - 动作执行（调用业务逻辑）
-    - 数据查询（获取数据源）
+    - 页面解析（Page Resolve）
+    - 动作执行（Action Gateway - 统一入口）
+    - 数据查询（Data Proxy - 统一入口）
+    - 活动状态查询
+    - 埋点上报（Track）
+    - 租户解析（Tenant Resolver）
+    - 健康检查（Health）
+    
+    核心原则：
+    - 所有业务动作只走 Action Gateway（鉴权/风控/幂等/审计/签名）
+    - 所有数据访问只走 Data Proxy（白名单/裁剪/脱敏/缓存）
+    - 全链路可追溯：pageVersionId + componentVersionId + actionId + traceId
   contact:
     name: DJVLC Team
     email: dev@djvlc.com
@@ -22,32 +31,42 @@ servers:
 
 tags:
   - name: Pages
-    description: 页面获取
+    description: 页面解析（Page Resolve）
   - name: Actions
-    description: 动作执行
+    description: 动作执行（Action Gateway）
   - name: Queries
-    description: 数据查询
+    description: 数据查询（Data Proxy）
   - name: Activities
-    description: 活动状态
+    description: 活动状态查询
   - name: Track
     description: 埋点上报
+  - name: Tenant
+    description: 租户解析
+  - name: Health
+    description: 健康检查
 
 paths:
-  # 页面获取
+  # 页面解析
   /pages/{pageId}:
     $ref: './paths/pages.yaml#/page'
   /pages/{pageId}/resolve:
     $ref: './paths/pages.yaml#/resolve'
   
-  # 动作执行
-  /actions/{actionId}/execute:
+  # Action Gateway（统一入口）
+  /actions/execute:
     $ref: './paths/actions.yaml#/execute'
-  /actions/{actionId}/validate:
+  /actions/validate:
     $ref: './paths/actions.yaml#/validate'
+  /actions/definitions:
+    $ref: './paths/actions.yaml#/definitions'
   
-  # 数据查询
-  /queries/{queryId}/execute:
-    $ref: './paths/queries.yaml#/execute'
+  # Data Proxy（统一入口）
+  /data/query:
+    $ref: './paths/queries.yaml#/query'
+  /data/query/batch:
+    $ref: './paths/queries.yaml#/batch'
+  /data/definitions:
+    $ref: './paths/queries.yaml#/definitions'
   
   # 活动状态
   /activities/{activityId}:
@@ -66,6 +85,20 @@ paths:
     $ref: './paths/track.yaml#/track'
   /track/batch:
     $ref: './paths/track.yaml#/trackBatch'
+  
+  # 租户解析
+  /tenant/resolve:
+    $ref: './paths/tenant.yaml#/resolve'
+  /tenant/config:
+    $ref: './paths/tenant.yaml#/config'
+  
+  # 健康检查
+  /health:
+    $ref: './paths/health.yaml#/health'
+  /health/ready:
+    $ref: './paths/health.yaml#/ready'
+  /health/live:
+    $ref: './paths/health.yaml#/live'
 
 components:
   schemas:
@@ -83,6 +116,19 @@ components:
       in: header
       name: X-API-Key
       description: API 密钥
+  parameters:
+    X-Trace-Id:
+      name: X-Trace-Id
+      in: header
+      schema:
+        type: string
+      description: 分布式追踪 ID（OTel）
+    X-App-Id:
+      name: X-App-Id
+      in: header
+      schema:
+        type: string
+      description: 应用/租户 ID
 
 security:
   - BearerAuth: []

package/openapi/src/paths/actions.yaml

@@ -1,23 +1,35 @@
-# 动作执行相关路径
+# 动作执行相关路径 - Action Gateway 统一入口
 
 execute:
   post:
     tags: [Actions]
     operationId: executeAction
-    summary: 执行动作
+    summary: 执行动作（统一入口）
     description: |
-      执行指定的动作，返回执行结果。
+      Action Gateway 唯一入口，所有业务动作都通过此接口执行。
       
-      支持：
-      - 自定义动作（通过 actionDefinitionVersionId）
-      - 内置动作（setState, navigate, etc.）
-    parameters:
-      - name: actionId
-        in: path
-        required: true
-        schema:
-          type: string
-        description: 动作 ID 或动作定义版本 ID
+      执行流程（Pipeline）：
+      1. Auth（登录态/票据/签名）
+      2. Risk（限流、黑名单、设备指纹、验证码开关）
+      3. Idempotency（幂等键检查）
+      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: 自定义动作
     requestBody:
       required: true
       content:
@@ -33,10 +45,20 @@ execute:
               $ref: '../components/schemas/_index.yaml#/ExecuteActionResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
-      '404':
-        $ref: '../components/responses/_index.yaml#/NotFound'
+      '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'
 
@@ -45,14 +67,9 @@ validate:
     tags: [Actions]
     operationId: validateActionParams
     summary: 验证动作参数
-    description: 验证动作参数是否符合 Schema 定义（不执行动作）
-    parameters:
-      - name: actionId
-        in: path
-        required: true
-        schema:
-          type: string
-        description: 动作 ID 或动作定义版本 ID
+    description: |
+      验证动作参数是否符合 Schema 定义（不执行动作）。
+      用于前端表单提交前的预校验。
     requestBody:
       required: true
       content:
@@ -66,5 +83,28 @@ validate:
           application/json:
             schema:
               $ref: '../components/schemas/_index.yaml#/ValidateActionResponse'
+      '400':
+        $ref: '../components/responses/_index.yaml#/BadRequest'
+
+definitions:
+  get:
+    tags: [Actions]
+    operationId: getActionDefinition
+    summary: 获取动作定义
+    description: 获取指定动作定义版本的详细信息（用于 Runtime 渲染动作配置）
+    parameters:
+      - name: actionDefinitionVersionId
+        in: query
+        required: true
+        schema:
+          type: string
+        description: 动作定义版本 ID
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/_index.yaml#/ActionDefinitionResponse'
       '404':
         $ref: '../components/responses/_index.yaml#/NotFound'

package/openapi/src/paths/health.yaml

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

package/openapi/src/paths/queries.yaml

@@ -1,39 +1,45 @@
-# 数据查询相关路径
+# Data Proxy 数据查询相关路径
 
-execute:
+query:
   post:
     tags: [Queries]
-    operationId: executeQuery
-    summary: 执行数据查询
+    operationId: queryData
+    summary: 执行数据查询（Data Proxy 统一入口）
     description: |
-      执行指定的数据查询，返回查询结果。
+      Data Proxy 统一入口，所有数据查询都通过此接口执行。
       
-      支持：
-      - 参数化查询
-      - 结果缓存
-      - 分页
-    parameters:
-      - name: queryId
-        in: path
-        required: true
-        schema:
-          type: string
-        description: 查询 ID 或查询定义版本 ID
+      功能：
+      - 白名单校验（queryVersionId 属于该 app/workspace）
+      - 字段裁剪、脱敏
+      - 缓存（短 TTL）
+      - 失败降级（兜底结构）
+      - 审计（可选，或采样）
+      
+      支持的数据源类型：
+      - http: HTTP 接口
+      - graphql: GraphQL 查询
+      - database: 数据库查询（受限）
+      - internal: 内部服务
+      - aggregation: 聚合查询
     requestBody:
       required: true
       content:
         application/json:
           schema:
-            $ref: '../components/schemas/_index.yaml#/ExecuteQueryRequest'
+            $ref: '../components/schemas/_index.yaml#/QueryDataRequest'
     responses:
       '200':
         description: 查询成功
         content:
           application/json:
             schema:
-              $ref: '../components/schemas/_index.yaml#/ExecuteQueryResponse'
+              $ref: '../components/schemas/_index.yaml#/QueryDataResponse'
       '400':
         $ref: '../components/responses/_index.yaml#/BadRequest'
+      '401':
+        $ref: '../components/responses/_index.yaml#/Unauthorized'
+      '403':
+        $ref: '../components/responses/_index.yaml#/Forbidden'
       '404':
         $ref: '../components/responses/_index.yaml#/NotFound'
       '422':
@@ -42,3 +48,50 @@ execute:
         $ref: '../components/responses/_index.yaml#/InternalError'
       '504':
         $ref: '../components/responses/_index.yaml#/GatewayTimeout'
+
+definitions:
+  get:
+    tags: [Queries]
+    operationId: getQueryDefinition
+    summary: 获取查询定义
+    description: 获取指定数据查询定义版本的详细信息
+    parameters:
+      - name: queryVersionId
+        in: query
+        required: true
+        schema:
+          type: string
+        description: 查询定义版本 ID
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/_index.yaml#/QueryDefinitionResponse'
+      '404':
+        $ref: '../components/responses/_index.yaml#/NotFound'
+
+batch:
+  post:
+    tags: [Queries]
+    operationId: batchQueryData
+    summary: 批量执行数据查询
+    description: |
+      批量执行多个数据查询，用于页面初始化时预取多个数据源。
+      所有查询并行执行，部分失败不影响其他查询返回。
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/_index.yaml#/BatchQueryRequest'
+    responses:
+      '200':
+        description: 批量查询结果
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/_index.yaml#/BatchQueryResponse'
+      '400':
+        $ref: '../components/responses/_index.yaml#/BadRequest'

package/openapi/src/paths/tenant.yaml

@@ -0,0 +1,93 @@
+# Tenant 租户解析 API
+
+resolve:
+  post:
+    tags:
+      - Tenant
+    summary: 解析租户信息
+    operationId: resolveTenant
+    description: |
+      根据 appKey 或 host 解析租户/应用信息。
+      
+      用于：
+      - Runtime 初始化时获取应用配置
+      - 多租户场景下的应用隔离
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              appKey:
+                type: string
+                description: 应用密钥
+              host:
+                type: string
+                description: 请求来源域名
+              channel:
+                type: string
+                description: 渠道标识
+            anyOf:
+              - required: [appKey]
+              - required: [host]
+    responses:
+      '200':
+        description: 解析成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  $ref: '../components/schemas/_index.yaml#/TenantInfo'
+      '400':
+        $ref: '../components/responses/_index.yaml#/BadRequest'
+      '404':
+        description: 租户不存在
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/_index.yaml#/ErrorResponse'
+    security: []
+
+config:
+  get:
+    tags:
+      - Tenant
+    summary: 获取租户配置
+    operationId: getTenantConfig
+    description: |
+      获取当前租户的运行时配置。
+      
+      包括：
+      - 功能开关
+      - 主题配置
+      - CDN 域名
+      - 阻断组件列表
+      - Kill Switch 状态
+    parameters:
+      - name: X-App-Id
+        in: header
+        required: true
+        schema:
+          type: string
+        description: 应用 ID
+    responses:
+      '200':
+        description: 成功
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                success:
+                  type: boolean
+                data:
+                  $ref: '../components/schemas/_index.yaml#/TenantConfig'
+      '401':
+        $ref: '../components/responses/_index.yaml#/Unauthorized'
+      '404':
+        $ref: '../components/responses/_index.yaml#/NotFound'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djvlc/openapi-user-client",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "DJV Low-code Platform - User API 客户端（自动生成）",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",