# QQBot 插件平台定时任务桥设计

日期：2026-06-16

状态：用户已确认方向，进入设计文档审阅。

## 背景

QQBot 第三期重构已经让 Plugin Platform 接管插件 manifest、安装生命周期、worker runtime、operation、event、运行事件和插件管理接口。但插件还没有统一的定时任务能力：如果某个插件需要周期同步数据，只能把定时逻辑藏进插件自身 `activate()` 或业务代码里。这会导致启停不可控、运行记录不可见、cron 不能在线修改，也无法复用于后续插件。

本轮要把“插件暴露的定时任务能力”升级为平台能力，并先用 BangDream 落地：定期同步 Bestdori JSON 主数据到服务端缓存，降低 `查分数表`、`查卡` 等重命令冷启动成本。

相关当前事实：

- API 已使用 `@nestjs/bullmq` + `bullmq` 管理 QQBot 插件 worker 请求队列。
- Admin 当前技术栈是 `antdv-next`，不是传统 `ant-design-vue`。
- BangDream 当前通过 `waitForBangDreamCatalogReady()` 懒加载 catalog；`remote-resource.client` 已具备 cache 路径参数形态，但当前文件缓存还未真正落地为“服务端预同步主数据”。
- 现有插件 manifest 没有 `tasks` 能力，`QqbotPluginWorkerRuntime` 也没有 `executeTask` RPC。

## 目标

1. Plugin Platform 统一管理插件暴露的定时任务能力。
2. 插件通过 manifest 声明定时任务，平台解析、持久化、展示、调度和执行。
3. 支持 Admin 在线启停任务、修改 cron 表达式、手动运行一次、查看运行记录。
4. 调度层使用 BullMQ Redis-backed 调度，不手写内存定时器，也不让插件自己 `setInterval`。
5. Admin cron 编辑不手写 cron 解析/生成算法，不引入 `ant-design-vue`；使用 `@vue-js-cron/core`，以现有 `antdv-next` 控件做薄适配。
6. BangDream 第一阶段只同步 Bestdori JSON 主数据；图片资源继续按需缓存。

## 非目标

- 本轮不做 Bestdori 全量图片镜像。
- 本轮不做所有插件的实际定时任务，只建立平台能力并完成 BangDream 参考实现。
- 本轮不做复杂任务依赖编排、分布式工作流 DAG、用户自定义脚本。
- 本轮不把 task 管理塞回现有“插件能力”页面，而是新增专门页面。

## 外部技术选择

### 后端调度

选择 BullMQ Job Scheduler / repeatable job 抽象作为平台调度实现。BullMQ v5 文档说明 Job Schedulers 是新版本对 repeatable jobs 的推荐能力，可按 fixed interval 或 cron 生成任务；当前 API 已引入 BullMQ，因此新增平台 task queue 不需要再引入另一套队列系统。

Nest 官方 `@nestjs/schedule` 支持动态 cron，但它是进程内调度。考虑线上 K8s、后续多副本和重启恢复，本轮不选 `@nestjs/schedule` 作为核心调度器。

### 前端 cron 编辑

选择 `@vue-js-cron/core`。它是 renderless Vue cron editor core，可以提供 cron 表达式生成/校验基础能力。Admin 侧新增 `CronEditorAntdvNext` 适配组件，只负责把现有 `antdv-next` 控件连接到 core 状态，不引入 `@vue-js-cron/ant`，因为该包依赖 `ant-design-vue`，会和当前 Admin 的 `antdv-next` 技术栈冲突。

参考来源：

- Nest task scheduling 文档：https://docs.nestjs.com/techniques/task-scheduling
- BullMQ Job Schedulers 文档：https://docs.bullmq.io/guide/job-schedulers
- Vue JS Cron 文档：https://abichinger.github.io/vue-js-cron/guide/getting-started-ant
- `@vue-js-cron/core` npm 信息：https://www.npmjs.com/package/@vue-js-cron/core

## Manifest 契约

`plugin.json` 新增 `tasks` 数组。旧插件不声明 `tasks` 时解析为 `[]`，保持兼容。

示例：

```json
{
  "tasks": [
    {
      "key": "bangdream.bestdori.sync-main-data",
      "name": "同步 Bestdori 主数据",
      "handlerName": "syncBestdoriMainData",
      "description": "同步 BangDream 重命令依赖的 Bestdori JSON 主数据。",
      "defaultCron": "0 */6 * * *",
      "enabled": true,
      "timeoutMs": 120000,
      "permissions": ["runtime.http", "plugin.storage.read", "plugin.storage.write"]
    }
  ]
}
```

字段规则：

- `key`：平台能力 key，使用现有 operation/event capability key 规则。
- `handlerName`：插件 worker 内部处理器名。
- `defaultCron`：标准 5 段 cron 表达式，平台存储前校验并规范化。
- `enabled`：安装时默认启用状态。管理员后续启停以数据库配置为准。
- `timeoutMs`：单次任务执行预算。
- `permissions`：任务需要的 host 权限，沿用 manifest 权限白名单。

Manifest parser 新增校验：

- task key 不合法时报 `INVALID_CAPABILITY_KEY`。
- task key 重复时报 `DUPLICATE_TASK_KEY`。
- handlerName 缺失时报 `MISSING_TASK_HANDLER`。
- cron 缺失或不合法时报 `INVALID_TASK_CRON`。
- timeoutMs 缺失时报 `MISSING_TASK_TIMEOUT`。
- permission 不在白名单内时报 `UNKNOWN_PERMISSION`。

## 数据模型

新增两张平台表。表结构仍遵循第三期规则：Snowflake `BIGINT` 主键、lower snake case、可查询字段结构化、日志表追加写。

### `qqbot_plugin_task`

表示插件安装实例暴露的一条可管理定时任务。

核心字段：

- `id`
- `plugin_id`
- `installation_id`
- `task_key`
- `task_name`
- `handler_name`
- `description`
- `default_cron`
- `cron_expression`
- `enabled`
- `timeout_ms`
- `runtime_status`：`idle | scheduled | running | failed | disabled`
- `last_run_id`
- `last_run_at`
- `last_status`
- `last_error`
- `last_duration_ms`
- `next_run_at`
- `create_time`
- `update_time`

唯一约束：`installation_id + task_key`。

### `qqbot_plugin_task_run`

表示一次任务运行记录。

核心字段：

- `id`
- `task_id`
- `plugin_id`
- `installation_id`
- `task_key`
- `trigger_type`：`schedule | manual | bootstrap`
- `status`：`running | success | failed | skipped`
- `job_id`
- `started_at`
- `finished_at`
- `duration_ms`
- `safe_summary`
- `error_message`
- `create_time`

索引：

- `task_id + create_time`
- `plugin_id + create_time`
- `status + create_time`

## 后端架构

新增 `plugin-platform/application/task` 能力域，职责与现有 operation/event/lifecycle 分开。

主要组件：

- `QqbotPluginTaskService`：任务查询、启停、cron 更新、手动运行、运行记录分页。
- `QqbotPluginTaskSchedulerService`：把 DB 中 enabled task 同步到 BullMQ scheduler，处理 enable/disable/update cron 的重建。
- `QqbotPluginTaskWorkerProcessor`：消费调度 job，创建 task run 记录，调用 active worker 的 `executeTask`，写回状态。
- `QqbotPluginTaskManifestSynchronizer`：安装、启用、升级插件时，将 manifest tasks 同步到 `qqbot_plugin_task`。
- `QqbotPluginTaskCronValidator`：后端统一校验 5 段 cron，拒绝空值、秒级 6/7 段表达式和过高频表达式。

调度语义：

- 插件启用后，平台同步任务记录，并为 enabled task 注册 BullMQ scheduler。
- 插件禁用或卸载后，平台暂停或移除该安装实例下的 scheduler。
- Admin 修改 cron 后，数据库先更新，再重建 scheduler；失败时回滚数据库更新或返回明确错误。
- 任务运行通过 worker RPC `executeTask`，不直接调用插件内部函数。
- 同一 `installationId + taskKey` 禁止重叠运行：上一轮未结束时，新一轮标记 `skipped`，不并发进入插件。
- 手动运行允许管理员显式触发；即使 schedule disabled，也可手动运行，但插件安装实例必须 enabled。
- 首次启用且没有成功运行记录的 enabled task，可触发一次 `bootstrap` run，用于预热缓存，但不阻塞 API 启动。

运行事件：

- task start/success/failed/skipped 同步写 `qqbot_plugin_task_run`。
- 摘要事件也写入 `qqbot_plugin_runtime_event`，eventType 使用 `task-started`、`task-finished`、`task-failed`、`task-skipped`。
- `safe_summary` 只存 taskKey、triggerType、resourceCounts、durationMs、outputKeys 等安全字段，不存大 JSON、不存图片、不存外部响应全文。

## Worker RPC

`QqbotPluginWorkerRequestType` 新增 `executeTask`。

请求字段：

- `taskId`
- `taskKey`
- `taskHandlerName`
- `triggerType`
- `input`
- `timeoutMs`
- `safeInputSummary`

worker thread 处理流程：

1. `load` 阶段创建插件实例。
2. `activate` 阶段完成插件基础预热。
3. `executeTask` 时按 `handlerName` 找到插件暴露的 task handler。
4. handler 返回结构化结果，例如 `{ syncedKeys, updatedFiles, cacheRoot, source }`。
5. worker 将错误序列化返回，平台记录 run 和 runtime event。

插件入口约定：

```ts
type QqbotIntegrationPlugin = {
  tasks?: Array<{
    key: string;
    handlerName: string;
    execute(input: Record<string, unknown>): Promise<Record<string, unknown>>;
  }>;
};
```

具体类型实现时应落到 plugin-platform contract，避免每个插件自己定义一套。

## BangDream 同步设计

新增 task：

- key：`bangdream.bestdori.sync-main-data`
- handlerName：`syncBestdoriMainData`
- defaultCron：`0 */6 * * *`
- timeoutMs：`120000`
- 默认 enabled：`true`

同步范围只包括 Bestdori JSON 主数据：

- `songs`
- `meta`
- `cards`
- `skills`
- `events`
- `gacha`
- `costumes`
- `bands`
- `characters`
- `areaItems`
- 后续如 operation catalog keys 明确需要，可追加 `items`、`degrees` 等 JSON 集合，但仍不含图片资源。

同步流程：

1. 读取 BangDream runtime config：`BANGDREAM_TSUGU_CACHE_ROOT`、Bestdori base url、请求超时和 retry。
2. 对目标 JSON key 逐个计算 Bestdori URL 和服务端缓存路径。
3. 使用 host HTTP 能力下载 JSON。
4. 写入插件服务端缓存目录，采用临时文件 + rename，避免半文件污染缓存。
5. 下载失败时保留上一份成功缓存，不删除旧文件。
6. 同步完成后刷新 worker 内存 catalog，让后续命令优先使用已同步数据。
7. 返回安全摘要：同步 key 数、成功数、失败数、缓存根路径是否存在、耗时。

缓存路径：

- 本地默认仍可使用 `.kt-workspace/cache/bangdream`。
- 生产应通过 env 配置到持久目录，例如 `BANGDREAM_TSUGU_CACHE_ROOT=/data/qqbot/plugins/bangdream/cache`。
- K8s 上需要为该目录配置持久卷或可复用 hostPath，否则重建 Pod 后缓存会丢失，定时同步只能降低运行期冷启动，不能跨发布保留。

命令 fallback：

- 若定时同步未完成或失败，BangDream 命令仍保留现有按需拉取逻辑。
- 命令读取缓存失败时可以继续请求 Bestdori，不因为预同步失败完全不可用。

## API 接口

新增接口均走 Vben 成功/错误响应包装，受 Admin auth 保护。

- `GET /qqbot/plugin-platform/tasks/page`
  - 支持 `pageNo/pageSize/pluginId/pluginKey/taskKey/enabled/status`
- `GET /qqbot/plugin-platform/tasks/:id`
- `POST /qqbot/plugin-platform/tasks/:id/enable`
- `POST /qqbot/plugin-platform/tasks/:id/disable`
- `POST /qqbot/plugin-platform/tasks/:id/cron`
  - body：`{ cronExpression: string }`
- `POST /qqbot/plugin-platform/tasks/:id/run`
  - body：`{ input?: Record<string, unknown> }`
- `GET /qqbot/plugin-platform/tasks/:id/runs`
  - 支持 `pageNo/pageSize/status/triggerType/startTime/endTime`

返回任务列表字段：

- `id`
- `pluginId`
- `pluginKey`
- `pluginName`
- `installationId`
- `taskKey`
- `taskName`
- `description`
- `cronExpression`
- `defaultCron`
- `enabled`
- `runtimeStatus`
- `lastStatus`
- `lastRunAt`
- `lastDurationMs`
- `lastError`
- `nextRunAt`

## Admin 页面

新增 QQBot 下的专门页面：插件定时任务。

建议路径：

- route path：`/qqbot/plugin-task`
- view root：`apps/web-antdv-next/src/views/qqbot/plugin-task`
- API caller：`apps/web-antdv-next/src/api/qqbot/plugin.ts` 扩展 task 方法，或拆 `plugin-task.ts` 并从 qqbot API index 暴露。

页面能力：

- KtTable 分页列表。
- 筛选：插件、任务 key、启用状态、运行状态。
- 操作：启用、停用、修改 cron、手动运行、查看运行记录。
- 状态列：enabled、runtimeStatus、lastStatus、lastRunAt、nextRunAt、duration。
- 运行记录 Drawer：展示最近运行状态、触发类型、耗时、安全摘要和错误。
- Cron 编辑 Modal：使用 `CronEditorAntdvNext`。

Cron 组件设计：

- 新增 `components/CronEditorAntdvNext.vue`。
- 内部使用 `@vue-js-cron/core` 管理 cron state/校验。
- UI 控件全部来自 `antdv-next`，例如 `RadioGroup`、`Select`、`Input`、`Segmented`、`Space`、`Alert`。
- 组件只输出标准 5 段 cron 表达式。
- Modal 保存前调用后端校验；前端校验只做即时反馈，后端仍是最终真相源。

依赖策略：

- 在 Admin workspace catalog 增加 `@vue-js-cron/core`。
- `apps/web-antdv-next` 依赖 `@vue-js-cron/core`。
- 不添加 `@vue-js-cron/ant`、`ant-design-vue` 或 `vue3-cron-antd`。

## 权限与菜单

新增 Admin 权限建议：

- `QqBot:PluginTask:List`
- `QqBot:PluginTask:UpdateCron`
- `QqBot:PluginTask:Enable`
- `QqBot:PluginTask:Disable`
- `QqBot:PluginTask:Run`
- `QqBot:PluginTask:RunLog`

菜单新增在 QQBot 管理分组下，标题“插件定时任务”。现有“插件平台”页继续负责安装、manifest、operation、runtime events 等；新页面只负责 scheduled task 管理。

## 错误处理

- cron 不合法：接口返回可读中文错误，不更新调度器。
- 插件未启用：手动运行返回“插件运行时未启用”。
- 任务禁用：scheduler 不触发；手动运行仍可触发，但要写 `triggerType=manual`。
- 上一轮未结束：新 schedule tick 写 `skipped`，不并发执行。
- worker 崩溃：任务 run 标记 failed，平台复用现有 worker recovery 机制；不删除上一次成功缓存。
- BullMQ/Redis 不可用：任务页展示 degraded，operation/event 命令仍按现有插件 runtime 能力运行，不因为调度器不可用整体停摆。
- BangDream 单个 JSON key 下载失败：记录失败 key，保留旧缓存，整体 run 可标记 failed 或 partial failed；第一版使用 failed，避免虚报成功。

## 验证计划

后端 TDD：

- Manifest parser：解析 `tasks`，拒绝重复 key、非法 cron、缺 handler、缺 timeout、未知权限。
- Persistence/schema：`qqbot_plugin_task`、`qqbot_plugin_task_run` 与 full schema SQL 对齐。
- Scheduler service：enable/disable/update cron 能同步 BullMQ scheduler，重复同步幂等。
- Worker runtime：`executeTask` RPC 进入 worker thread 并按 handlerName 分发。
- Platform service：安装/启用/升级插件时同步 task 能力，禁用插件时暂停 scheduler。
- BangDream：mock Bestdori JSON，验证 sync task 写入缓存、刷新 catalog、失败保留旧缓存。

Admin TDD：

- API caller：任务分页、启停、改 cron、手动运行、运行记录接口路径和参数正确。
- Cron component：不依赖 `ant-design-vue`，输出 5 段 cron，非法值展示错误。
- 页面状态：列表操作触发对应 caller，运行记录 Drawer 可打开。

集成验证：

- 本地 API 启动后真实请求：
  - `GET /qqbot/plugin-platform/tasks/page`
  - `POST /qqbot/plugin-platform/tasks/:id/cron`
  - `POST /qqbot/plugin-platform/tasks/:id/run`
  - `GET /qqbot/plugin-platform/tasks/:id/runs`
- 本地 Admin 页面 route smoke：`/qqbot/plugin-task` 能加载，cron modal 能打开并保存。
- BangDream 手动运行 task 后，缓存目录出现目标 JSON 文件，`/查分数表 cn` 或 `/查卡 472` 走热缓存不再每次重新拉全量主数据。
- 上线后验证 Jenkins/K8s、Redis/BullMQ、task 手动 run、BangDream 命令 smoke。

## 实施边界

实现计划应拆成后端平台能力、BangDream 任务、Admin 页面和上线闭环四段。每段都必须有独立 RED/GREEN 检查，不能先写 UI 再补接口，也不能让 BangDream 直接绕过平台调度。

本 spec 通过后，下一步进入 KT workflow `KT plan writing`。