@djvlc/openapi-user-client 1.8.0 → 1.8.1

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