@kne/fastify-task 3.0.0-alpha.3 → 3.0.0-alpha.5

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
@@ -14,335 +14,609 @@ npm i --save @kne/fastify-task
14
14
 
15
15
  @kne/fastify-task 是一个 Fastify 插件,用于任务编排、追踪任务执行状态和结果。支持系统自动执行和手动执行两种模式,提供完整的任务生命周期管理。
16
16
 
17
- ### 主要特性
18
-
19
- - **任务创建与管理**:支持创建、取消、重试、完成任务
20
- - **多种执行模式**:支持系统自动执行(system)和手动执行(manual)
21
- - **定时任务调度**:基于 cron 表达式的定时任务执行
22
- - **任务状态追踪**:实时追踪任务进度、轮询结果
23
- - **异步回调支持**:支持外部系统回调通知任务完成
24
- - **日志记录**:支持任务执行日志记录,最多保留100条
17
+ ### 核心架构与流程
25
18
 
26
- ### 使用场景
19
+ ```
20
+ 创建任务 (create)
21
+ ↓
22
+ pending(待执行)
23
+ ↓ (cron 调度 runner / 手动 complete)
24
+ running(执行中)
25
+ ├→ executor 执行任务脚本
26
+ │ ├→ 正常完成 → success
27
+ │ ├→ 调用 next() → waiting(等待外部回调)
28
+ │ └→ 异常失败 → 判断重试 → pending / failed
29
+ ├→ waiting → processNext / callbackWithSignature → success / failed
30
+ └→ 超时检测 (checkTimeout) → failed
31
+ ```
27
32
 
28
- - 文档导出、数据迁移等异步处理任务
29
- - 第三方 API 调用后异步回调处理
30
- - 定时批量数据处理
31
- - 需要追踪进度和状态的长时任务
33
+ > **关键设计**:cron 每次触发 `runner` 时,先执行 `checkTimeout` 检测超时任务,再按 **优先级降序 + startTime 升序** 取待执行系统任务,受 `limit` 并发上限控制。
32
34
 
33
- ### 任务状态流转
35
+ ### 核心概念详解
34
36
 
35
- | 状态 | 说明 |
36
- |----------|--------|
37
- | pending | 待执行 |
38
- | running | 执行中 |
39
- | waiting | 等待外部回调 |
40
- | success | 执行成功 |
41
- | failed | 执行失败 |
42
- | canceled | 已取消 |
37
+ #### 任务状态
43
38
 
44
- ### 签名验证
39
+ | 状态 | 说明 | 可流转到 |
40
+ |------|------|----------|
41
+ | `pending` | 待执行 | `running`、`canceled` |
42
+ | `running` | 执行中 | `success`、`failed`、`waiting`、`pending`(重试) |
43
+ | `waiting` | 等待外部回调 | `success`、`failed` |
44
+ | `success` | 执行成功 | 终态 |
45
+ | `failed` | 执行失败 | `pending`(重试) |
46
+ | `canceled` | 已取消 | `pending`(重试) |
45
47
 
46
- 当任务的 `context.secret` 设置了密钥时,外部调用需要提供 HMAC-SHA256 签名进行验证。
48
+ #### 执行模式
47
49
 
48
- #### 签名生成方法
50
+ | 模式 | runnerType | 触发方式 | 说明 |
51
+ |------|-----------|----------|------|
52
+ | 系统自动 | `system` | cron 定时调度 `runner` | 按优先级和 startTime 自动执行 |
53
+ | 手动执行 | `manual` | 用户通过 `complete` 接口完成 | 任务创建后等待人工操作 |
49
54
 
50
- ```javascript
51
- const crypto = require('node:crypto');
52
-
53
- function generateSignature({ secret, id, data }) {
54
- // data 可以是字符串或对象
55
- const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
56
- const dataToSign = `${id}|${dataStr}`;
57
- const hmac = crypto.createHmac('sha256', secret);
58
- hmac.update(dataToSign);
59
- return hmac.digest('hex');
60
- }
61
- ```
55
+ ### 主要特性
62
56
 
63
- #### 各接口签名数据格式
57
+ | 特性 | 说明 |
58
+ |------|------|
59
+ | 任务创建与管理 | 支持创建、取消、重试、完成任务 |
60
+ | 多种执行模式 | system 自动执行 / manual 手动执行 |
61
+ | 定时任务调度 | 基于 cron 表达式定时执行系统任务 |
62
+ | 任务状态追踪 | 实时追踪进度、轮询结果 |
63
+ | 异步回调支持 | 支持 `next` → `processNext`/`callback` 回调链路 |
64
+ | 日志记录 | 任务执行日志,最多保留 100 条 |
65
+ | 优先级与依赖 | 优先级排序 + 父子任务链式执行 |
66
+ | 自动重试 | 指数退避重试策略 |
67
+ | 超时控制 | 任务级别超时设置,超时自动标记 failed |
68
+ | 统计面板 | 任务统计数据查询 + SSE 实时推送 |
64
69
 
65
- | 接口 | data 格式 |
66
- |----------------------|----------------------------------|
67
- | processNext | `result` 字符串(JSON格式结果) |
68
- | logWithSignature | `{ data, message }` 对象 |
69
- | callbackWithSignature| `{ code, data, message }` 对象 |
70
+ ### 使用方法
70
71
 
71
- #### 示例
72
+ #### 插件注册与配置
72
73
 
73
74
  ```javascript
74
- // processNext 签名
75
- const result = JSON.stringify({ code: 0, data: { output: 'done' } });
76
- const signature = generateSignature({ secret: 'your-secret', id: 'task-1', data: result });
77
-
78
- // logWithSignature 签名
79
- const signature = generateSignature({
80
- secret: 'your-secret',
81
- id: 'task-1',
82
- data: { data: { key: 'value' }, message: '日志消息' }
75
+ // 基础注册
76
+ const fastify = require('fastify')();
77
+ fastify.register(require('@kne/fastify-task'), {
78
+ // 可选配置项,参见 api.md 配置项章节
83
79
  });
80
+ ```
84
81
 
85
- // callbackWithSignature 签名
86
- const signature = generateSignature({
87
- secret: 'your-secret',
88
- id: 'task-1',
89
- data: { code: 0, data: { result: 'done' }, message: '成功' }
82
+ ```javascript
83
+ // 带任务类型处理函数的注册
84
+ fastify.register(require('@kne/fastify-task'), {
85
+ task: {
86
+ 'export-excel': async ({ task, result, context }) => {
87
+ console.log('导出任务完成:', result);
88
+ },
89
+ 'send-email': async ({ task, result }) => {
90
+ // 发送邮件完成后的处理
91
+ }
92
+ }
90
93
  });
91
94
  ```
92
95
 
93
- ### 示例
94
-
95
- ### API
96
-
97
- ### 插件配置
98
-
99
- | 属性名 | 类型 | 默认值 | 说明 |
100
- |-------------------|----------|----------------|----------------------|
101
- | dbTableNamePrefix | string | 't_' | 数据库表名前缀 |
102
- | prefix | string | '/api/task' | API 路由前缀 |
103
- | name | string | 'task' | 命名空间名称 |
104
- | limit | number | 10 | 并发执行任务数上限 |
105
- | dir | string | 'libs/tasks' | 任务脚本目录 |
106
- | cronTime | string | '*/10 * * * *' | cron 执行周期,设为 null 禁用 |
107
- | scriptName | string | 'index' | 默认任务脚本名称 |
108
- | maxPollTimes | number | 20 | 最大轮询次数 |
109
- | pollInterval | number | 10000 | 轮询间隔(毫秒) |
110
- | getUserModel | function | - | 获取用户模型的函数 |
111
- | getAuthenticate | function | - | 获取认证中间件的函数 |
112
- | task | object | {} | 任务类型处理函数映射 |
113
-
114
- ### HTTP API
115
-
116
- #### 获取任务列表
117
-
118
- **GET** `{prefix}/list`
119
-
120
- | 参数名 | 类型 | 默认值 | 说明 |
121
- |------------------------------|--------|-----|------------|
122
- | perPage | number | 20 | 每页数量 |
123
- | currentPage | number | 1 | 当前页码 |
124
- | filter.id | string | - | 任务ID |
125
- | filter.targetId | string | - | 目标对象ID |
126
- | filter.targetName | string | - | 目标名称(模糊匹配) |
127
- | filter.type | string | - | 任务类型 |
128
- | filter.status | string | - | 任务状态 |
129
- | filter.runnerType | string | - | 执行者类型 |
130
- | filter.createdAt.startTime | string | - | 创建时间起始 |
131
- | filter.createdAt.endTime | string | - | 创建时间结束 |
132
- | filter.completedAt.startTime | string | - | 完成时间起始 |
133
- | filter.completedAt.endTime | string | - | 完成时间结束 |
134
- | sort | object | - | 排序规则 |
135
-
136
- **返回值**
137
-
138
- | 属性名 | 类型 | 说明 |
139
- |------------|--------|------|
140
- | pageData | array | 任务列表 |
141
- | totalCount | number | 总数量 |
142
-
143
- #### 手动完成任务
96
+ #### 任务脚本开发
144
97
 
145
- **POST** `{prefix}/complete`
98
+ 在 `dirs` 配置的目录下创建任务脚本,目录结构:
146
99
 
147
- | 参数名 | 类型 | 必填 | 说明 |
148
- |--------|--------|----|-------------------|
149
- | id | string | 是 | 任务ID |
150
- | status | string | 是 | 状态:success/failed |
151
- | error | string | 否 | 错误信息 |
152
- | msg | string | 否 | 消息 |
153
- | output | object | 否 | 输出数据 |
154
-
155
- #### 取消任务
156
-
157
- **POST** `{prefix}/cancel`
158
-
159
- | 参数名 | 类型 | 必填 | 说明 |
160
- |-----|--------|----|------|
161
- | id | string | 是 | 任务ID |
162
-
163
- #### 重试任务
164
-
165
- **POST** `{prefix}/retry`
100
+ ```
101
+ libs/tasks/
102
+ └── <任务类型>/
103
+ └── <scriptName>.js # 默认 scriptName 为 'index'
104
+ ```
166
105
 
167
- | 参数名 | 类型 | 必填 | 说明 |
168
- |---------|----------|----|--------|
169
- | id | string | 否 | 单个任务ID |
170
- | taskIds | string[] | 否 | 任务ID数组 |
106
+ **脚本模板:**
171
107
 
172
- #### 处理任务 Next
108
+ ```javascript
109
+ module.exports = async (fastify, options, { task, updateProgress, polling, next, log }) => {
110
+ const { input } = task;
111
+
112
+ // 更新进度 (0-100)
113
+ await updateProgress(50);
114
+
115
+ // 轮询外部服务
116
+ const result = await polling(async () => {
117
+ const res = await fetch('external-api');
118
+ return {
119
+ result: 'success | failed | pending',
120
+ data: res.data,
121
+ message: '消息',
122
+ progress: 80
123
+ };
124
+ }, {
125
+ maxPollTimes: 20,
126
+ pollInterval: 10000
127
+ });
128
+
129
+ // 等待外部回调(任务状态变为 waiting)
130
+ await next({
131
+ secret: '签名密钥',
132
+ // 其他上下文数据,回调时可在 context 中获取
133
+ });
134
+
135
+ return { /* 返回结果 */ };
136
+ };
137
+ ```
173
138
 
174
- **POST** `{prefix}/next`
139
+ #### executor 辅助方法
175
140
 
176
- | 参数名 | 类型 | 必填 | 说明 |
177
- |-----------|--------|----|----------------------------------------|
178
- | id | string | 是 | 任务ID |
179
- | signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
180
- | result | string | 是 | JSON格式的结果 |
141
+ | 方法签名 | 说明 |
142
+ |----------|------|
143
+ | `updateProgress(progress)` | 更新任务进度 (0-100) |
144
+ | `polling(callback, options)` | 轮询外部服务直到完成 |
145
+ | `next(context)` | 设置任务为 waiting 状态,返回 `false` 暂停执行 |
146
+ | `log({ data, message })` | 记录任务执行日志 |
181
147
 
182
- #### 记录任务日志
148
+ **polling options 参数:**
183
149
 
184
- **POST** `{prefix}/log`
150
+ | 参数名 | 类型 | 默认值 | 说明 |
151
+ |--------|------|--------|------|
152
+ | `maxPollTimes` | number | `20` | 最大轮询次数 |
153
+ | `pollInterval` | number | `10000` | 轮询间隔(毫秒) |
185
154
 
186
- | 参数名 | 类型 | 必填 | 说明 |
187
- |-----------|--------|----|----------------------------------------|
188
- | id | string | 是 | 任务ID(body) |
189
- | taskId | string | 是 | 任务ID(query) |
190
- | data | object | 否 | 日志数据 |
191
- | message | string | 否 | 日志消息 |
192
- | signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
155
+ **polling callback 返回格式:**
193
156
 
194
- #### 任务回调
157
+ | 字段 | 类型 | 说明 |
158
+ |------|------|------|
159
+ | `result` | string | `'success'` / `'failed'` / `'pending'` |
160
+ | `data` | object | 成功时返回的数据 |
161
+ | `message` | string | 消息 |
162
+ | `progress` | number | 当前进度 |
195
163
 
196
- **POST** `{prefix}/callback`
164
+ #### 任务类型处理函数
197
165
 
198
- | 参数名 | 类型 | 必填 | 说明 |
199
- |-----------|--------|----|----------------------------------------|
200
- | id | string | 是 | 任务ID(body) |
201
- | taskId | string | 是 | 任务ID(query) |
202
- | code | number | 是 | 状态码,0为成功 |
203
- | data | object | 否 | 回调数据 |
204
- | message | string | 否 | 回调消息 |
205
- | signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
166
+ 任务完成后自动调用对应 `task[type]` 处理函数,接收参数:
206
167
 
207
- ### 服务层 API
168
+ | 参数名 | 类型 | 说明 |
169
+ |--------|------|------|
170
+ | `task` | Task | 任务实例 |
171
+ | `result` | object / string | 任务输出结果 |
172
+ | `context` | object | 任务上下文(`next` 时设置的数据) |
208
173
 
209
- #### create - 创建任务
174
+ #### 运行时动态添加
210
175
 
211
- | 参数名 | 类型 | 必填 | 说明 |
212
- |------------|--------|----|---------------------|
213
- | userId | string | 否 | 用户ID |
214
- | input | object | 否 | 输入数据 |
215
- | type | string | 是 | 任务类型 |
216
- | targetId | string | 是 | 目标对象ID |
217
- | targetType | string | 是 | 目标对象类型 |
218
- | runnerType | string | 否 | 执行者类型:manual/system |
219
- | delay | number | 否 | 延迟执行秒数 |
220
- | scriptName | string | 否 | 脚本名称 |
221
- | options | object | 否 | 扩展选项 |
176
+ ```javascript
177
+ // 通过 append 方法运行时添加任务目录和类型
178
+ const result = await fastify.task.services.append({
179
+ dirs: ['/path/to/tasks'],
180
+ tasks: {
181
+ 'new-type': async ({ task, result }) => { /* 处理逻辑 */ }
182
+ }
183
+ });
184
+ // result.dirs → 实际添加的目录列表
185
+ // result.tasks → 实际添加的类型列表
186
+ ```
222
187
 
223
- **返回值**:Task 实例
188
+ #### 签名验证
224
189
 
225
- #### detail - 获取任务详情
190
+ 当任务通过 `next({ secret: '密钥' })` 设置了密钥时,外部回调需提供 HMAC-SHA256 签名。
226
191
 
227
- | 参数名 | 类型 | 必填 | 说明 |
228
- |-----|--------|----|------|
229
- | id | string | 是 | 任务ID |
192
+ **签名生成方法:**
230
193
 
231
- **返回值**:Task 实例
194
+ ```javascript
195
+ const crypto = require('node:crypto');
232
196
 
233
- #### list - 获取任务列表
197
+ function generateSignature({ secret, id, data }) {
198
+ const dataStr = typeof data === 'string' ? data : JSON.stringify(data);
199
+ const dataToSign = `${id}|${dataStr}`;
200
+ const hmac = crypto.createHmac('sha256', secret);
201
+ hmac.update(dataToSign);
202
+ return hmac.digest('hex');
203
+ }
204
+ ```
234
205
 
235
- 同 HTTP API list 接口参数
206
+ **各接口签名数据格式:**
236
207
 
237
- #### complete - 完成任务
208
+ | 接口 | data 格式 |
209
+ |------|-----------|
210
+ | `processNext` | `result` 字符串(JSON 格式结果) |
211
+ | `logWithSignature` | `{ data, message }` 对象 |
212
+ | `callbackWithSignature` | `{ code, data, message }` 对象 |
238
213
 
239
- | 参数名 | 类型 | 必填 | 说明 |
240
- |--------|--------|----|-------------------|
241
- | id | string | 是 | 任务ID |
242
- | userId | string | 否 | 完成人ID |
243
- | output | object | 否 | 输出数据 |
244
- | status | string | 是 | 状态:success/failed |
245
- | error | string | 否 | 错误信息 |
214
+ ```javascript
215
+ // processNext 签名
216
+ const result = JSON.stringify({ code: 0, data: { output: 'done' } });
217
+ const signature = generateSignature({ secret: 'your-secret', id: 'task-1', data: result });
246
218
 
247
- #### cancel - 取消任务
219
+ // callbackWithSignature 签名
220
+ const signature = generateSignature({
221
+ secret: 'your-secret', id: 'task-1',
222
+ data: { code: 0, data: { result: 'done' }, message: '成功' }
223
+ });
224
+ ```
248
225
 
249
- | 参数名 | 类型 | 必填 | 说明 |
250
- |------------|--------|----|--------------|
251
- | id | string | 否 | 任务ID |
252
- | targetId | string | 否 | 目标对象ID(批量取消) |
253
- | targetType | string | 否 | 目标对象类型(批量取消) |
254
- | type | string | 否 | 任务类型(批量取消) |
226
+ > **关键设计**:未设置 `context.secret` 时签名验证自动跳过,不阻塞无密钥任务的回调。
255
227
 
256
- #### retry - 重试任务
228
+ #### 插件依赖
257
229
 
258
- | 参数名 | 类型 | 必填 | 说明 |
259
- |---------|----------|----|--------|
260
- | id | string | 否 | 单个任务ID |
261
- | taskIds | string[] | 否 | 任务ID数组 |
230
+ | 依赖 | 说明 |
231
+ |------|------|
232
+ | `fastify-cron` | 定时任务支持 |
233
+ | `@kne/fastify-namespace` | 命名空间模块化 |
234
+ | `@kne/fastify-statistics` | 统计数据采集 |
235
+ | `fastify-sequelize` | 数据库模型支持 |
262
236
 
263
- #### log - 记录日志(内部调用)
264
237
 
265
- > 内部调用方法,不需要签名验证
238
+ ### 示例
266
239
 
267
- | 参数名 | 类型 | 必填 | 说明 |
268
- |-----------|--------|----|-----------------|
269
- | id | string | 是 | 任务ID |
270
- | taskId | string | 是 | 任务ID(id的别名) |
271
- | data | object | 否 | 日志数据 |
272
- | message | string | 否 | 日志消息 |
240
+ ### API
273
241
 
274
- #### logWithSignature - 记录日志(外部调用)
242
+ ### 配置项
243
+
244
+ | 属性名 | 类型 | 必填 | 默认值 | 说明 |
245
+ |--------|------|------|--------|------|
246
+ | `dbTableNamePrefix` | string | 否 | `'t_'` | 数据库表名前缀 |
247
+ | `prefix` | string | 否 | `'/api/task'` | API 路由前缀 |
248
+ | `name` | string | 否 | `'task'` | 插件命名空间名称 |
249
+ | `limit` | number | 否 | `10` | 系统任务并发执行上限 |
250
+ | `dir` | string | 否 | `'libs/tasks'` | 任务脚本目录(向后兼容,优先级高于 dirs) |
251
+ | `dirs` | array | 否 | `null` | 任务脚本目录列表,运行时可通过 `append` 动态添加 |
252
+ | `cronTime` | string | 否 | `'*/10 * * * *'` | 定时任务 Cron 表达式 |
253
+ | `scriptName` | string | 否 | `'index'` | 默认任务脚本名称 |
254
+ | `maxPollTimes` | number | 否 | `20` | 最大轮询次数 |
255
+ | `pollInterval` | number | 否 | `10000` | 轮询间隔(毫秒) |
256
+ | `taskTimeout` | number | 否 | `1800000` | 任务执行超时时间(毫秒),0 表示不超时,默认 30 分钟 |
257
+ | `retryBaseDelay` | number | 否 | `5000` | 重试基础延迟(毫秒),实际延迟 = `retryBaseDelay * 2^(retryCount-1)` |
258
+ | `getUserModel` | function | 否 | - | 获取用户 Model 的函数 |
259
+ | `getAuthenticate` | function | 否 | - | 获取认证中间件的函数 |
260
+ | `task` | object | 否 | `{}` | 任务类型处理函数配置,`{ [type]: handler }` |
261
+
262
+ > **关键设计**:`dirs` 初始化逻辑 — 优先使用用户传入的 `dirs`,否则以 `dir` 为默认值;若 `dirs` 中不包含 `dir`,则将 `dir` 插入 `dirs` 首位,保证向后兼容。
263
+
264
+ ### HTTP 接口
265
+
266
+ #### POST `{prefix}/create`
267
+
268
+ 创建任务,需 `write` 权限。
269
+
270
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
271
+ |--------|------|------|--------|------|
272
+ | type | string | 是 | - | 任务类型,必须在 `task` 配置中声明 |
273
+ | targetId | string | 是 | - | 目标对象ID |
274
+ | targetType | string | 是 | - | 目标对象类型 |
275
+ | input | object | 否 | - | 输入数据 |
276
+ | runnerType | string | 否 | - | 执行者类型:`manual` / `system` |
277
+ | delay | number | 否 | `0` | 延迟执行秒数 |
278
+ | scriptName | string | 否 | - | 任务脚本名称 |
279
+ | priority | number | 否 | `0` | 优先级,数值越大越优先 |
280
+ | parentTaskId | string | 否 | - | 父任务ID,用于任务依赖 |
281
+ | maxRetries | number | 否 | `0` | 最大自动重试次数 |
282
+ | timeout | number | 否 | `60` | 任务超时时间(分钟),0 表示不超时 |
283
+
284
+ 返回值:
285
+
286
+ | 属性名 | 类型 | 说明 |
287
+ |--------|------|------|
288
+ | id | string | 任务ID |
289
+
290
+ #### GET `{prefix}/list`
291
+
292
+ 获取任务列表,需 `read` 权限。
293
+
294
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
295
+ |--------|------|------|--------|------|
296
+ | perPage | number | 否 | `20` | 每页数量 |
297
+ | currentPage | number | 否 | `1` | 当前页码 |
298
+ | filter.id | string | 否 | - | 任务ID |
299
+ | filter.targetId | string | 否 | - | 目标对象ID |
300
+ | filter.targetName | string | 否 | - | 目标名称(模糊匹配 `input.name`) |
301
+ | filter.type | string | 否 | - | 任务类型 |
302
+ | filter.status | string | 否 | - | 任务状态 |
303
+ | filter.runnerType | string | 否 | - | 执行者类型 |
304
+ | filter.createdAt.startTime | string | 否 | - | 创建时间起始 |
305
+ | filter.createdAt.endTime | string | 否 | - | 创建时间结束 |
306
+ | filter.completedAt.startTime | string | 否 | - | 完成时间起始 |
307
+ | filter.completedAt.endTime | string | 否 | - | 完成时间结束 |
308
+ | sort | object | 否 | - | 排序规则(支持 `completedAt`、`updatedAt` 等字段,`ASC`/`DESC`) |
309
+
310
+ 返回值:
311
+
312
+ | 属性名 | 类型 | 说明 |
313
+ |--------|------|------|
314
+ | pageData | array | 任务列表 |
315
+ | totalCount | number | 总数量 |
316
+
317
+ #### POST `{prefix}/complete`
318
+
319
+ 手动完成任务,需 `write` 权限。
320
+
321
+ | 参数名 | 类型 | 必填 | 说明 |
322
+ |--------|------|------|------|
323
+ | id | string | 是 | 任务ID |
324
+ | status | string | 是 | 完成状态:`success` / `failed` |
325
+ | error | string | 否 | 错误信息 |
326
+ | msg | string | 否 | 消息 |
327
+ | output | object | 否 | 输出数据 |
328
+
329
+ #### POST `{prefix}/cancel`
330
+
331
+ 取消任务,需 `write` 权限。支持单个取消(`id`)或批量取消(`targetId` + `targetType` + `type`)。
332
+
333
+ | 参数名 | 类型 | 必填 | 说明 |
334
+ |--------|------|------|------|
335
+ | id | string | 否 | 任务ID(单个取消) |
336
+ | targetId | string | 否 | 目标对象ID(批量取消,需配合 `targetType` 和 `type`) |
337
+ | targetType | string | 否 | 目标对象类型(批量取消) |
338
+ | type | string | 否 | 任务类型(批量取消) |
339
+
340
+ #### POST `{prefix}/retry`
341
+
342
+ 重试任务,需 `write` 权限。仅允许重试 `failed` 或 `canceled` 状态的任务。
343
+
344
+ | 参数名 | 类型 | 必填 | 说明 |
345
+ |--------|------|------|------|
346
+ | id | string | 否 | 单个任务ID |
347
+ | taskIds | string[] | 否 | 任务ID数组 |
348
+
349
+ #### POST `{prefix}/next`
350
+
351
+ 处理等待回调的任务,无需认证。当任务设置了 `context.secret` 时需提供签名。
352
+
353
+ | 参数名 | 类型 | 必填 | 说明 |
354
+ |--------|------|------|------|
355
+ | id | string | 是 | 任务ID |
356
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
357
+ | result | string | 是 | JSON 格式结果字符串 |
358
+
359
+ #### POST `{prefix}/log`
360
+
361
+ 记录任务日志,无需认证。当任务设置了 `context.secret` 时需提供签名。
362
+
363
+ | 参数名 | 类型 | 必填 | 说明 |
364
+ |--------|------|------|------|
365
+ | id | string | 否 | 任务ID(body) |
366
+ | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
367
+ | data | object | 否 | 日志数据 |
368
+ | message | string | 否 | 日志消息 |
369
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
370
+
371
+ #### POST `{prefix}/callback`
372
+
373
+ 任务回调,无需认证。当任务设置了 `context.secret` 时需提供签名。
374
+
375
+ | 参数名 | 类型 | 必填 | 说明 |
376
+ |--------|------|------|------|
377
+ | id | string | 否 | 任务ID(body) |
378
+ | taskId | string | 否 | 任务ID(query,替代 body 中的 `id`) |
379
+ | code | number | 是 | 状态码,0 为成功 |
380
+ | data | object | 否 | 回调数据 |
381
+ | message | string | 否 | 回调消息 |
382
+ | signature | string | 否 | HMAC-SHA256 签名(当 `context.secret` 存在时必填) |
383
+
384
+ #### GET `{prefix}/statistics`
385
+
386
+ 获取任务统计概览,需 `statistics` 权限。
387
+
388
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
389
+ |--------|------|------|--------|------|
390
+ | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
391
+ | timezone | string | 否 | 服务器时区 | 时区,如 `Asia/Shanghai` |
392
+ | type | string | 否 | - | 按任务类型筛选 |
393
+ | runnerType | string | 否 | - | 按执行方式筛选 `manual` / `system` |
394
+
395
+ 返回值:
396
+
397
+ | 属性名 | 类型 | 说明 |
398
+ |--------|------|------|
399
+ | range | string | 时间范围标识 |
400
+ | rangeLabel | string | 时间范围中文描述 |
401
+ | totalTasks | number | 任务总数 |
402
+ | byStatus | object | 按状态统计 `{ success, failed, canceled }` |
403
+ | byType | object | 按类型统计 |
404
+ | byRunnerType | object | 按执行方式统计 |
405
+ | recentTrend | array | 近期每日趋势 `[{ date, count }]` |
406
+ | recentTrendByStatus | array | 近期每日按状态趋势 |
407
+ | recentTrendByType | array | 近期每日按类型趋势 |
408
+ | durationTrend | array | 按日时长趋势 |
409
+ | hourlyTrend | array | 小时级完成趋势 |
410
+ | hourlyCompletionTrend | array | 小时级完成详情趋势 |
411
+
412
+ #### GET `{prefix}/statistics/sse`
413
+
414
+ SSE 实时推送任务统计数据,需 `statistics` 权限。
415
+
416
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
417
+ |--------|------|------|--------|------|
418
+ | range | string | 否 | `'7d'` | 时间范围 |
419
+ | timezone | string | 否 | 服务器时区 | 时区 |
420
+ | type | string | 否 | - | 按任务类型筛选 |
421
+ | runnerType | string | 否 | - | 按执行方式筛选 |
422
+ | interval | number | 否 | `5` | 推送间隔时间(秒),最小 1 秒 |
423
+
424
+ ### 程序化 API
425
+
426
+ 通过 `fastify.task.services` 访问。
427
+
428
+ #### 任务管理
429
+
430
+ | 方法签名 | 说明 |
431
+ |----------|------|
432
+ | `services.create({ userId, input, type, targetId, targetType, runnerType, delay, scriptName, priority, parentTaskId, maxRetries, timeout, options })` | 创建任务,返回 Task 实例 |
433
+ | `services.detail({ id })` | 获取任务详情,返回 Task 实例 |
434
+ | `services.list({ filter, perPage, currentPage, sort })` | 获取任务列表,返回 `{ pageData, totalCount }` |
435
+ | `services.complete({ id, userId, status, output, error })` | 手动完成任务 |
436
+ | `services.cancel({ id, targetId, targetType, type })` | 取消任务,支持单个或批量 |
437
+ | `services.retry({ id, taskIds })` | 重试任务,仅允许 `failed`/`canceled` 状态 |
438
+ | `services.waitingComplete({ id, pollInterval, maxPollTimes })` | 等待任务完成(轮询),返回任务输出数据 |
439
+
440
+ **services.create 参数:**
441
+
442
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
443
+ |--------|------|------|--------|------|
444
+ | userId | string | 否 | - | 用户ID |
445
+ | input | object | 否 | - | 输入数据 |
446
+ | type | string | 是 | - | 任务类型 |
447
+ | targetId | string | 是 | - | 目标对象ID |
448
+ | targetType | string | 是 | - | 目标对象类型 |
449
+ | runnerType | string | 否 | - | 执行者类型 |
450
+ | delay | number | 否 | `0` | 延迟执行秒数 |
451
+ | scriptName | string | 否 | - | 脚本名称 |
452
+ | priority | number | 否 | `0` | 优先级 |
453
+ | parentTaskId | string | 否 | - | 父任务ID |
454
+ | maxRetries | number | 否 | `0` | 最大重试次数 |
455
+ | timeout | number | 否 | `60` | 超时时间(分钟) |
456
+ | options | object | 否 | - | 扩展选项 |
457
+
458
+ **services.waitingComplete 参数:**
459
+
460
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
461
+ |--------|------|------|--------|------|
462
+ | id | string | 是 | - | 任务ID |
463
+ | pollInterval | number | 否 | `1000` | 轮询间隔(毫秒) |
464
+ | maxPollTimes | number | 否 | `20` | 最大轮询次数 |
465
+
466
+ #### 回调与日志
467
+
468
+ | 方法签名 | 说明 |
469
+ |----------|------|
470
+ | `services.processNext({ id, signature, result })` | 处理等待回调的任务,需签名验证 |
471
+ | `services.callback({ id, code, data, message })` | 任务回调(内部调用,无需签名) |
472
+ | `services.callbackWithSignature({ id, code, data, message, signature })` | 任务回调(外部调用,需签名验证) |
473
+ | `services.log({ id, taskId, data, message })` | 记录日志(内部调用,无需签名),最多 100 条 |
474
+ | `services.logWithSignature({ id, taskId, data, message, signature })` | 记录日志(外部调用,需签名验证) |
475
+
476
+ #### 系统调度
477
+
478
+ | 方法签名 | 说明 |
479
+ |----------|------|
480
+ | `services.runner()` | 执行系统任务,由 cron 定时调用 |
481
+ | `services.resetAll()` | 重置所有 running 任务为 pending |
482
+ | `services.append({ dirs, tasks })` | 运行时动态添加任务目录和类型,返回 `{ dirs, tasks }` |
483
+
484
+ #### 统计查询
485
+
486
+ | 方法签名 | 说明 |
487
+ |----------|------|
488
+ | `services.queryStatistics({ range, timezone, type, runnerType })` | 查询任务统计数据 |
489
+ | `services.sseStatistics({ range, timezone, type, runnerType, interval }, reply)` | SSE 实时推送统计数据 |
490
+
491
+ **services.queryStatistics 参数:**
492
+
493
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
494
+ |--------|------|------|--------|------|
495
+ | range | string | 否 | `'7d'` | 时间范围:`7d` / `1m` / `3m` / `1y` |
496
+ | timezone | string | 否 | 服务器时区 | 时区 |
497
+ | type | string | 否 | - | 按任务类型筛选 |
498
+ | runnerType | string | 否 | - | 按执行方式筛选 |
499
+
500
+ **services.sseStatistics 参数:**
501
+
502
+ | 参数名 | 类型 | 必填 | 默认值 | 说明 |
503
+ |--------|------|------|--------|------|
504
+ | range | string | 否 | `'7d'` | 时间范围 |
505
+ | timezone | string | 否 | 服务器时区 | 时区 |
506
+ | type | string | 否 | - | 按任务类型筛选 |
507
+ | runnerType | string | 否 | - | 按执行方式筛选 |
508
+ | interval | number | 否 | `5` | 推送间隔(秒) |
509
+ | reply | object | 是 | - | Fastify reply 对象(第二个参数) |
510
+
511
+ ### 数据模型
512
+
513
+ #### Task
514
+
515
+ | 属性名 | 类型 | 说明 |
516
+ |--------|------|------|
517
+ | type | STRING | 任务类型 |
518
+ | scriptName | STRING | 任务脚本名称 |
519
+ | targetId | STRING | 任务目标对象ID |
520
+ | targetType | STRING | 任务目标对象类型 |
521
+ | runnerType | ENUM | 执行者类型 (`manual` / `system`),默认 `manual` |
522
+ | priority | INTEGER | 任务优先级,数值越大越优先,默认 0 |
523
+ | parentTaskId | STRING | 父任务ID,用于任务依赖 |
524
+ | retryCount | INTEGER | 已重试次数,默认 0 |
525
+ | maxRetries | INTEGER | 最大重试次数,0 表示不自动重试 |
526
+ | timeout | INTEGER | 任务超时时间(分钟),0 表示不超时,默认 60 |
527
+ | startTime | DATE | 任务最早执行时间 |
528
+ | startedAt | DATE | 任务实际开始执行时间 |
529
+ | completedAt | DATE | 任务完成时间 |
530
+ | completedUserId | STRING | 完成任务的用户ID |
531
+ | input | JSON | 输入数据 |
532
+ | output | JSON | 输出数据 |
533
+ | error | JSON | 错误信息 |
534
+ | status | ENUM | 任务状态 (`pending` / `running` / `waiting` / `success` / `failed` / `canceled`),默认 `pending` |
535
+ | context | JSON | 上下文信息 |
536
+ | pollResults | JSON | 轮询执行结果 |
537
+ | pollCount | INTEGER | 轮询次数,默认 0 |
538
+ | progress | INTEGER | 任务进度 (0-100),默认 0 |
539
+ | msg | TEXT | 任务消息 |
540
+ | options | JSON | 任务扩展选项(含 `logs` 日志数组) |
541
+
542
+ **关联关系:**
543
+
544
+ | 关联 | 外键 | 说明 |
545
+ |------|------|------|
546
+ | belongsTo User | `userId` | 创建人,`as: 'createdUser'` |
547
+ | belongsTo User | `completedUserId` | 完成人,`as: 'completedUser'` |
548
+ | belongsTo Task | `parentTaskId` | 父任务,`as: 'parentTask'` |
549
+
550
+ **索引:**
551
+
552
+ | 索引字段 |
553
+ |----------|
554
+ | `created_at` |
555
+ | `status` |
556
+ | `type` |
557
+ | `runner_type` |
558
+ | `type, status` |
559
+ | `runner_type, status` |
560
+ | `target_id, target_type, type` |
561
+ | `parent_task_id` |
562
+ | `priority` |
563
+
564
+ ### 机制说明
565
+
566
+ #### 签名验证
567
+
568
+ 使用 HMAC-SHA256 算法,签名数据格式为 `{id}|{data}`,其中 `data` 为 JSON 字符串或原始字符串。
569
+
570
+ | 接口 | 签名 data 内容 |
571
+ |------|----------------|
572
+ | `processNext` | `result` 参数值(原始 JSON 字符串) |
573
+ | `logWithSignature` | `{ data, message }` 对象的 JSON 序列化 |
574
+ | `callbackWithSignature` | `{ code, data, message }` 对象的 JSON 序列化 |
575
+
576
+ > **关键设计**:未设置 `context.secret` 时 `verifySignature` 直接返回 `true`,不阻塞无密钥任务的回调。
577
+
578
+ #### 重试策略
579
+
580
+ 任务执行失败时,判断是否满足自动重试条件(`retryCount < maxRetries`):
581
+
582
+ | 条件 | 行为 |
583
+ |------|------|
584
+ | `retryCount < maxRetries` | 重置为 `pending`,`startTime` 设为当前时间 + 退避延迟 |
585
+ | `retryCount >= maxRetries` | 标记为 `failed`,记录错误信息 |
586
+
587
+ 退避公式:`delay = retryBaseDelay × 2^(retryCount - 1)`
588
+
589
+ > **关键设计**:手动调用 `retry` 接口会重置 `retryCount` 为 0,重新开始重试计数。
590
+
591
+ #### 超时检测
592
+
593
+ 每次 `runner` 执行时先调用 `checkTimeout`,扫描所有 `running` / `waiting` 且 `timeout > 0` 的任务:
275
594
 
276
- > 外部调用方法,需要签名验证(HTTP API使用)
277
-
278
- | 参数名 | 类型 | 必填 | 说明 |
279
- |-----------|--------|----|----------------------------------------|
280
- | id | string | 是 | 任务ID |
281
- | taskId | string | 是 | 任务ID(id的别名) |
282
- | data | object | 否 | 日志数据 |
283
- | message | string | 否 | 日志消息 |
284
- | signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
285
-
286
- #### callback - 任务回调(内部调用)
287
-
288
- > 内部调用方法,不需要签名验证
289
-
290
- | 参数名 | 类型 | 必填 | 说明 |
291
- |-----------|--------|----|-----------|
292
- | id | string | 是 | 任务ID |
293
- | code | number | 是 | 状态码,0为成功 |
294
- | data | object | 否 | 回调数据 |
295
- | message | string | 否 | 回调消息 |
296
-
297
- #### callbackWithSignature - 任务回调(外部调用)
298
-
299
- > 外部调用方法,需要签名验证(HTTP API使用)
300
-
301
- | 参数名 | 类型 | 必填 | 说明 |
302
- |-----------|--------|----|----------------------------------------|
303
- | id | string | 是 | 任务ID |
304
- | code | number | 是 | 状态码,0为成功 |
305
- | data | object | 否 | 回调数据 |
306
- | message | string | 否 | 回调消息 |
307
- | signature | string | 否 | HMAC-SHA256签名(当任务设置了context.secret时必填) |
595
+ ```
596
+ 当前时间 - startedAt > timeout × 60 × 1000 → 标记为 failed
597
+ ```
308
598
 
309
- #### runner - 执行系统任务
599
+ > **关键设计**:`taskTimeout`(全局配置)和 `timeout`(任务级别,单位分钟)是两个不同概念。全局 `taskTimeout` 在 executor 执行时通过 `Promise.race` 控制;任务 `timeout` 字段在 cron 轮询时检测。
310
600
 
311
- 无参数,由 cron 定时调用
312
-
313
- #### resetAll - 重置所有运行中任务
601
+ #### 父子任务依赖
314
602
 
315
- 无参数,将所有 running 状态任务重置为 pending
603
+ 当父任务执行成功后,自动激活 `parentTaskId` 指向该父任务且状态为 `pending` 的子任务:
316
604
 
317
- #### waitingComplete - 等待任务完成
605
+ | 子任务 runnerType | 激活行为 |
606
+ |-------------------|----------|
607
+ | `system` | 立即调用 `processSystemTask` 执行 |
608
+ | `manual` | 保持 `pending`,等待手动执行 |
318
609
 
319
- | 参数名 | 类型 | 默认值 | 说明 |
320
- |--------------|--------|------|----------|
321
- | id | string | - | 任务ID |
322
- | pollInterval | number | 1000 | 轮询间隔(毫秒) |
323
- | maxPollTimes | number | 20 | 最大轮询次数 |
610
+ > **关键设计**:只有父任务 **成功** 后才触发子任务,失败或取消不会激活子任务。
324
611
 
325
- **返回值**:任务输出数据
612
+ #### 统计数据采集
326
613
 
327
- ### 任务模型字段
614
+ 任务完成时通过 `@kne/fastify-statistics` 采集数据,channel 格式为 `{type}:{runnerType}:{completedHour}`,采集维度:
328
615
 
329
- | 属性名 | 类型 | 说明 |
330
- |-------------|--------|---------------------|
331
- | id | string | 任务ID |
332
- | type | string | 任务类型 |
333
- | scriptName | string | 脚本名称 |
334
- | targetId | string | 目标对象ID |
335
- | targetType | string | 目标对象类型 |
336
- | runnerType | enum | 执行者类型:manual/system |
337
- | startTime | date | 最早执行时间 |
338
- | completedAt | date | 完成时间 |
339
- | input | json | 输入数据 |
340
- | output | json | 输出数据 |
341
- | error | json | 错误信息 |
342
- | status | enum | 任务状态 |
343
- | context | json | 上下文信息 |
344
- | pollResults | json | 轮询结果记录 |
345
- | pollCount | number | 轮询次数 |
346
- | progress | number | 进度(0-100) |
347
- | msg | text | 消息 |
348
- | options | json | 扩展选项 |
616
+ | 维度 | 单位 | 说明 |
617
+ |------|------|------|
618
+ | total | count | 总完成数 |
619
+ | success / failed / canceled | count | 按状态计数 |
620
+ | waitingTime | ms | 等待时长(startedAt - createdAt) |
621
+ | executionTime | ms | 执行时长(completedAt - startedAt) |
622
+ | totalTime | ms | 总时长(completedAt - createdAt) |