@djvlc/openapi-user-client 1.8.0 → 1.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/dist/index.d.mts +2456 -3410
  2. package/dist/index.d.ts +2456 -3410
  3. package/dist/index.js +1822 -2709
  4. package/dist/index.mjs +1645 -2417
  5. package/openapi/dist/user-api.yaml +1198 -1599
  6. package/openapi/src/components/schemas/_index.yaml +829 -1041
  7. package/openapi/src/openapi.yaml +20 -20
  8. package/openapi/src/paths/actions.yaml +32 -52
  9. package/openapi/src/paths/activities.yaml +138 -161
  10. package/openapi/src/paths/health.yaml +34 -61
  11. package/openapi/src/paths/pages.yaml +63 -70
  12. package/openapi/src/paths/queries.yaml +49 -54
  13. package/openapi/src/paths/tenant.yaml +25 -49
  14. package/openapi/src/paths/track.yaml +9 -53
  15. package/package.json +1 -1
package/openapi/dist/user-api.yaml CHANGED
@@ -1,18 +1,18 @@
1
1
  openapi: 3.0.3
2
2
  info:
3
- title: DJVLC User API
3
+ title: 平台用户端 API
4
4
  version: 1.0.0
5
5
  description: |
6
- DJVLC 低代码平台用户端 API（数据面）
6
+ 平台用户端 API 文档 (User API)
7
7
 
8
8
  提供以下功能：
9
- - 页面解析（Page Resolve）
10
- - 动作执行（Action Gateway - 统一入口）
11
- - 数据查询（Data Proxy - 统一入口）
12
- - 活动状态查询
13
- - 埋点上报（Track）
14
- - 租户解析（Tenant Resolver）
15
- - 健康检查（Health）
9
+ - 页面运行时（Pages）- 页面解析与渲染
10
+ - 动作网关（Actions）- 统一动作执行入口
11
+ - 数据查询（Queries）- 数据代理查询
12
+ - 活动运行时（Activities）- 活动状态查询
13
+ - 埋点追踪（Track）- 用户行为追踪
14
+ - 租户解析（Tenant）- 多租户解析
15
+ - 健康检查（Health）- 服务健康状态
16
16
 
17
17
  核心原则：
18
18
  - 所有业务动作只走 Action Gateway（鉴权/风控/幂等/审计/签名）
@@ -32,58 +32,44 @@ security:
32
32
  - ApiKey: []
33
33
  tags:
34
34
  - name: Pages
35
- description: 页面解析（Page Resolve）
35
+ description: 页面运行时 - 页面解析与渲染
36
36
  - name: Actions
37
- description: 动作执行（Action Gateway）
37
+ description: 动作网关 - 统一动作执行入口
38
38
  - name: Queries
39
- description: 数据查询（Data Proxy）
39
+ description: 数据查询 - 数据代理查询
40
40
  - name: Activities
41
- description: 活动状态查询
41
+ description: 活动运行时 - 活动状态查询
42
42
  - name: Track
43
- description: 埋点上报
43
+ description: 埋点追踪 - 用户行为追踪
44
44
  - name: Tenant
45
- description: 租户解析
45
+ description: 租户解析 - 多租户解析
46
46
  - name: Health
47
- description: 健康检查
47
+ description: 健康检查 - 服务健康状态
48
48
  paths:
49
49
  /page/resolve:
50
50
  get:
51
51
  tags:
52
52
  - Pages
53
53
  operationId: resolvePage
54
- summary: 解析页面（Runtime 核心接口）
54
+ summary: 解析页面
55
55
  description: |
56
- Runtime 的核心接口，返回渲染所需的完整数据。
56
+ Runtime 核心接口，返回渲染所需的完整数据。
57
57
 
58
58
  支持两种模式：
59
59
  1. 稳定入口（推荐）：支持灰度/回滚/ops，返回 resolvedVersionId 和 CDN 地址
60
- 2. 保底模式：当 includeSnapshot=1 时，返回完整 snapshot（CDN 失败时使用）
61
-
62
- 响应包含：
63
- - resolvedVersionId: 解析后的页面版本 ID（考虑灰度/回滚）
64
- - cdnBase: CDN 基础地址
65
- - snapshotUrl: snapshot.json 的完整 URL
66
- - manifestUrl: manifest.json 的完整 URL
67
- - ops: 运维配置（killSwitch、blockedComponents、flags）
68
- - etag: 内容哈希（用于缓存）
69
- - cacheTtlSeconds: 缓存 TTL（建议 10~30 秒）
70
- - snapshot: 完整快照（仅当 includeSnapshot=1 时返回）
60
+ 2. 保底模式：当 includeSnapshot=true 时，返回完整 snapshot（CDN 失败时使用）
71
61
  parameters:
72
- - name: X-Trace-Id
73
- in: header
74
- required: false
75
- schema:
76
- type: string
77
- description: 链路追踪 ID（OTel，全链路透传）
78
62
  - name: pageId
79
63
  in: query
80
64
  required: true
65
+ description: 页面 ID
81
66
  schema:
82
67
  type: string
83
- description: 页面 ID
68
+ example: page_123456
84
69
  - name: env
85
70
  in: query
86
71
  required: false
72
+ description: 环境
87
73
  schema:
88
74
  type: string
89
75
  enum:
@@ -91,39 +77,65 @@ paths:
91
77
  - preview
92
78
  - staging
93
79
  default: prod
94
- description: 环境（prod/preview/staging）
80
+ example: prod
81
+ - name: includeSnapshot
82
+ in: query
83
+ required: false
84
+ description: 是否包含完整快照（CDN 失败保底）
85
+ schema:
86
+ type: boolean
87
+ default: false
95
88
  - name: uid
96
89
  in: query
97
90
  required: false
91
+ description: 用户 ID（契约 query；也可用 Header x-user-id）
98
92
  schema:
99
93
  type: string
100
- description: 用户 ID（用于灰度路由）
94
+ maxLength: 64
95
+ example: user_123456
101
96
  - name: deviceId
102
97
  in: query
103
98
  required: false
99
+ description: 设备 ID（契约 query；也可用 Header x-device-id）
104
100
  schema:
105
101
  type: string
106
- description: 设备 ID
102
+ maxLength: 64
103
+ example: device_123456
107
104
  - name: channel
108
105
  in: query
109
106
  required: false
107
+ description: 渠道（契约 query；也可用 Header x-channel）
110
108
  schema:
111
109
  type: string
112
- description: 渠道标识
113
- - name: includeSnapshot
114
- in: query
115
- required: false
110
+ maxLength: 64
111
+ example: wechat
112
+ - name: x-user-id
113
+ in: header
114
+ required: true
116
115
  schema:
117
- type: boolean
118
- default: false
119
- description: 是否包含完整 snapshot（CDN 失败保底时使用）
116
+ type: string
117
+ - name: x-device-id
118
+ in: header
119
+ required: true
120
+ schema:
121
+ type: string
122
+ - name: x-channel
123
+ in: header
124
+ required: true
125
+ schema:
126
+ type: string
120
127
  responses:
121
128
  '200':
122
129
  description: 解析成功
123
130
  content:
124
131
  application/json:
125
132
  schema:
126
- $ref: '#/components/schemas/ResolvePageResponse'
133
+ allOf:
134
+ - $ref: '#/components/schemas/SuccessResponse'
135
+ - type: object
136
+ properties:
137
+ data:
138
+ $ref: '#/components/schemas/ResolvePageResponse'
127
139
  '400':
128
140
  $ref: '#/components/responses/BadRequest'
129
141
  '404':
@@ -136,28 +148,19 @@ paths:
136
148
  - Pages
137
149
  operationId: getPageManifest
138
150
  summary: 获取组件清单
139
- description: |
140
- 返回页面的组件锁定清单（manifest），包含所有引用的组件版本和资源信息。
141
-
142
- 用途：
143
- - Runtime 根据 manifest 预加载组件资源
144
- - Editor 根据 manifest 展示组件依赖
151
+ description: 返回页面的组件锁定清单
145
152
  parameters:
146
- - name: X-Trace-Id
147
- in: header
148
- required: false
149
- schema:
150
- type: string
151
- description: 链路追踪 ID（OTel，全链路透传）
152
153
  - name: pageId
153
154
  in: query
154
155
  required: true
156
+ description: 页面 ID
155
157
  schema:
156
158
  type: string
157
- description: 页面 ID
159
+ example: page_123456
158
160
  - name: env
159
161
  in: query
160
162
  required: false
163
+ description: 环境
161
164
  schema:
162
165
  type: string
163
166
  enum:
@@ -165,19 +168,19 @@ paths:
165
168
  - preview
166
169
  - staging
167
170
  default: prod
168
- description: 环境（prod/preview/staging）
171
+ example: prod
169
172
  responses:
170
173
  '200':
171
174
  description: 获取成功
172
175
  content:
173
176
  application/json:
174
177
  schema:
175
- type: object
176
- properties:
177
- success:
178
- type: boolean
179
- data:
180
- $ref: '#/components/schemas/ResourceManifests'
178
+ allOf:
179
+ - $ref: '#/components/schemas/SuccessResponse'
180
+ - type: object
181
+ properties:
182
+ data:
183
+ $ref: '#/components/schemas/ManifestResponse'
181
184
  '400':
182
185
  $ref: '#/components/responses/BadRequest'
183
186
  '404':
@@ -188,22 +191,12 @@ paths:
188
191
  - Pages
189
192
  operationId: getPageConfig
190
193
  summary: 获取运维配置
191
- description: |
192
- 返回当前运维配置（killSwitch、blockedComponents、featureFlags 等）。
193
-
194
- 用途：
195
- - Runtime 启动时获取全局运维配置
196
- - 判断是否有组件被阻断或功能被关闭
194
+ description: 返回当前运维配置（killSwitch、blockedComponents 等）
197
195
  parameters:
198
- - name: X-Trace-Id
199
- in: header
200
- required: false
201
- schema:
202
- type: string
203
- description: 链路追踪 ID（OTel，全链路透传）
204
196
  - name: env
205
197
  in: query
206
198
  required: false
199
+ description: 环境
207
200
  schema:
208
201
  type: string
209
202
  enum:
@@ -211,19 +204,19 @@ paths:
211
204
  - preview
212
205
  - staging
213
206
  default: prod
214
- description: 环境（prod/preview/staging）
207
+ example: prod
215
208
  responses:
216
209
  '200':
217
210
  description: 获取成功
218
211
  content:
219
212
  application/json:
220
213
  schema:
221
- type: object
222
- properties:
223
- success:
224
- type: boolean
225
- data:
226
- $ref: '#/components/schemas/OpsConfig'
214
+ allOf:
215
+ - $ref: '#/components/schemas/SuccessResponse'
216
+ - type: object
217
+ properties:
218
+ data:
219
+ $ref: '#/components/schemas/OpsConfig'
227
220
  '503':
228
221
  $ref: '#/components/responses/ServiceUnavailable'
229
222
  /actions/execute:
@@ -231,9 +224,9 @@ paths:
231
224
  tags:
232
225
  - Actions
233
226
  operationId: executeAction
234
- summary: 执行动作（统一入口）
227
+ summary: 执行动作
235
228
  description: |
236
- Action Gateway 唯一入口，所有业务动作都通过此接口执行。
229
+ 统一的动作执行入口，支持领取、签到等业务动作。
237
230
 
238
231
  执行流程（Pipeline）：
239
232
  1. Auth（登录态/票据/签名）
@@ -242,36 +235,6 @@ paths:
242
235
  4. Execute（执行器：Claim/Signin/Lottery...）
243
236
  5. Audit（审计落库 + outbox）
244
237
  6. Normalize（统一错误码/返回）
245
-
246
- 支持的动作类型：
247
- - claim: 领取
248
- - signin: 签到
249
- - lottery: 抽奖
250
- - reserve: 预约
251
- - bind: 绑定
252
- - task_complete: 任务完成
253
- - vote: 投票
254
- - share: 分享
255
- - form_submit: 表单提交
256
- - navigate: 页面跳转（内置）
257
- - setState: 状态更新（内置）
258
- - showToast: 提示消息（内置）
259
- - custom: 自定义动作
260
- parameters:
261
- - name: Idempotency-Key
262
- in: header
263
- required: false
264
- schema:
265
- type: string
266
- minLength: 16
267
- maxLength: 128
268
- description: 幂等键（与 body.idempotencyKey 二选一，推荐 header 传递）
269
- - name: X-Trace-Id
270
- in: header
271
- required: false
272
- schema:
273
- type: string
274
- description: 链路追踪 ID（OTel，全链路透传）
275
238
  requestBody:
276
239
  required: true
277
240
  content:
@@ -280,38 +243,33 @@ paths:
280
243
  $ref: '#/components/schemas/ExecuteActionRequest'
281
244
  responses:
282
245
  '200':
283
- description: 执行成功
246
+ description: 执行结果
284
247
  content:
285
248
  application/json:
286
249
  schema:
287
- $ref: '#/components/schemas/ExecuteActionResponse'
250
+ allOf:
251
+ - $ref: '#/components/schemas/SuccessResponse'
252
+ - type: object
253
+ properties:
254
+ data:
255
+ $ref: '#/components/schemas/ExecuteActionResponse'
288
256
  '400':
289
257
  $ref: '#/components/responses/BadRequest'
290
258
  '401':
291
259
  $ref: '#/components/responses/Unauthorized'
292
- '403':
293
- $ref: '#/components/responses/Forbidden'
294
- '409':
295
- description: 幂等冲突（重复请求）
296
- content:
297
- application/json:
298
- schema:
299
- $ref: '#/components/schemas/IdempotencyConflictResponse'
300
- '422':
301
- $ref: '#/components/responses/UnprocessableEntity'
302
260
  '429':
303
261
  $ref: '#/components/responses/TooManyRequests'
304
262
  '500':
305
263
  $ref: '#/components/responses/InternalError'
264
+ security:
265
+ - BearerAuth: []
306
266
  /actions/validate:
307
267
  post:
308
268
  tags:
309
269
  - Actions
310
270
  operationId: validateActionParams
311
271
  summary: 验证动作参数
312
- description: |
313
- 验证动作参数是否符合 Schema 定义（不执行动作）。
314
- 用于前端表单提交前的预校验。
272
+ description: 验证参数是否符合 Schema 定义，不执行动作
315
273
  requestBody:
316
274
  required: true
317
275
  content:
@@ -324,54 +282,54 @@ paths:
324
282
  content:
325
283
  application/json:
326
284
  schema:
327
- $ref: '#/components/schemas/ValidateActionResponse'
285
+ allOf:
286
+ - $ref: '#/components/schemas/SuccessResponse'
287
+ - type: object
288
+ properties:
289
+ data:
290
+ $ref: '#/components/schemas/ValidateActionResponse'
328
291
  '400':
329
292
  $ref: '#/components/responses/BadRequest'
293
+ security:
294
+ - BearerAuth: []
330
295
  /actions/definitions:
331
296
  get:
332
297
  tags:
333
298
  - Actions
334
299
  operationId: getActionDefinition
335
300
  summary: 获取动作定义
336
- description: 获取指定动作定义版本的详细信息（用于 Runtime 渲染动作配置）
301
+ description: 按版本 ID 获取动作定义详情
337
302
  parameters:
338
303
  - name: actionDefinitionVersionId
339
304
  in: query
340
305
  required: true
306
+ description: 动作定义版本 ID
341
307
  schema:
342
308
  type: string
343
- description: 动作定义版本 ID
309
+ example: 202401efgh87654321
344
310
  responses:
345
311
  '200':
346
- description: 成功
312
+ description: 动作定义版本信息
347
313
  content:
348
314
  application/json:
349
315
  schema:
350
- $ref: '#/components/schemas/ActionDefinitionResponse'
316
+ allOf:
317
+ - $ref: '#/components/schemas/SuccessResponse'
318
+ - type: object
319
+ properties:
320
+ data:
321
+ $ref: '#/components/schemas/ActionDefinitionVersionResponse'
351
322
  '404':
352
323
  $ref: '#/components/responses/NotFound'
324
+ security:
325
+ - BearerAuth: []
353
326
  /data/query:
354
327
  post:
355
328
  tags:
356
329
  - Queries
357
330
  operationId: queryData
358
- summary: 执行数据查询（Data Proxy 统一入口）
359
- description: |
360
- Data Proxy 统一入口，所有数据查询都通过此接口执行。
361
-
362
- 功能：
363
- - 白名单校验（queryVersionId 属于该 app/workspace）
364
- - 字段裁剪、脱敏
365
- - 缓存（短 TTL）
366
- - 失败降级（兜底结构）
367
- - 审计（可选，或采样）
368
-
369
- 支持的数据源类型：
370
- - http: HTTP 接口
371
- - graphql: GraphQL 查询
372
- - database: 数据库查询（受限）
373
- - internal: 内部服务
374
- - aggregation: 聚合查询
331
+ summary: 执行数据查询
332
+ description: 通过 queryVersionId 查询数据
375
333
  requestBody:
376
334
  required: true
377
335
  content:
@@ -384,30 +342,27 @@ paths:
384
342
  content:
385
343
  application/json:
386
344
  schema:
387
- $ref: '#/components/schemas/QueryDataResponse'
345
+ allOf:
346
+ - $ref: '#/components/schemas/SuccessResponse'
347
+ - type: object
348
+ properties:
349
+ data:
350
+ $ref: '#/components/schemas/QueryDataResponse'
388
351
  '400':
389
352
  $ref: '#/components/responses/BadRequest'
390
353
  '401':
391
354
  $ref: '#/components/responses/Unauthorized'
392
- '403':
393
- $ref: '#/components/responses/Forbidden'
394
- '404':
395
- $ref: '#/components/responses/NotFound'
396
- '422':
397
- $ref: '#/components/responses/UnprocessableEntity'
398
355
  '500':
399
356
  $ref: '#/components/responses/InternalError'
400
- '504':
401
- $ref: '#/components/responses/GatewayTimeout'
357
+ security:
358
+ - BearerAuth: []
402
359
  /data/query/batch:
403
360
  post:
404
361
  tags:
405
362
  - Queries
406
363
  operationId: batchQueryData
407
364
  summary: 批量执行数据查询
408
- description: |
409
- 批量执行多个数据查询，用于页面初始化时预取多个数据源。
410
- 所有查询并行执行，部分失败不影响其他查询返回。
365
+ description: 批量执行多个数据查询，所有查询并行执行
411
366
  requestBody:
412
367
  required: true
413
368
  content:
@@ -416,49 +371,56 @@ paths:
416
371
  $ref: '#/components/schemas/BatchQueryRequest'
417
372
  responses:
418
373
  '200':
419
- description: 批量查询结果
374
+ description: 批量查询成功
420
375
  content:
421
376
  application/json:
422
377
  schema:
423
- $ref: '#/components/schemas/BatchQueryResponse'
378
+ allOf:
379
+ - $ref: '#/components/schemas/SuccessResponse'
380
+ - type: object
381
+ properties:
382
+ data:
383
+ $ref: '#/components/schemas/BatchQueryResponse'
424
384
  '400':
425
385
  $ref: '#/components/responses/BadRequest'
386
+ security:
387
+ - BearerAuth: []
426
388
  /data/definitions:
427
389
  get:
428
390
  tags:
429
391
  - Queries
430
392
  operationId: getQueryDefinition
431
393
  summary: 获取查询定义
432
- description: 获取指定数据查询定义版本的详细信息
394
+ description: 按版本 ID 获取数据查询定义
433
395
  parameters:
434
396
  - name: queryVersionId
435
397
  in: query
436
398
  required: true
437
399
  schema:
438
400
  type: string
439
- description: 查询定义版本 ID
440
401
  responses:
441
402
  '200':
442
- description: 成功
403
+ description: 获取查询定义成功
443
404
  content:
444
405
  application/json:
445
406
  schema:
446
- $ref: '#/components/schemas/QueryDefinitionResponse'
407
+ allOf:
408
+ - $ref: '#/components/schemas/SuccessResponse'
409
+ - type: object
410
+ properties:
411
+ data:
412
+ $ref: '#/components/schemas/QueryDefinitionResponse'
447
413
  '404':
448
414
  $ref: '#/components/responses/NotFound'
415
+ security:
416
+ - BearerAuth: []
449
417
  /activities/{activityId}:
450
418
  get:
451
419
  tags:
452
420
  - Activities
453
- summary: 获取活动信息（公开）
454
421
  operationId: getActivityInfo
455
- description: |
456
- 获取活动的公开信息，不需要登录。
457
-
458
- 返回内容包括：
459
- - 活动基本信息
460
- - 时间范围
461
- - 奖品列表（脱敏）
422
+ summary: 获取活动信息（公开）
423
+ description: 获取活动的公开信息，不需要登录
462
424
  parameters:
463
425
  - name: activityId
464
426
  in: path
@@ -467,16 +429,16 @@ paths:
467
429
  type: string
468
430
  responses:
469
431
  '200':
470
- description: 成功
432
+ description: 获取活动信息成功
471
433
  content:
472
434
  application/json:
473
435
  schema:
474
- type: object
475
- properties:
476
- success:
477
- type: boolean
478
- data:
479
- $ref: '#/components/schemas/PublicActivityInfo'
436
+ allOf:
437
+ - $ref: '#/components/schemas/SuccessResponse'
438
+ - type: object
439
+ properties:
440
+ data:
441
+ $ref: '#/components/schemas/ActivityInfoResponse'
480
442
  '404':
481
443
  $ref: '#/components/responses/NotFound'
482
444
  security: []
@@ -484,83 +446,79 @@ paths:
484
446
  get:
485
447
  tags:
486
448
  - Activities
487
- summary: 获取用户活动状态
488
449
  operationId: getActivityState
489
- description: |
490
- 查询用户在指定活动中的参与状态。
491
-
492
- 返回内容包括：
493
- - 是否可参与
494
- - 剩余次数
495
- - 类型特定状态（领取/签到/抽奖等）
450
+ summary: 获取用户活动状态
451
+ description: 查询用户在指定活动中的参与状态
496
452
  parameters:
497
453
  - name: activityId
498
454
  in: path
499
455
  required: true
500
456
  schema:
501
457
  type: string
458
+ - name: uid
459
+ in: query
460
+ required: false
461
+ description: 用户 UID
462
+ schema:
463
+ type: string
502
464
  responses:
503
465
  '200':
504
- description: 成功
466
+ description: 获取活动状态成功
505
467
  content:
506
468
  application/json:
507
469
  schema:
508
- type: object
509
- properties:
510
- success:
511
- type: boolean
512
- data:
513
- $ref: '#/components/schemas/UserActivityState'
470
+ allOf:
471
+ - $ref: '#/components/schemas/SuccessResponse'
472
+ - type: object
473
+ properties:
474
+ data:
475
+ $ref: '#/components/schemas/ActivityStatusResponse'
514
476
  '404':
515
477
  $ref: '#/components/responses/NotFound'
516
- security:
517
- - BearerAuth: []
518
478
  /activities/{activityId}/signin/calendar:
519
479
  get:
520
480
  tags:
521
481
  - Activities
522
- summary: 获取签到日历
523
482
  operationId: getSigninCalendar
524
- description: |
525
- 获取用户的签到日历数据。
526
-
527
- 返回内容包括：
528
- - 当前周期的签到记录
529
- - 连续签到天数
530
- - 累计签到天数
531
- - 奖励进度
483
+ summary: 获取签到日历
484
+ description: 获取用户的签到日历数据
532
485
  parameters:
533
486
  - name: activityId
534
487
  in: path
535
488
  required: true
536
489
  schema:
537
490
  type: string
491
+ - name: uid
492
+ in: query
493
+ required: true
494
+ description: 用户 UID
495
+ schema:
496
+ type: string
538
497
  - name: month
539
498
  in: query
540
- description: 月份（YYYY-MM），默认当前月
499
+ required: false
500
+ description: 月份（YYYY-MM）
541
501
  schema:
542
502
  type: string
543
- pattern: ^\d{4}-\d{2}$
503
+ example: 2024-01
544
504
  responses:
545
505
  '200':
546
- description: 成功
506
+ description: 获取签到日历成功
547
507
  content:
548
508
  application/json:
549
509
  schema:
550
- type: object
551
- properties:
552
- success:
553
- type: boolean
554
- data:
555
- $ref: '#/components/schemas/SigninCalendar'
556
- security:
557
- - BearerAuth: []
510
+ allOf:
511
+ - $ref: '#/components/schemas/SuccessResponse'
512
+ - type: object
513
+ properties:
514
+ data:
515
+ $ref: '#/components/schemas/SigninCalendarResponse'
558
516
  /activities/{activityId}/claims:
559
517
  get:
560
518
  tags:
561
519
  - Activities
562
- summary: 获取领取记录
563
520
  operationId: getClaimRecords
521
+ summary: 获取领取记录
564
522
  description: 获取用户在指定活动中的领取记录
565
523
  parameters:
566
524
  - name: activityId
@@ -568,39 +526,43 @@ paths:
568
526
  required: true
569
527
  schema:
570
528
  type: string
529
+ - name: pageToken
530
+ in: query
531
+ required: false
532
+ description: 分页游标
533
+ schema:
534
+ type: string
571
535
  - name: pageSize
572
536
  in: query
537
+ required: false
538
+ description: 每页条数
573
539
  schema:
574
- type: integer
575
- default: 20
576
- - name: pageToken
540
+ type: number
541
+ example: 20
542
+ - name: uid
577
543
  in: query
544
+ required: false
545
+ description: 用户 UID，不传则返回空
578
546
  schema:
579
547
  type: string
580
548
  responses:
581
549
  '200':
582
- description: 成功
550
+ description: 获取领取记录成功
583
551
  content:
584
552
  application/json:
585
553
  schema:
586
- type: object
587
- properties:
588
- success:
589
- type: boolean
590
- data:
591
- type: array
592
- items:
593
- $ref: '#/components/schemas/ClaimRecordInfo'
594
- meta:
595
- $ref: '#/components/schemas/PaginationMeta'
596
- security:
597
- - BearerAuth: []
554
+ allOf:
555
+ - $ref: '#/components/schemas/SuccessResponse'
556
+ - type: object
557
+ properties:
558
+ data:
559
+ $ref: '#/components/schemas/PaginatedRecordsResponse'
598
560
  /activities/{activityId}/lottery:
599
561
  get:
600
562
  tags:
601
563
  - Activities
602
- summary: 获取抽奖记录
603
564
  operationId: getLotteryRecords
565
+ summary: 获取抽奖记录
604
566
  description: 获取用户在指定活动中的抽奖记录
605
567
  parameters:
606
568
  - name: activityId
@@ -610,40 +572,37 @@ paths:
610
572
  type: string
611
573
  - name: pageSize
612
574
  in: query
575
+ required: false
576
+ description: 每页条数
613
577
  schema:
614
- type: integer
578
+ type: number
615
579
  default: 20
580
+ example: 20
616
581
  - name: pageToken
617
582
  in: query
583
+ required: false
584
+ description: 分页游标
618
585
  schema:
619
586
  type: string
620
587
  responses:
621
588
  '200':
622
- description: 成功
589
+ description: 获取抽奖记录成功
623
590
  content:
624
591
  application/json:
625
592
  schema:
626
- type: object
627
- properties:
628
- success:
629
- type: boolean
630
- data:
631
- type: array
632
- items:
633
- $ref: '#/components/schemas/LotteryRecordInfo'
634
- meta:
635
- $ref: '#/components/schemas/PaginationMeta'
636
- security:
637
- - BearerAuth: []
593
+ allOf:
594
+ - $ref: '#/components/schemas/SuccessResponse'
595
+ - type: object
596
+ properties:
597
+ data:
598
+ $ref: '#/components/schemas/PaginatedRecordsResponse'
638
599
  /activities/{activityId}/status:
639
600
  get:
640
601
  tags:
641
602
  - Activities
642
- summary: 获取活动状态（兼容）
643
603
  operationId: getActivityStatus
644
- description: |
645
- 获取活动的当前状态信息，包括是否进行中、时间范围等。
646
- 不需要登录，可用于前端判断活动是否在有效期内。
604
+ summary: 获取活动状态（兼容）
605
+ description: 获取活动的当前状态信息
647
606
  parameters:
648
607
  - name: activityId
649
608
  in: path
@@ -652,16 +611,16 @@ paths:
652
611
  type: string
653
612
  responses:
654
613
  '200':
655
- description: 成功
614
+ description: 获取活动状态成功
656
615
  content:
657
616
  application/json:
658
617
  schema:
659
- type: object
660
- properties:
661
- success:
662
- type: boolean
663
- data:
664
- $ref: '#/components/schemas/ActivityStatus'
618
+ allOf:
619
+ - $ref: '#/components/schemas/SuccessResponse'
620
+ - type: object
621
+ properties:
622
+ data:
623
+ $ref: '#/components/schemas/ActivityStatusResponse'
665
624
  '404':
666
625
  $ref: '#/components/responses/NotFound'
667
626
  security: []
@@ -669,8 +628,8 @@ paths:
669
628
  get:
670
629
  tags:
671
630
  - Activities
672
- summary: 获取领取状态
673
631
  operationId: getClaimStatus
632
+ summary: 获取领取状态
674
633
  description: 获取用户在指定活动中的领取状态
675
634
  parameters:
676
635
  - name: activityId
@@ -681,30 +640,27 @@ paths:
681
640
  - name: uid
682
641
  in: query
683
642
  required: true
643
+ description: 用户 UID
684
644
  schema:
685
645
  type: string
686
- description: 用户 UID
687
646
  responses:
688
647
  '200':
689
- description: 成功
648
+ description: 获取领取状态成功
690
649
  content:
691
650
  application/json:
692
651
  schema:
693
- type: object
694
- properties:
695
- success:
696
- type: boolean
697
- data:
698
- type: object
699
- description: 领取状态数据
700
- security:
701
- - BearerAuth: []
652
+ allOf:
653
+ - $ref: '#/components/schemas/SuccessResponse'
654
+ - type: object
655
+ properties:
656
+ data:
657
+ $ref: '#/components/schemas/ClaimStatusResponse'
702
658
  /activities/{activityId}/signin/status:
703
659
  get:
704
660
  tags:
705
661
  - Activities
706
- summary: 获取签到状态
707
662
  operationId: getSigninStatus
663
+ summary: 获取签到状态
708
664
  description: 获取用户在指定活动中的签到状态
709
665
  parameters:
710
666
  - name: activityId
@@ -715,74 +671,50 @@ paths:
715
671
  - name: uid
716
672
  in: query
717
673
  required: true
674
+ description: 用户 UID
718
675
  schema:
719
676
  type: string
720
- description: 用户 UID
721
677
  responses:
722
678
  '200':
723
- description: 成功
679
+ description: 获取签到状态成功
724
680
  content:
725
681
  application/json:
726
682
  schema:
727
- type: object
728
- properties:
729
- success:
730
- type: boolean
731
- data:
732
- type: object
733
- description: 签到状态数据
734
- security:
735
- - BearerAuth: []
683
+ allOf:
684
+ - $ref: '#/components/schemas/SuccessResponse'
685
+ - type: object
686
+ properties:
687
+ data:
688
+ $ref: '#/components/schemas/SigninStatusResponse'
736
689
  /track:
737
690
  post:
738
691
  tags:
739
692
  - Track
740
- summary: 埋点上报
741
693
  operationId: track
742
- description: |
743
- 接收客户端埋点数据，异步写入 Outbox。
744
-
745
- 特点：
746
- - 高性能：不阻塞主链路
747
- - 可靠：通过 Outbox 异步持久化
748
- - 可追溯：自动关联 pageVersionId/componentVersionId/traceId
694
+ summary: 单个埋点上报
695
+ description: 接收客户端埋点数据，异步处理
749
696
  requestBody:
750
697
  required: true
751
698
  content:
752
699
  application/json:
753
700
  schema:
754
- $ref: '#/components/schemas/TrackRequest'
701
+ $ref: '#/components/schemas/TrackSingleRequest'
755
702
  responses:
756
703
  '202':
757
704
  description: 接收成功（异步处理）
758
705
  content:
759
706
  application/json:
760
707
  schema:
761
- type: object
762
- properties:
763
- success:
764
- type: boolean
765
- example: true
766
- data:
767
- type: object
768
- properties:
769
- eventId:
770
- type: string
771
- description: 事件 ID
708
+ $ref: '#/components/schemas/TrackSingleResponse'
772
709
  '400':
773
710
  $ref: '#/components/responses/BadRequest'
774
711
  /track/batch:
775
712
  post:
776
713
  tags:
777
714
  - Track
778
- summary: 批量埋点上报
779
715
  operationId: trackBatch
780
- description: |
781
- 批量接收客户端埋点数据，提高上报效率。
782
-
783
- 限制：
784
- - 单次最多 100 条
785
- - 单条事件不超过 10KB
716
+ summary: 批量埋点上报
717
+ description: 批量接收客户端埋点数据，提高上报效率
786
718
  requestBody:
787
719
  required: true
788
720
  content:
@@ -795,75 +727,34 @@ paths:
795
727
  content:
796
728
  application/json:
797
729
  schema:
798
- type: object
799
- properties:
800
- success:
801
- type: boolean
802
- data:
803
- type: object
804
- properties:
805
- accepted:
806
- type: integer
807
- description: 接收的事件数量
808
- rejected:
809
- type: integer
810
- description: 拒绝的事件数量
811
- errors:
812
- type: array
813
- items:
814
- type: object
815
- properties:
816
- index:
817
- type: integer
818
- reason:
819
- type: string
730
+ $ref: '#/components/schemas/TrackBatchResponse'
820
731
  '400':
821
732
  $ref: '#/components/responses/BadRequest'
822
733
  /tenant/resolve:
823
734
  post:
824
735
  tags:
825
736
  - Tenant
826
- summary: 解析租户信息
827
737
  operationId: resolveTenant
828
- description: |
829
- 根据 appKey 或 host 解析租户/应用信息。
830
-
831
- 用于：
832
- - Runtime 初始化时获取应用配置
833
- - 多租户场景下的应用隔离
738
+ summary: 解析租户信息
739
+ description: 根据 appKey 或 host 解析租户/应用信息
834
740
  requestBody:
835
741
  required: true
836
742
  content:
837
743
  application/json:
838
744
  schema:
839
- type: object
840
- properties:
841
- appKey:
842
- type: string
843
- description: 应用密钥
844
- host:
845
- type: string
846
- description: 请求来源域名
847
- channel:
848
- type: string
849
- description: 渠道标识
850
- anyOf:
851
- - required:
852
- - appKey
853
- - required:
854
- - host
745
+ $ref: '#/components/schemas/ResolveTenantRequest'
855
746
  responses:
856
747
  '200':
857
748
  description: 解析成功
858
749
  content:
859
750
  application/json:
860
751
  schema:
861
- type: object
862
- properties:
863
- success:
864
- type: boolean
865
- data:
866
- $ref: '#/components/schemas/TenantInfo'
752
+ allOf:
753
+ - $ref: '#/components/schemas/SuccessResponse'
754
+ - type: object
755
+ properties:
756
+ data:
757
+ $ref: '#/components/schemas/ResolveTenantResponse'
867
758
  '400':
868
759
  $ref: '#/components/responses/BadRequest'
869
760
  '404':
@@ -877,36 +768,32 @@ paths:
877
768
  get:
878
769
  tags:
879
770
  - Tenant
880
- summary: 获取租户配置
881
771
  operationId: getTenantConfig
882
- description: |
883
- 获取当前租户的运行时配置。
884
-
885
- 包括：
886
- - 功能开关
887
- - 主题配置
888
- - CDN 域名
889
- - 阻断组件列表
890
- - Kill Switch 状态
772
+ summary: 获取租户配置
773
+ description: 获取当前租户的运行时配置
891
774
  parameters:
775
+ - name: x-app-id
776
+ in: header
777
+ required: true
778
+ schema:
779
+ type: string
892
780
  - name: X-App-Id
893
781
  in: header
894
782
  required: true
895
783
  schema:
896
784
  type: string
897
- description: 应用 ID
898
785
  responses:
899
786
  '200':
900
- description: 成功
787
+ description: 获取成功
901
788
  content:
902
789
  application/json:
903
790
  schema:
904
- type: object
905
- properties:
906
- success:
907
- type: boolean
908
- data:
909
- $ref: '#/components/schemas/TenantConfig'
791
+ allOf:
792
+ - $ref: '#/components/schemas/SuccessResponse'
793
+ - type: object
794
+ properties:
795
+ data:
796
+ $ref: '#/components/schemas/TenantConfigResponse'
910
797
  '401':
911
798
  $ref: '#/components/responses/Unauthorized'
912
799
  '404':
@@ -915,85 +802,61 @@ paths:
915
802
  get:
916
803
  tags:
917
804
  - Health
918
- summary: 健康检查
919
805
  operationId: healthCheck
920
- description: |
921
- 综合健康检查，包含所有依赖服务状态。
922
-
923
- 返回：
924
- - 服务状态（healthy/degraded/unhealthy）
925
- - 版本信息
926
- - 运行时间
927
- - 依赖服务状态
806
+ summary: 健康检查
807
+ description: 综合健康检查，返回服务状态和时间戳
928
808
  responses:
929
809
  '200':
930
- description: 服务健康
931
- content:
932
- application/json:
933
- schema:
934
- $ref: '#/components/schemas/HealthResponse'
935
- '503':
936
- description: 服务不健康
810
+ description: 健康
937
811
  content:
938
812
  application/json:
939
813
  schema:
940
- $ref: '#/components/schemas/HealthResponse'
814
+ allOf:
815
+ - $ref: '#/components/schemas/SuccessResponse'
816
+ - type: object
817
+ properties:
818
+ data:
819
+ $ref: '#/components/schemas/HealthCheckResponse'
941
820
  security: []
942
- /health/ready:
821
+ /health/live:
943
822
  get:
944
823
  tags:
945
824
  - Health
946
- summary: 就绪检查
947
- operationId: readinessCheck
948
- description: |
949
- Kubernetes readiness probe。
950
- 检查服务是否准备好接收流量。
825
+ operationId: livenessCheck
826
+ summary: 存活检查
827
+ description: Kubernetes liveness probe
951
828
  responses:
952
829
  '200':
953
- description: 服务就绪
954
- content:
955
- application/json:
956
- schema:
957
- type: object
958
- properties:
959
- ready:
960
- type: boolean
961
- example: true
962
- '503':
963
- description: 服务未就绪
830
+ description: 存活
964
831
  content:
965
832
  application/json:
966
833
  schema:
967
- type: object
968
- properties:
969
- ready:
970
- type: boolean
971
- example: false
972
- reason:
973
- type: string
834
+ allOf:
835
+ - $ref: '#/components/schemas/SuccessResponse'
836
+ - type: object
837
+ properties:
838
+ data:
839
+ $ref: '#/components/schemas/LivenessResponse'
974
840
  security: []
975
- /health/live:
841
+ /health/ready:
976
842
  get:
977
843
  tags:
978
844
  - Health
979
- summary: 存活检查
980
- operationId: livenessCheck
981
- description: |
982
- Kubernetes liveness probe。
983
- 检查服务是否存活。
845
+ operationId: readinessCheck
846
+ summary: 就绪检查
847
+ description: Kubernetes readiness probe
984
848
  responses:
985
849
  '200':
986
- description: 服务存活
850
+ description: 就绪
987
851
  content:
988
852
  application/json:
989
853
  schema:
990
- type: object
991
- properties:
992
- alive:
993
- type: boolean
994
- example: true
995
- '503':
996
- description: 服务不存活
854
+ allOf:
855
+ - $ref: '#/components/schemas/SuccessResponse'
856
+ - type: object
857
+ properties:
858
+ data:
859
+ $ref: '#/components/schemas/ReadinessResponse'
997
860
  security: []
998
861
  components:
999
862
  schemas:
@@ -1006,346 +869,167 @@ components:
1006
869
  - data
1007
870
  - timestamp
1008
871
  - path
1009
- description: 成功响应（ApiSuccessResponse，与 types/src/common/api.ts 保持一致）
872
+ description: 成功响应（BaseResponseVo）
1010
873
  properties:
1011
874
  success:
1012
875
  type: boolean
1013
- enum:
1014
- - true
876
+ description: 请求是否成功
1015
877
  example: true
1016
- description: 是否成功（固定为 true）
1017
878
  code:
1018
879
  type: string
1019
- example: OK
1020
880
  description: 业务状态码
881
+ example: OK
1021
882
  message:
1022
883
  type: string
1023
- example: 操作成功
1024
884
  description: 响应消息
885
+ example: 操作成功
1025
886
  data:
1026
- description: 响应数据（泛型 T）
887
+ type: object
888
+ description: 响应数据
1027
889
  timestamp:
1028
- type: integer
1029
- format: int64
890
+ type: number
891
+ description: 响应时间戳
1030
892
  example: 1702300000000
1031
- description: 响应时间戳（Unix 毫秒时间戳，number）
1032
893
  path:
1033
894
  type: string
1034
- example: /api/user/pages/resolve
1035
895
  description: 请求路径
896
+ example: /api/users
1036
897
  requestId:
1037
898
  type: string
899
+ description: 请求ID
1038
900
  example: uuid-string
1039
- description: 请求 ID（可选）
1040
- KillSwitchItem:
1041
- type: object
1042
- required:
1043
- - targetType
1044
- - targetId
1045
- - enabled
1046
- description: Kill-Switch 条目
1047
- properties:
1048
- targetType:
1049
- type: string
1050
- enum:
1051
- - action
1052
- - component
1053
- - feature
1054
- - page
1055
- - query
1056
- description: 目标类型
1057
- targetId:
1058
- type: string
1059
- description: 目标 ID（actionType/componentName/featureKey/pageId/queryId）
1060
- enabled:
1061
- type: boolean
1062
- description: 是否启用（true = 被关闭）
1063
- reason:
1064
- type: string
1065
- description: 关闭原因
1066
- enabledAt:
1067
- type: string
1068
- format: date-time
1069
- description: 关闭时间（ISO8601）
1070
- enabledBy:
1071
- type: string
1072
- description: 关闭操作者
1073
- userMessage:
901
+ traceId:
1074
902
  type: string
1075
- description: 用户提示消息
1076
- BlockedComponentItem:
903
+ description: 链路追踪ID（用于全链路定位问题）
904
+ example: trace-uuid-string
905
+ BlockedComponent:
1077
906
  type: object
1078
907
  required:
1079
908
  - name
1080
909
  - reason
1081
- description: 被阻断的组件条目
910
+ - blockedAt
911
+ - blockedBy
912
+ description: 被阻断的组件（BlockedComponentVo）
1082
913
  properties:
1083
914
  name:
1084
915
  type: string
1085
916
  description: 组件名称
1086
917
  version:
1087
918
  type: string
1088
- pattern: ^\d+\.\d+\.\d+$
1089
- description: 组件版本（可选，不指定则阻断所有版本）
919
+ description: 组件版本（不填则阻断所有版本）
1090
920
  reason:
1091
921
  type: string
1092
922
  description: 阻断原因
1093
923
  blockedAt:
1094
924
  type: string
1095
- format: date-time
1096
- description: 阻断时间（ISO8601）
925
+ description: 阻断时间
1097
926
  blockedBy:
1098
927
  type: string
1099
- description: 阻断操作者
1100
- fallbackVersion:
1101
- type: string
1102
- pattern: ^\d+\.\d+\.\d+$
1103
- description: 降级版本（可选）
1104
- urgent:
928
+ description: 操作者
929
+ DegradeConfig:
930
+ type: object
931
+ required:
932
+ - enabled
933
+ - mode
934
+ description: 降级配置（DegradeConfigVo）
935
+ properties:
936
+ enabled:
1105
937
  type: boolean
1106
- description: 是否紧急阻断
938
+ description: 是否启用降级
939
+ mode:
940
+ type: string
941
+ description: 降级模式
942
+ enum:
943
+ - fallback
944
+ - static
945
+ - error
946
+ message:
947
+ type: string
948
+ description: 降级消息
1107
949
  OpsConfig:
1108
950
  type: object
1109
- description: 运维配置（运行时下发，与 types/page/snapshot.ts OpsConfig 对齐）
1110
951
  required:
1111
952
  - killSwitch
1112
953
  - blockedComponents
1113
- - flags
954
+ - blockedPages
955
+ - featureFlags
956
+ - degradeConfig
957
+ description: 运维配置（OpsConfigVo）
1114
958
  properties:
1115
- configVersionId:
1116
- type: string
1117
- description: 配置版本 ID（用于缓存失效）
1118
959
  killSwitch:
960
+ type: boolean
961
+ description: 全局 kill-switch
962
+ blockedComponents:
963
+ description: 被阻断的组件列表
1119
964
  type: array
1120
965
  items:
1121
- $ref: '#/components/schemas/KillSwitchItem'
1122
- description: Kill-Switch 列表（被紧急关闭的功能/动作）
1123
- blockedComponents:
966
+ $ref: '#/components/schemas/BlockedComponent'
967
+ blockedPages:
968
+ description: 被阻断的页面列表
1124
969
  type: array
1125
970
  items:
1126
- $ref: '#/components/schemas/BlockedComponentItem'
1127
- description: 被阻断的组件列表
1128
- flags:
971
+ type: string
972
+ featureFlags:
1129
973
  type: object
974
+ description: 功能开关
1130
975
  additionalProperties:
1131
976
  type: boolean
1132
- description: 功能开关（Feature Flags）
1133
- expiresAt:
1134
- type: string
1135
- format: date-time
1136
- description: 配置过期时间（ISO8601）
977
+ degradeConfig:
978
+ description: 降级配置
979
+ allOf:
980
+ - $ref: '#/components/schemas/DegradeConfig'
1137
981
  ResolvePageResponse:
1138
- allOf:
1139
- - $ref: '#/components/schemas/SuccessResponse'
1140
- - type: object
1141
- properties:
1142
- data:
1143
- type: object
1144
- required:
1145
- - pageId
1146
- - resolvedVersionId
1147
- - cdnBase
1148
- - snapshotUrl
1149
- - manifestUrl
1150
- - ops
1151
- - etag
1152
- - cacheTtlSeconds
1153
- properties:
1154
- pageId:
1155
- type: string
1156
- description: 页面 ID（UniqueId）
1157
- resolvedVersionId:
1158
- type: string
1159
- description: 解析后的页面版本 ID（考虑灰度/回滚后的实际版本，UniqueId）
1160
- cdnBase:
1161
- type: string
1162
- format: uri
1163
- description: CDN 基础地址
1164
- snapshotUrl:
1165
- type: string
1166
- format: uri
1167
- description: snapshot.json 的完整 URL
1168
- manifestUrl:
1169
- type: string
1170
- format: uri
1171
- description: manifest.json 的完整 URL
1172
- ops:
1173
- $ref: '#/components/schemas/OpsConfig'
1174
- description: 运维配置（killSwitch、blockedComponents、flags）
1175
- etag:
1176
- type: string
1177
- description: 内容哈希（用于缓存验证）
1178
- cacheTtlSeconds:
1179
- type: integer
1180
- minimum: 0
1181
- maximum: 300
1182
- default: 30
1183
- description: 缓存 TTL（秒），建议 10~30 秒
1184
- traceId:
1185
- type: string
1186
- description: 链路追踪 ID（全链路透传，与 types 可观测原则一致）
1187
- runtimeVersion:
1188
- type: string
1189
- pattern: ^\d+\.\d+\.\d+$
1190
- description: 运行时版本（SemVer，与 manifest.runtime.version 一致）
1191
- rolloutMatch:
1192
- type: object
1193
- description: 灰度匹配信息（可选，用于调试）
1194
- properties:
1195
- strategyId:
1196
- type: string
1197
- description: 匹配的策略 ID
1198
- strategyName:
1199
- type: string
1200
- description: 匹配的策略名称
1201
- isDefault:
1202
- type: boolean
1203
- description: 是否使用默认版本
1204
- snapshot:
1205
- type: object
1206
- description: 完整快照（仅当 includeSnapshot=1 时返回，CDN 失败保底使用）
1207
- properties:
1208
- page:
1209
- type: object
1210
- description: 页面 Schema（PageSnapshotPage）
1211
- properties:
1212
- schemaVersion:
1213
- type: string
1214
- pageId:
1215
- type: string
1216
- pageVersion:
1217
- type: string
1218
- pattern: ^\d+\.\d+\.\d+$
1219
- title:
1220
- type: string
1221
- initialState:
1222
- type: object
1223
- additionalProperties: true
1224
- bindings:
1225
- type: array
1226
- items:
1227
- type: object
1228
- root:
1229
- type: object
1230
- config:
1231
- type: object
1232
- manifest:
1233
- type: object
1234
- description: 组件锁定清单（PageSnapshotManifest）
1235
- properties:
1236
- components:
1237
- type: array
1238
- items:
1239
- type: object
1240
- properties:
1241
- name:
1242
- type: string
1243
- version:
1244
- type: string
1245
- pattern: ^\d+\.\d+\.\d+$
1246
- source:
1247
- type: string
1248
- enum:
1249
- - bundled
1250
- - remote
1251
- description: 组件来源：bundled = 内置组件，remote = 远程组件
1252
- integrity:
1253
- type: string
1254
- pattern: ^sha(256|384|512)-
1255
- assetsUrl:
1256
- type: string
1257
- format: uri
1258
- description: CDN 资源基础 URL（source 为 remote 时必填）
1259
- entrypoints:
1260
- type: object
1261
- description: 入口点（source 为 remote 时必填）
1262
- properties:
1263
- js:
1264
- type: string
1265
- css:
1266
- type: string
1267
- chunks:
1268
- type: array
1269
- items:
1270
- type: string
1271
- runtime:
1272
- type: object
1273
- properties:
1274
- version:
1275
- type: string
1276
- pattern: ^\d+\.\d+\.\d+$
1277
- minVersion:
1278
- type: string
1279
- pattern: ^\d+\.\d+\.\d+$
1280
- definitionsDigest:
1281
- type: object
1282
- description: 绑定的 Definition 版本摘要（DefinitionsDigest）
1283
- properties:
1284
- actions:
1285
- type: array
1286
- items:
1287
- type: object
1288
- properties:
1289
- id:
1290
- type: string
1291
- name:
1292
- type: string
1293
- versionId:
1294
- type: string
1295
- hash:
1296
- type: string
1297
- queries:
1298
- type: array
1299
- items:
1300
- type: object
1301
- properties:
1302
- id:
1303
- type: string
1304
- name:
1305
- type: string
1306
- versionId:
1307
- type: string
1308
- hash:
1309
- type: string
1310
- meta:
1311
- type: object
1312
- description: 元数据（PageSnapshotMeta）
1313
- properties:
1314
- pageId:
1315
- type: string
1316
- pageVersionId:
1317
- type: string
1318
- publishId:
1319
- type: string
1320
- schemaVersion:
1321
- type: string
1322
- createdAt:
1323
- type: string
1324
- format: date-time
1325
- createdBy:
1326
- type: string
1327
- contentHash:
1328
- type: string
1329
- bindings:
1330
- type: object
1331
- properties:
1332
- componentVersions:
1333
- type: array
1334
- items:
1335
- type: string
1336
- definitionVersions:
1337
- type: array
1338
- items:
1339
- type: string
1340
- runtimeVersion:
1341
- type: string
1342
- pattern: ^\d+\.\d+\.\d+$
1343
- env:
1344
- type: string
1345
- enum:
1346
- - preview
1347
- - staging
1348
- - prod
982
+ type: object
983
+ required:
984
+ - pageId
985
+ - resolvedVersionId
986
+ - cdnBase
987
+ - snapshotUrl
988
+ - manifestUrl
989
+ - ops
990
+ - etag
991
+ - cacheTtlSeconds
992
+ description: 页面解析响应（PageResolveResponseVo）
993
+ properties:
994
+ pageId:
995
+ type: string
996
+ description: 页面 ID
997
+ example: page_123456
998
+ resolvedVersionId:
999
+ type: string
1000
+ description: 解析后的页面版本 ID
1001
+ example: pv_20240101_abc
1002
+ cdnBase:
1003
+ type: string
1004
+ description: CDN 基础 URL
1005
+ example: https://cdn.example.com
1006
+ snapshotUrl:
1007
+ type: string
1008
+ description: Snapshot URL
1009
+ example: https://cdn.example.com/pages/page_123456/snapshot.json
1010
+ manifestUrl:
1011
+ type: string
1012
+ description: Manifest URL
1013
+ example: https://cdn.example.com/pages/page_123456/manifest.json
1014
+ ops:
1015
+ description: 运维配置
1016
+ allOf:
1017
+ - $ref: '#/components/schemas/OpsConfig'
1018
+ etag:
1019
+ type: string
1020
+ description: ETag（用于缓存）
1021
+ example: '"abc123"'
1022
+ cacheTtlSeconds:
1023
+ type: number
1024
+ description: 缓存 TTL（秒）
1025
+ example: 300
1026
+ traceId:
1027
+ type: string
1028
+ description: 链路追踪 ID
1029
+ runtimeVersion:
1030
+ type: string
1031
+ description: 运行时版本（SemVer）
1032
+ example: 1.0.0
1349
1033
  ErrorResponse:
1350
1034
  type: object
1351
1035
  required:
@@ -1354,160 +1038,125 @@ components:
1354
1038
  - message
1355
1039
  - timestamp
1356
1040
  - path
1357
- description: 错误响应（ApiErrorResponse，与 types/src/common/api.ts 保持一致）
1041
+ description: 错误响应（ErrorResponseVo）
1358
1042
  properties:
1359
1043
  success:
1360
1044
  type: boolean
1361
- enum:
1362
- - false
1045
+ description: 请求是否成功
1363
1046
  example: false
1364
- description: 是否成功（固定为 false）
1365
1047
  code:
1366
1048
  type: string
1367
- example: VALIDATION_INVALID_PARAMS
1368
- description: 错误码（ErrorCode | string）
1049
+ description: 错误码
1050
+ example: USER_NOT_FOUND
1369
1051
  message:
1370
1052
  type: string
1371
- example: 请求参数无效
1372
- description: 错误消息（用户可读）
1373
- data:
1374
- type: object
1375
- additionalProperties: true
1376
- description: 错误详情（Record<string, unknown>，与 types ApiErrorResponse.data 一致）
1053
+ description: 错误消息
1054
+ example: 用户不存在
1377
1055
  timestamp:
1378
- type: integer
1379
- format: int64
1056
+ type: number
1057
+ description: 响应时间戳
1380
1058
  example: 1702300000000
1381
- description: 响应时间戳（Unix 毫秒时间戳，number）
1382
1059
  path:
1383
1060
  type: string
1384
- example: /api/user/pages/resolve
1385
1061
  description: 请求路径
1062
+ example: /api/users/123
1386
1063
  requestId:
1387
1064
  type: string
1065
+ description: 请求ID
1388
1066
  example: uuid-string
1389
- description: 请求 ID（可选）
1390
1067
  traceId:
1391
1068
  type: string
1392
- example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
1393
- description: 链路追踪 ID（可选，用于分布式追踪）
1394
- ComponentManifest:
1069
+ description: 链路追踪ID（用于全链路定位问题）
1070
+ example: trace-uuid-string
1071
+ ManifestComponent:
1395
1072
  type: object
1396
1073
  required:
1397
- - componentType
1074
+ - name
1398
1075
  - version
1399
1076
  - source
1077
+ - integrity
1078
+ description: 组件清单项（ManifestComponentSwaggerVo）
1400
1079
  properties:
1401
- componentType:
1080
+ name:
1402
1081
  type: string
1403
- description: 组件类型
1082
+ description: 组件名称（Custom Element 标签名）
1083
+ example: djvlc-button
1404
1084
  version:
1405
1085
  type: string
1406
- description: 组件版本
1086
+ description: 版本号
1087
+ example: 1.0.0
1407
1088
  source:
1408
1089
  type: string
1090
+ description: 组件来源
1409
1091
  enum:
1410
1092
  - bundled
1411
1093
  - remote
1412
- description: 组件来源：bundled = 内置组件（随 Runtime 打包），remote = 远程组件（从 CDN 加载）
1413
- entryUrl:
1094
+ entry:
1414
1095
  type: string
1415
- format: uri
1416
- description: 组件入口 URL（source 为 remote 时必填）
1417
- styleUrl:
1096
+ description: 入口 URL（remote 组件必填）
1097
+ styleEntry:
1418
1098
  type: string
1419
- format: uri
1420
- description: 样式文件 URL
1099
+ description: 样式入口 URL
1421
1100
  integrity:
1422
1101
  type: string
1423
1102
  description: SRI 完整性哈希
1424
- blocked:
1103
+ preload:
1425
1104
  type: boolean
1426
- description: 是否被阻断
1427
- fallback:
1428
- type: string
1429
- description: 降级组件类型
1430
- ActionManifest:
1105
+ description: 是否预加载
1106
+ ManifestRuntime:
1431
1107
  type: object
1432
1108
  required:
1433
- - actionId
1434
- - actionDefinitionVersionId
1109
+ - version
1110
+ - minVersion
1111
+ description: Runtime 版本信息（ManifestRuntimeVo）
1435
1112
  properties:
1436
- actionId:
1437
- type: string
1438
- description: 动作 ID
1439
- actionDefinitionVersionId:
1113
+ version:
1440
1114
  type: string
1441
- description: 动作定义版本 ID
1442
- actionType:
1115
+ description: 版本
1116
+ example: 1.0.0
1117
+ minVersion:
1443
1118
  type: string
1444
- enum:
1445
- - claim
1446
- - signin
1447
- - lottery
1448
- - reserve
1449
- - bind
1450
- - task_complete
1451
- - vote
1452
- - share
1453
- - form_submit
1454
- - navigate
1455
- - setState
1456
- - showToast
1457
- - refreshData
1458
- - custom
1459
- description: 动作类型
1460
- builtin:
1461
- type: boolean
1462
- description: 是否内置动作
1463
- QueryManifest:
1119
+ description: 最低兼容版本
1120
+ example: 0.9.0
1121
+ ManifestResponse:
1464
1122
  type: object
1465
1123
  required:
1466
- - queryId
1467
- - queryVersionId
1124
+ - pageVersionId
1125
+ - manifestVersion
1126
+ - components
1127
+ - runtime
1128
+ description: 组件清单响应（ManifestSwaggerVo）
1468
1129
  properties:
1469
- queryId:
1130
+ pageVersionId:
1470
1131
  type: string
1471
- description: 查询 ID
1472
- queryVersionId:
1132
+ description: 页面版本 ID
1133
+ manifestVersion:
1473
1134
  type: string
1474
- description: 查询定义版本 ID
1475
- cacheTtl:
1476
- type: integer
1477
- description: 缓存 TTL（秒）
1478
- ResourceManifests:
1479
- type: object
1480
- properties:
1135
+ description: 清单版本
1481
1136
  components:
1137
+ description: 组件列表
1482
1138
  type: array
1483
1139
  items:
1484
- $ref: '#/components/schemas/ComponentManifest'
1485
- description: 组件资源清单
1486
- actions:
1487
- type: array
1488
- items:
1489
- $ref: '#/components/schemas/ActionManifest'
1490
- description: 动作资源清单
1491
- queries:
1492
- type: array
1493
- items:
1494
- $ref: '#/components/schemas/QueryManifest'
1495
- description: 查询资源清单
1140
+ $ref: '#/components/schemas/ManifestComponent'
1141
+ runtime:
1142
+ description: Runtime 版本
1143
+ allOf:
1144
+ - $ref: '#/components/schemas/ManifestRuntime'
1496
1145
  ActionClientContext:
1497
1146
  type: object
1498
- description: 动作执行上下文（ActionClientContext，问题追溯必须字段）
1499
1147
  required:
1500
1148
  - pageVersionId
1149
+ description: 动作执行上下文（ActionContextDto）
1501
1150
  properties:
1502
1151
  pageVersionId:
1503
1152
  type: string
1504
- description: 页面版本 ID（不可变，UniqueId）
1153
+ description: 页面版本 ID
1505
1154
  componentVersionId:
1506
1155
  type: string
1507
- description: 组件版本 ID（UniqueId）
1156
+ description: 组件版本 ID
1508
1157
  componentInstanceId:
1509
1158
  type: string
1510
- description: 组件实例 ID（UniqueId）
1159
+ description: 组件实例 ID
1511
1160
  triggerEvent:
1512
1161
  type: string
1513
1162
  description: 触发事件名
@@ -1516,372 +1165,332 @@ components:
1516
1165
  description: 设备 ID
1517
1166
  channel:
1518
1167
  type: string
1519
- description: 渠道标识
1168
+ description: 渠道
1520
1169
  clientTimestamp:
1521
1170
  type: string
1522
- format: date-time
1523
- description: 客户端时间戳（ISODateTime）
1171
+ description: 客户端时间戳（ISO 8601）
1524
1172
  extra:
1525
1173
  type: object
1174
+ description: 扩展数据
1526
1175
  additionalProperties: true
1527
- description: 扩展数据（Record<string, JsonValue>）
1528
1176
  ExecuteActionRequest:
1529
1177
  type: object
1530
1178
  required:
1531
1179
  - actionType
1532
1180
  - params
1533
1181
  - context
1534
- description: 动作执行请求（ActionExecuteRequest）
1182
+ description: 动作执行请求（ActionExecuteDto）
1535
1183
  properties:
1536
1184
  actionType:
1537
1185
  type: string
1538
- enum:
1539
- - claim
1540
- - signin
1541
- - lottery
1542
- - reserve
1543
- - bind
1544
- - task_complete
1545
- - vote
1546
- - share
1547
- - form_submit
1548
- - navigate
1549
- - setState
1550
- - showToast
1551
- - refreshData
1552
- - custom
1553
- description: 动作类型（ActionType | string）
1186
+ description: 动作类型
1187
+ example: claim
1554
1188
  actionDefinitionVersionId:
1555
1189
  type: string
1556
- description: 动作定义版本 ID（可选，不提供则使用最新稳定版，UniqueId）
1190
+ description: 动作定义版本 ID（不提供则使用最新稳定版）
1557
1191
  params:
1558
1192
  type: object
1193
+ description: 动作参数
1559
1194
  additionalProperties: true
1560
- description: 动作参数（Record<string, JsonValue>）
1561
- context:
1562
- $ref: '#/components/schemas/ActionClientContext'
1563
- description: 客户端上下文（ActionClientContext，必填）
1195
+ example:
1196
+ couponId: '12345'
1197
+ quantity: 1
1198
+ default: {}
1564
1199
  idempotencyKey:
1565
1200
  type: string
1566
- minLength: 16
1567
- maxLength: 128
1568
- description: 幂等键（部分策略需要客户端提供，防重复提交）
1569
- ActionEffect:
1570
- type: object
1571
- required:
1572
- - type
1573
- properties:
1574
- type:
1575
- type: string
1576
- enum:
1577
- - setState
1578
- - navigate
1579
- - showToast
1580
- - refreshData
1581
- - openDialog
1582
- - closeDialog
1583
- - custom
1584
- description: 副作用类型
1585
- payload:
1586
- type: object
1587
- additionalProperties: true
1588
- description: 副作用参数
1201
+ description: 幂等键
1202
+ context:
1203
+ description: 客户端上下文
1204
+ allOf:
1205
+ - $ref: '#/components/schemas/ActionClientContext'
1589
1206
  ExecuteActionResponse:
1590
- allOf:
1591
- - $ref: '#/components/schemas/SuccessResponse'
1592
- - type: object
1593
- properties:
1594
- data:
1595
- type: object
1596
- properties:
1597
- actionId:
1598
- type: string
1599
- description: 动作执行 ID（UniqueId，用于审计追溯）
1600
- result:
1601
- description: 执行结果（泛型 T）
1602
- effects:
1603
- type: array
1604
- items:
1605
- $ref: '#/components/schemas/ActionEffect'
1606
- description: 副作用列表
1607
- errorCode:
1608
- type: string
1609
- description: 错误码（失败时）
1610
- errorMessage:
1611
- type: string
1612
- description: 错误消息（失败时，用户可见）
1613
- errorDetails:
1614
- type: object
1615
- additionalProperties: true
1616
- description: 错误详情（失败时，调试用）
1617
- requestId:
1618
- type: string
1619
- description: 请求 ID
1620
- traceId:
1621
- type: string
1622
- description: 链路追踪 ID
1623
- duration:
1624
- type: integer
1625
- description: 执行耗时（毫秒）
1626
- retryable:
1627
- type: boolean
1628
- description: 是否可重试
1629
- retryAfter:
1630
- type: integer
1631
- description: 建议重试延迟（毫秒）
1632
- riskDecision:
1633
- type: object
1634
- description: 风控决策（可选，风控拒绝时返回）
1635
- properties:
1636
- allowed:
1637
- type: boolean
1638
- description: 是否放行
1639
- reason:
1640
- type: string
1641
- description: 拒绝原因（如 RISK_BLOCKED）
1642
- code:
1643
- type: string
1644
- description: 风控错误码
1645
- IdempotencyConflictResponse:
1646
1207
  type: object
1647
1208
  required:
1648
1209
  - success
1649
- - data
1210
+ - requestId
1211
+ - traceId
1212
+ - actionId
1213
+ - duration
1214
+ description: 动作执行响应（ActionExecuteVo）
1650
1215
  properties:
1651
1216
  success:
1652
1217
  type: boolean
1653
- example: true
1218
+ description: 是否成功
1654
1219
  data:
1655
1220
  type: object
1656
- properties:
1657
- idempotent:
1658
- type: boolean
1659
- example: true
1660
- originalActionId:
1661
- type: string
1662
- description: 原始动作执行 ID
1663
- originalResult:
1664
- description: 原始执行结果
1665
- originalExecutedAt:
1666
- type: string
1667
- format: date-time
1668
- description: 原始执行时间
1221
+ description: 业务数据
1222
+ additionalProperties: true
1223
+ example:
1224
+ couponId: '12345'
1225
+ claimedAt: '2024-01-01T00:00:00Z'
1226
+ errorCode:
1227
+ type: string
1228
+ description: 错误码
1229
+ errorMessage:
1230
+ type: string
1231
+ description: 错误信息（用户可见）
1232
+ errorDetails:
1233
+ type: object
1234
+ description: 错误详情（调试用）
1235
+ additionalProperties: true
1236
+ requestId:
1237
+ type: string
1238
+ description: 请求 ID
1239
+ traceId:
1240
+ type: string
1241
+ description: 链路追踪 ID
1242
+ actionId:
1243
+ type: string
1244
+ description: 动作 ID（用于审计追溯）
1245
+ duration:
1246
+ type: number
1247
+ description: 执行耗时（毫秒）
1248
+ retryable:
1249
+ type: boolean
1250
+ description: 是否可重试
1251
+ retryAfter:
1252
+ type: number
1253
+ description: 建议重试延迟（毫秒）
1669
1254
  ValidateActionRequest:
1670
1255
  type: object
1671
1256
  required:
1672
- - actionType
1257
+ - actionDefinitionVersionId
1673
1258
  - params
1259
+ description: 动作参数验证请求（ActionValidateDto）
1674
1260
  properties:
1675
- actionType:
1676
- type: string
1677
- description: 动作类型
1678
1261
  actionDefinitionVersionId:
1679
1262
  type: string
1680
1263
  description: 动作定义版本 ID
1681
1264
  params:
1682
1265
  type: object
1266
+ description: 待验证参数
1683
1267
  additionalProperties: true
1684
- description: 待验证的参数
1268
+ example:
1269
+ couponId: '12345'
1270
+ quantity: 1
1271
+ default: {}
1685
1272
  ValidateActionResponse:
1686
1273
  type: object
1687
1274
  required:
1688
- - data
1275
+ - valid
1276
+ description: 动作参数验证响应（ActionValidateVo）
1689
1277
  properties:
1690
- data:
1691
- type: object
1692
- required:
1693
- - valid
1694
- properties:
1695
- valid:
1696
- type: boolean
1697
- description: 是否有效
1698
- errors:
1699
- type: array
1700
- items:
1701
- type: object
1702
- properties:
1703
- path:
1704
- type: string
1705
- description: 参数路径
1706
- message:
1707
- type: string
1708
- description: 错误消息
1709
- code:
1710
- type: string
1711
- description: 错误码
1712
- description: 验证错误
1713
- ActionDefinitionResponse:
1278
+ valid:
1279
+ type: boolean
1280
+ description: 是否通过校验
1281
+ errors:
1282
+ description: 校验错误列表
1283
+ type: array
1284
+ items:
1285
+ type: string
1286
+ ActionDefinitionVersionResponse:
1714
1287
  type: object
1715
1288
  required:
1716
- - data
1289
+ - uid
1290
+ - definitionUid
1291
+ - versionNumber
1292
+ - spec
1293
+ - status
1294
+ - createdBy
1295
+ - createdByUsername
1296
+ - createdAt
1297
+ description: 动作定义版本响应（ActionDefinitionVersionVo）
1717
1298
  properties:
1718
- data:
1299
+ uid:
1300
+ type: string
1301
+ description: 版本 UID
1302
+ example: 202401efgh87654321
1303
+ definitionUid:
1304
+ type: string
1305
+ description: 所属定义 UID
1306
+ example: 202401abcd12345678
1307
+ versionNumber:
1308
+ type: number
1309
+ description: 版本号（递增）
1310
+ example: 1
1311
+ versionLabel:
1312
+ type: string
1313
+ nullable: true
1314
+ description: 版本标签（可选，如 v1.0.0）
1315
+ example: v1.0.0
1316
+ description:
1317
+ type: string
1318
+ nullable: true
1319
+ description: 版本描述
1320
+ spec:
1321
+ description: 规格快照（不可变的 ActionSpec）
1719
1322
  type: object
1720
- properties:
1721
- actionDefinitionVersionId:
1722
- type: string
1723
- actionType:
1724
- type: string
1725
- name:
1726
- type: string
1727
- paramsSchema:
1728
- type: object
1729
- description: 参数 JSON Schema
1730
- resultSchema:
1731
- type: object
1732
- description: 结果 JSON Schema
1323
+ additionalProperties: true
1324
+ status:
1325
+ type: string
1326
+ description: 版本状态
1327
+ enum:
1328
+ - draft
1329
+ - stable
1330
+ - deprecated
1331
+ - blocked
1332
+ example: stable
1333
+ createdBy:
1334
+ type: string
1335
+ description: 创建者 UID
1336
+ example: 202401user1234
1337
+ createdByUsername:
1338
+ type: string
1339
+ description: 创建者用户名
1340
+ example: admin
1341
+ createdAt:
1342
+ type: string
1343
+ format: date-time
1344
+ description: 创建时间
1733
1345
  QueryContext:
1734
1346
  type: object
1735
- description: 数据查询上下文（DataQueryRequest.context）
1347
+ description: 数据查询上下文（DataQueryContextDto）
1736
1348
  properties:
1349
+ uid:
1350
+ type: string
1351
+ description: 用户 UID
1737
1352
  pageVersionId:
1738
1353
  type: string
1739
- description: 页面版本 ID（UniqueId）
1354
+ description: 页面版本 ID
1740
1355
  componentVersionId:
1741
1356
  type: string
1742
- description: 组件版本 ID（UniqueId，可选）
1357
+ description: 组件版本 ID
1743
1358
  QueryDataRequest:
1744
1359
  type: object
1745
1360
  required:
1746
1361
  - queryVersionId
1747
- description: 数据查询请求（DataQueryRequest）
1362
+ description: 数据查询请求（DataQueryDto）
1748
1363
  properties:
1749
1364
  queryVersionId:
1750
1365
  type: string
1751
- description: 查询定义版本 ID（UniqueId）
1366
+ description: 查询版本 ID
1752
1367
  params:
1753
1368
  type: object
1369
+ description: 查询参数
1754
1370
  additionalProperties: true
1755
- description: 查询参数（Record<string, JsonValue>）
1756
- cacheControl:
1757
- type: object
1758
- description: 缓存策略覆盖
1759
- properties:
1760
- noCache:
1761
- type: boolean
1762
- description: 是否跳过缓存
1763
- forceRefresh:
1764
- type: boolean
1765
- description: 强制刷新缓存
1766
1371
  context:
1767
- $ref: '#/components/schemas/QueryContext'
1768
- description: 客户端上下文（可选）
1372
+ description: 上下文
1373
+ allOf:
1374
+ - $ref: '#/components/schemas/QueryContext'
1375
+ QueryMetadata:
1376
+ type: object
1377
+ description: 查询元数据（DataQueryMetadataVo）
1378
+ properties:
1379
+ fromCache:
1380
+ type: boolean
1381
+ description: 是否来自缓存
1382
+ duration:
1383
+ type: number
1384
+ description: 查询耗时（毫秒）
1769
1385
  QueryDataResponse:
1770
- allOf:
1771
- - $ref: '#/components/schemas/SuccessResponse'
1772
- - type: object
1773
- properties:
1774
- data:
1775
- description: 查询结果数据（泛型 T）
1776
- errorCode:
1777
- type: string
1778
- description: 错误码（失败时）
1779
- errorMessage:
1780
- type: string
1781
- description: 错误消息（失败时）
1782
- fromCache:
1783
- type: boolean
1784
- description: 是否来自缓存
1785
- cachedAt:
1786
- type: string
1787
- format: date-time
1788
- description: 缓存时间戳（ISODateTime）
1789
- age:
1790
- type: integer
1791
- description: 数据新鲜度（秒）
1792
- requestId:
1793
- type: string
1794
- description: 请求 ID
1795
- traceId:
1796
- type: string
1797
- description: 链路追踪 ID
1798
- duration:
1799
- type: integer
1800
- description: 查询耗时（毫秒）
1801
- degraded:
1802
- type: boolean
1803
- description: 是否为降级数据
1804
- degradedReason:
1805
- type: string
1806
- description: 降级原因
1386
+ type: object
1387
+ required:
1388
+ - success
1389
+ description: 数据查询响应（DataQueryVo）
1390
+ properties:
1391
+ success:
1392
+ type: boolean
1393
+ description: 是否成功
1394
+ data:
1395
+ type: object
1396
+ description: 数据
1397
+ additionalProperties: true
1398
+ errorCode:
1399
+ type: string
1400
+ description: 错误码
1401
+ errorMessage:
1402
+ type: string
1403
+ description: 错误消息
1404
+ metadata:
1405
+ description: 元数据
1406
+ allOf:
1407
+ - $ref: '#/components/schemas/QueryMetadata'
1408
+ BatchQueryItemRequest:
1409
+ type: object
1410
+ required:
1411
+ - queryVersionId
1412
+ description: 批量查询项（DataQueryBatchItemDto）
1413
+ properties:
1414
+ queryVersionId:
1415
+ type: string
1416
+ description: 查询版本 ID
1417
+ params:
1418
+ type: object
1419
+ description: 查询参数
1420
+ additionalProperties: true
1807
1421
  BatchQueryRequest:
1808
1422
  type: object
1809
1423
  required:
1810
1424
  - queries
1425
+ description: 批量查询请求（DataQueryBatchDto）
1811
1426
  properties:
1812
1427
  queries:
1428
+ description: 查询列表
1813
1429
  type: array
1814
1430
  items:
1815
- type: object
1816
- required:
1817
- - queryVersionId
1818
- properties:
1819
- queryVersionId:
1820
- type: string
1821
- params:
1822
- type: object
1823
- alias:
1824
- type: string
1825
- description: 查询别名（用于结果映射）
1826
- maxItems: 20
1827
- description: 查询列表（最多 20 个）
1828
- context:
1829
- $ref: '#/components/schemas/QueryContext'
1431
+ $ref: '#/components/schemas/BatchQueryItemRequest'
1830
1432
  BatchQueryResponse:
1831
1433
  type: object
1832
1434
  required:
1833
- - success
1834
- - data
1435
+ - results
1436
+ description: 批量查询响应（DataQueryBatchVo）
1835
1437
  properties:
1836
- success:
1837
- type: boolean
1838
- data:
1839
- type: object
1840
- additionalProperties:
1841
- type: object
1842
- properties:
1843
- success:
1844
- type: boolean
1845
- data:
1846
- description: 查询结果
1847
- error:
1848
- type: object
1849
- properties:
1850
- code:
1851
- type: string
1852
- message:
1853
- type: string
1854
- description: 按 alias 或 queryVersionId 索引的结果
1438
+ results:
1439
+ description: 各查询结果列表
1440
+ type: array
1441
+ items:
1442
+ $ref: '#/components/schemas/QueryDataResponse'
1855
1443
  QueryDefinitionResponse:
1856
1444
  type: object
1857
1445
  required:
1858
- - data
1446
+ - uid
1447
+ - queryUid
1448
+ - versionNumber
1449
+ - spec
1450
+ - status
1451
+ description: 查询定义响应（DataQueryDefinitionVo）
1859
1452
  properties:
1860
- data:
1453
+ uid:
1454
+ type: string
1455
+ description: 版本 UID
1456
+ example: 202401efgh87654321
1457
+ queryUid:
1458
+ type: string
1459
+ description: 所属查询 UID
1460
+ example: 202401abcd12345678
1461
+ versionNumber:
1462
+ type: number
1463
+ description: 版本号（递增）
1464
+ example: 1
1465
+ versionLabel:
1466
+ type: string
1467
+ nullable: true
1468
+ description: 版本标签（可选，如 v1.0.0）
1469
+ example: v1.0.0
1470
+ spec:
1471
+ description: 规格快照（不可变的 DataQuerySpec）
1861
1472
  type: object
1862
- properties:
1863
- queryVersionId:
1864
- type: string
1865
- name:
1866
- type: string
1867
- paramsSchema:
1868
- type: object
1869
- description: 参数 JSON Schema
1870
- resultSchema:
1871
- type: object
1872
- description: 结果 JSON Schema
1873
- cacheTtl:
1874
- type: integer
1875
- description: 缓存 TTL（秒）
1876
- PublicActivityInfo:
1473
+ additionalProperties: true
1474
+ status:
1475
+ type: string
1476
+ description: 版本状态
1477
+ enum:
1478
+ - draft
1479
+ - stable
1480
+ - deprecated
1481
+ - blocked
1482
+ example: stable
1483
+ ActivityInfoData:
1877
1484
  type: object
1878
1485
  required:
1879
- - id
1486
+ - activityId
1880
1487
  - name
1881
1488
  - type
1882
- - status
1489
+ - startAt
1490
+ - endAt
1491
+ description: 活动信息数据（ActivityInfoDataVo）
1883
1492
  properties:
1884
- id:
1493
+ activityId:
1885
1494
  type: string
1886
1495
  description: 活动 ID
1887
1496
  name:
@@ -1889,593 +1498,583 @@ components:
1889
1498
  description: 活动名称
1890
1499
  type:
1891
1500
  type: string
1892
- enum:
1893
- - claim
1894
- - signin
1895
- - lottery
1896
- - reserve
1897
- - task
1898
- - vote
1899
- - share
1900
- - bind
1901
- - custom
1902
1501
  description: 活动类型
1903
- status:
1904
- type: string
1905
- enum:
1906
- - active
1907
- - ended
1908
- description: 活动状态
1909
- description:
1910
- type: string
1911
- description: 活动描述
1912
- startTime:
1502
+ startAt:
1913
1503
  type: string
1914
- format: date-time
1915
1504
  description: 开始时间
1916
- endTime:
1917
- type: string
1918
1505
  format: date-time
1506
+ endAt:
1507
+ type: string
1919
1508
  description: 结束时间
1920
- rules:
1921
- type: object
1922
- additionalProperties: true
1923
- description: 活动规则（公开部分）
1924
- rewards:
1925
- type: array
1926
- items:
1927
- type: object
1928
- properties:
1929
- name:
1930
- type: string
1931
- description:
1932
- type: string
1933
- icon:
1934
- type: string
1935
- description: 奖励列表
1936
- UserActivityState:
1509
+ format: date-time
1510
+ ActivityInfoResponse:
1937
1511
  type: object
1938
1512
  required:
1939
- - activityId
1940
- - userId
1941
- - activityType
1942
- - canParticipate
1943
- - typeState
1944
- description: 用户活动状态（UserActivityState，根据 types/src/activity/index.ts）
1513
+ - success
1514
+ - data
1515
+ description: 活动信息响应（ActivityInfoVo）
1945
1516
  properties:
1946
- activityId:
1517
+ success:
1518
+ type: boolean
1519
+ description: 是否成功
1520
+ data:
1521
+ description: 活动数据
1522
+ allOf:
1523
+ - $ref: '#/components/schemas/ActivityInfoData'
1524
+ ActivityStatusResponse:
1525
+ type: object
1526
+ description: 活动状态响应
1527
+ properties:
1528
+ activityUid:
1947
1529
  type: string
1948
- description: 活动 ID（UniqueId）
1949
- userId:
1530
+ description: 活动 UID
1531
+ name:
1950
1532
  type: string
1951
- description: 用户 ID
1952
- activityType:
1533
+ description: 活动名称
1534
+ type:
1953
1535
  type: string
1536
+ description: 活动类型
1954
1537
  enum:
1955
1538
  - claim
1956
1539
  - signin
1957
- - lottery
1958
- - reserve
1959
- - task
1960
- - vote
1961
- - share
1962
- - bind
1963
- - custom
1964
- description: 活动类型（ActivityType）
1965
- canParticipate:
1540
+ isInProgress:
1966
1541
  type: boolean
1967
- description: 是否可参与
1968
- notParticipateReason:
1542
+ description: 是否进行中
1543
+ startAt:
1969
1544
  type: string
1970
- description: 不可参与原因
1971
- remainingCount:
1972
- type: integer
1973
- description: 剩余参与次数
1974
- typeState:
1975
- type: object
1976
- description: 类型特定状态（ClaimState | SigninState | LotteryState）
1977
- oneOf:
1978
- - type: object
1979
- required:
1980
- - type
1981
- - claimed
1982
- properties:
1983
- type:
1984
- type: string
1985
- enum:
1986
- - claim
1987
- claimed:
1988
- type: boolean
1989
- claimedAt:
1990
- type: string
1991
- format: date-time
1992
- claimedPrizeId:
1993
- type: string
1994
- availablePrizes:
1995
- type: array
1996
- items:
1997
- type: object
1998
- properties:
1999
- prizeId:
2000
- type: string
2001
- name:
2002
- type: string
2003
- stock:
2004
- type: integer
2005
- - type: object
2006
- required:
2007
- - type
2008
- - signedToday
2009
- - consecutiveDays
2010
- - totalDays
2011
- - cycleRecords
2012
- - makeupAvailable
2013
- properties:
2014
- type:
2015
- type: string
2016
- enum:
2017
- - signin
2018
- signedToday:
2019
- type: boolean
2020
- todaySignedAt:
2021
- type: string
2022
- format: date-time
2023
- consecutiveDays:
2024
- type: integer
2025
- totalDays:
2026
- type: integer
2027
- cycleRecords:
2028
- type: array
2029
- items:
2030
- type: object
2031
- properties:
2032
- dayKey:
2033
- type: string
2034
- signed:
2035
- type: boolean
2036
- isMakeup:
2037
- type: boolean
2038
- makeupAvailable:
2039
- type: integer
2040
- nextReward:
2041
- type: object
2042
- properties:
2043
- type:
2044
- type: string
2045
- enum:
2046
- - consecutive
2047
- - cumulative
2048
- daysNeeded:
2049
- type: integer
2050
- reward:
2051
- type: object
2052
- additionalProperties: true
2053
- - type: object
2054
- required:
2055
- - type
2056
- - freeDrawsRemaining
2057
- - todayDrawCount
2058
- - totalDrawCount
2059
- properties:
2060
- type:
2061
- type: string
2062
- enum:
2063
- - lottery
2064
- freeDrawsRemaining:
2065
- type: integer
2066
- todayDrawCount:
2067
- type: integer
2068
- totalDrawCount:
2069
- type: integer
2070
- pityProgress:
2071
- type: object
2072
- properties:
2073
- current:
2074
- type: integer
2075
- target:
2076
- type: integer
2077
- resources:
2078
- type: array
2079
- items:
2080
- type: object
2081
- properties:
2082
- type:
2083
- type: string
2084
- amount:
2085
- type: integer
2086
- SigninCalendar:
1545
+ description: 开始时间
1546
+ endAt:
1547
+ type: string
1548
+ description: 结束时间
1549
+ SigninCalendarData:
2087
1550
  type: object
2088
1551
  required:
2089
- - year
1552
+ - activityId
2090
1553
  - month
2091
- - records
1554
+ - signedDates
1555
+ - consecutiveDays
1556
+ - totalDays
1557
+ description: 签到日历数据（SigninCalendarDataVo）
2092
1558
  properties:
2093
- year:
2094
- type: integer
2095
- description: 年份
1559
+ activityId:
1560
+ type: string
1561
+ description: 活动 ID
2096
1562
  month:
2097
- type: integer
2098
- minimum: 1
2099
- maximum: 12
2100
- description: 月份
2101
- records:
1563
+ type: string
1564
+ description: 月份（YYYY-MM）
1565
+ example: 2024-01
1566
+ signedDates:
1567
+ description: 已签到日期列表
1568
+ example:
1569
+ - '2024-01-01'
1570
+ - '2024-01-02'
2102
1571
  type: array
2103
1572
  items:
2104
- type: object
2105
- properties:
2106
- day:
2107
- type: integer
2108
- minimum: 1
2109
- maximum: 31
2110
- signedIn:
2111
- type: boolean
2112
- reward:
2113
- type: object
2114
- properties:
2115
- name:
2116
- type: string
2117
- amount:
2118
- type: number
2119
- description: 签到记录
1573
+ type: string
2120
1574
  consecutiveDays:
2121
- type: integer
1575
+ type: number
2122
1576
  description: 连续签到天数
2123
1577
  totalDays:
2124
- type: integer
2125
- description: 本月签到总天数
2126
- ClaimRecordInfo:
1578
+ type: number
1579
+ description: 累计签到天数
1580
+ SigninCalendarResponse:
2127
1581
  type: object
2128
1582
  required:
2129
- - id
2130
- - rewardType
2131
- - status
2132
- - createdAt
1583
+ - success
1584
+ - data
1585
+ description: 签到日历响应（SigninCalendarVo）
2133
1586
  properties:
2134
- id:
2135
- type: string
2136
- description: 记录 ID
2137
- activityId:
2138
- type: string
2139
- description: 活动 ID
2140
- rewardType:
2141
- type: string
2142
- description: 奖励类型
2143
- rewardName:
2144
- type: string
2145
- description: 奖励名称
2146
- rewardValue:
1587
+ success:
1588
+ type: boolean
1589
+ description: 是否成功
1590
+ data:
1591
+ description: 日历数据
1592
+ allOf:
1593
+ - $ref: '#/components/schemas/SigninCalendarData'
1594
+ CursorPaginationMeta:
1595
+ type: object
1596
+ description: 游标分页元数据（PageRecordsMetaVo）
1597
+ properties:
1598
+ pageSize:
2147
1599
  type: number
2148
- description: 奖励值
2149
- status:
1600
+ description: 每页条数
1601
+ pageToken:
2150
1602
  type: string
2151
- enum:
2152
- - pending
2153
- - claimed
2154
- - expired
2155
- description: 领取状态
2156
- createdAt:
2157
- type: string
2158
- format: date-time
2159
- description: 创建时间
2160
- claimedAt:
2161
- type: string
2162
- format: date-time
2163
- description: 领取时间
2164
- expiresAt:
2165
- type: string
2166
- format: date-time
2167
- description: 过期时间
2168
- PaginationMeta:
1603
+ description: 下一页游标
1604
+ PaginatedRecordsResponse:
2169
1605
  type: object
2170
1606
  required:
2171
- - page
2172
- - pageSize
2173
- - total
2174
- - totalPages
2175
- - hasNext
2176
- - hasPrev
2177
- description: 分页元数据（PaginationMeta）
1607
+ - success
1608
+ - data
1609
+ description: 分页记录响应（PaginatedRecordsVo）
2178
1610
  properties:
2179
- page:
2180
- type: integer
2181
- minimum: 1
2182
- description: 当前页码
2183
- pageSize:
2184
- type: integer
2185
- minimum: 1
2186
- maximum: 100
2187
- description: 每页数量
2188
- total:
2189
- type: integer
2190
- minimum: 0
2191
- description: 总记录数
2192
- totalPages:
2193
- type: integer
2194
- minimum: 0
2195
- description: 总页数
2196
- hasNext:
2197
- type: boolean
2198
- description: 是否有下一页
2199
- hasPrev:
1611
+ success:
2200
1612
  type: boolean
2201
- description: 是否有上一页
2202
- LotteryRecordInfo:
1613
+ description: 是否成功
1614
+ data:
1615
+ type: array
1616
+ description: 记录列表
1617
+ items:
1618
+ type: object
1619
+ meta:
1620
+ description: 分页元数据
1621
+ allOf:
1622
+ - $ref: '#/components/schemas/CursorPaginationMeta'
1623
+ ClaimStatusResponse:
2203
1624
  type: object
2204
1625
  required:
2205
- - id
2206
- - prizeId
2207
- - status
2208
- - createdAt
1626
+ - activityUid
1627
+ - hasClaimed
1628
+ - remainingCount
1629
+ - totalCount
1630
+ description: 领取状态响应（ClaimStatusVo）
2209
1631
  properties:
2210
- id:
2211
- type: string
2212
- description: 记录 ID
2213
- activityId:
2214
- type: string
2215
- description: 活动 ID
2216
- prizeId:
2217
- type: string
2218
- description: 奖品 ID
2219
- prizeName:
2220
- type: string
2221
- description: 奖品名称
2222
- prizeType:
2223
- type: string
2224
- enum:
2225
- - physical
2226
- - virtual
2227
- - coupon
2228
- - points
2229
- - none
2230
- description: 奖品类型
2231
- status:
2232
- type: string
2233
- enum:
2234
- - won
2235
- - notWon
2236
- - claimed
2237
- - shipped
2238
- description: 状态
2239
- createdAt:
1632
+ activityUid:
2240
1633
  type: string
2241
- format: date-time
2242
- description: 抽奖时间
1634
+ description: 活动 UID
1635
+ hasClaimed:
1636
+ type: boolean
1637
+ description: 是否已领取
2243
1638
  claimedAt:
2244
1639
  type: string
2245
- format: date-time
2246
1640
  description: 领取时间
2247
- ActivityStatus:
1641
+ remainingCount:
1642
+ type: number
1643
+ description: 剩余领取次数
1644
+ totalCount:
1645
+ type: number
1646
+ description: 总领取次数
1647
+ RewardInfo:
2248
1648
  type: object
2249
1649
  required:
2250
- - activityUid
2251
- - name
2252
1650
  - type
2253
- - isInProgress
2254
- - startAt
2255
- - endAt
2256
- description: 活动状态信息（与 docs ActivityStatusVo 对齐）
1651
+ - value
1652
+ - description
1653
+ description: 奖励信息（RewardInfoVo）
2257
1654
  properties:
2258
- activityUid:
2259
- type: string
2260
- description: 活动 UID
2261
- name:
2262
- type: string
2263
- description: 活动名称
2264
1655
  type:
2265
1656
  type: string
2266
- description: 活动类型
2267
- enum:
2268
- - claim
2269
- - signin
2270
- isInProgress:
2271
- type: boolean
2272
- description: 是否进行中
2273
- startAt:
1657
+ description: 奖励类型
1658
+ value:
1659
+ type: number
1660
+ description: 奖励值
1661
+ description:
2274
1662
  type: string
2275
- format: date-time
2276
- description: 开始时间（ISODateTime）
2277
- endAt:
1663
+ description: 奖励描述
1664
+ MilestoneInfo:
1665
+ type: object
1666
+ required:
1667
+ - days
1668
+ - reward
1669
+ description: 里程碑信息（MilestoneInfoVo）
1670
+ properties:
1671
+ days:
1672
+ type: number
1673
+ description: 目标天数
1674
+ reward:
1675
+ description: 里程碑奖励
1676
+ allOf:
1677
+ - $ref: '#/components/schemas/RewardInfo'
1678
+ SigninStatusResponse:
1679
+ type: object
1680
+ required:
1681
+ - activityUid
1682
+ - hasSignedToday
1683
+ - consecutiveDays
1684
+ - totalDays
1685
+ - signedDates
1686
+ description: 签到状态响应（SigninStatusVo）
1687
+ properties:
1688
+ activityUid:
2278
1689
  type: string
2279
- format: date-time
2280
- description: 结束时间（ISODateTime）
2281
- TrackRequest:
1690
+ description: 活动 UID
1691
+ hasSignedToday:
1692
+ type: boolean
1693
+ description: 今日是否已签到
1694
+ consecutiveDays:
1695
+ type: number
1696
+ description: 连续签到天数
1697
+ totalDays:
1698
+ type: number
1699
+ description: 累计签到天数
1700
+ signedDates:
1701
+ description: 签到日期列表
1702
+ type: array
1703
+ items:
1704
+ type: string
1705
+ todayReward:
1706
+ description: 今日奖励
1707
+ allOf:
1708
+ - $ref: '#/components/schemas/RewardInfo'
1709
+ nextMilestone:
1710
+ description: 下一个里程碑
1711
+ allOf:
1712
+ - $ref: '#/components/schemas/MilestoneInfo'
1713
+ TrackEvent:
2282
1714
  type: object
2283
1715
  required:
1716
+ - eventType
2284
1717
  - eventName
1718
+ description: 埋点事件（TrackEventDto）
2285
1719
  properties:
2286
- eventName:
2287
- type: string
2288
- minLength: 1
2289
- maxLength: 255
2290
- description: 事件名称
2291
1720
  eventType:
2292
1721
  type: string
2293
- enum:
2294
- - page_view
2295
- - click
2296
- - exposure
2297
- - custom
2298
- default: custom
2299
1722
  description: 事件类型
1723
+ eventName:
1724
+ type: string
1725
+ description: 事件名称
2300
1726
  properties:
2301
1727
  type: object
2302
- additionalProperties: true
2303
1728
  description: 事件属性
2304
1729
  timestamp:
1730
+ type: number
1731
+ description: 事件时间戳（毫秒）
1732
+ TrackContext:
1733
+ type: object
1734
+ description: 埋点上下文（TrackContextDto）
1735
+ properties:
1736
+ uid:
2305
1737
  type: string
2306
- format: date-time
2307
- description: 事件时间（默认为服务器接收时间）
1738
+ description: 用户 UID
1739
+ pageVersionId:
1740
+ type: string
1741
+ description: 页面版本 ID
1742
+ componentVersionId:
1743
+ type: string
1744
+ description: 组件版本 ID
1745
+ deviceId:
1746
+ type: string
1747
+ description: 设备 ID
1748
+ sessionId:
1749
+ type: string
1750
+ description: 会话 ID
1751
+ appId:
1752
+ type: string
1753
+ description: 应用 ID
1754
+ TrackSingleRequest:
1755
+ type: object
1756
+ required:
1757
+ - event
1758
+ description: 单个埋点请求（TrackSingleDto）
1759
+ properties:
1760
+ event:
1761
+ description: 事件
1762
+ allOf:
1763
+ - $ref: '#/components/schemas/TrackEvent'
2308
1764
  context:
1765
+ description: 上下文
1766
+ allOf:
1767
+ - $ref: '#/components/schemas/TrackContext'
1768
+ TrackSingleResponse:
1769
+ type: object
1770
+ required:
1771
+ - success
1772
+ - data
1773
+ description: 单个埋点响应（TrackSingleResponseVo）
1774
+ properties:
1775
+ success:
1776
+ type: boolean
1777
+ description: 是否成功
1778
+ data:
2309
1779
  type: object
1780
+ required:
1781
+ - eventId
2310
1782
  properties:
2311
- pageVersionId:
2312
- type: string
2313
- componentVersionId:
2314
- type: string
2315
- sessionId:
2316
- type: string
2317
- deviceType:
2318
- type: string
2319
- traceId:
1783
+ eventId:
2320
1784
  type: string
2321
- description: 上下文信息
1785
+ description: 事件 ID
2322
1786
  TrackBatchRequest:
2323
1787
  type: object
2324
1788
  required:
2325
1789
  - events
1790
+ description: 批量埋点请求（TrackBatchDto）
2326
1791
  properties:
2327
1792
  events:
1793
+ description: 事件列表
2328
1794
  type: array
2329
1795
  items:
2330
- $ref: '#/components/schemas/TrackRequest'
2331
- maxItems: 100
2332
- description: 事件列表（最多 100 个）
2333
- TenantInfo:
1796
+ $ref: '#/components/schemas/TrackEvent'
1797
+ context:
1798
+ description: 上下文
1799
+ allOf:
1800
+ - $ref: '#/components/schemas/TrackContext'
1801
+ TrackBatchError:
1802
+ type: object
1803
+ required:
1804
+ - index
1805
+ - reason
1806
+ description: 批量埋点错误（TrackBatchErrorVo）
1807
+ properties:
1808
+ index:
1809
+ type: number
1810
+ description: 错误索引
1811
+ reason:
1812
+ type: string
1813
+ description: 错误原因
1814
+ TrackBatchResponse:
1815
+ type: object
1816
+ required:
1817
+ - success
1818
+ - data
1819
+ description: 批量埋点响应（TrackBatchResponseVo）
1820
+ properties:
1821
+ success:
1822
+ type: boolean
1823
+ description: 是否成功
1824
+ data:
1825
+ type: object
1826
+ required:
1827
+ - accepted
1828
+ - rejected
1829
+ - errors
1830
+ properties:
1831
+ accepted:
1832
+ type: number
1833
+ description: 接受的事件数量
1834
+ rejected:
1835
+ type: number
1836
+ description: 拒绝的事件数量
1837
+ errors:
1838
+ description: 错误列表
1839
+ type: array
1840
+ items:
1841
+ $ref: '#/components/schemas/TrackBatchError'
1842
+ ResolveTenantRequest:
1843
+ type: object
1844
+ description: 租户解析请求（TenantResolveDto）
1845
+ properties:
1846
+ appKey:
1847
+ type: string
1848
+ description: 应用 Key
1849
+ host:
1850
+ type: string
1851
+ description: 主机/域名
1852
+ channel:
1853
+ type: string
1854
+ description: 渠道
1855
+ ResolveTenantData:
2334
1856
  type: object
2335
1857
  required:
2336
1858
  - appId
2337
- - appName
1859
+ - name
2338
1860
  - status
1861
+ - type
1862
+ description: 租户解析数据（TenantResolveDataVo）
2339
1863
  properties:
2340
1864
  appId:
2341
1865
  type: string
2342
1866
  description: 应用 ID
2343
- appName:
1867
+ name:
2344
1868
  type: string
2345
- description: 应用名称
1869
+ description: 租户名称
2346
1870
  status:
2347
1871
  type: string
2348
- enum:
2349
- - active
2350
- - suspended
2351
- - disabled
2352
- description: 应用状态
2353
- workspaceId:
2354
- type: string
2355
- description: 工作空间 ID
2356
- cdnDomain:
2357
- type: string
2358
- format: uri
2359
- description: CDN 域名
2360
- apiDomain:
2361
- type: string
2362
- format: uri
2363
- description: API 域名
2364
- TenantConfig:
1872
+ description: 租户状态
1873
+ example: active
1874
+ type:
1875
+ type: string
1876
+ description: 租户类型
1877
+ example: standard
1878
+ logo:
1879
+ type: string
1880
+ description: 租户 Logo URL
1881
+ config:
1882
+ type: object
1883
+ description: 租户配置
1884
+ additionalProperties: true
1885
+ channel:
1886
+ type: string
1887
+ description: 渠道
1888
+ domain:
1889
+ type: string
1890
+ description: 自定义域名
1891
+ ResolveTenantResponse:
2365
1892
  type: object
1893
+ required:
1894
+ - success
1895
+ - data
1896
+ description: 租户解析响应（TenantResolveVo）
2366
1897
  properties:
2367
- features:
1898
+ success:
1899
+ type: boolean
1900
+ description: 是否成功
1901
+ data:
1902
+ description: 租户数据
1903
+ allOf:
1904
+ - $ref: '#/components/schemas/ResolveTenantData'
1905
+ TenantConfigData:
1906
+ type: object
1907
+ required:
1908
+ - appId
1909
+ - status
1910
+ description: 租户配置数据（TenantConfigDataVo）
1911
+ properties:
1912
+ appId:
1913
+ type: string
1914
+ description: 应用 ID
1915
+ status:
1916
+ type: string
1917
+ description: 租户状态
1918
+ example: active
1919
+ featureFlags:
2368
1920
  type: object
1921
+ description: 功能开关
2369
1922
  additionalProperties:
2370
1923
  type: boolean
2371
- description: 功能开关
2372
1924
  theme:
2373
1925
  type: object
2374
- additionalProperties: true
2375
1926
  description: 主题配置
2376
- cdnDomain:
2377
- type: string
2378
- format: uri
2379
- description: CDN 域名
2380
- runtimeVersion:
1927
+ additionalProperties: true
1928
+ cdnBase:
2381
1929
  type: string
2382
- description: 推荐的 Runtime 版本
1930
+ description: CDN 基地址
2383
1931
  blockedComponents:
1932
+ description: 阻断组件列表
2384
1933
  type: array
2385
1934
  items:
2386
- type: object
2387
- properties:
2388
- componentType:
2389
- type: string
2390
- version:
2391
- type: string
2392
- reason:
2393
- type: string
2394
- description: 阻断的组件列表
1935
+ type: string
2395
1936
  killSwitch:
2396
- type: object
2397
- properties:
2398
- enabled:
2399
- type: boolean
2400
- pageIds:
2401
- type: array
2402
- items:
2403
- type: string
2404
- description: 被 Kill 的页面 ID 列表
2405
- fallbackUrl:
2406
- type: string
2407
- format: uri
2408
- description: Kill Switch 配置
2409
- HealthResponse:
1937
+ type: boolean
1938
+ description: 全局 killSwitch
1939
+ TenantConfigResponse:
1940
+ type: object
1941
+ required:
1942
+ - success
1943
+ - data
1944
+ description: 租户配置响应（TenantConfigVo）
1945
+ properties:
1946
+ success:
1947
+ type: boolean
1948
+ description: 是否成功
1949
+ data:
1950
+ description: 配置数据
1951
+ allOf:
1952
+ - $ref: '#/components/schemas/TenantConfigData'
1953
+ HealthCheckResponse:
2410
1954
  type: object
2411
1955
  required:
2412
1956
  - status
2413
- - version
1957
+ - timestamp
1958
+ description: 健康检查响应（HealthCheckVo）
2414
1959
  properties:
2415
1960
  status:
2416
1961
  type: string
2417
- enum:
2418
- - healthy
2419
- - degraded
2420
- - unhealthy
2421
1962
  description: 服务状态
2422
- version:
2423
- type: string
2424
- description: 服务版本
2425
- uptime:
2426
- type: integer
2427
- description: 运行时间（秒）
1963
+ example: healthy
2428
1964
  timestamp:
2429
1965
  type: string
2430
- format: date-time
2431
- description: 检查时间
2432
- dependencies:
1966
+ description: 响应时间戳
1967
+ example: '2026-02-04T12:00:00.000Z'
1968
+ LivenessResponse:
1969
+ type: object
1970
+ required:
1971
+ - status
1972
+ description: 存活检查响应（LivenessVo）
1973
+ properties:
1974
+ status:
1975
+ type: string
1976
+ description: 服务状态
1977
+ example: alive
1978
+ HealthCheckItem:
1979
+ type: object
1980
+ description: 健康检查项
1981
+ properties:
1982
+ status:
1983
+ type: string
1984
+ description: 检查状态
1985
+ message:
1986
+ type: string
1987
+ description: 检查消息
1988
+ ReadinessResponse:
1989
+ type: object
1990
+ required:
1991
+ - status
1992
+ - checks
1993
+ description: 就绪检查响应（ReadinessVo）
1994
+ properties:
1995
+ status:
1996
+ type: string
1997
+ description: 服务状态
1998
+ example: ready
1999
+ checks:
2433
2000
  type: object
2001
+ description: 各检查项状态
2434
2002
  additionalProperties:
2435
- type: object
2436
- properties:
2437
- status:
2438
- type: string
2439
- enum:
2440
- - healthy
2441
- - degraded
2442
- - unhealthy
2443
- latency:
2444
- type: integer
2445
- description: 延迟（毫秒）
2446
- message:
2447
- type: string
2448
- description: 依赖服务状态
2449
- PageResponse:
2450
- allOf:
2451
- - $ref: '#/components/schemas/SuccessResponse'
2452
- - type: object
2453
- properties:
2454
- data:
2455
- type: object
2456
- required:
2457
- - pageId
2458
- - version
2459
- - meta
2460
- properties:
2461
- pageId:
2462
- type: string
2463
- description: 页面 ID
2464
- version:
2465
- type: string
2466
- description: 页面版本
2467
- meta:
2468
- type: object
2469
- properties:
2470
- title:
2471
- type: string
2472
- description: 页面标题
2473
- description:
2474
- type: string
2475
- description: 页面描述
2476
- integrity:
2477
- type: string
2478
- description: 完整性哈希
2003
+ $ref: '#/components/schemas/HealthCheckItem'
2004
+ example:
2005
+ database:
2006
+ status: healthy
2007
+ message: Connection OK
2008
+ redis:
2009
+ status: healthy
2010
+ message: Connection OK
2011
+ PaginationMeta:
2012
+ type: object
2013
+ required:
2014
+ - page
2015
+ - pageSize
2016
+ - total
2017
+ - totalPages
2018
+ - hasNext
2019
+ - hasPrevious
2020
+ description: 分页元数据（PageMetaVo）
2021
+ properties:
2022
+ page:
2023
+ type: number
2024
+ description: 当前页码
2025
+ example: 1
2026
+ pageSize:
2027
+ type: number
2028
+ description: 每页条数
2029
+ example: 10
2030
+ total:
2031
+ type: number
2032
+ description: 总条数
2033
+ example: 100
2034
+ totalPages:
2035
+ type: number
2036
+ description: 总页数
2037
+ example: 10
2038
+ hasNext:
2039
+ type: boolean
2040
+ description: 是否有下一页
2041
+ example: true
2042
+ hasPrevious:
2043
+ type: boolean
2044
+ description: 是否有上一页
2045
+ example: false
2046
+ ActivityStatus:
2047
+ type: object
2048
+ required:
2049
+ - activityUid
2050
+ - name
2051
+ - type
2052
+ - isInProgress
2053
+ - startAt
2054
+ - endAt
2055
+ description: 活动状态（ActivityStatusVo）
2056
+ properties:
2057
+ activityUid:
2058
+ type: string
2059
+ description: 活动 UID
2060
+ name:
2061
+ type: string
2062
+ description: 活动名称
2063
+ type:
2064
+ type: string
2065
+ description: 活动类型
2066
+ enum:
2067
+ - claim
2068
+ - signin
2069
+ isInProgress:
2070
+ type: boolean
2071
+ description: 是否进行中
2072
+ startAt:
2073
+ type: string
2074
+ description: 开始时间
2075
+ endAt:
2076
+ type: string
2077
+ description: 结束时间
2479
2078
  responses:
2480
2079
  BadRequest:
2481
2080
  description: 请求参数错误
@@ -2533,59 +2132,59 @@ components:
2533
2132
  timestamp: 1702300000000
2534
2133
  path: /api/user/pages/resolve
2535
2134
  requestId: uuid-string
2536
- Forbidden:
2537
- description: 无权限
2135
+ TooManyRequests:
2136
+ description: 请求过于频繁
2538
2137
  content:
2539
2138
  application/json:
2540
2139
  schema:
2541
2140
  $ref: '#/components/schemas/ErrorResponse'
2542
2141
  example:
2543
2142
  success: false
2544
- code: PERMISSION_DENIED
2545
- message: 无访问权限
2143
+ code: RISK_RATE_LIMITED
2144
+ message: 请求过于频繁，请稍后再试
2546
2145
  timestamp: 1702300000000
2547
- path: /api/user/pages/resolve
2146
+ path: /api/user/actions/execute
2548
2147
  requestId: uuid-string
2549
- UnprocessableEntity:
2550
- description: 请求无法处理
2148
+ InternalError:
2149
+ description: 服务器内部错误
2551
2150
  content:
2552
2151
  application/json:
2553
2152
  schema:
2554
2153
  $ref: '#/components/schemas/ErrorResponse'
2555
2154
  example:
2556
2155
  success: false
2557
- code: BUSINESS_ACTIVITY_NOT_STARTED
2558
- message: 参数验证失败
2156
+ code: SYSTEM_INTERNAL_ERROR
2157
+ message: 服务器内部错误
2559
2158
  timestamp: 1702300000000
2560
- path: /api/user/actions/execute
2159
+ path: /api/user/pages/resolve
2561
2160
  requestId: uuid-string
2562
- TooManyRequests:
2563
- description: 请求过于频繁
2161
+ traceId: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
2162
+ Forbidden:
2163
+ description: 无权限
2564
2164
  content:
2565
2165
  application/json:
2566
2166
  schema:
2567
2167
  $ref: '#/components/schemas/ErrorResponse'
2568
2168
  example:
2569
2169
  success: false
2570
- code: RISK_RATE_LIMITED
2571
- message: 请求过于频繁，请稍后再试
2170
+ code: PERMISSION_DENIED
2171
+ message: 无访问权限
2572
2172
  timestamp: 1702300000000
2573
- path: /api/user/actions/execute
2173
+ path: /api/user/pages/resolve
2574
2174
  requestId: uuid-string
2575
- InternalError:
2576
- description: 服务器内部错误
2175
+ UnprocessableEntity:
2176
+ description: 请求无法处理
2577
2177
  content:
2578
2178
  application/json:
2579
2179
  schema:
2580
2180
  $ref: '#/components/schemas/ErrorResponse'
2581
2181
  example:
2582
2182
  success: false
2583
- code: SYSTEM_INTERNAL_ERROR
2584
- message: 服务器内部错误
2183
+ code: BUSINESS_ACTIVITY_NOT_STARTED
2184
+ message: 参数验证失败
2585
2185
  timestamp: 1702300000000
2586
- path: /api/user/pages/resolve
2186
+ path: /api/user/actions/execute
2587
2187
  requestId: uuid-string
2588
- traceId: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
2589
2188
  GatewayTimeout:
2590
2189
  description: 网关超时
2591
2190
  content:
@@ -2604,7 +2203,7 @@ components:
2604
2203
  type: http
2605
2204
  scheme: bearer
2606
2205
  bearerFormat: JWT
2607
- description: JWT 认证令牌（可选）
2206
+ description: 请输入 JWT 访问令牌
2608
2207
  ApiKey:
2609
2208
  type: apiKey
2610
2209
  in: header