@djvlc/openapi-admin-client 1.6.10 → 1.6.12

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

@@ -1,5 +1,28 @@
 # Schema 组件索引
 
+# ============================================================================
+# 复杂类型引用（引用 JSON Schema 文件，types 与 packages/schemas 为单一数据源）
+# ============================================================================
+
+# PageSchema：页面 Schema 定义（单一数据源为 JSON Schema，此处为占位以兼容 OpenAPI Generator）
+# 类型：types/src/page/schema.ts - PageSchema
+# 完整结构：packages/schemas/schemas/page-schema.json（Schema ID: https://djvlc.com/schemas/page-schema.v1.json）
+# 校验与编辑器请使用 @djvlc/contracts-schemas 或 page-schema.json
+PageSchema:
+  type: object
+  description: |
+    页面 Schema（PageSchema）。完整定义与校验见 packages/schemas/schemas/page-schema.json 与 types/src/page/schema.ts。
+  additionalProperties: true
+
+# ComponentMeta：组件元数据定义（单一数据源为 JSON Schema，此处为占位以兼容 OpenAPI Generator）
+# 类型：types/src/component/meta.ts - ComponentMeta
+# 完整结构：packages/schemas/schemas/component-meta.json（Schema ID: https://djvlc.com/schemas/component-meta.v1.json）
+ComponentMeta:
+  type: object
+  description: |
+    组件元数据（ComponentMeta）。完整定义与校验见 packages/schemas/schemas/component-meta.json 与 types/src/component/meta.ts。
+  additionalProperties: true
+
 # ============================================================================
 # 通用
 # ============================================================================
@@ -26,34 +49,120 @@ PaginationMeta:
       minimum: 0
       description: 总页数
 
+# ============================================================================
+# 统一响应结构（与 platform 仓库保持一致）
+# ============================================================================
+
+SuccessResponse:
+  type: object
+  required: [success, code, message, data, timestamp, path]
+  description: 成功响应（ApiSuccessResponse，与 types/src/common/api.ts 保持一致）
+  properties:
+    success:
+      type: boolean
+      enum: [true]
+      example: true
+      description: 是否成功（固定为 true）
+    code:
+      type: string
+      example: OK
+      description: 业务状态码
+    message:
+      type: string
+      example: 操作成功
+      description: 响应消息
+    data:
+      description: 响应数据（泛型 T）
+    timestamp:
+      type: integer
+      format: int64
+      example: 1702300000000
+      description: 响应时间戳（Unix 毫秒时间戳，number）
+    path:
+      type: string
+      example: /api/admin/pages
+      description: 请求路径
+    requestId:
+      type: string
+      example: uuid-string
+      description: 请求 ID（可选）
+
 ErrorResponse:
   type: object
-  required: [code, message]
+  required: [success, code, message, timestamp, path]
+  description: 错误响应（ApiErrorResponse，与 types/src/common/api.ts 保持一致）
   properties:
+    success:
+      type: boolean
+      enum: [false]
+      example: false
+      description: 是否成功（固定为 false）
     code:
       type: string
-      description: 错误码
+      example: VALIDATION_INVALID_PARAMS
+      description: 错误码（ErrorCode | string）
     message:
       type: string
-      description: 错误消息
-    details:
-      type: array
-      items:
-        $ref: '#/ErrorDetail'
-      description: 错误详情
+      example: 请求参数无效
+      description: 错误消息（用户可读）
+    # 不使 oneOf(array|object)，避免生成器产出 Array<...> 等非法 TS；不指定 type 表示允许 array 或 object
+    data:
+      description: 错误详情（验证错误时使用 ApiErrorDetail[]，其他情况使用 unknown，放在 data 字段中）
+      nullable: true
+    timestamp:
+      type: integer
+      format: int64
+      example: 1702300000000
+      description: 响应时间戳（Unix 毫秒时间戳，number）
+    path:
+      type: string
+      example: /api/admin/pages
+      description: 请求路径
+    requestId:
+      type: string
+      example: uuid-string
+      description: 请求 ID（可选）
+    traceId:
+      type: string
+      example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+      description: 链路追踪 ID（可选，用于分布式追踪）
 
 ErrorDetail:
   type: object
+  required: [message]
+  description: 错误详情（ApiErrorDetail，与 types/src/common/api.ts 保持一致）
   properties:
     field:
       type: string
-      description: 字段名
+      description: 字段路径（可选）
     message:
       type: string
-      description: 字段错误信息
+      description: 错误消息（必填）
     code:
       type: string
-      description: 字段错误码
+      description: 错误码（可选）
+
+# 具名 schema，供 ErrorResponse.data oneOf 使用，避免生成器产出 Array<...> 非法类型名
+ErrorDetailList:
+  type: array
+  description: 验证错误时的 data（ApiErrorDetail[]）
+  items:
+    $ref: '#/ErrorDetail'
+
+ErrorResponseData:
+  type: object
+  additionalProperties: true
+  description: 错误响应数据（用于非验证错误场景，对应 unknown 类型）
+
+# 具名 schema，供 oneOf 使用，避免生成器产出无效 TypeScript（自由对象分支须有命名类型）
+ErrorResponseDataObject:
+  type: object
+  description: 错误响应 data 的非数组分支（任意结构）
+  properties:
+    _:
+      type: string
+      description: 占位属性，确保生成器产出命名类型
+  additionalProperties: true
 
 # ============================================================================
 # 页面相关
@@ -100,22 +209,28 @@ PageInfo:
       description: 更新者 ID
 
 PageListResponse:
-  type: object
-  required: [data, meta]
-  properties:
-    data:
-      type: array
-      items:
-        $ref: '#/PageInfo'
-    meta:
-      $ref: '#/PaginationMeta'
+  allOf:
+    - $ref: '#/SuccessResponse'
+    - type: object
+      properties:
+        data:
+          type: object
+          required: [items, meta]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: '#/PageInfo'
+            meta:
+              $ref: '#/PaginationMeta'
 
 PageResponse:
-  type: object
-  required: [data]
-  properties:
-    data:
-      $ref: '#/PageInfo'
+  allOf:
+    - $ref: '#/SuccessResponse'
+    - type: object
+      properties:
+        data:
+          $ref: '#/PageInfo'
 
 CreatePageRequest:
   type: object
@@ -170,26 +285,32 @@ DraftResponse:
 
 DraftData:
   type: object
-  required: [pageId, content, updatedAt]
+  required: [id, pageId, schema, isDirty, savedAt, savedBy, updatedAt]
+  description: 页面草稿（PageDraft，根据 types/src/page/draft.ts）
   properties:
+    id:
+      type: string
+      description: 草稿 ID（UniqueId）
     pageId:
       type: string
-      description: 页面 ID
-    content:
-      type: object
-      description: 页面 Schema 内容
-    baseVersion:
+      description: 页面 ID（UniqueId）
+    schema:
+      $ref: '#/PageSchema'
+      description: 草稿内容（PageSchema，见 packages/schemas/schemas/page-schema.json）
+    isDirty:
+      type: boolean
+      description: 是否有未保存的更改
+    savedAt:
+      type: string
+      format: date-time
+      description: 最后保存时间（ISODateTime）
+    savedBy:
       type: string
-      description: 基于的版本号
+      description: 最后保存者
     updatedAt:
       type: string
       format: date-time
-      description: 最后更新时间
-    updatedBy:
-      type: string
-      description: 最后更新者 ID
-    lockInfo:
-      $ref: '#/LockInfo'
+      description: 更新时间（ISODateTime）
 
 LockInfo:
   type: object
@@ -208,14 +329,15 @@ LockInfo:
 
 SaveDraftRequest:
   type: object
-  required: [content]
+  required: [schema]
+  description: 保存草稿请求（根据 types/src/page/draft.ts）
   properties:
-    content:
-      type: object
-      description: 页面 Schema 内容
+    schema:
+      $ref: '#/PageSchema'
+      description: 页面 Schema 内容（PageSchema，见 packages/schemas/schemas/page-schema.json）
     baseVersion:
       type: string
-      description: 基于的版本号（用于冲突检测）
+      description: 基于的版本号（用于冲突检测，UniqueId）
     force:
       type: boolean
       default: false
@@ -285,18 +407,230 @@ VersionResponse:
 
 PublishRequest:
   type: object
+  description: 发布页面请求（PublishConfig，根据设计总纲 V2 和 platform 实现）
   properties:
-    changelog:
+    channel:
       type: string
-      maxLength: 2048
-      description: 变更日志
-    versionBump:
+      enum: [preview, prod, gray]
+      default: prod
+      description: 发布渠道PublishChannel（preview/prod/gray）
+    description:
       type: string
-      enum: [major, minor, patch]
-      default: patch
-      description: 版本号升级类型
-    rollout:
-      $ref: '#/RolloutConfig'
+      maxLength: 500
+      description: 发布描述/备注
+    publishConfig:
+      type: object
+      description: 发布配置（PublishConfig）
+      properties:
+        rollout:
+          type: object
+          description: 灰度配置（PublishRolloutConfig，单次发布时的临时配置）
+          properties:
+            strategy:
+              type: object
+              description: 灰度策略配置（RolloutStrategyConfig，支持 percentage/whitelist/blacklist/feature/time_window/ab_test/canary）
+              oneOf:
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [percentage]
+                    percentage:
+                      type: integer
+                      minimum: 0
+                      maximum: 100
+                    bucketKey:
+                      type: string
+                      enum: [uid, device_id, session_id]
+                    bucketSeed:
+                      type: string
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [whitelist]
+                    userIds:
+                      type: array
+                      items:
+                        type: string
+                    deviceIds:
+                      type: array
+                      items:
+                        type: string
+                    ips:
+                      type: array
+                      items:
+                        type: string
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [blacklist]
+                    userIds:
+                      type: array
+                      items:
+                        type: string
+                    deviceIds:
+                      type: array
+                      items:
+                        type: string
+                    ips:
+                      type: array
+                      items:
+                        type: string
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [feature]
+                    conditions:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          field:
+                            type: string
+                          operator:
+                            type: string
+                            enum: [eq, ne, in, not_in, regex, contains, starts_with, ends_with]
+                          value:
+                            $ref: '#/ConditionValue'
+                    logic:
+                      type: string
+                      enum: [and, or]
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [time_window]
+                    startAt:
+                      type: string
+                      format: date-time
+                    endAt:
+                      type: string
+                      format: date-time
+                    timezone:
+                      type: string
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [ab_test]
+                    experimentId:
+                      type: string
+                    variantId:
+                      type: string
+                    variants:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                          name:
+                            type: string
+                          weight:
+                            type: number
+                          pageVersionId:
+                            type: string
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      enum: [canary]
+                    stages:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          name:
+                            type: string
+                          percentage:
+                            type: integer
+                          durationSeconds:
+                            type: integer
+                          requireApproval:
+                            type: boolean
+                    currentStageIndex:
+                      type: integer
+                    autoAdvance:
+                      type: object
+                      properties:
+                        enabled:
+                          type: boolean
+                        stageDurationSeconds:
+                          type: integer
+                        healthCheck:
+                          type: object
+                          properties:
+                            errorRateThreshold:
+                              type: number
+                            latencyThresholdMs:
+                              type: integer
+                            windowSeconds:
+                              type: integer
+            persist:
+              type: boolean
+              description: 是否保存为持久化配置
+            persistName:
+              type: string
+              description: 持久化时的策略名称
+            persistPriority:
+              type: integer
+              description: 持久化时的优先级
+        cdn:
+          type: object
+          description: CDN 配置（PublishCdnConfig）
+          properties:
+            refreshCache:
+              type: boolean
+              description: 是否刷新缓存
+            warmupUrls:
+              type: array
+              items:
+                type: string
+                format: uri
+              description: 预热 URL 列表
+            priority:
+              type: string
+              enum: [high, normal, low]
+              description: 刷新优先级
+        notification:
+          type: object
+          description: 发布通知配置（PublishNotificationConfig）
+          properties:
+            enabled:
+              type: boolean
+              description: 是否发送通知
+            channels:
+              type: array
+              items:
+                type: string
+                enum: [email, webhook, slack, dingtalk]
+              description: 通知渠道
+            recipients:
+              type: array
+              items:
+                type: string
+              description: 通知接收者
+            webhookUrl:
+              type: string
+              format: uri
+              description: Webhook URL
+        skipValidation:
+          type: boolean
+          description: 是否跳过校验（仅开发环境有效）
+        immediate:
+          type: boolean
+          description: 是否立即生效（false 时进入待发布状态）
+        scheduledAt:
+          type: string
+          format: date-time
+          description: 定时发布时间（immediate 为 false 时有效）
+    versionUid:
+      type: string
+      maxLength: 32
+      description: 指定发布的版本 UID（不传则使用当前页面最新内容，UniqueId）
 
 RolloutConfig:
   type: object
@@ -511,6 +845,10 @@ SetKillSwitchRequest:
 # ============================================================================
 # Rollout 灰度发布相关
 # ============================================================================
+# 灰度策略 feature 条件中的 value：实际为 string | number | boolean | string[]，不使 oneOf 避免生成器产出非法 TS
+ConditionValue:
+  description: 条件值（string | number | boolean | string[]，运行时为 JSON 值）
+  nullable: true
 
 RolloutStrategy:
   type: object
@@ -989,91 +1327,97 @@ HealthResponse:
 
 ActivityInfo:
   type: object
-  required: [id, name, type, status, createdAt]
+  required: [id, appId, name, type, status, createdAt]
+  description: 活动信息（Activity，根据 types/src/activity/index.ts）
   properties:
     id:
       type: string
-      description: 活动 ID
+      description: 活动 ID（UniqueId）
+    appId:
+      type: string
+      description: 应用 ID（UniqueId）
     name:
       type: string
       description: 活动名称
+    description:
+      type: string
+      description: 活动描述
     type:
       type: string
-      enum: [signin, lottery, redpack, coupon, custom]
-      description: 活动类型
+      enum: [claim, signin, lottery, reserve, task, vote, share, bind, custom]
+      description: 活动类型（ActivityType）
     status:
       type: string
-      enum: [draft, scheduled, active, paused, ended]
-      description: 活动状态
-    startTime:
-      type: string
-      format: date-time
-      description: 开始时间
-    endTime:
-      type: string
-      format: date-time
-      description: 结束时间
+      enum: [draft, scheduled, active, paused, ended, archived]
+      description: 活动状态（ActivityStatus）
     createdAt:
       type: string
       format: date-time
-      description: 创建时间
+      description: 创建时间（ISODateTime）
     updatedAt:
       type: string
       format: date-time
-      description: 更新时间
+      description: 更新时间（ISODateTime）
+    createdBy:
+      type: string
+      description: 创建者
+    updatedBy:
+      type: string
+      description: 更新者
 
 ActivityDetail:
   type: object
-  required: [id, name, type, status, config, createdAt]
+  required: [id, appId, name, type, rule, status, createdAt]
+  description: 活动详情（Activity，根据 types/src/activity/index.ts）
   properties:
     id:
       type: string
-      description: 活动 ID
+      description: 活动 ID（UniqueId）
+    appId:
+      type: string
+      description: 应用 ID（UniqueId）
     name:
       type: string
       description: 活动名称
-    type:
-      type: string
-      enum: [signin, lottery, redpack, coupon, custom]
-      description: 活动类型
-    status:
-      type: string
-      enum: [draft, scheduled, active, paused, ended]
-      description: 活动状态
     description:
       type: string
       description: 活动描述
-    config:
-      type: object
-      additionalProperties: true
-      description: 活动配置
-    rules:
+    type:
+      type: string
+      enum: [claim, signin, lottery, reserve, task, vote, share, bind, custom]
+      description: 活动类型（ActivityType）
+    rule:
       type: object
+      description: 活动规则（ActivityRule，联合类型：ClaimActivityRule | SigninActivityRule | LotteryActivityRule）
+      # 这里应该使用 oneOf 来定义不同的规则类型，但为了简化，使用 object
       additionalProperties: true
-      description: 活动规则
-    startTime:
-      type: string
-      format: date-time
-      description: 开始时间
-    endTime:
+    status:
       type: string
-      format: date-time
-      description: 结束时间
+      enum: [draft, scheduled, active, paused, ended, archived]
+      description: 活动状态（ActivityStatus）
     createdAt:
       type: string
       format: date-time
-      description: 创建时间
+      description: 创建时间（ISODateTime）
     updatedAt:
       type: string
       format: date-time
-      description: 更新时间
+      description: 更新时间（ISODateTime）
     createdBy:
       type: string
-      description: 创建者 ID
+      description: 创建者
+    updatedBy:
+      type: string
+      description: 更新者
+    extensions:
+      type: object
+      additionalProperties: true
+      description: 扩展数据（Record<string, unknown>）
 
 CreateActivityRequest:
   type: object
-  required: [name, type]
+  required: [name, type, rule]
+  description: 创建活动请求（根据 types/src/activity/index.ts）
   properties:
     name:
       type: string
@@ -1082,28 +1426,62 @@ CreateActivityRequest:
       description: 活动名称
     type:
       type: string
-      enum: [signin, lottery, redpack, coupon, custom]
-      description: 活动类型
+      enum: [claim, signin, lottery, reserve, task, vote, share, bind, custom]
+      description: 活动类型（ActivityType）
     description:
       type: string
       maxLength: 1024
       description: 活动描述
-    config:
+    rule:
       type: object
+      description: 活动规则（ActivityRule，根据 type 不同而不同）
+      # 这里应该使用 oneOf 来定义不同的规则类型
+      # 为了简化，使用 object，但实际应该根据 type 字段动态校验
       additionalProperties: true
-      description: 活动配置
-    rules:
-      type: object
-      additionalProperties: true
-      description: 活动规则
-    startTime:
-      type: string
-      format: date-time
-      description: 开始时间
-    endTime:
-      type: string
-      format: date-time
-      description: 结束时间
+      # 基础规则字段（BaseActivityRule）
+      properties:
+        startAt:
+          type: string
+          format: date-time
+          description: 开始时间（ISODateTime）
+        endAt:
+          type: string
+          format: date-time
+          description: 结束时间（ISODateTime）
+        timezone:
+          type: string
+          description: 时区
+        requireAuth:
+          type: boolean
+          description: 是否要求登录
+        participationLimit:
+          type: object
+          description: 参与次数限制（ParticipationLimit）
+          properties:
+            perUser:
+              type: integer
+            perUserPerDay:
+              type: integer
+            perUserPerWeek:
+              type: integer
+            global:
+              type: integer
+            globalPerDay:
+              type: integer
+        preconditions:
+          type: array
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum: [user_level, membership, whitelist, prerequisite_activity, custom]
+              config:
+                type: object
+                additionalProperties: true
+              errorMessage:
+                type: string
+          description: 前置条件（ActivityPrecondition[]）
 
 UpdateActivityRequest:
   type: object