@kne/fastify-task 3.0.0 → 3.0.4

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.
package/README.md CHANGED
@@ -15,7 +15,7 @@ npm i --save @kne/fastify-task
15
15
  `@kne/fastify-task` 是一个 Fastify 插件,用于任务编排、执行状态追踪、结果回调、日志记录和统计分析。插件支持 **system 自动执行
16
16
  ** 与 **manual 手动完成** 两种模式,适合处理导出、同步、通知、外部异步回调等后台任务场景。
17
17
 
18
- ### 核心架构与流程
18
+ #### 核心架构与流程
19
19
 
20
20
  ```
21
21
  创建任务 (services.create)
@@ -35,67 +35,67 @@ pending(待执行)
35
35
  └→ waiting → processNext / callbackWithSignature → handler → next task → success / failed
36
36
  ```
37
37
 
38
- | 节点 | 说明 |
39
- |-------------------------|-----------------------------------------------------|
40
- | `checkTimeout` | 每次调度前检测 `running` / `waiting` 中已超过任务级 `timeout` 的任务 |
41
- | `claimPendingTasks` | 使用带状态条件的更新将 `pending` 原子认领为 `running`,避免多实例重复执行 |
42
- | `processSystemTask` | 执行任务脚本,并根据结果、异常、重试次数和回调状态更新任务 |
43
- | `collectTaskStatistics` | 任务进入终态后采集数量和耗时指标 |
44
- | `taskRegistry` | 维护主项目与插件通过 `append` 注册的任务声明、脚本目录和生命周期钩子 |
38
+ | 节点 | 说明 |
39
+ | ----------------------- | ------------------------------------------------------------------------- |
40
+ | `checkTimeout` | 每次调度前检测 `running` / `waiting` 中已超过任务级 `timeout` 的任务 |
41
+ | `claimPendingTasks` | 使用带状态条件的更新将 `pending` 原子认领为 `running`,避免多实例重复执行 |
42
+ | `processSystemTask` | 执行任务脚本,并根据结果、异常、重试次数和回调状态更新任务 |
43
+ | `collectTaskStatistics` | 任务进入终态后采集数量和耗时指标 |
44
+ | `taskRegistry` | 维护主项目与插件通过 `append` 注册的任务声明、脚本目录和生命周期钩子 |
45
45
 
46
46
  > **关键设计**:cron 每次触发 `runner` 时先检测超时任务,再按 **优先级降序 + startTime 升序** 认领待执行系统任务。认领通过条件更新完成,只有仍处于
47
- `pending` 的任务会被当前实例执行。
48
-
49
- ### 核心概念详解
50
-
51
- #### 任务状态
52
-
53
- | 状态 | 说明 | 可流转到 |
54
- |------------|--------|--------------------------------------------|
55
- | `pending` | 待执行 | `running`、`canceled` |
56
- | `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
57
- | `waiting` | 等待外部回调 | `success`、`failed` |
58
- | `success` | 执行成功 | 终态 |
59
- | `failed` | 执行失败 | `pending`(重试) |
60
- | `canceled` | 已取消 | `pending`(重试) |
61
-
62
- #### 执行模式
63
-
64
- | 模式 | runnerType | 触发方式 | 说明 |
65
- |------|------------|----------------------|----------------------|
66
- | 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
67
- | 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
68
-
69
- #### 调度与恢复
70
-
71
- | 机制 | 触发时机 | 说明 |
72
- |------|--------------------------|-------------------------------------------------------------------|
73
- | 并发上限 | 每次 `runner()` 执行 | 当前 `running` 系统任务数达到 `limit` 时不再认领新任务 |
74
- | 原子认领 | 查询到候选 `pending` 任务后 | 通过 `id + runnerType + status + startTime` 条件更新为 `running`,认领失败则跳过 |
75
- | 启动恢复 | Fastify `onReady` | 默认只将超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务恢复为 `pending` |
76
- | 手动重置 | 调用 `services.resetAll()` | 不传 `staleOnly` 时会将所有 `running` 任务重置为 `pending` |
77
-
78
- ### 主要特性
79
-
80
- | 特性 | 说明 |
81
- |---------|-------------------------------------------|
82
- | 任务创建与管理 | 支持创建、取消、重试、完成任务 |
83
- | 多种执行模式 | system 自动执行 / manual 手动执行 |
84
- | 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
85
- | 任务状态追踪 | 实时追踪进度、轮询结果 |
86
- | 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
87
- | 日志记录 | 任务执行日志,最多保留 100 条 |
88
- | 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
89
- | 自动重试 | 指数退避重试策略 |
90
- | 超时控制 | 全局执行超时和任务级超时均使用毫秒,超时自动标记 failed |
91
- | 多实例调度 | 待执行任务通过原子认领进入 running,降低重复执行风险 |
92
- | 插件任务注册 | 插件可通过 `append` 注册自己的任务目录、脚本名、处理函数和错误处理 |
93
- | 链式任务 | 支持通过 `next` 声明后续任务,按当前输出创建下一任务 |
94
- | 统计面板 | 任务统计数据查询 + SSE 实时推送 |
95
-
96
- ### 使用方法
97
-
98
- #### 插件注册与配置
47
+ > `pending` 的任务会被当前实例执行。
48
+
49
+ #### 核心概念详解
50
+
51
+ ##### 任务状态
52
+
53
+ | 状态 | 说明 | 可流转到 |
54
+ | ---------- | ------------ | ------------------------------------------------- |
55
+ | `pending` | 待执行 | `running`、`canceled` |
56
+ | `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
57
+ | `waiting` | 等待外部回调 | `success`、`failed` |
58
+ | `success` | 执行成功 | 终态 |
59
+ | `failed` | 执行失败 | `pending`(重试) |
60
+ | `canceled` | 已取消 | `pending`(重试) |
61
+
62
+ ##### 执行模式
63
+
64
+ | 模式 | runnerType | 触发方式 | 说明 |
65
+ | -------- | ---------- | ---------------------------- | ----------------------------- |
66
+ | 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
67
+ | 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
68
+
69
+ ##### 调度与恢复
70
+
71
+ | 机制 | 触发时机 | 说明 |
72
+ | -------- | --------------------------- | -------------------------------------------------------------------------------- |
73
+ | 并发上限 | 每次 `runner()` 执行 | 当前 `running` 系统任务数达到 `limit` 时不再认领新任务 |
74
+ | 原子认领 | 查询到候选 `pending` 任务后 | 通过 `id + runnerType + status + startTime` 条件更新为 `running`,认领失败则跳过 |
75
+ | 启动恢复 | Fastify `onReady` | 默认只将超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务恢复为 `pending` |
76
+ | 手动重置 | 调用 `services.resetAll()` | 不传 `staleOnly` 时会将所有 `running` 任务重置为 `pending` |
77
+
78
+ #### 主要特性
79
+
80
+ | 特性 | 说明 |
81
+ | -------------- | ------------------------------------------------------------------ |
82
+ | 任务创建与管理 | 支持创建、取消、重试、完成任务 |
83
+ | 多种执行模式 | system 自动执行 / manual 手动执行 |
84
+ | 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
85
+ | 任务状态追踪 | 实时追踪进度、轮询结果 |
86
+ | 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
87
+ | 日志记录 | 任务执行日志,最多保留 100 条 |
88
+ | 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
89
+ | 自动重试 | 指数退避重试策略 |
90
+ | 超时控制 | 全局执行超时和任务级超时均使用毫秒,超时自动标记 failed |
91
+ | 多实例调度 | 待执行任务通过原子认领进入 running,降低重复执行风险 |
92
+ | 插件任务注册 | 插件可通过 `append` 注册自己的任务目录、脚本名、处理函数和错误处理 |
93
+ | 链式任务 | 支持通过 `next` 声明后续任务,按当前输出创建下一任务 |
94
+ | 统计面板 | 任务统计数据查询 + SSE 实时推送 |
95
+
96
+ #### 使用方法
97
+
98
+ ##### 插件注册与配置
99
99
 
100
100
  ```js
101
101
  // 基础注册
@@ -124,19 +124,19 @@ fastify.register(require('@kne/fastify-task'), {
124
124
  });
125
125
  ```
126
126
 
127
- #### 任务声明与命名空间
127
+ ##### 任务声明与命名空间
128
128
 
129
129
  任务类型可以由主项目注册时的 `task` 配置声明,也可以由其他插件通过 `append` 动态声明。声明对象支持 `handler`、`errorHandler` 和
130
130
  `next`,其中 `handler` 可省略;只要任务类型已经声明并存在对应执行脚本,就可以创建和执行任务。
131
131
 
132
- | 声明来源 | 默认命名空间 | 任务名解析规则 |
133
- |------------|--------------|-----------------------------------------------|
132
+ | 声明来源 | 默认命名空间 | 任务名解析规则 |
133
+ | ------------- | -------------- | --------------------------------------------------------------- |
134
134
  | 主项目 `task` | `options.name` | 可直接使用本地任务名,也可使用 `{options.name}.任务名` |
135
- | 插件 `append` | `append.name` | 本地任务名只在当前插件内查找,跨插件使用 `{append.name}.任务名` |
135
+ | 插件 `append` | `append.name` | 本地任务名只在当前插件内查找,跨插件使用 `{append.name}.任务名` |
136
136
 
137
137
  > **关键设计**:插件任务不能访问主项目中的任务。插件内的裸任务名只解析到当前插件命名空间,跨插件访问必须使用 `包名.任务名`。
138
138
 
139
- #### 任务脚本开发
139
+ ##### 任务脚本开发
140
140
 
141
141
  在 `dirs` 配置的目录下创建任务脚本,目录结构:
142
142
 
@@ -156,75 +156,80 @@ module.exports = async (fastify, options, { task, updateProgress, polling, next,
156
156
  await updateProgress(50);
157
157
 
158
158
  // 轮询外部服务
159
- const result = await polling(async () => {
160
- const res = await fetch('external-api');
161
- return {
162
- result: 'success | failed | pending',
163
- data: res.data,
164
- message: '消息',
165
- progress: 80
166
- };
167
- }, {
168
- maxPollTimes: 20,
169
- pollInterval: 10000
170
- });
159
+ const result = await polling(
160
+ async () => {
161
+ const res = await fetch('external-api');
162
+ return {
163
+ result: 'success | failed | pending',
164
+ data: res.data,
165
+ message: '消息',
166
+ progress: 80
167
+ };
168
+ },
169
+ {
170
+ maxPollTimes: 20,
171
+ pollInterval: 10000
172
+ }
173
+ );
171
174
 
172
175
  // 等待外部回调(任务状态变为 waiting)
173
176
  await next({
174
- secret: '签名密钥',
177
+ secret: '签名密钥'
175
178
  // 其他上下文数据,回调时可在 context 中获取
176
179
  });
177
180
 
178
- return { /* 返回结果 */ };
181
+ return {
182
+ /* 返回结果 */
183
+ };
179
184
  };
180
185
  ```
181
186
 
182
- #### executor 辅助方法
187
+ ##### executor 辅助方法
183
188
 
184
- | 方法签名 | 说明 |
185
- |------------------------------|----------------------------------|
186
- | `updateProgress(progress)` | 更新任务进度 (0-100) |
187
- | `polling(callback, options)` | 轮询外部服务直到完成 |
189
+ | 方法签名 | 说明 |
190
+ | ---------------------------- | ---------------------------------------------- |
191
+ | `updateProgress(progress)` | 更新任务进度 (0-100) |
192
+ | `polling(callback, options)` | 轮询外部服务直到完成 |
188
193
  | `next(context)` | 设置任务为 waiting 状态,返回 `false` 暂停执行 |
189
- | `log({ data, message })` | 记录任务执行日志 |
194
+ | `log({ data, message })` | 记录任务执行日志 |
190
195
 
191
196
  **polling options 参数:**
192
197
 
193
- | 参数名 | 类型 | 默认值 | 说明 |
194
- |----------------|--------|---------|----------|
195
- | `maxPollTimes` | number | `20` | 最大轮询次数 |
198
+ | 参数名 | 类型 | 默认值 | 说明 |
199
+ | -------------- | ------ | ------- | ---------------- |
200
+ | `maxPollTimes` | number | `20` | 最大轮询次数 |
196
201
  | `pollInterval` | number | `10000` | 轮询间隔(毫秒) |
197
202
 
198
203
  **polling callback 返回格式:**
199
204
 
200
- | 字段 | 类型 | 说明 |
201
- |------------|--------|----------------------------------------|
205
+ | 字段 | 类型 | 说明 |
206
+ | ---------- | ------ | -------------------------------------- |
202
207
  | `result` | string | `'success'` / `'failed'` / `'pending'` |
203
- | `data` | object | 成功时返回的数据 |
204
- | `message` | string | 消息 |
205
- | `progress` | number | 当前进度 |
208
+ | `data` | object | 成功时返回的数据 |
209
+ | `message` | string | 消息 |
210
+ | `progress` | number | 当前进度 |
206
211
 
207
- #### 任务类型处理函数
212
+ ##### 任务类型处理函数
208
213
 
209
214
  任务成功后如果配置了 `handler`,会自动调用对应处理函数;未配置时直接进入成功收尾。处理函数接收参数:
210
215
 
211
- | 参数名 | 类型 | 说明 |
212
- |-----------|-----------------|----------------------|
213
- | `task` | Task | 任务实例 |
214
- | `result` | object / string | 任务输出结果 |
216
+ | 参数名 | 类型 | 说明 |
217
+ | --------- | --------------- | --------------------------------- |
218
+ | `task` | Task | 任务实例 |
219
+ | `result` | object / string | 任务输出结果 |
215
220
  | `context` | object | 任务上下文(`next` 时设置的数据) |
216
221
 
217
- #### 错误处理函数
222
+ ##### 错误处理函数
218
223
 
219
224
  任务最终失败时优先调用任务声明中的 `errorHandler`;未配置时调用全局 `errorHandler`。如果任务级 `errorHandler` 抛出异常,仍会继续交给全局
220
225
  `errorHandler` 处理。
221
226
 
222
- | 处理器 | 触发条件 | 说明 |
223
- |------------------------|---------------|----------------------------|
224
- | `tasks[type].errorHandler` | 当前任务最终失败 | 当前任务类型自己的错误处理,优先级最高 |
225
- | `options.errorHandler` | 未配置任务级处理或任务级处理抛错 | 全局兜底错误处理,不改变任务最终失败状态 |
227
+ | 处理器 | 触发条件 | 说明 |
228
+ | -------------------------- | -------------------------------- | ---------------------------------------- |
229
+ | `tasks[type].errorHandler` | 当前任务最终失败 | 当前任务类型自己的错误处理,优先级最高 |
230
+ | `options.errorHandler` | 未配置任务级处理或任务级处理抛错 | 全局兜底错误处理,不改变任务最终失败状态 |
226
231
 
227
- #### 运行时动态添加
232
+ ##### 运行时动态添加
228
233
 
229
234
  ```js
230
235
  // 插件包通过 append 方法运行时添加任务目录和类型
@@ -250,14 +255,14 @@ const result = await fastify.task.services.append({
250
255
 
251
256
  `append.scriptName` 只影响本次 append 注册的任务;未配置时固定使用 `index.js`,不会使用主项目注册 task 时的 `options.scriptName`。
252
257
 
253
- #### 链式任务 next
258
+ ##### 链式任务 next
254
259
 
255
260
  `tasks[type].next` 用于声明当前任务成功后的后续任务,只配置任务名称:
256
261
 
257
- | next 类型 | 下一个任务选择方式 |
258
- |---------|------------------------------------|
259
- | string | 固定创建该任务名对应的下一任务 |
260
- | array | 从当前任务 `output.next` 读取下一任务名,并要求在数组中 |
262
+ | next 类型 | 下一个任务选择方式 |
263
+ | --------- | ------------------------------------------------------- |
264
+ | string | 固定创建该任务名对应的下一任务 |
265
+ | array | 从当前任务 `output.next` 读取下一任务名,并要求在数组中 |
261
266
 
262
267
  创建下一任务时,`input` 使用当前任务 `output`,`input.name` 沿用当前任务的 `input.name`,`targetType` 固定为 `task`,`targetId` 和
263
268
  `parentTaskId` 为当前任务 id,`context` 从当前任务深拷贝。
@@ -361,12 +366,15 @@ await fastify.task.services.create({
361
366
 
362
367
  ```js
363
368
  module.exports = async (fastify, options, { task }) => {
364
- const approvals = [...(task.context.approvals || []), {
365
- node: 'manager',
366
- approver: 'u-manager-1',
367
- result: 'approved',
368
- time: new Date().toISOString()
369
- }];
369
+ const approvals = [
370
+ ...(task.context.approvals || []),
371
+ {
372
+ node: 'manager',
373
+ approver: 'u-manager-1',
374
+ result: 'approved',
375
+ time: new Date().toISOString()
376
+ }
377
+ ];
370
378
 
371
379
  await task.update({
372
380
  context: {
@@ -386,12 +394,15 @@ module.exports = async (fastify, options, { task }) => {
386
394
 
387
395
  ```js
388
396
  module.exports = async (fastify, options, { task }) => {
389
- const approvals = [...(task.context.approvals || []), {
390
- node: 'finance',
391
- approver: 'u-finance-1',
392
- result: 'approved',
393
- time: new Date().toISOString()
394
- }];
397
+ const approvals = [
398
+ ...(task.context.approvals || []),
399
+ {
400
+ node: 'finance',
401
+ approver: 'u-finance-1',
402
+ result: 'approved',
403
+ time: new Date().toISOString()
404
+ }
405
+ ];
395
406
 
396
407
  await task.update({
397
408
  context: {
@@ -411,7 +422,7 @@ module.exports = async (fastify, options, { task }) => {
411
422
  在这个流程中,`finance-approval` 会拿到主管审批后复制过来的 `context.approvals`;`legal-approval` 或 `archive-contract`
412
423
  也会继续拿到财务审批后更新过的 `context`。每次创建下一任务都会深拷贝当前任务完成时的 `context`,不会和上一任务共享同一个对象引用。
413
424
 
414
- #### 签名验证
425
+ ##### 签名验证
415
426
 
416
427
  当任务通过 `next({ secret: '密钥' })` 设置了密钥时,外部回调需提供 HMAC-SHA256 签名。
417
428
 
@@ -431,11 +442,11 @@ function generateSignature({ secret, id, data }) {
431
442
 
432
443
  **各接口签名数据格式:**
433
444
 
434
- | 接口 | data 格式 |
435
- |-------------------------|------------------------------|
436
- | `processNext` | `result` 字符串(JSON 格式结果) |
437
- | `logWithSignature` | `{ data, message }` 对象 |
438
- | `callbackWithSignature` | `{ code, data, message }` 对象 |
445
+ | 接口 | data 格式 |
446
+ | ----------------------- | -------------------------------- |
447
+ | `processNext` | `result` 字符串(JSON 格式结果) |
448
+ | `logWithSignature` | `{ data, message }` 对象 |
449
+ | `callbackWithSignature` | `{ code, data, message }` 对象 |
439
450
 
440
451
  ```js
441
452
  // processNext 签名
@@ -444,20 +455,21 @@ const signature = generateSignature({ secret: 'your-secret', id: 'task-1', data:
444
455
 
445
456
  // callbackWithSignature 签名
446
457
  const signature = generateSignature({
447
- secret: 'your-secret', id: 'task-1',
458
+ secret: 'your-secret',
459
+ id: 'task-1',
448
460
  data: { code: 0, data: { result: 'done' }, message: '成功' }
449
461
  });
450
462
  ```
451
463
 
452
464
  > **关键设计**:未设置 `context.secret` 时签名验证自动跳过,不阻塞无密钥任务的回调。
453
465
 
454
- #### 插件依赖
466
+ ##### 插件依赖
455
467
 
456
- | 依赖 | 说明 |
457
- |---------------------------|---------|
458
- | `fastify-cron` | 定时任务支持 |
468
+ | 依赖 | 说明 |
469
+ | ------------------------- | -------------- |
470
+ | `fastify-cron` | 定时任务支持 |
459
471
  | `@kne/fastify-namespace` | 命名空间模块化 |
460
- | `@kne/fastify-statistics` | 统计数据采集 |
472
+ | `@kne/fastify-statistics` | 统计数据采集 |
461
473
  | `fastify-sequelize` | 数据库模型支持 |
462
474
 
463
475
 
@@ -465,54 +477,55 @@ const signature = generateSignature({
465
477
 
466
478
  ### API
467
479
 
468
- ### 配置项
469
-
470
- | 属性名 | 类型 | 必填 | 默认值 | 说明 |
471
- |------------------------------|---------------|----|------------------|--------------------------------------------------------------------------------|
472
- | `dbTableNamePrefix` | string | 否 | `'t_'` | 数据库表名前缀 |
473
- | `prefix` | string | 否 | `'/api/task'` | API 路由前缀 |
474
- | `name` | string | 否 | `'task'` | 插件命名空间名称 |
475
- | `limit` | number | 否 | `10` | 系统任务并发执行上限 |
476
- | `dir` | string | 否 | `'libs/tasks'` | 任务脚本目录(向后兼容,优先级高于 dirs) |
477
- | `dirs` | array | 否 | `null` | 任务脚本目录列表,运行时可通过 `append` 动态添加 |
478
- | `cronTime` | string | 否 | `'*/10 * * * *'` | 定时任务 Cron 表达式 |
479
- | `scriptName` | string | 否 | `'index'` | 默认任务脚本名称 |
480
- | `maxPollTimes` | number | 否 | `20` | 最大轮询次数 |
481
- | `pollInterval` | number | 否 | `10000` | 轮询间隔(毫秒) |
482
- | `taskTimeout` | number | 否 | `1800000` | 任务执行超时时间(毫秒),0 表示不超时 |
483
- | `recoverRunningTaskAfter` | number / null | 否 | `null` | 启动恢复 running 任务的陈旧阈值(毫秒);未传时使用 `taskTimeout`,若 `taskTimeout` 为 0 则使用 `1800000` |
484
- | `recoverRunningTasksOnStart` | boolean | 否 | `true` | 启动时是否恢复陈旧 running 任务 |
485
- | `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
486
- | `errorHandler` | function | 否 | - | 全局错误处理函数,任务级 `errorHandler` 未配置或抛错时调用 |
487
- | `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
488
- | `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
489
- | `task` | object | 否 | `{}` | 主项目任务声明,支持 `{ [type]: handler }` 或 `{ [type]: { handler, errorHandler, next } }` |
480
+ #### 配置项
481
+
482
+ | 属性名 | 类型 | 必填 | 默认值 | 说明 |
483
+ | ---------------------------- | ------------- | ---- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
484
+ | `dbTableNamePrefix` | string | 否 | `'t_'` | 数据库表名前缀 |
485
+ | `prefix` | string | 否 | `'/api/task'` | API 路由前缀 |
486
+ | `name` | string | 否 | `'task'` | 插件命名空间名称 |
487
+ | `limit` | number | 否 | `10` | 系统任务并发执行上限 |
488
+ | `dir` | string | 否 | `'libs/tasks'` | 任务脚本目录(向后兼容,优先级高于 dirs) |
489
+ | `dirs` | array | 否 | `null` | 任务脚本目录列表,运行时可通过 `append` 动态添加 |
490
+ | `cronTime` | string | 否 | `'*/10 * * * *'` | 定时任务 Cron 表达式 |
491
+ | `scriptName` | string | 否 | `'index'` | 默认任务脚本名称 |
492
+ | `maxPollTimes` | number | 否 | `20` | 最大轮询次数 |
493
+ | `pollInterval` | number | 否 | `10000` | 轮询间隔(毫秒) |
494
+ | `taskTimeout` | number | 否 | `1800000` | 任务执行超时时间(毫秒),0 表示不超时 |
495
+ | `recoverRunningTaskAfter` | number / null | 否 | `null` | 启动恢复 running 任务的陈旧阈值(毫秒);未传时使用 `taskTimeout`,若 `taskTimeout` 为 0 则使用 `1800000` |
496
+ | `recoverRunningTasksOnStart` | boolean | 否 | `true` | 启动时是否恢复陈旧 running 任务 |
497
+ | `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
498
+ | `errorHandler` | function | 否 | - | 全局错误处理函数,任务级 `errorHandler` 未配置或抛错时调用 |
499
+ | `cancelHandler` | function | 否 | - | 全局取消处理函数,任务级 `cancelHandler` 未配置时调用,任务被取消后触发 |
500
+ | `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
501
+ | `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
502
+ | `task` | object | 否 | `{}` | 主项目任务声明,支持 `{ [type]: handler }` 或 `{ [type]: { handler, errorHandler, cancelHandler, next } }` |
490
503
 
491
504
  > **关键设计**:`dirs` 初始化逻辑 — 优先使用用户传入的 `dirs`,否则以 `dir` 为默认值;若 `dirs` 中不包含 `dir`,则将 `dir`
492
505
  > 插入 `dirs` 首位,保证向后兼容。
493
506
 
494
507
  > **关键设计**:`recoverRunningTasksOnStart` 只恢复陈旧 `running` 任务,避免多实例部署时某个实例重启误重置其他实例正在执行的任务。
495
508
 
496
- ### HTTP 接口
509
+ #### HTTP 接口
497
510
 
498
- #### POST `{prefix}/create`
511
+ ##### POST `{prefix}/create`
499
512
 
500
513
  创建任务,需 `write` 权限。
501
514
 
502
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
503
- |--------------|--------|----|-----------|---------------------------|
504
- | type | string | 是 | - | 任务类型,必须已在主项目或 `append` 中声明 |
505
- | targetId | string | 是 | - | 目标对象ID |
506
- | targetType | string | 是 | - | 目标对象类型 |
507
- | input | object | 否 | - | 输入数据 |
508
- | runnerType | string | 否 | - | 执行者类型:`manual` / `system` |
509
- | delay | number | 否 | `0` | 延迟执行秒数 |
510
- | scriptName | string | 否 | - | 任务脚本名称 |
511
- | priority | number | 否 | `0` | 优先级,数值越大越优先 |
512
- | parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
513
- | maxRetries | number | 否 | `0` | 最大自动重试次数 |
514
- | timeout | number | 否 | `3600000` | 任务超时时间(毫秒),0 表示不超时 |
515
- | context | object | 否 | `{}` | 初始上下文,用于回调签名、日志或链式任务传递 |
515
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
516
+ | ------------ | ------ | ---- | --------- | -------------------------------------------- |
517
+ | type | string | 是 | - | 任务类型,必须已在主项目或 `append` 中声明 |
518
+ | targetId | string | 是 | - | 目标对象ID |
519
+ | targetType | string | 是 | - | 目标对象类型 |
520
+ | input | object | 否 | - | 输入数据 |
521
+ | runnerType | string | 否 | - | 执行者类型:`manual` / `system` |
522
+ | delay | number | 否 | `0` | 延迟执行秒数 |
523
+ | scriptName | string | 否 | - | 任务脚本名称 |
524
+ | priority | number | 否 | `0` | 优先级,数值越大越优先 |
525
+ | parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
526
+ | maxRetries | number | 否 | `0` | 最大自动重试次数 |
527
+ | timeout | number | 否 | `3600000` | 任务超时时间(毫秒),0 表示不超时 |
528
+ | context | object | 否 | `{}` | 初始上下文,用于回调签名、日志或链式任务传递 |
516
529
 
517
530
  返回值:
518
531
 
@@ -522,24 +535,24 @@ const signature = generateSignature({
522
535
  }
523
536
  ```
524
537
 
525
- #### GET `{prefix}/list`
538
+ ##### GET `{prefix}/list`
526
539
 
527
540
  获取任务列表,需 `read` 权限。
528
541
 
529
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
530
- |------------------------------|--------|----|------|-----------------------------------------------------|
531
- | perPage | number | 否 | `20` | 每页数量 |
532
- | currentPage | number | 否 | `1` | 当前页码 |
533
- | filter.id | string | 否 | - | 任务ID |
534
- | filter.targetId | string | 否 | - | 目标对象ID |
535
- | filter.type | string | 否 | - | 任务类型 |
536
- | filter.status | string | 否 | - | 任务状态 |
537
- | filter.runnerType | string | 否 | - | 执行者类型 |
538
- | filter.createdAt.startTime | string | 否 | - | 创建时间起始 |
539
- | filter.createdAt.endTime | string | 否 | - | 创建时间结束 |
540
- | filter.completedAt.startTime | string | 否 | - | 完成时间起始 |
541
- | filter.completedAt.endTime | string | 否 | - | 完成时间结束 |
542
- | sort | object | 否 | - | 排序规则(支持 `completedAt`、`updatedAt` 等字段,`ASC`/`DESC`) |
542
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
543
+ | ---------------------------- | ------ | ---- | ------ | ---------------------------------------------------------------- |
544
+ | perPage | number | 否 | `20` | 每页数量 |
545
+ | currentPage | number | 否 | `1` | 当前页码 |
546
+ | filter.id | string | 否 | - | 任务ID |
547
+ | filter.targetId | string | 否 | - | 目标对象ID |
548
+ | filter.type | string | 否 | - | 任务类型 |
549
+ | filter.status | string | 否 | - | 任务状态 |
550
+ | filter.runnerType | string | 否 | - | 执行者类型 |
551
+ | filter.createdAt.startTime | string | 否 | - | 创建时间起始 |
552
+ | filter.createdAt.endTime | string | 否 | - | 创建时间结束 |
553
+ | filter.completedAt.startTime | string | 否 | - | 完成时间起始 |
554
+ | filter.completedAt.endTime | string | 否 | - | 完成时间结束 |
555
+ | sort | object | 否 | - | 排序规则(支持 `completedAt`、`updatedAt` 等字段,`ASC`/`DESC`) |
543
556
 
544
557
  返回值:
545
558
 
@@ -550,17 +563,17 @@ const signature = generateSignature({
550
563
  }
551
564
  ```
552
565
 
553
- #### POST `{prefix}/complete`
566
+ ##### POST `{prefix}/complete`
554
567
 
555
568
  手动完成任务,需 `write` 权限。
556
569
 
557
- | 参数名 | 类型 | 必填 | 说明 |
558
- |--------|--------|----|---------------------------|
559
- | id | string | 是 | 任务ID |
560
- | status | string | 是 | 完成状态:`success` / `failed` |
561
- | error | string | 否 | 错误信息 |
562
- | msg | string | 否 | 消息 |
563
- | output | object | 否 | 输出数据 |
570
+ | 参数名 | 类型 | 必填 | 说明 |
571
+ | ------ | ------ | ---- | ------------------------------ |
572
+ | id | string | 是 | 任务ID |
573
+ | status | string | 是 | 完成状态:`success` / `failed` |
574
+ | error | string | 否 | 错误信息 |
575
+ | msg | string | 否 | 消息 |
576
+ | output | object | 否 | 输出数据 |
564
577
 
565
578
  返回空对象:
566
579
 
@@ -568,16 +581,16 @@ const signature = generateSignature({
568
581
  {}
569
582
  ```
570
583
 
571
- #### POST `{prefix}/cancel`
584
+ ##### POST `{prefix}/cancel`
572
585
 
573
- 取消任务,需 `write` 权限。支持单个取消(`id`)或批量取消(`targetId` + `targetType` + `type`)。
586
+ 取消任务,需 `write` 权限。支持单个取消(`id`)或批量取消(`targetId` + `targetType` + `type`)。只有 `pending` / `running` 的任务会被取消,每个被取消的任务会触发一次 `cancelHandler`(见「取消处理」)。
574
587
 
575
- | 参数名 | 类型 | 必填 | 说明 |
576
- |------------|--------|----|----------------------------------------|
577
- | id | string | 否 | 任务ID(单个取消) |
578
- | targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
579
- | targetType | string | 否 | 目标对象类型(批量取消) |
580
- | type | string | 否 | 任务类型(批量取消) |
588
+ | 参数名 | 类型 | 必填 | 说明 |
589
+ | ---------- | ------ | ---- | ----------------------------------------------------- |
590
+ | id | string | 否 | 任务ID(单个取消) |
591
+ | targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
592
+ | targetType | string | 否 | 目标对象类型(批量取消) |
593
+ | type | string | 否 | 任务类型(批量取消) |
581
594
 
582
595
  返回空对象:
583
596
 
@@ -585,14 +598,14 @@ const signature = generateSignature({
585
598
  {}
586
599
  ```
587
600
 
588
- #### POST `{prefix}/retry`
601
+ ##### POST `{prefix}/retry`
589
602
 
590
603
  重试任务,需 `write` 权限。仅允许重试 `failed` 或 `canceled` 状态的任务。
591
604
 
592
- | 参数名 | 类型 | 必填 | 说明 |
593
- |---------|----------|----|--------|
594
- | id | string | 否 | 单个任务ID |
595
- | taskIds | array | 否 | 任务ID数组 |
605
+ | 参数名 | 类型 | 必填 | 说明 |
606
+ | ------- | ------ | ---- | ---------- |
607
+ | id | string | 否 | 单个任务ID |
608
+ | taskIds | array | 否 | 任务ID数组 |
596
609
 
597
610
  返回空对象:
598
611
 
@@ -600,15 +613,15 @@ const signature = generateSignature({
600
613
  {}
601
614
  ```
602
615
 
603
- #### POST `{prefix}/next`
616
+ ##### POST `{prefix}/next`
604
617
 
605
618
  处理等待回调的任务,无需认证。当任务设置了 `context.secret` 时需提供签名。
606
619
 
607
- | 参数名 | 类型 | 必填 | 说明 |
608
- |-----------|--------|----|------------------------------------------|
609
- | id | string | 是 | 任务ID |
610
- | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
611
- | result | string | 是 | JSON 格式结果字符串 |
620
+ | 参数名 | 类型 | 必填 | 说明 |
621
+ | --------- | ------ | ---- | -------------------------------------------------- |
622
+ | id | string | 是 | 任务ID |
623
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
624
+ | result | string | 是 | JSON 格式结果字符串 |
612
625
 
613
626
  成功处理时返回空对象:
614
627
 
@@ -616,17 +629,17 @@ const signature = generateSignature({
616
629
  {}
617
630
  ```
618
631
 
619
- #### POST `{prefix}/log`
632
+ ##### POST `{prefix}/log`
620
633
 
621
634
  记录任务日志,无需认证。当任务设置了 `context.secret` 时需提供签名。
622
635
 
623
- | 参数名 | 类型 | 必填 | 说明 |
624
- |-----------|--------|----|------------------------------------------|
625
- | id | string | 否 | 任务ID(body) |
626
- | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
627
- | data | object | 否 | 日志数据 |
628
- | message | string | 否 | 日志消息 |
629
- | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
636
+ | 参数名 | 类型 | 必填 | 说明 |
637
+ | --------- | ------ | ---- | -------------------------------------------------- |
638
+ | id | string | 否 | 任务ID(body) |
639
+ | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
640
+ | data | object | 否 | 日志数据 |
641
+ | message | string | 否 | 日志消息 |
642
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
630
643
 
631
644
  返回更新后的 Task 实例:
632
645
 
@@ -639,18 +652,21 @@ const signature = generateSignature({
639
652
  }
640
653
  ```
641
654
 
642
- #### POST `{prefix}/callback`
655
+ ##### POST `{prefix}/callback`
643
656
 
644
- 任务回调,无需认证。当任务设置了 `context.secret` 时需提供签名。
657
+ 任务回调,无需认证。当任务设置了 `context.secret` 时需提供签名。同一个接口既用于上报最终结果,也用于上报中间进度(见「回调进度上报」)。
645
658
 
646
- | 参数名 | 类型 | 必填 | 说明 |
647
- |-----------|--------|----|------------------------------------------|
648
- | id | string | 否 | 任务ID(body) |
649
- | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
650
- | code | number | 是 | 状态码,0 为成功 |
651
- | data | object | 否 | 回调数据 |
652
- | message | string | 否 | 回调消息 |
653
- | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
659
+ | 参数名 | 类型 | 必填 | 说明 |
660
+ | --------- | ------ | ---- | --------------------------------------------------- |
661
+ | id | string | 否 | 任务ID(body) |
662
+ | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
663
+ | code | number | 是 | 状态码,0 为成功 |
664
+ | data | object | 否 | 回调数据 |
665
+ | message | string | 否 | 回调消息 |
666
+ | progress | number | 否 | 任务进度 0-100;`code` 为 0 且小于 100 时仅上报进度 |
667
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
668
+
669
+ > `code` 必填,缺失时接口返回 400,任务状态不变(此前缺失会被当作失败回调)。
654
670
 
655
671
  成功处理时返回空对象:
656
672
 
@@ -658,23 +674,27 @@ const signature = generateSignature({
658
674
  {}
659
675
  ```
660
676
 
661
- #### GET `{prefix}/statistics`
677
+ ##### GET `{prefix}/statistics`
662
678
 
663
679
  获取任务统计概览,需 `statistics` 权限。
664
680
 
665
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
666
- |------------|--------|----|--------|--------------------------------|
667
- | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
668
- | timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
669
- | type | string | 否 | - | 按任务类型筛选 |
670
- | runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
681
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
682
+ | ---------- | ------ | ---- | ---------- | ----------------------------------- |
683
+ | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
684
+ | timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
685
+ | type | string | 否 | - | 按任务类型筛选 |
686
+ | runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
671
687
 
672
688
  返回值:
673
689
 
674
690
  ```json
675
691
  {
676
692
  "range": "7d",
677
- "rangeLabel": "最近7天",
693
+ "rangeLabel": "近7天",
694
+ "granularity": "day",
695
+ "startTime": "2026-05-23T16:00:00.000Z",
696
+ "endTime": "2026-05-29T12:00:00.000Z",
697
+ "buckets": [{ "key": "2026-05-24", "start": "2026-05-23T16:00:00.000Z", "end": "2026-05-24T16:00:00.000Z" }],
678
698
  "totalTasks": 0,
679
699
  "byStatus": {},
680
700
  "byType": {},
@@ -683,178 +703,190 @@ const signature = generateSignature({
683
703
  "recentTrendByStatus": [],
684
704
  "recentTrendByType": [],
685
705
  "durationTrend": [],
706
+ "duration": {},
686
707
  "hourlyTrend": [],
687
708
  "hourlyCompletionTrend": []
688
709
  }
689
710
  ```
690
711
 
691
- #### GET `{prefix}/statistics/sse`
712
+ 趋势按 `granularity` 分桶,每个桶单独查询,`recentTrend` / `recentTrendByStatus` 覆盖全部桶(无数据补 0),`date` 为桶 key:
713
+
714
+ | range | granularity | 桶数 | 桶 key 格式 |
715
+ | ----- | ----------- | ---- | -------------------- |
716
+ | `7d` | `day` | 7 | `YYYY-MM-DD` |
717
+ | `1m` | `day` | 30 | `YYYY-MM-DD` |
718
+ | `3m` | `week` | 13 | `YYYY-MM-DD`(周一) |
719
+ | `1y` | `month` | 12 | `YYYY-MM` |
720
+
721
+ `duration` 为范围内耗时汇总(平均等待 / 执行 / 总耗时,毫秒),含 `byType`、`byRunnerType`、`byTypeByRunnerType` 拆分。
722
+
723
+ ##### GET `{prefix}/statistics/sse`
692
724
 
693
725
  SSE 实时推送任务统计数据,需 `statistics` 权限。
694
726
 
695
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
696
- |------------|--------|----|--------|------------------|
697
- | range | string | 否 | `'7d'` | 时间范围 |
698
- | timezone | string | 否 | 服务器时区 | 时区 |
699
- | type | string | 否 | - | 按任务类型筛选 |
700
- | runnerType | string | 否 | - | 按执行方式筛选 |
701
- | interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
727
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
728
+ | ---------- | ------ | ---- | ---------- | ----------------------------- |
729
+ | range | string | 否 | `'7d'` | 时间范围 |
730
+ | timezone | string | 否 | 服务器时区 | 时区 |
731
+ | type | string | 否 | - | 按任务类型筛选 |
732
+ | runnerType | string | 否 | - | 按执行方式筛选 |
733
+ | interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
702
734
 
703
- ### 程序化 API
735
+ #### 程序化 API
704
736
 
705
737
  通过 `fastify.task.services` 访问。
706
738
 
707
- #### 任务管理
739
+ ##### 任务管理
708
740
 
709
- | 方法签名 | 说明 |
710
- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
741
+ | 方法签名 | 说明 |
742
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
711
743
  | `services.create({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, priority, parentTaskId, maxRetries, timeout, context, options })` | 创建任务,返回 Task 实例 |
712
- | `services.detail({ id })` | 获取任务详情,返回 Task 实例 |
713
- | `services.list({ filter, perPage, currentPage, sort })` | 获取任务列表,返回 `{ pageData, totalCount }` |
714
- | `services.complete({ id, userId, status, output, error })` | 手动完成任务 |
715
- | `services.cancel({ id, targetId, targetType, type })` | 取消任务,支持单个或批量 |
716
- | `services.retry({ id, taskIds })` | 重试任务,仅允许 `failed`/`canceled` 状态 |
717
- | `services.waitingComplete({ id, pollInterval, maxPollTimes })` | 等待任务完成(轮询),返回任务输出数据 |
744
+ | `services.detail({ id })` | 获取任务详情,返回 Task 实例 |
745
+ | `services.list({ filter, perPage, currentPage, sort })` | 获取任务列表,返回 `{ pageData, totalCount }` |
746
+ | `services.complete({ id, userId, status, output, error })` | 手动完成任务 |
747
+ | `services.cancel({ id, targetId, targetType, type })` | 取消任务,支持单个或批量 |
748
+ | `services.retry({ id, taskIds })` | 重试任务,仅允许 `failed`/`canceled` 状态 |
749
+ | `services.waitingComplete({ id, pollInterval, maxPollTimes })` | 等待任务完成(轮询),返回任务输出数据 |
718
750
 
719
751
  **services.create 参数:**
720
752
 
721
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
722
- |--------------|--------|----|-----------|----------|
723
- | userId | string | 否 | - | 用户ID |
724
- | input | object | 否 | - | 输入数据 |
725
- | type | string | 是 | - | 任务类型 |
726
- | targetId | string | 是 | - | 目标对象ID |
727
- | targetType | string | 是 | - | 目标对象类型 |
728
- | runnerType | string | 否 | - | 执行者类型 |
729
- | delay | number | 否 | `0` | 延迟执行秒数 |
730
- | scriptName | string | 否 | - | 脚本名称 |
731
- | priority | number | 否 | `0` | 优先级 |
732
- | parentTaskId | string | 否 | - | 父任务ID |
733
- | maxRetries | number | 否 | `0` | 最大重试次数 |
734
- | timeout | number | 否 | `3600000` | 超时时间(毫秒) |
735
- | context | object | 否 | `{}` | 初始上下文 |
736
- | options | object | 否 | - | 扩展选项 |
753
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
754
+ | ------------ | ------ | ---- | --------- | ---------------- |
755
+ | userId | string | 否 | - | 用户ID |
756
+ | input | object | 否 | - | 输入数据 |
757
+ | type | string | 是 | - | 任务类型 |
758
+ | targetId | string | 是 | - | 目标对象ID |
759
+ | targetType | string | 是 | - | 目标对象类型 |
760
+ | runnerType | string | 否 | - | 执行者类型 |
761
+ | delay | number | 否 | `0` | 延迟执行秒数 |
762
+ | scriptName | string | 否 | - | 脚本名称 |
763
+ | priority | number | 否 | `0` | 优先级 |
764
+ | parentTaskId | string | 否 | - | 父任务ID |
765
+ | maxRetries | number | 否 | `0` | 最大重试次数 |
766
+ | timeout | number | 否 | `3600000` | 超时时间(毫秒) |
767
+ | context | object | 否 | `{}` | 初始上下文 |
768
+ | options | object | 否 | - | 扩展选项 |
737
769
 
738
770
  **services.waitingComplete 参数:**
739
771
 
740
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
741
- |--------------|--------|----|--------|----------|
742
- | id | string | 是 | - | 任务ID |
743
- | pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
744
- | maxPollTimes | number | 否 | `20` | 最大轮询次数 |
772
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
773
+ | ------------ | ------ | ---- | ------ | ---------------- |
774
+ | id | string | 是 | - | 任务ID |
775
+ | pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
776
+ | maxPollTimes | number | 否 | `20` | 最大轮询次数 |
745
777
 
746
- #### 回调与日志
778
+ ##### 回调与日志
747
779
 
748
- | 方法签名 | 说明 |
749
- |--------------------------------------------------------------------------|--------------------------|
750
- | `services.processNext({ id, signature, result })` | 处理等待回调的任务,需签名验证 |
751
- | `services.callback({ id, code, data, message })` | 任务回调(内部调用,无需签名) |
752
- | `services.callbackWithSignature({ id, code, data, message, signature })` | 任务回调(外部调用,需签名验证) |
753
- | `services.log({ id, taskId, data, message })` | 记录日志(内部调用,无需签名),最多 100 条 |
754
- | `services.logWithSignature({ id, taskId, data, message, signature })` | 记录日志(外部调用,需签名验证) |
780
+ | 方法签名 | 说明 |
781
+ | ---------------------------------------------------------------------------------- | ------------------------------------------- |
782
+ | `services.processNext({ id, signature, result })` | 处理等待回调的任务,需签名验证 |
783
+ | `services.callback({ id, code, data, message, progress })` | 任务回调(内部调用,无需签名) |
784
+ | `services.callbackWithSignature({ id, code, data, message, progress, signature })` | 任务回调(外部调用,需签名验证) |
785
+ | `services.log({ id, taskId, data, message })` | 记录日志(内部调用,无需签名),最多 100 条 |
786
+ | `services.logWithSignature({ id, taskId, data, message, signature })` | 记录日志(外部调用,需签名验证) |
755
787
 
756
- #### 系统调度
788
+ ##### 系统调度
757
789
 
758
- | 方法签名 | 说明 |
759
- |--------------------------------------------|------------------------------------------------------|
760
- | `services.runner()` | 执行系统任务,由 cron 定时调用 |
761
- | `services.claimPendingTasks(limit)` | 按优先级和开始时间认领待执行系统任务,返回已认领任务列表 |
762
- | `services.processSystemTask(task, opts)` | 执行系统任务;`opts.claimed` 为 `true` 时跳过重复置为 running |
763
- | `services.resetAll({ staleOnly, before })` | 重置 running 任务为 pending;`staleOnly` 为 `true` 时只恢复陈旧任务 |
764
- | `services.append({ name, dir, dirs, scriptName, tasks, override })` | 运行时动态添加任务声明,返回 `{ dirs, tasks, skippedTasks }` |
790
+ | 方法签名 | 说明 |
791
+ | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
792
+ | `services.runner()` | 执行系统任务,由 cron 定时调用 |
793
+ | `services.claimPendingTasks(limit)` | 按优先级和开始时间认领待执行系统任务,返回已认领任务列表 |
794
+ | `services.processSystemTask(task, opts)` | 执行系统任务;`opts.claimed` 为 `true` 时跳过重复置为 running |
795
+ | `services.resetAll({ staleOnly, before })` | 重置 running 任务为 pending;`staleOnly` 为 `true` 时只恢复陈旧任务 |
796
+ | `services.append({ name, dir, dirs, scriptName, tasks, override })` | 运行时动态添加任务声明,返回 `{ dirs, tasks, skippedTasks }` |
765
797
 
766
798
  **services.append 参数:**
767
799
 
768
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
769
- |-------------|---------|----|----------------|-----------------------------------------|
770
- | name | string | 否 | `options.name` | 本次 append 注册的任务命名空间,插件包通常传自身 `options.name` |
771
- | dir | string | 否 | - | 任务脚本目录,等价于单项 `dirs` |
772
- | dirs | array | 否 | - | 任务脚本目录列表 |
773
- | scriptName | string | 否 | `'index'` | 本次 append 注册任务的默认脚本名 |
774
- | tasks | object | 否 | - | 任务声明映射,支持函数简写或对象配置 |
775
- | override | boolean | 否 | `false` | 是否覆盖已存在的同名任务声明 |
800
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
801
+ | ---------- | ------- | ---- | -------------- | --------------------------------------------------------------- |
802
+ | name | string | 否 | `options.name` | 本次 append 注册的任务命名空间,插件包通常传自身 `options.name` |
803
+ | dir | string | 否 | - | 任务脚本目录,等价于单项 `dirs` |
804
+ | dirs | array | 否 | - | 任务脚本目录列表 |
805
+ | scriptName | string | 否 | `'index'` | 本次 append 注册任务的默认脚本名 |
806
+ | tasks | object | 否 | - | 任务声明映射,支持函数简写或对象配置 |
807
+ | override | boolean | 否 | `false` | 是否覆盖已存在的同名任务声明 |
776
808
 
777
809
  **tasks[type] 对象配置:**
778
810
 
779
- | 属性名 | 类型 | 必填 | 默认值 | 说明 |
780
- |---------------|----------------|----|-----|-----------------------------------------|
781
- | handler | function | 否 | - | 任务成功后的处理函数 |
782
- | errorHandler | function | 否 | - | 当前任务类型自己的错误处理函数 |
783
- | next | string / array | 否 | - | 成功后创建的下一任务;数组模式从 `output.next` 中选择下一任务 |
811
+ | 属性名 | 类型 | 必填 | 默认值 | 说明 |
812
+ | ------------ | -------------- | ---- | ------ | ------------------------------------------------------------- |
813
+ | handler | function | 否 | - | 任务成功后的处理函数 |
814
+ | errorHandler | function | 否 | - | 当前任务类型自己的错误处理函数 |
815
+ | next | string / array | 否 | - | 成功后创建的下一任务;数组模式从 `output.next` 中选择下一任务 |
784
816
 
785
817
  > **关键设计**:`append.scriptName` 只影响本次 append 注册的任务。未传时固定使用 `index.js`,不会使用主项目注册 task 时的
786
818
  > `options.scriptName`。
787
819
 
788
- #### 统计查询
820
+ ##### 统计查询
789
821
 
790
- | 方法签名 | 说明 |
791
- |----------------------------------------------------------------------------------|--------------|
822
+ | 方法签名 | 说明 |
823
+ | -------------------------------------------------------------------------------- | -------------------- |
792
824
  | `services.queryStatistics({ range, timezone, type, runnerType })` | 查询任务统计数据 |
793
825
  | `services.sseStatistics({ range, timezone, type, runnerType, interval }, reply)` | SSE 实时推送统计数据 |
794
826
 
795
827
  **services.queryStatistics 参数:**
796
828
 
797
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
798
- |------------|--------|----|--------|--------------------------------|
799
- | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
800
- | timezone | string | 否 | 服务器时区 | 时区 |
801
- | type | string | 否 | - | 按任务类型筛选 |
802
- | runnerType | string | 否 | - | 按执行方式筛选 |
829
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
830
+ | ---------- | ------ | ---- | ---------- | ----------------------------------- |
831
+ | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
832
+ | timezone | string | 否 | 服务器时区 | 时区 |
833
+ | type | string | 否 | - | 按任务类型筛选 |
834
+ | runnerType | string | 否 | - | 按执行方式筛选 |
803
835
 
804
836
  **services.sseStatistics 参数:**
805
837
 
806
- | 参数名 | 类型 | 必填 | 默认值 | 说明 |
807
- |------------|--------|----|--------|-------------------------|
808
- | range | string | 否 | `'7d'` | 时间范围 |
809
- | timezone | string | 否 | 服务器时区 | 时区 |
810
- | type | string | 否 | - | 按任务类型筛选 |
811
- | runnerType | string | 否 | - | 按执行方式筛选 |
812
- | interval | number | 否 | `5` | 推送间隔(秒) |
813
- | reply | object | 是 | - | Fastify reply 对象(第二个参数) |
838
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
839
+ | ---------- | ------ | ---- | ---------- | -------------------------------- |
840
+ | range | string | 否 | `'7d'` | 时间范围 |
841
+ | timezone | string | 否 | 服务器时区 | 时区 |
842
+ | type | string | 否 | - | 按任务类型筛选 |
843
+ | runnerType | string | 否 | - | 按执行方式筛选 |
844
+ | interval | number | 否 | `5` | 推送间隔(秒) |
845
+ | reply | object | 是 | - | Fastify reply 对象(第二个参数) |
814
846
 
815
- ### 数据模型
847
+ #### 数据模型
816
848
 
817
- #### Task
849
+ ##### Task
818
850
 
819
- | 属性名 | 类型 | 说明 |
820
- |-----------------|-----------------|-----------------------------------------------------------------------------------------|
821
- | type | string | 任务类型 |
822
- | scriptName | string | 任务脚本名称 |
823
- | targetId | string | 任务目标对象ID |
851
+ | 属性名 | 类型 | 说明 |
852
+ | --------------- | --------------- | ----------------------------------------------------------------------------------------------- |
853
+ | type | string | 任务类型 |
854
+ | scriptName | string | 任务脚本名称 |
855
+ | targetId | string | 任务目标对象ID |
824
856
  | targetType | string | 任务目标对象类型 |
825
- | runnerType | string | 执行者类型:`manual` / `system`,默认 `manual` |
826
- | priority | number | 任务优先级,数值越大越优先,默认 0 |
827
- | parentTaskId | string | 父任务ID,用于任务依赖 |
857
+ | runnerType | string | 执行者类型:`manual` / `system`,默认 `manual` |
858
+ | priority | number | 任务优先级,数值越大越优先,默认 0 |
859
+ | parentTaskId | string | 父任务ID,用于任务依赖 |
828
860
  | retryCount | number | 已重试次数,默认 0 |
829
- | maxRetries | number | 最大重试次数,0 表示不自动重试 |
830
- | timeout | number | 任务超时时间(毫秒),0 表示不超时,默认 3600000 |
861
+ | maxRetries | number | 最大重试次数,0 表示不自动重试 |
862
+ | timeout | number | 任务超时时间(毫秒),0 表示不超时,默认 3600000 |
831
863
  | startTime | Date | 任务最早执行时间 |
832
- | startedAt | Date | 任务实际开始执行时间 |
833
- | completedAt | Date | 任务完成时间 |
834
- | completedUserId | string | 完成任务的用户ID |
835
- | input | object | 输入数据 |
836
- | output | object | 输出数据 |
837
- | error | string / object | 错误信息 |
864
+ | startedAt | Date | 任务实际开始执行时间 |
865
+ | completedAt | Date | 任务完成时间 |
866
+ | completedUserId | string | 完成任务的用户ID |
867
+ | input | object | 输入数据 |
868
+ | output | object | 输出数据 |
869
+ | error | string / object | 错误信息 |
838
870
  | status | string | 任务状态:`pending` / `running` / `waiting` / `success` / `failed` / `canceled`,默认 `pending` |
839
- | context | object | 上下文信息 |
840
- | pollResults | array | 轮询执行结果 |
841
- | pollCount | number | 轮询次数,默认 0 |
842
- | progress | number | 任务进度 (0-100),默认 0 |
843
- | msg | string | 任务消息 |
844
- | options | object | 任务扩展选项(含 `logs` 日志数组) |
871
+ | context | object | 上下文信息 |
872
+ | pollResults | array | 轮询执行结果 |
873
+ | pollCount | number | 轮询次数,默认 0 |
874
+ | progress | number | 任务进度 (0-100),默认 0 |
875
+ | msg | string | 任务消息 |
876
+ | options | object | 任务扩展选项(含 `logs` 日志数组) |
845
877
 
846
878
  **关联关系:**
847
879
 
848
- | 关联 | 外键 | 说明 |
849
- |----------------|-------------------|---------------------------|
880
+ | 关联 | 外键 | 说明 |
881
+ | -------------- | ----------------- | ----------------------------- |
850
882
  | belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
851
883
  | belongsTo User | `completedUserId` | 完成人,`as: 'completedUser'` |
852
884
  | belongsTo Task | `parentTaskId` | 父任务,`as: 'parentTask'` |
853
885
 
854
886
  **索引:**
855
887
 
856
- | 索引字段 |
857
- |--------------------------------|
888
+ | 索引字段 |
889
+ | ------------------------------ |
858
890
  | `created_at` |
859
891
  | `status` |
860
892
  | `type` |
@@ -865,61 +897,117 @@ SSE 实时推送任务统计数据,需 `statistics` 权限。
865
897
  | `parent_task_id` |
866
898
  | `priority` |
867
899
 
868
- ### 机制说明
900
+ #### 机制说明
869
901
 
870
- #### 任务声明与命名空间
902
+ ##### 任务声明与命名空间
871
903
 
872
904
  任务类型由 task registry 统一维护。主项目注册 task 插件时可以通过 `task` 直接声明任务,插件包可以通过 `services.append` 声明自己的任务。
873
905
 
874
- | 来源 | 命名空间 | 可访问任务范围 |
875
- |----------------|---------------|-----------------------------------------------|
876
- | 主项目 `task` | `options.name` | 主项目任务、插件任务;插件任务需使用 `{append.name}.任务名` |
877
- | 插件 `append` | `append.name` | 当前插件任务、其他插件任务;不能访问主项目任务 |
878
- | `create({type})` | 根据任务名解析 | 无点号时优先主项目任务;跨插件或指定命名空间时使用 `命名空间.任务名` |
906
+ | 来源 | 命名空间 | 可访问任务范围 |
907
+ | ---------------- | -------------- | -------------------------------------------------------------------- |
908
+ | 主项目 `task` | `options.name` | 主项目任务、插件任务;插件任务需使用 `{append.name}.任务名` |
909
+ | 插件 `append` | `append.name` | 当前插件任务、其他插件任务;不能访问主项目任务 |
910
+ | `create({type})` | 根据任务名解析 | 无点号时优先主项目任务;跨插件或指定命名空间时使用 `命名空间.任务名` |
879
911
 
880
912
  `append` 注册的任务可以没有 `handler`,只要存在对应执行脚本即可执行。主项目原有的 `{ [type]: handler }` 写法仍然兼容。
881
913
 
882
914
  > **关键设计**:插件内的裸任务名只在当前插件命名空间内解析;跨插件访问必须使用 `包名.任务名`。插件任务不允许访问主项目任务。
883
915
 
884
- #### 成功与错误处理
916
+ ##### 成功与错误处理
885
917
 
886
918
  任务执行成功后会先调用当前任务声明的 `handler`,再创建 `next` 任务,最后将当前任务更新为 `success` 并采集统计数据。
887
919
 
888
- | 阶段 | 行为 |
889
- |---------|-----------------------------------------|
890
- | handler | 如果声明了 `handler`,等待它执行完成;未声明则跳过 |
891
- | next | 如果声明了 `next`,解析并创建下一任务 |
920
+ | 阶段 | 行为 |
921
+ | ------- | ---------------------------------------------------- |
922
+ | handler | 如果声明了 `handler`,等待它执行完成;未声明则跳过 |
923
+ | next | 如果声明了 `next`,解析并创建下一任务 |
892
924
  | success | 更新 `status/output/progress/completedAt` 并采集统计 |
893
925
 
894
926
  任务最终失败时会触发错误处理:
895
927
 
896
- | 处理器 | 触发时机 |
897
- |------------------------|------------------------------|
898
- | `tasks[type].errorHandler` | 当前任务最终失败时优先调用 |
899
- | `options.errorHandler` | 未配置任务级错误处理,或任务级错误处理抛错时调用 |
928
+ | 处理器 | 触发时机 |
929
+ | -------------------------- | ------------------------------------------------ |
930
+ | `tasks[type].errorHandler` | 当前任务最终失败时优先调用 |
931
+ | `options.errorHandler` | 未配置任务级错误处理,或任务级错误处理抛错时调用 |
900
932
 
901
933
  > **关键设计**:自动重试期间不会触发最终错误处理;只有任务最终进入 `failed` 状态时才调用错误处理函数。
902
934
 
903
- #### next 链式任务
935
+ ##### 取消处理
936
+
937
+ `cancel` 把任务置为 `canceled` 后,会通知任务声明的取消处理器,方便业务把自己的状态(如关联的业务记录)同步为已取消。
938
+
939
+ | 处理器 | 触发时机 |
940
+ | --------------------------- | ---------------------------- |
941
+ | `tasks[type].cancelHandler` | 任务被取消后优先调用 |
942
+ | `options.cancelHandler` | 未配置任务级取消处理器时调用 |
943
+
944
+ 处理器参数为 `{ task, context }`,其中 `task.status` 已是 `canceled`。
945
+
946
+ ```js
947
+ fastify.register(fastifyTask, {
948
+ task: {
949
+ Readiness: {
950
+ handler: onSuccess,
951
+ errorHandler: onFailed,
952
+ // 任务被取消后,把关联的业务数据同步为已取消
953
+ cancelHandler: async ({ task }) => {
954
+ await markCanceled(task.context.runId);
955
+ }
956
+ }
957
+ }
958
+ });
959
+ ```
960
+
961
+ > **关键设计**:只有本次 `cancel` 真正完成 `pending` / `running` → `canceled` 的任务才会触发处理器,已结束的任务不会重复通知;批量取消按任务逐个触发。取消已经生效,处理器抛错只记录日志,不会让 `cancel` 失败。
962
+
963
+ ##### 回调进度上报
964
+
965
+ 外部服务使用同一个 `{prefix}/callback` 接口上报进度和最终结果,由 `code` 与 `progress` 的组合决定含义:
966
+
967
+ | `code` | `progress` | 含义 |
968
+ | ------ | ------------ | --------------------------------------------------------------- |
969
+ | `0` | `0` ~ `<100` | 进度上报:更新任务 `progress`,记一条日志,任务保持原状态不结束 |
970
+ | `0` | 不传 / `100` | 最终成功:与原行为一致,任务置为 `success` 并触发 `handler` |
971
+ | 非 `0` | 任意 | 最终失败:任务置为 `failed`(`message` 作为错误)并触发错误处理 |
972
+
973
+ ```js
974
+ // 上报进度(任务继续保持 running)
975
+ await fetch(`${origin}/api/task/callback?taskId=${taskId}`, {
976
+ method: 'POST',
977
+ headers: { 'content-type': 'application/json' },
978
+ body: JSON.stringify({ code: 0, progress: 40, message: '解析简历中' })
979
+ });
980
+
981
+ // 上报最终结果(不带 progress,行为与之前一致)
982
+ await fetch(`${origin}/api/task/callback?taskId=${taskId}`, {
983
+ method: 'POST',
984
+ headers: { 'content-type': 'application/json' },
985
+ body: JSON.stringify({ code: 0, data: { score: 90 } })
986
+ });
987
+ ```
988
+
989
+ > **关键设计**:进度上报只对 `pending` / `running` / `waiting` 的任务生效,任务已结束(含已取消)时静默忽略,不写日志;`progress` 会四舍五入为整数,超出 0-100 时接口返回 400。进度上报不会触发 `handler`、`next` 与错误处理。
990
+
991
+ ##### next 链式任务
904
992
 
905
993
  `tasks[type].next` 只声明下一任务名称,不声明下一任务的执行参数。
906
994
 
907
- | next 配置 | 解析规则 |
908
- |---------|-----------------------------------------|
909
- | string | 固定使用该任务名作为下一任务 |
910
- | array | 从当前任务 `output.next` 读取任务名,并要求它包含在数组中 |
995
+ | next 配置 | 解析规则 |
996
+ | --------- | --------------------------------------------------------- |
997
+ | string | 固定使用该任务名作为下一任务 |
998
+ | array | 从当前任务 `output.next` 读取任务名,并要求它包含在数组中 |
911
999
 
912
1000
  下一任务创建规则:
913
1001
 
914
- | 字段 | 取值 |
915
- |--------------|---------------------------------------------------|
916
- | `type` | 解析后的下一任务声明类型 |
917
- | `input` | 当前任务 `output`,并将 `input.name` 设为当前任务 `input.name` |
918
- | `targetType` | 固定为 `task` |
919
- | `targetId` | 当前任务 id |
920
- | `parentTaskId` | 当前任务 id |
921
- | `context` | 当前任务 `context` 的深拷贝 |
922
- | `runnerType` | 当前任务 `runnerType` |
1002
+ | 字段 | 取值 |
1003
+ | -------------- | -------------------------------------------------------------- |
1004
+ | `type` | 解析后的下一任务声明类型 |
1005
+ | `input` | 当前任务 `output`,并将 `input.name` 设为当前任务 `input.name` |
1006
+ | `targetType` | 固定为 `task` |
1007
+ | `targetId` | 当前任务 id |
1008
+ | `parentTaskId` | 当前任务 id |
1009
+ | `context` | 当前任务 `context` 的深拷贝 |
1010
+ | `runnerType` | 当前任务 `runnerType` |
923
1011
 
924
1012
  如果 `next` 是数组且 `output.next` 缺失,或 `output.next` 不在允许列表中,当前任务会转为 `failed`。
925
1013
 
@@ -1022,12 +1110,15 @@ await fastify.task.services.create({
1022
1110
 
1023
1111
  ```js
1024
1112
  module.exports = async (fastify, options, { task }) => {
1025
- const approvals = [...(task.context.approvals || []), {
1026
- node: 'manager',
1027
- approver: 'u-manager-1',
1028
- result: 'approved',
1029
- time: new Date().toISOString()
1030
- }];
1113
+ const approvals = [
1114
+ ...(task.context.approvals || []),
1115
+ {
1116
+ node: 'manager',
1117
+ approver: 'u-manager-1',
1118
+ result: 'approved',
1119
+ time: new Date().toISOString()
1120
+ }
1121
+ ];
1031
1122
 
1032
1123
  await task.update({
1033
1124
  context: {
@@ -1048,12 +1139,15 @@ module.exports = async (fastify, options, { task }) => {
1048
1139
 
1049
1140
  ```js
1050
1141
  module.exports = async (fastify, options, { task }) => {
1051
- const approvals = [...(task.context.approvals || []), {
1052
- node: 'finance',
1053
- approver: 'u-finance-1',
1054
- result: 'approved',
1055
- time: new Date().toISOString()
1056
- }];
1142
+ const approvals = [
1143
+ ...(task.context.approvals || []),
1144
+ {
1145
+ node: 'finance',
1146
+ approver: 'u-finance-1',
1147
+ result: 'approved',
1148
+ time: new Date().toISOString()
1149
+ }
1150
+ ];
1057
1151
 
1058
1152
  await task.update({
1059
1153
  context: {
@@ -1074,32 +1168,32 @@ module.exports = async (fastify, options, { task }) => {
1074
1168
  在这个流程中,`finance-approval` 会拿到主管审批后复制过来的 `context.approvals`;`legal-approval` 或 `archive-contract`
1075
1169
  也会继续拿到财务审批后更新过的 `context`。每次创建下一任务都会深拷贝当前任务完成时的 `context`,不会和上一任务共享同一个对象引用。
1076
1170
 
1077
- #### 签名验证
1171
+ ##### 签名验证
1078
1172
 
1079
1173
  使用 HMAC-SHA256 算法,签名数据格式为 `{id}|{data}`,其中 `data` 为 JSON 字符串或原始字符串。
1080
1174
 
1081
- | 接口 | 签名 data 内容 |
1082
- |-------------------------|----------------------------------------|
1083
- | `processNext` | `result` 参数值(原始 JSON 字符串) |
1084
- | `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
1085
- | `callbackWithSignature` | `{ code, data, message }` 对象的 JSON 序列化 |
1175
+ | 接口 | 签名 data 内容 |
1176
+ | ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
1177
+ | `processNext` | `result` 参数值(原始 JSON 字符串) |
1178
+ | `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
1179
+ | `callbackWithSignature` | `{ code, data, message, progress }` 对象的 JSON 序列化(未传 `progress` 时与 `{ code, data, message }` 完全一致) |
1086
1180
 
1087
1181
  > **关键设计**:未设置 `context.secret` 时 `verifySignature` 直接返回 `true`,不阻塞无密钥任务的回调。
1088
1182
 
1089
- #### 重试策略
1183
+ ##### 重试策略
1090
1184
 
1091
1185
  任务执行失败时,判断是否满足自动重试条件(`retryCount < maxRetries`):
1092
1186
 
1093
- | 条件 | 行为 |
1094
- |----------------------------|-----------------------------------------|
1187
+ | 条件 | 行为 |
1188
+ | -------------------------- | ----------------------------------------------------- |
1095
1189
  | `retryCount < maxRetries` | 重置为 `pending`,`startTime` 设为当前时间 + 退避延迟 |
1096
- | `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
1190
+ | `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
1097
1191
 
1098
1192
  退避公式:`delay = retryBaseDelay × 2^(retryCount - 1)`
1099
1193
 
1100
1194
  > **关键设计**:手动调用 `retry` 接口会重置 `retryCount` 为 0,重新开始重试计数。
1101
1195
 
1102
- #### 超时检测
1196
+ ##### 超时检测
1103
1197
 
1104
1198
  每次 `runner` 执行时先调用 `checkTimeout`,扫描所有 `running` / `waiting` 且 `timeout > 0` 的任务:
1105
1199
 
@@ -1108,38 +1202,38 @@ module.exports = async (fastify, options, { task }) => {
1108
1202
  ```
1109
1203
 
1110
1204
  > **关键设计**:`taskTimeout`(全局配置)和 `timeout`(任务级别)均使用毫秒作为单位。全局 `taskTimeout` 在 executor 执行时通过
1111
- `Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
1205
+ > `Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
1112
1206
 
1113
- #### 任务认领与启动恢复
1207
+ ##### 任务认领与启动恢复
1114
1208
 
1115
- | 机制 | 表达式 / 条件 | 说明 |
1116
- |------|-------------------------------------------------------------|-----------------------------------------------------|
1117
- | 认领候选 | `runnerType = system`、`status = pending`、`startTime <= now` | 按 `priority DESC`、`startTime ASC` 查询候选任务 |
1118
- | 原子认领 | `id + runnerType + status + startTime` 条件更新 | 只有更新影响 1 行的任务会被当前实例执行 |
1119
- | 启动恢复 | `resetAll({ staleOnly: true })` | 启动时只恢复超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务 |
1120
- | 手动重置 | `resetAll()` | 不传 `staleOnly` 时会重置所有 `running` 任务 |
1209
+ | 机制 | 表达式 / 条件 | 说明 |
1210
+ | -------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
1211
+ | 认领候选 | `runnerType = system`、`status = pending`、`startTime <= now` | 按 `priority DESC`、`startTime ASC` 查询候选任务 |
1212
+ | 原子认领 | `id + runnerType + status + startTime` 条件更新 | 只有更新影响 1 行的任务会被当前实例执行 |
1213
+ | 启动恢复 | `resetAll({ staleOnly: true })` | 启动时只恢复超过 `recoverRunningTaskAfter` 的陈旧 `running` 任务 |
1214
+ | 手动重置 | `resetAll()` | 不传 `staleOnly` 时会重置所有 `running` 任务 |
1121
1215
 
1122
1216
  > **关键设计**:多实例部署时,任务执行前必须先认领;启动恢复默认只处理陈旧任务,避免误中断其他实例正在执行的任务。
1123
1217
 
1124
- #### 父子任务依赖
1218
+ ##### 父子任务依赖
1125
1219
 
1126
1220
  当父任务执行成功后,自动激活 `parentTaskId` 指向该父任务且状态为 `pending` 的子任务:
1127
1221
 
1128
- | 子任务 runnerType | 激活行为 |
1129
- |----------------|-----------------------------|
1130
- | `system` | 立即调用 `processSystemTask` 执行 |
1131
- | `manual` | 保持 `pending`,等待手动执行 |
1222
+ | 子任务 runnerType | 激活行为 |
1223
+ | ----------------- | --------------------------------- |
1224
+ | `system` | 立即调用 `processSystemTask` 执行 |
1225
+ | `manual` | 保持 `pending`,等待手动执行 |
1132
1226
 
1133
1227
  > **关键设计**:只有父任务 **成功** 后才触发子任务,失败或取消不会激活子任务。
1134
1228
 
1135
- #### 统计数据采集
1229
+ ##### 统计数据采集
1136
1230
 
1137
1231
  任务完成时通过 `@kne/fastify-statistics` 采集数据,channel 格式为 `{type}:{runnerType}:{completedHour}`,采集维度:
1138
1232
 
1139
- | 维度 | 单位 | 说明 |
1140
- |-----------------------------|-------|-------------------------------|
1141
- | total | count | 总完成数 |
1142
- | success / failed / canceled | count | 按状态计数 |
1233
+ | 维度 | 单位 | 说明 |
1234
+ | --------------------------- | ----- | ----------------------------------- |
1235
+ | total | count | 总完成数 |
1236
+ | success / failed / canceled | count | 按状态计数 |
1143
1237
  | waitingTime | ms | 等待时长(startedAt - createdAt) |
1144
1238
  | executionTime | ms | 执行时长(completedAt - startedAt) |
1145
- | totalTime | ms | 总时长(completedAt - createdAt) |
1239
+ | totalTime | ms | 总时长(completedAt - createdAt) |