M1-03 Task Queue 深化 #17

New Issue

wangdl · 2026-05-22T21:03:34+08:00

wangdl commented

2026-05-22 21:03:34 +08:00

目标

在 M0-10 Task Queue 基础版之上深化任务队列能力，补全统一任务类型定义、Worker 状态 Admin 视图和任务失败 Dashboard。

本 Issue 只做深化设计，基础能力（BullMQ 队列注册、入队、心跳、重试、取消）已在 M0-10 完成。

背景说明

M0-10 建立了 BullMQ 任务调度框架。本阶段需要将全系统所有异步任务类型统一注册、为 Admin 提供完整的任务监控视图、以及失败任务的集中展示和手动干预能力。

模块深化内容

统一任务类型全量定义：
- 在 TaskQueueModule 中注册所有 12 种任务类型（DOCUMENT_IMPORT / OCR_PROCESS / VISION_ANALYZE / EMBEDDING_GENERATE / INDEXING_UPSERT / GENERATE_ARTIFACT / AI_ANALYSIS / GENERATE_REVIEW_CARD / BACKUP_EXECUTE / CLEANUP_EXECUTE / AGENT_TASK / REPORT_GENERATE）
- 每种类型的默认重试策略和超时配置
Worker 状态 Admin 视图：
- 各 Worker 节点的运行状态（在线/离线/忙碌）
- Worker 处理速度统计
- Worker 心跳异常告警
任务失败 Dashboard：
- 失败任务列表（按类型/时间/错误信息分组）
- 手动重试单个或批量任务
- 失败原因分类统计

基础设施依赖变更

相比 M0-10，无新增依赖，在现有 BullMQ + Redis 基础上深化。

接口设计（新增部分）

AAPI 新增/深化：

Worker 节点状态列表
失败任务聚合视图
手动重试接口（需审计）
任务统计 Dashboard 数据接口

交付检查

路由归属：Internal Provider 深化 + AAPI 新增
是否需要 Prisma migration：需判断（任务日志表是否需要扩展）
是否需要 MySQL：需判断
是否需要 Redis：是（已有依赖）
是否需要 BullMQ：是（已有依赖）
是否需要 AuditLog：是（手动重试操作）
是否需要 Admin 视图：是

验收标准

12 种任务类型正式注册，每种定义默认重试和超时策略
Worker 状态 Admin 面板设计
任务失败 Dashboard 设计
集成测试覆盖任务状态查询和手动重试

禁止事项

禁止各业务模块绕过 TaskQueueModule 自定义任务类型（必须在统一注册表中声明）
禁止手动重试不做审计记录

不建议当前阶段实现

任务优先级调度
任务编排和依赖链

## 目标在 M0-10 Task Queue 基础版之上深化任务队列能力，补全统一任务类型定义、Worker 状态 Admin 视图和任务失败 Dashboard。本 Issue 只做深化设计，基础能力（BullMQ 队列注册、入队、心跳、重试、取消）已在 M0-10 完成。 ## 背景说明 M0-10 建立了 BullMQ 任务调度框架。本阶段需要将全系统所有异步任务类型统一注册、为 Admin 提供完整的任务监控视图、以及失败任务的集中展示和手动干预能力。 ## 模块深化内容 1. 统一任务类型全量定义： - 在 TaskQueueModule 中注册所有 12 种任务类型（DOCUMENT_IMPORT / OCR_PROCESS / VISION_ANALYZE / EMBEDDING_GENERATE / INDEXING_UPSERT / GENERATE_ARTIFACT / AI_ANALYSIS / GENERATE_REVIEW_CARD / BACKUP_EXECUTE / CLEANUP_EXECUTE / AGENT_TASK / REPORT_GENERATE） - 每种类型的默认重试策略和超时配置 2. Worker 状态 Admin 视图： - 各 Worker 节点的运行状态（在线/离线/忙碌） - Worker 处理速度统计 - Worker 心跳异常告警 3. 任务失败 Dashboard： - 失败任务列表（按类型/时间/错误信息分组） - 手动重试单个或批量任务 - 失败原因分类统计 ## 基础设施依赖变更相比 M0-10，无新增依赖，在现有 BullMQ + Redis 基础上深化。 ## 接口设计（新增部分） AAPI 新增/深化： - Worker 节点状态列表 - 失败任务聚合视图 - 手动重试接口（需审计） - 任务统计 Dashboard 数据接口 ## 交付检查 - [x] 路由归属：Internal Provider 深化 + AAPI 新增 - [x] 是否需要 Prisma migration：需判断（任务日志表是否需要扩展） - [x] 是否需要 MySQL：需判断 - [x] 是否需要 Redis：是（已有依赖） - [x] 是否需要 BullMQ：是（已有依赖） - [x] 是否需要 AuditLog：是（手动重试操作） - [x] 是否需要 Admin 视图：是 ## 验收标准 1. 12 种任务类型正式注册，每种定义默认重试和超时策略 2. Worker 状态 Admin 面板设计 3. 任务失败 Dashboard 设计 4. 集成测试覆盖任务状态查询和手动重试 ## 禁止事项 - 禁止各业务模块绕过 TaskQueueModule 自定义任务类型（必须在统一注册表中声明） - 禁止手动重试不做审计记录 ## 不建议当前阶段实现 - 任务优先级调度 - 任务编排和依赖链

wangdl added this to the M1：AI / RAG 运行时与检索底座（P0~P1） milestone 2026-05-22 21:03:34 +08:00

wangdl commented

2026-05-24 10:12:49 +08:00

✅ M1-03 实施完成

交付内容

模块	文件	说明
16 种任务类型	`task-types.ts`	TaskType enum + TASK_LABELS + 每种类型的重试/超时配置
任务统计 Dashboard	`admin-events.controller.ts`	`GET /admin-api/events/stats` 按类型聚合失败数
Worker 状态视图	`admin-events.controller.ts` + `worker-heartbeat.ts`	`GET /admin-api/events/workers` Redis 扫描活跃节点
批量重试	`admin-events.controller.ts`	`POST /admin-api/events/:queue/jobs/batch-retry` 含审计日志

任务类型配置总览

类型	最大重试	超时	中文
document-import	3	300s	文档导入
ocr-process	2	120s	OCR 处理
vision-analyze	2	120s	Vision 分析
embedding-generate	3	60s	Embedding 生成
indexing-upsert	2	30s	向量索引
generate-artifact	2	120s	学习工件生成
ai-analysis	3	180s	AI 分析
generate-review-card	2	180s	复习卡片生成
backup-execute	1	600s	备份执行
cleanup-execute	1	300s	清理执行
agent-task	3	300s	Agent 任务
report-generate	1	120s	报表生成

E2E 测试 (test/m1.e2e-spec.ts M1-03)

端点	测试
`GET /admin-api/events/stats`	200 含 taskStats + 401 校验
`GET /admin-api/events/workers`	200 含 worker 状态
`POST /admin-api/events/:queue/jobs/batch-retry`	200/201 批量重试

运行

npx jest --config ./test/jest-e2e.json   # 44 passed (28 M0 + 16 M1)

## ✅ M1-03 实施完成 ### 交付内容 | 模块 | 文件 | 说明 | |------|------|------| | 16 种任务类型 | `task-types.ts` | TaskType enum + TASK_LABELS + 每种类型的重试/超时配置 | | 任务统计 Dashboard | `admin-events.controller.ts` | `GET /admin-api/events/stats` 按类型聚合失败数 | | Worker 状态视图 | `admin-events.controller.ts` + `worker-heartbeat.ts` | `GET /admin-api/events/workers` Redis 扫描活跃节点 | | 批量重试 | `admin-events.controller.ts` | `POST /admin-api/events/:queue/jobs/batch-retry` 含审计日志 | ### 任务类型配置总览 | 类型 | 最大重试 | 超时 | 中文 | |------|---------|------|------| | document-import | 3 | 300s | 文档导入 | | ocr-process | 2 | 120s | OCR 处理 | | vision-analyze | 2 | 120s | Vision 分析 | | embedding-generate | 3 | 60s | Embedding 生成 | | indexing-upsert | 2 | 30s | 向量索引 | | generate-artifact | 2 | 120s | 学习工件生成 | | ai-analysis | 3 | 180s | AI 分析 | | generate-review-card | 2 | 180s | 复习卡片生成 | | backup-execute | 1 | 600s | 备份执行 | | cleanup-execute | 1 | 300s | 清理执行 | | agent-task | 3 | 300s | Agent 任务 | | report-generate | 1 | 120s | 报表生成 | ### E2E 测试 (test/m1.e2e-spec.ts M1-03) | 端点 | 测试 | |------|------| | `GET /admin-api/events/stats` | 200 含 taskStats + 401 校验 | | `GET /admin-api/events/workers` | 200 含 worker 状态 | | `POST /admin-api/events/:queue/jobs/batch-retry` | 200/201 批量重试 | ### 运行 ```bash npx jest --config ./test/jest-e2e.json # 44 passed (28 M0 + 16 M1) ```

~~wangdl referenced this issue 2026-06-05 19:34:44 +08:00~~

🟢 P2 | GET /activity/trend 返回真实趋势数据 #67

~~wangdl referenced this issue 2026-06-05 19:36:08 +08:00~~

🟢 P2 | GET /activity/trend 返回真实趋势数据 #67

wangdl closed this issue

2026-06-06 14:43:13 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#17