@kne/fastify-task 3.0.0-alpha.9 → 3.0.0

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.
@@ -1,4 +1,23 @@
1
1
  const fp = require('fastify-plugin');
2
+ const { any, success, empty, TASK_STATUS, RUNNER_TYPE, task, taskList } = require('../schema/response');
3
+
4
+ const TAG = '任务-任务管理';
5
+ const CALLBACK_TAG = '任务-外部回调';
6
+ const SIGNATURE_HINT = '任务 context.secret 存在时校验 HMAC-SHA256 签名(密钥为 secret,内容为 `${id}|${JSON 数据}`),不通过报错;未设置 secret 时不校验';
7
+ const timeRange = name => ({
8
+ type: 'object',
9
+ properties: {
10
+ startTime: {
11
+ type: 'string',
12
+ description: `${name}起始时间(含),可被 Date 解析的时间字符串`
13
+ },
14
+ endTime: {
15
+ type: 'string',
16
+ description: `${name}结束时间(含),可被 Date 解析的时间字符串`
17
+ }
18
+ },
19
+ description: `${name}区间查找`
20
+ });
2
21
 
3
22
  module.exports = fp(async (fastify, options) => {
4
23
  const { services } = fastify[options.name];
@@ -8,7 +27,9 @@ module.exports = fp(async (fastify, options) => {
8
27
  {
9
28
  onRequest: options.getAuthenticate('write'),
10
29
  schema: {
30
+ tags: [TAG],
11
31
  summary: '创建任务',
32
+ description: '创建一条 pending 状态的任务,到达开始时间后由定时器按优先级调度执行(system)或等待人工完成(manual);type 必须是已注册的任务类型,返回新任务 ID',
12
33
  body: {
13
34
  type: 'object',
14
35
  properties: {
@@ -24,6 +45,12 @@ module.exports = fp(async (fastify, options) => {
24
45
  type: 'string',
25
46
  description: '目标对象类型'
26
47
  },
48
+ context: {
49
+ description: '执行上下文,任务执行时可读取;其中 secret 用于外部回调签名校验'
50
+ },
51
+ options: {
52
+ description: '任务扩展选项'
53
+ },
27
54
  input: {
28
55
  type: 'object',
29
56
  description: '输入数据'
@@ -31,15 +58,15 @@ module.exports = fp(async (fastify, options) => {
31
58
  runnerType: {
32
59
  type: 'string',
33
60
  enum: ['manual', 'system'],
34
- description: '执行者类型'
61
+ description: `执行者类型,${RUNNER_TYPE},默认 manual`
35
62
  },
36
63
  delay: {
37
64
  type: 'number',
38
- description: '延迟执行秒数'
65
+ description: '延迟执行秒数,必须为非负数,默认 0 立即可执行'
39
66
  },
40
67
  scriptName: {
41
68
  type: 'string',
42
- description: '任务脚本名称'
69
+ description: '任务脚本名称(不含 .js),只能包含字母、数字、下划线或中划线;不传使用任务类型声明的脚本,默认 index'
43
70
  },
44
71
  priority: {
45
72
  type: 'number',
@@ -59,7 +86,12 @@ module.exports = fp(async (fastify, options) => {
59
86
  }
60
87
  },
61
88
  required: ['type', 'targetId', 'targetType']
62
- }
89
+ },
90
+ response: success('创建成功', {
91
+ type: 'object',
92
+ additionalProperties: true,
93
+ properties: { id: any('新任务 ID') }
94
+ })
63
95
  }
64
96
  },
65
97
  async request => {
@@ -73,68 +105,62 @@ module.exports = fp(async (fastify, options) => {
73
105
  {
74
106
  onRequest: options.getAuthenticate('read'),
75
107
  schema: {
108
+ tags: [TAG],
76
109
  summary: '获取任务列表',
110
+ description: '分页查询任务,默认按创建时间倒序;filter / sort 也支持 filter[key]=value 形式的扁平 query 参数',
77
111
  query: {
78
112
  type: 'object',
79
113
  properties: {
80
114
  perPage: {
81
115
  type: 'number',
82
- default: 20
116
+ default: 20,
117
+ description: '每页条数'
83
118
  },
84
119
  currentPage: {
85
120
  type: 'number',
86
- default: 1
121
+ default: 1,
122
+ description: '页码,从 1 开始'
87
123
  },
88
124
  filter: {
89
125
  type: 'object',
126
+ description: '筛选条件',
90
127
  properties: {
91
128
  id: {
92
- type: 'string'
129
+ type: 'string',
130
+ description: '任务ID'
93
131
  },
94
132
  targetId: {
95
- type: 'string'
133
+ type: 'string',
134
+ description: '目标对象ID'
135
+ },
136
+ targetName: {
137
+ type: 'string',
138
+ description: '目标对象名称,对应任务 input.name'
96
139
  },
97
140
  type: {
98
- type: 'string'
141
+ type: 'string',
142
+ description: '任务类型'
99
143
  },
100
144
  status: {
101
- type: 'string'
145
+ type: 'string',
146
+ description: TASK_STATUS
102
147
  },
103
148
  runnerType: {
104
- type: 'string'
149
+ type: 'string',
150
+ description: RUNNER_TYPE
105
151
  },
106
- createdAt: {
107
- type: 'object',
108
- properties: {
109
- startTime: {
110
- type: 'string'
111
- },
112
- endTime: {
113
- type: 'string'
114
- }
115
- },
116
- description: 'createdAt区间查找'
117
- },
118
- completedAt: {
119
- type: 'object',
120
- properties: {
121
- startTime: {
122
- type: 'string'
123
- },
124
- endTime: {
125
- type: 'string'
126
- }
127
- },
128
- description: 'completedAt区间查找'
129
- }
152
+ createdAt: timeRange('createdAt'),
153
+ completedAt: timeRange('completedAt')
130
154
  }
131
155
  },
132
156
  sort: {
133
157
  type: 'object',
134
- description: '按completedAt、updatedAt字段排序,ASC为升序,DESC为降序'
158
+ description:
159
+ "排序,键为字段名、值为 ASC 升序 / DESC 降序,如 { completedAt: 'DESC' };可排序字段:id、targetId、targetType、type、status、runnerType、priority、createdAt、updatedAt、startTime、startedAt、completedAt,其他字段报错"
135
160
  }
136
161
  }
137
- }
162
+ },
163
+ response: success('任务分页结果', taskList)
138
164
  }
139
165
  },
140
166
  async request => {
@@ -147,33 +173,43 @@ module.exports = fp(async (fastify, options) => {
147
173
  {
148
174
  onRequest: options.getAuthenticate('write'),
149
175
  schema: {
176
+ tags: [TAG],
150
177
  summary: '手动完成任务',
178
+ description: '人工把任务标记为成功或失败并记录完成人;成功时执行任务类型的完成回调,回调出错则转为失败;只有未结束的任务会被更新;只接受下列声明的字段,其它字段(如 context、userId)会被忽略',
151
179
  body: {
152
180
  type: 'object',
153
181
  properties: {
154
182
  id: {
155
- type: 'string'
183
+ type: 'string',
184
+ description: '任务ID'
156
185
  },
157
186
  status: {
158
187
  type: 'string',
159
- enum: ['success', 'failed']
188
+ enum: ['success', 'failed'],
189
+ description: '完成结果:success 成功,failed 失败'
160
190
  },
161
191
  error: {
162
- type: 'string'
192
+ type: 'string',
193
+ description: '失败原因,status 为 failed 时记录,不传记为「任务失败」'
163
194
  },
164
195
  msg: {
165
- type: 'string'
196
+ type: 'string',
197
+ description: '任务消息,status 为 failed 时写入任务'
166
198
  },
167
199
  output: {
168
- type: 'object'
200
+ type: 'object',
201
+ description: '任务输出数据'
169
202
  }
170
203
  },
171
204
  required: ['id', 'status']
172
- }
205
+ },
206
+ response: empty('操作成功,返回空对象')
173
207
  }
174
208
  },
175
209
  async request => {
176
- await services.complete(Object.assign({}, request.body, { userId: request.userInfo?.id }));
210
+ // 只透传 schema 声明的字段,避免客户端借失败分支覆盖 context.secret 等任意列
211
+ const { id, status, error, msg, output } = request.body;
212
+ await services.complete({ id, status, error, msg, output, userId: request.userInfo?.id });
177
213
  return {};
178
214
  }
179
215
  );
@@ -183,7 +219,9 @@ module.exports = fp(async (fastify, options) => {
183
219
  {
184
220
  onRequest: options.getAuthenticate('write'),
185
221
  schema: {
222
+ tags: [TAG],
186
223
  summary: '取消任务',
224
+ description: '把 pending / running 状态的任务置为 canceled:传 id 取消单个任务;同时传 targetId、targetType、type 时批量取消该目标下该类型的任务(优先于 id);两种都没传报错',
187
225
  body: {
188
226
  type: 'object',
189
227
  properties: {
@@ -204,7 +242,8 @@ module.exports = fp(async (fastify, options) => {
204
242
  description: '任务类型(批量取消时使用)'
205
243
  }
206
244
  }
207
- }
245
+ },
246
+ response: empty('操作成功,返回空对象')
208
247
  }
209
248
  },
210
249
  async request => {
@@ -218,21 +257,26 @@ module.exports = fp(async (fastify, options) => {
218
257
  {
219
258
  onRequest: options.getAuthenticate('write'),
220
259
  schema: {
260
+ tags: [TAG],
221
261
  summary: '重试任务',
262
+ description: '把 failed / canceled 状态的任务重置为 pending 并清空完成信息、错误和重试计数,等待重新调度;其他状态报错,批量时遇到错误即中止',
222
263
  body: {
223
264
  type: 'object',
224
265
  properties: {
225
266
  id: {
226
- type: 'string'
267
+ type: 'string',
268
+ description: '任务ID(单个重试)'
227
269
  },
228
270
  taskIds: {
229
271
  type: 'array',
230
272
  items: {
231
273
  type: 'string'
232
- }
274
+ },
275
+ description: '任务ID列表(批量重试),可与 id 同时传'
233
276
  }
234
277
  }
235
- }
278
+ },
279
+ response: empty('操作成功,返回空对象')
236
280
  }
237
281
  },
238
282
  async request => {
@@ -245,7 +289,9 @@ module.exports = fp(async (fastify, options) => {
245
289
  `${options.prefix}/next`,
246
290
  {
247
291
  schema: {
292
+ tags: [CALLBACK_TAG],
248
293
  summary: '处理任务next',
294
+ description: `外部服务回传 waiting 状态任务的执行结果:result 为 JSON 字符串,code 为 0 时任务成功(data 交给任务完成回调),否则任务失败;${SIGNATURE_HINT}。该接口不鉴权`,
249
295
  body: {
250
296
  type: 'object',
251
297
  properties: {
@@ -255,14 +301,15 @@ module.exports = fp(async (fastify, options) => {
255
301
  },
256
302
  signature: {
257
303
  type: 'string',
258
- description: '签名'
304
+ description: '签名:以任务 context.secret 为密钥,对 `${id}|${result}` 做 HMAC-SHA256 的十六进制摘要'
259
305
  },
260
306
  result: {
261
307
  type: 'string',
262
- description: '结果'
308
+ description: '结果 JSON 字符串,形如 {"code":0,"data":{}};解析失败任务置为失败'
263
309
  }
264
310
  }
265
- }
311
+ },
312
+ response: { 200: { description: '处理完成,响应体为空' } }
266
313
  }
267
314
  },
268
315
  async request => {
@@ -274,18 +321,23 @@ module.exports = fp(async (fastify, options) => {
274
321
  `${options.prefix}/log`,
275
322
  {
276
323
  schema: {
324
+ tags: [CALLBACK_TAG],
277
325
  summary: '记录任务日志',
326
+ description: `外部服务为任务追加一条日志,保存在任务 options.logs(新的在前,最多 100 条);${SIGNATURE_HINT}。该接口不鉴权`,
278
327
  body: {
279
328
  type: 'object',
280
329
  properties: {
281
330
  id: {
282
- type: 'string'
331
+ type: 'string',
332
+ description: '任务ID,与 query.taskId 二选一,优先使用 id'
283
333
  },
284
334
  data: {
285
- type: 'object'
335
+ type: 'object',
336
+ description: '日志数据'
286
337
  },
287
338
  message: {
288
- type: 'string'
339
+ type: 'string',
340
+ description: '日志内容'
289
341
  },
290
342
  signature: {
291
343
  type: 'string',
@@ -297,10 +349,12 @@ module.exports = fp(async (fastify, options) => {
297
349
  type: 'object',
298
350
  properties: {
299
351
  taskId: {
300
- type: 'string'
352
+ type: 'string',
353
+ description: '任务ID,body 未传 id 时使用'
301
354
  }
302
355
  }
303
- }
356
+ },
357
+ response: success('更新后的任务记录', task)
304
358
  }
305
359
  },
306
360
  async request => {
@@ -312,21 +366,27 @@ module.exports = fp(async (fastify, options) => {
312
366
  `${options.prefix}/callback`,
313
367
  {
314
368
  schema: {
369
+ tags: [CALLBACK_TAG],
315
370
  summary: '任务回调',
371
+ description: `外部服务回传任务最终结果:先把回调内容记入任务日志,code 为 0 时任务成功(data 作为输出),否则任务失败(message 作为错误);${SIGNATURE_HINT}。该接口不鉴权`,
316
372
  body: {
317
373
  type: 'object',
318
374
  properties: {
319
375
  id: {
320
- type: 'string'
376
+ type: 'string',
377
+ description: '任务ID,与 query.taskId 二选一,优先使用 id'
321
378
  },
322
379
  code: {
323
- type: 'number'
380
+ type: 'number',
381
+ description: '结果码,0 表示成功,其他表示失败'
324
382
  },
325
383
  data: {
326
- type: 'object'
384
+ type: 'object',
385
+ description: '结果数据,作为任务输出'
327
386
  },
328
387
  message: {
329
- type: 'string'
388
+ type: 'string',
389
+ description: '结果说明,失败时作为错误信息'
330
390
  },
331
391
  signature: {
332
392
  type: 'string',
@@ -338,10 +398,12 @@ module.exports = fp(async (fastify, options) => {
338
398
  type: 'object',
339
399
  properties: {
340
400
  taskId: {
341
- type: 'string'
401
+ type: 'string',
402
+ description: '任务ID,body 未传 id 时使用'
342
403
  }
343
404
  }
344
- }
405
+ },
406
+ response: { 200: { description: '处理完成,响应体为空' } }
345
407
  }
346
408
  },
347
409
  async request => {
@@ -1,4 +1,7 @@
1
1
  const fp = require('fastify-plugin');
2
+ const { success, statistics } = require('../schema/response');
3
+
4
+ const TAG = '任务-统计';
2
5
 
3
6
  module.exports = fp(async (fastify, options) => {
4
7
  const { services } = fastify[options.name];
@@ -8,7 +11,9 @@ module.exports = fp(async (fastify, options) => {
8
11
  {
9
12
  onRequest: options.getAuthenticate('statistics'),
10
13
  schema: {
14
+ tags: [TAG],
11
15
  summary: '获取任务统计概览',
16
+ description: '按时间范围汇总已结束任务的数量、状态/类型/执行方式分布、每日与按小时趋势及耗时;不支持的 range 报错,其他查询异常时返回空统计',
12
17
  query: {
13
18
  type: 'object',
14
19
  properties: {
@@ -17,7 +22,8 @@ module.exports = fp(async (fastify, options) => {
17
22
  type: { type: 'string', description: '按任务类型筛选' },
18
23
  runnerType: { type: 'string', description: '按执行方式筛选 manual / system' }
19
24
  }
20
- }
25
+ },
26
+ response: success('任务统计数据', statistics)
21
27
  }
22
28
  },
23
29
  async request => {
@@ -32,7 +38,9 @@ module.exports = fp(async (fastify, options) => {
32
38
  {
33
39
  onRequest: options.getAuthenticate('statistics'),
34
40
  schema: {
41
+ tags: [TAG],
35
42
  summary: 'SSE实时推送任务统计数据',
43
+ description: '以 text/event-stream 长连接按 interval 推送实时统计(当天各状态数量、执行中/等待中任务数等),客户端断开后停止',
36
44
  query: {
37
45
  type: 'object',
38
46
  properties: {
@@ -42,7 +50,8 @@ module.exports = fp(async (fastify, options) => {
42
50
  runnerType: { type: 'string', description: '按执行方式筛选 manual / system' },
43
51
  interval: { type: 'integer', minimum: 1, default: 5, description: '推送间隔时间(秒),最小1秒,默认5秒' }
44
52
  }
45
- }
53
+ },
54
+ response: { 200: { description: 'text/event-stream 事件流,每条 data 为实时统计 JSON' } }
46
55
  }
47
56
  },
48
57
  async (request, reply) => {
@@ -212,7 +212,17 @@ const createContext = (fastify, options) => {
212
212
  const getTaskDeclaration = type => {
213
213
  const declaration = resolveTaskDeclaration(type);
214
214
  if (!declaration) {
215
- throw new Error('未找到合法的任务声明');
215
+ const { taskName } = splitTaskName(type);
216
+ return registerTaskDeclaration({
217
+ namespace: mainNamespace,
218
+ taskName,
219
+ dirs: options.dirs,
220
+ scriptName: options.scriptName,
221
+ config: {},
222
+ override: false,
223
+ syncLegacyTask: false,
224
+ useGlobalDirs: true
225
+ }).declaration;
216
226
  }
217
227
  return declaration;
218
228
  };
@@ -0,0 +1,74 @@
1
+ // 响应 schema 只用于 OpenAPI 文档:字段可空、对象允许额外字段,避免序列化改变实际输出
2
+ const str = description => ({ type: 'string', nullable: true, description });
3
+ const num = description => ({ type: 'number', nullable: true, description });
4
+ // ID、日期、JSON 列可能是 number / string / Date / 任意结构,不声明类型,原样输出
5
+ const any = description => ({ description });
6
+ const obj = (description, properties = {}) => ({ type: 'object', nullable: true, additionalProperties: true, description, properties });
7
+ const list = (description, items) => ({ type: 'array', nullable: true, description, items });
8
+
9
+ const success = (description, schema) => ({ 200: Object.assign({}, schema || { type: 'object', additionalProperties: true }, { description }) });
10
+ const empty = description => success(description || '操作成功,返回空对象');
11
+
12
+ const TASK_STATUS = '任务状态:pending 待执行,running 执行中,waiting 等待外部回调/轮询,success 成功,failed 失败,canceled 已取消';
13
+ const RUNNER_TYPE = '执行方式:manual 手动执行,system 系统自动执行';
14
+
15
+ const task = obj('任务', {
16
+ id: any('任务 ID'),
17
+ type: str('任务类型'),
18
+ scriptName: str('任务脚本名称'),
19
+ targetId: any('任务目标对象 ID'),
20
+ targetType: str('任务目标对象类型'),
21
+ runnerType: str(RUNNER_TYPE),
22
+ priority: num('优先级,数值越大越优先'),
23
+ parentTaskId: any('父任务 ID'),
24
+ retryCount: num('已自动重试次数'),
25
+ maxRetries: num('最大自动重试次数,0 表示不自动重试'),
26
+ timeout: num('任务超时时间(毫秒),0 表示不超时'),
27
+ startTime: any('任务最早执行时间'),
28
+ startedAt: any('实际开始执行时间'),
29
+ completedAt: any('完成时间'),
30
+ userId: any('创建人用户 ID,系统创建为空'),
31
+ completedUserId: any('完成任务的用户 ID'),
32
+ input: any('输入数据'),
33
+ output: any('输出数据'),
34
+ error: any('错误信息'),
35
+ status: str(TASK_STATUS),
36
+ context: any('执行上下文,如回调签名密钥等'),
37
+ pollResults: any('轮询执行结果列表'),
38
+ pollCount: num('已轮询次数'),
39
+ progress: num('任务进度(0-100)'),
40
+ msg: str('任务消息或错误信息'),
41
+ options: any('扩展选项,logs 为最近 100 条任务日志(新的在前)'),
42
+ createdAt: any('创建时间'),
43
+ updatedAt: any('更新时间')
44
+ });
45
+
46
+ const taskList = {
47
+ type: 'object',
48
+ additionalProperties: true,
49
+ properties: {
50
+ pageData: list('当前页任务列表,默认按创建时间倒序', task),
51
+ totalCount: num('符合条件的任务总数')
52
+ }
53
+ };
54
+
55
+ const statistics = {
56
+ type: 'object',
57
+ additionalProperties: true,
58
+ properties: {
59
+ range: str('时间范围:7d / 1m / 3m / 1y'),
60
+ rangeLabel: str('时间范围名称,如「近7天」'),
61
+ totalTasks: num('范围内已结束(成功、失败、取消)的任务总数'),
62
+ byStatus: any('按状态统计的任务数,键为 success / failed / canceled'),
63
+ byType: any('按任务类型统计的任务数,键为任务类型'),
64
+ byRunnerType: any('按执行方式统计的任务数,键为 manual / system'),
65
+ recentTrend: any('每日趋势,每项为 { date, count }'),
66
+ recentTrendByStatus: any('每日按状态趋势,每项为 { date, status, count }'),
67
+ recentTrendByType: any('每日按类型趋势,每项为 { date, type, count }'),
68
+ durationTrend: any('每日耗时趋势,每项含 date、完成/成功/失败数及平均等待、执行、总耗时(毫秒)'),
69
+ hourlyTrend: any('按小时趋势,每项为 { date, hour, total, success, failed, canceled };查询失败或无数据时不返回'),
70
+ hourlyCompletionTrend: any('按小时、类型、执行方式的完成明细,每项含 date、hour、type、runnerType 及完成/成功/失败/取消数')
71
+ }
72
+ };
73
+
74
+ module.exports = { str, num, any, obj, list, success, empty, TASK_STATUS, RUNNER_TYPE, task, taskList, statistics };
@@ -43,6 +43,13 @@ const getHour = (date, tz) => {
43
43
  return d.hour();
44
44
  };
45
45
 
46
+ const getZonedChannelHour = (periodTime, serverHour, tz) => {
47
+ if (!tz) return { date: formatDate(periodTime), hour: serverHour };
48
+ const localPeriodTime = dayjs(periodTime).hour(serverHour).minute(0).second(0).millisecond(0);
49
+ const zonedTime = localPeriodTime.tz(tz);
50
+ return { date: zonedTime.format('YYYY-MM-DD'), hour: zonedTime.hour() };
51
+ };
52
+
46
53
  const safeNum = v => {
47
54
  const n = Number(v);
48
55
  return (typeof n === 'number' && !isNaN(n) ? n : 0);
@@ -62,9 +69,12 @@ const toAvgDuration = ({ count, sumWaiting, sumExecution, sumTotal }) => ({
62
69
 
63
70
  const parseChannel = channel => {
64
71
  const parts = channel.split(':');
65
- return parts.length >= 2
66
- ? { type: parts[0], runnerType: parts[1] }
67
- : { type: channel, runnerType: null };
72
+ const hour = Number(parts[2]);
73
+ return {
74
+ type: parts[0],
75
+ runnerType: parts.length >= 2 ? parts[1] : null,
76
+ completedHour: parts.length >= 3 && Number.isInteger(hour) && hour >= 0 && hour < 24 ? hour : null
77
+ };
68
78
  };
69
79
 
70
80
  const buildChannels = async (statisticsServices, type, runnerType) => {
@@ -81,6 +91,20 @@ const buildChannels = async (statisticsServices, type, runnerType) => {
81
91
  return channels;
82
92
  };
83
93
 
94
+ const buildHourlyChannels = (channels, runnerType) => {
95
+ const types = [...new Set(channels.map(ch => ch.split(':')[0]).filter(Boolean))];
96
+ const runnerTypes = runnerType ? [runnerType] : RUNNER_TYPES;
97
+ const hourlyChannels = [];
98
+ for (const type of types) {
99
+ for (const rt of runnerTypes) {
100
+ for (let hour = 0; hour < 24; hour += 1) {
101
+ hourlyChannels.push(`${type}:${rt}:${hour}`);
102
+ }
103
+ }
104
+ }
105
+ return hourlyChannels;
106
+ };
107
+
84
108
  // 确保时长累加器存在于 map 中
85
109
  const ensureDurationAcc = (map, key) => {
86
110
  if (!map[key]) map[key] = { count: 0, sumWaiting: 0, sumExecution: 0, sumTotal: 0 };
@@ -102,9 +126,48 @@ const createDailyMapEntry = () => ({ total: 0, byStatus: { success: 0, failed: 0
102
126
  const createDailyDurationEntry = () => ({
103
127
  completedCount: 0, successCount: 0, failedCount: 0, canceledCount: 0,
104
128
  sumWaiting: 0, sumExecution: 0, sumTotal: 0, countWithTiming: 0,
105
- byType: {}, byRunnerType: {}
129
+ byType: {}, byRunnerType: {}, byTypeByRunnerType: {}
106
130
  });
107
131
 
132
+ const createHourlyAccumulator = () => ({
133
+ hourlyMap: {},
134
+ hourlyStatusMap: {},
135
+ hourlyTypeMap: {},
136
+ hourlyDetailMap: {}
137
+ });
138
+
139
+ const mergeHourlyItem = (result, { date, hour, typeName, runnerTypeName, count, sum, includeSummary = true }) => {
140
+ if (includeSummary) {
141
+ if (!result.hourlyMap[date]) result.hourlyMap[date] = {};
142
+ result.hourlyMap[date][hour] = (result.hourlyMap[date][hour] || 0) + count;
143
+
144
+ if (!result.hourlyStatusMap[date]) result.hourlyStatusMap[date] = {};
145
+ if (!result.hourlyStatusMap[date][hour]) result.hourlyStatusMap[date][hour] = {};
146
+ for (const status of ['success', 'failed', 'canceled']) {
147
+ const sc = safeNum(sum[status]);
148
+ if (sc > 0) result.hourlyStatusMap[date][hour][status] = (result.hourlyStatusMap[date][hour][status] || 0) + sc;
149
+ }
150
+
151
+ if (!result.hourlyTypeMap[date]) result.hourlyTypeMap[date] = {};
152
+ if (!result.hourlyTypeMap[date][hour]) result.hourlyTypeMap[date][hour] = {};
153
+ if (count > 0) result.hourlyTypeMap[date][hour][typeName] = (result.hourlyTypeMap[date][hour][typeName] || 0) + count;
154
+ }
155
+
156
+ if (runnerTypeName) {
157
+ if (!result.hourlyDetailMap[date]) result.hourlyDetailMap[date] = {};
158
+ if (!result.hourlyDetailMap[date][hour]) result.hourlyDetailMap[date][hour] = {};
159
+ if (!result.hourlyDetailMap[date][hour][typeName]) result.hourlyDetailMap[date][hour][typeName] = {};
160
+ if (!result.hourlyDetailMap[date][hour][typeName][runnerTypeName]) {
161
+ result.hourlyDetailMap[date][hour][typeName][runnerTypeName] = { total: 0, success: 0, failed: 0, canceled: 0 };
162
+ }
163
+ const detail = result.hourlyDetailMap[date][hour][typeName][runnerTypeName];
164
+ detail.total += count;
165
+ detail.success += safeNum(sum.success);
166
+ detail.failed += safeNum(sum.failed);
167
+ detail.canceled += safeNum(sum.canceled);
168
+ }
169
+ };
170
+
108
171
  // 查询 statistics 并解析结果
109
172
  // 写入数据全使用服务器时间(DB 中存储的是服务器时间),查询用客户端时间转换展示
110
173
  const queryAndParse = async (statisticsServices, { channels, startTime, endTime, timezone: tz, runnerType: runnerTypeFilter }) => {
@@ -192,19 +255,7 @@ const queryAndParse = async (statisticsServices, { channels, startTime, endTime,
192
255
 
193
256
  // 小时级趋势(仅 period='h')
194
257
  if (isHourly) {
195
- if (!result.hourlyMap[date]) result.hourlyMap[date] = {};
196
- result.hourlyMap[date][hour] = (result.hourlyMap[date][hour] || 0) + count;
197
-
198
- if (!result.hourlyStatusMap[date]) result.hourlyStatusMap[date] = {};
199
- if (!result.hourlyStatusMap[date][hour]) result.hourlyStatusMap[date][hour] = {};
200
- for (const status of ['success', 'failed', 'canceled']) {
201
- const sc = safeNum(sum[status]);
202
- if (sc > 0) result.hourlyStatusMap[date][hour][status] = (result.hourlyStatusMap[date][hour][status] || 0) + sc;
203
- }
204
-
205
- if (!result.hourlyTypeMap[date]) result.hourlyTypeMap[date] = {};
206
- if (!result.hourlyTypeMap[date][hour]) result.hourlyTypeMap[date][hour] = {};
207
- if (count > 0) result.hourlyTypeMap[date][hour][typeName] = (result.hourlyTypeMap[date][hour][typeName] || 0) + count;
258
+ mergeHourlyItem(result, { date, hour, typeName, runnerTypeName: null, count, sum });
208
259
  }
209
260
  }
210
261
 
@@ -227,22 +278,20 @@ const queryAndParse = async (statisticsServices, { channels, startTime, endTime,
227
278
  // 按日 byRunnerType 时长
228
279
  if (dailyDurationMap[date]) {
229
280
  accumDuration(ensureDurationAcc(dailyDurationMap[date].byRunnerType, runnerTypeName), count, sum);
281
+ if (!dailyDurationMap[date].byTypeByRunnerType[runnerTypeName]) {
282
+ dailyDurationMap[date].byTypeByRunnerType[runnerTypeName] = {};
283
+ }
284
+ accumDuration(
285
+ ensureDurationAcc(dailyDurationMap[date].byTypeByRunnerType[runnerTypeName], typeName),
286
+ count,
287
+ sum
288
+ );
230
289
  }
231
290
  }
232
291
 
233
292
  // hourlyDetailMap(仅 period='h')
234
293
  if (isHourly) {
235
- if (!result.hourlyDetailMap[date]) result.hourlyDetailMap[date] = {};
236
- if (!result.hourlyDetailMap[date][hour]) result.hourlyDetailMap[date][hour] = {};
237
- if (!result.hourlyDetailMap[date][hour][typeName]) result.hourlyDetailMap[date][hour][typeName] = {};
238
- if (!result.hourlyDetailMap[date][hour][typeName][runnerTypeName]) {
239
- result.hourlyDetailMap[date][hour][typeName][runnerTypeName] = { total: 0, success: 0, failed: 0, canceled: 0 };
240
- }
241
- const detail = result.hourlyDetailMap[date][hour][typeName][runnerTypeName];
242
- detail.total += count;
243
- detail.success += safeNum(sum.success);
244
- detail.failed += safeNum(sum.failed);
245
- detail.canceled += safeNum(sum.canceled);
294
+ mergeHourlyItem(result, { date, hour, typeName, runnerTypeName, count, sum, includeSummary: false });
246
295
  }
247
296
  }
248
297
  }
@@ -260,12 +309,51 @@ const queryAndParse = async (statisticsServices, { channels, startTime, endTime,
260
309
  avgExecutionTime: computeAvg(dd.sumExecution, dd.countWithTiming),
261
310
  avgTotalTime: computeAvg(dd.sumTotal, dd.countWithTiming),
262
311
  byType: Object.fromEntries(Object.entries(dd.byType).map(([n, td]) => [n, toAvgDuration(td)])),
263
- byRunnerType: Object.fromEntries(Object.entries(dd.byRunnerType).map(([n, rt]) => [n, toAvgDuration(rt)]))
312
+ byRunnerType: Object.fromEntries(Object.entries(dd.byRunnerType).map(([n, rt]) => [n, toAvgDuration(rt)])),
313
+ byTypeByRunnerType: Object.fromEntries(
314
+ Object.entries(dd.byTypeByRunnerType).map(([rtName, types]) => [
315
+ rtName,
316
+ Object.fromEntries(Object.entries(types).map(([typeName, td]) => [typeName, toAvgDuration(td)]))
317
+ ])
318
+ )
264
319
  }));
265
320
 
266
321
  return result;
267
322
  };
268
323
 
324
+ const queryHourlyChildChannels = async (statisticsServices, { channels, startTime, endTime, timezone: tz, runnerType: runnerTypeFilter }) => {
325
+ const hourlyChannels = buildHourlyChannels(channels, runnerTypeFilter);
326
+ if (hourlyChannels.length === 0) return null;
327
+
328
+ const statResult = await statisticsServices.query({
329
+ channels: hourlyChannels, startTime, endTime,
330
+ attributeNames: STAT_ATTRS,
331
+ aggregates: ['sum'],
332
+ timezone: tz || undefined
333
+ });
334
+
335
+ const result = createHourlyAccumulator();
336
+ for (const item of statResult.list || []) {
337
+ const { type: typeName, runnerType: runnerTypeName, completedHour } = parseChannel(item.channel);
338
+ if (completedHour == null) continue;
339
+ if (runnerTypeFilter && runnerTypeName !== runnerTypeFilter) continue;
340
+
341
+ const sum = getSumData(item);
342
+ const count = safeNum(sum.total);
343
+ const { date, hour } = getZonedChannelHour(item.time, completedHour, tz);
344
+ mergeHourlyItem(result, {
345
+ date,
346
+ hour,
347
+ typeName,
348
+ runnerTypeName,
349
+ count,
350
+ sum
351
+ });
352
+ }
353
+
354
+ return result;
355
+ };
356
+
269
357
  // 构建 todayDuration 结果
270
358
  const buildDurationResult = (d) => ({
271
359
  completedCount: d.completedCount,
@@ -377,9 +465,10 @@ module.exports = fp(async (fastify, options) => {
377
465
  const channels = await buildChannels(statisticsServices, type, runnerType);
378
466
  const parsed = await queryAndParse(statisticsServices, { channels, startTime, endTime, timezone, runnerType });
379
467
  if (!parsed) return emptyResult;
468
+ const hourlyParsed = await queryHourlyChildChannels(statisticsServices, { channels, startTime, endTime, timezone, runnerType });
380
469
 
381
470
  const { recentTrend, recentTrendByStatus, recentTrendByType } = buildDailyTrendArrays(parsed);
382
- const { hourlyTrend, hourlyCompletionTrend } = buildHourlyTrendArrays(parsed);
471
+ const { hourlyTrend, hourlyCompletionTrend } = buildHourlyTrendArrays(hourlyParsed || createHourlyAccumulator());
383
472
 
384
473
  return {
385
474
  range: rangeKey, rangeLabel: label,
@@ -4,7 +4,9 @@ const getTaskServiceContext = require('../helpers/task-service-context');
4
4
  module.exports = fp(async (fastify, options) => {
5
5
  const context = getTaskServiceContext(fastify, options);
6
6
  const { models, Op } = context;
7
+ const Sequelize = fastify.sequelize.Sequelize;
7
8
  const SORTABLE_FIELDS = new Set(['id', 'targetId', 'targetType', 'type', 'status', 'runnerType', 'priority', 'createdAt', 'updatedAt', 'startTime', 'startedAt', 'completedAt']);
9
+ const INTEGER_PRIORITY_MAX = 2147483647;
8
10
 
9
11
  const cancel = async ({ id, targetId, targetType, type }) => {
10
12
  if (!id && !(targetId && targetType && type)) {
@@ -73,7 +75,7 @@ module.exports = fp(async (fastify, options) => {
73
75
  await context.updateTaskByStatus({
74
76
  task,
75
77
  allowedStatuses: ['pending'],
76
- updateData: { priority: Number.MAX_SAFE_INTEGER }
78
+ updateData: { priority: INTEGER_PRIORITY_MAX }
77
79
  });
78
80
  const claimedTask = await fastify[options.name].services.claimTask(task);
79
81
  if (claimedTask) {
@@ -142,7 +144,76 @@ module.exports = fp(async (fastify, options) => {
142
144
  }
143
145
  };
144
146
 
145
- const list = async ({ filter, perPage = 20, currentPage = 1, sort }) => {
147
+ const normalizeListQuery = (query = {}) => {
148
+ const normalized = Object.assign({}, query);
149
+
150
+ Object.entries(query || {}).forEach(([rawKey, value]) => {
151
+ const match = rawKey.match(/^(filter|sort)\[([^\]]+)\](?:\[([^\]]+)\])?$/);
152
+ if (!match) {
153
+ return;
154
+ }
155
+
156
+ const [, root, key, childKey] = match;
157
+ if (!normalized[root] || typeof normalized[root] !== 'object' || Array.isArray(normalized[root])) {
158
+ normalized[root] = {};
159
+ }
160
+
161
+ if (childKey) {
162
+ if (!normalized[root][key] || typeof normalized[root][key] !== 'object' || Array.isArray(normalized[root][key])) {
163
+ normalized[root][key] = {};
164
+ }
165
+ normalized[root][key][childKey] = value;
166
+ } else {
167
+ normalized[root][key] = value;
168
+ }
169
+ delete normalized[rawKey];
170
+ });
171
+
172
+ return normalized;
173
+ };
174
+
175
+ const quoteIdentifier = identifier => `"${String(identifier).replaceAll('"', '""')}"`;
176
+
177
+ const getJsonTextExpression = fieldPath => {
178
+ if (typeof Sequelize.literal !== 'function') {
179
+ return null;
180
+ }
181
+
182
+ const [field, key] = String(fieldPath).split('.');
183
+ const column = quoteIdentifier(models.task.rawAttributes?.[field]?.field || field);
184
+ const dialect = models.task.sequelize?.getDialect?.();
185
+
186
+ if (dialect === 'postgres') {
187
+ return Sequelize.literal(`${column}->>'${key}'`);
188
+ }
189
+
190
+ if (dialect === 'sqlite') {
191
+ return Sequelize.literal(`json_extract(${column}, '$.${key}')`);
192
+ }
193
+
194
+ return typeof Sequelize.json === 'function' ? Sequelize.json(fieldPath) : null;
195
+ };
196
+
197
+ const appendJsonFieldLikeFilter = (whereQuery, fieldPath, value) => {
198
+ const keyword = String(value).toLowerCase();
199
+ const condition = {
200
+ [Op.like]: `%${keyword}%`
201
+ };
202
+ const fallbackCondition = {
203
+ [Op.like]: `%${value}%`
204
+ };
205
+ const jsonTextExpression = getJsonTextExpression(fieldPath);
206
+
207
+ if (typeof Sequelize.where === 'function' && typeof Sequelize.fn === 'function' && jsonTextExpression && Op.and) {
208
+ whereQuery[Op.and] = [...(whereQuery[Op.and] || []), Sequelize.where(Sequelize.fn('lower', jsonTextExpression), condition)];
209
+ return;
210
+ }
211
+
212
+ whereQuery[fieldPath] = fallbackCondition;
213
+ };
214
+
215
+ const list = async query => {
216
+ const { filter, perPage = 20, currentPage = 1, sort } = normalizeListQuery(query);
146
217
  const whereQuery = {};
147
218
 
148
219
  ['id', 'targetId', 'type', 'status', 'runnerType'].forEach(key => {
@@ -151,6 +222,10 @@ module.exports = fp(async (fastify, options) => {
151
222
  }
152
223
  });
153
224
 
225
+ if (filter && filter.targetName) {
226
+ appendJsonFieldLikeFilter(whereQuery, 'input.name', filter.targetName);
227
+ }
228
+
154
229
  if (filter && filter.createdAt) {
155
230
  whereQuery.createdAt = getTimeQuery(filter.createdAt);
156
231
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kne/fastify-task",
3
- "version": "3.0.0-alpha.9",
3
+ "version": "3.0.0",
4
4
  "description": "一个 Fastify 插件,用于任务编排、追踪任务执行状态和结果。支持系统自动执行和手动执行两种模式,提供完整的任务生命周期管理",
5
5
  "main": "index.js",
6
6
  "scripts": {