Files

duanshuwen 67808a459e feat: 新增定时任务功能

2026-04-11 23:17:54 +08:00

13 KiB

Raw Blame History

zn-ai 定时任务（Cron）功能开发计划

项目概述

基于ClawX项目的定时任务功能分析，制定zn-ai项目的功能迁移开发计划。目标是在zn-ai项目中实现类似的定时任务管理功能，保持核心功能一致性，同时适配zn-ai的技术栈（Vue 3 + Element Plus + Pinia + Tailwind CSS）。

核心目标

实现定时任务管理：创建、编辑、删除、启用/禁用定时任务
支持调度配置：预设调度和自定义Cron表达式
提供基础交付模式：至少支持"仅应用内"模式
集成现有架构：与zn-ai现有状态管理、API通信、国际化系统集成
保持UI一致性：使用Element Plus和现有设计模式

技术约束

前端框架：Vue 3 Composition API
状态管理：Pinia
UI组件库：Element Plus + Tailwind CSS
国际化：Vue I18n
API通信：现有hostApiFetch IPC机制
后端集成：需评估现有任务调度能力，必要时实现简化版本

开发原则

分阶段实施：优先核心功能，逐步增强
渐进式增强：先实现基本功能，再添加高级特性
代码复用：尽可能复用现有组件和工具函数
类型安全：使用TypeScript确保类型安全
测试驱动：关键功能编写单元测试

阶段一：基础架构与类型定义

目标

建立定时任务功能的基础架构，包括类型定义、状态管理和API接口。

任务清单

1.1 创建类型定义文件

文件：src/lib/cron-types.ts
内容：
- 复制并适配ClawX的CronJob、CronJobCreateInput、CronJobDelivery等核心类型
- 根据zn-ai需求调整类型定义（如简化交付配置）
- 添加必要的工具类型和类型守卫
依赖：无
预估工时：2小时

1.2 创建Pinia Store

文件：src/store/cron.ts
内容：
- 定义store状态：jobs、loading、error
- 实现操作：fetchJobs、createJob、updateJob、deleteJob、toggleJob、triggerJob
- 使用现有hostApiFetch进行API调用
- 添加适当的错误处理和状态管理
依赖：cron-types.ts、hostApiFetch
预估工时：4小时

1.3 创建API接口占位

文件：更新现有API服务或创建src/lib/cron-api.ts
内容：
- 定义API端点常量
- 创建API函数包装器（如果现有hostApiFetch不足）
- 添加模拟数据用于开发测试
依赖：hostApiFetch、cron-types.ts
预估工时：3小时

1.4 创建国际化文件

文件：src/i18n/locales/{zh,en,ja}/cron.json
内容：
- 翻译ClawX的cron.json文件
- 适配zn-ai的翻译键命名约定
- 确保所有UI文本都有翻译键
依赖：ClawX翻译文件
预估工时：2小时

1.5 更新国际化配置

文件：src/i18n/constants.ts、src/i18n/index.ts
内容：
- 添加cron命名空间到NAMESPACES数组
- 确保翻译文件正确加载
依赖：国际化文件
预估工时：1小时

交付成果

完整的类型定义系统
可工作的Pinia store（带模拟数据）
国际化支持
基础API接口层

阶段验收标准

TypeScript编译无错误
Store基本操作可通过模拟数据工作
国际化文件正确加载
代码符合项目代码规范

阶段二：核心UI组件开发

目标

开发定时任务功能的核心用户界面组件。

任务清单

2.1 创建主页面组件

文件：src/pages/cron/index.vue
内容：
- 页面布局和结构
- 集成统计卡片区域
- 任务列表展示区域
- 空状态处理
- 加载状态和错误显示
- 创建任务按钮
依赖：Cron store、国际化
预估工时：6小时

2.2 创建任务卡片组件

文件：src/pages/cron/components/CronJobCard.vue
内容：
- 任务信息展示（名称、调度、消息预览）
- 状态指示器（启用/禁用）
- 操作按钮（运行、编辑、删除）
- 最后运行状态显示
- 下次运行时间显示
- 悬停和交互效果
依赖：Cron store、国际化、Element Plus组件
预估工时：5小时

2.3 创建任务对话框组件

文件：src/pages/cron/components/CronTaskDialog.vue
内容：
- 表单布局和字段（名称、消息、调度、交付模式等）
- 预设调度选择器
- 自定义Cron表达式输入
- 表单验证和错误提示
- 调度预览（下一次运行时间）
- 提交和取消按钮
依赖：Element Plus表单组件、Cron store、国际化
预估工时：8小时

2.4 创建统计卡片组件

文件：src/pages/cron/components/CronStats.vue（或复用现有模式）
内容：
- 总任务数卡片
- 活跃任务卡片
- 暂停任务卡片
- 失败任务卡片
- 响应式布局
依赖：Cron store、国际化、Tailwind CSS
预估工时：3小时

2.5 创建工具函数

文件：src/pages/cron/utils.ts
内容：
- Cron表达式解析和格式化函数
- 下一次运行时间预估函数
- 时间格式化辅助函数
- 交付模式处理函数
依赖：cron-types.ts
预估工时：4小时

交付成果

完整的用户界面组件
响应式布局和设计
基本的用户交互
表单验证和反馈

阶段验收标准

所有组件可独立渲染
表单验证正常工作
响应式设计适配不同屏幕尺寸
与现有设计风格一致

阶段三：功能集成与数据绑定

目标

将UI组件与store和API集成，实现完整的功能流程。

任务清单

3.1 集成Store到主页面

内容：
- 连接主页面与Cron store
- 实现数据加载和状态管理
- 添加刷新功能
- 处理空状态和错误状态
依赖：阶段一和二的成果
预估工时：3小时

3.2 实现任务操作集成

内容：
- 连接任务卡片操作按钮到store方法
- 实现启用/禁用切换
- 实现立即触发功能
- 实现删除功能（带确认）
依赖：Cron store、Element Plus MessageBox
预估工时：4小时

3.3 实现对话框表单提交

内容：
- 连接对话框表单到store创建/更新方法
- 实现表单数据验证
- 添加提交状态反馈
- 处理成功/失败场景
依赖：Cron store、Element Plus表单验证
预估工时：5小时

3.4 实现调度预览功能

内容：
- 实时计算并显示下一次运行时间
- 支持预设调度和自定义Cron表达式
- 添加时间格式化
依赖：Cron工具函数
预估工时：3小时

3.5 添加加载状态和反馈

内容：
- 全局加载状态管理
- 操作反馈（成功/错误toast）
- 网络错误处理
- 数据缓存策略
依赖：Element Plus反馈组件、Cron store
预估工时：3小时

3.6 集成路由和导航

文件：src/router/index.ts
内容：
- 添加定时任务页面路由
- 更新侧边栏菜单（如果需要）
- 添加路由守卫（如果需要）
依赖：主页面组件
预估工时：2小时

交付成果

完整的功能流程
实时数据绑定
用户操作反馈
错误处理和恢复

阶段验收标准

可以完整执行创建、编辑、删除任务流程
所有操作有适当的反馈
数据实时同步
错误场景得到妥善处理

阶段四：测试、优化与完善

目标

确保功能质量，优化性能，添加高级特性。

任务清单

4.1 编写单元测试

文件：tests/unit/cron-store.test.ts、tests/unit/cron-utils.test.ts
内容：
- Store逻辑单元测试
- 工具函数单元测试
- 组件逻辑单元测试
依赖：Vue Test Utils、Vitest
预估工时：6小时

4.2 添加集成测试

文件：tests/e2e/cron.spec.ts
内容：
- 完整用户流程测试
- 表单验证测试
- 错误场景测试
依赖：Playwright或Cypress
预估工时：5小时

4.3 性能优化

内容：
- 虚拟滚动（如果任务数量多）
- 数据缓存优化
- 减少不必要的重新渲染
- 代码分割和懒加载
预估工时：4小时

4.4 可访问性改进

内容：
- 添加ARIA属性
- 键盘导航支持
- 屏幕阅读器优化
- 颜色对比度检查
预估工时：3小时

4.5 高级功能增强

内容：
- 任务导入/导出功能
- 批量操作支持
- 任务执行历史查看
- 高级调度选项（时区支持等）
预估工时：8小时（可选）

4.6 文档编写

内容：
- 组件API文档
- 用户使用指南
- 开发指南
预估工时：3小时

交付成果

完整的测试覆盖
优化后的性能
可访问性支持
可选的高级功能

阶段验收标准

关键路径测试覆盖率达到80%以上
性能指标符合要求
通过可访问性检查
代码质量通过审查

时间总览

阶段	任务数	预估工时	累计工时
阶段一	5	12小时	12小时
阶段二	5	26小时	38小时
阶段三	6	20小时	58小时
阶段四	6	29小时	87小时
总计	22	87小时	87小时

注：阶段四的高级功能增强为可选，如不包括则总工时为79小时

风险与缓解措施

技术风险

风险1：后端调度引擎缺失

描述：zn-ai可能没有现成的任务调度引擎
影响：核心功能无法实现
概率：中
缓解措施：
1. 评估现有electron/process/目录中的任务执行能力
2. 实现简化版的Node.js调度器（使用node-cron或node-schedule）
3. 与Gateway功能解耦，设计可插拔的后端接口

风险2：频道系统不兼容

描述：zn-ai的频道系统与ClawX的频道系统完全不同
影响：交付功能无法直接迁移
概率：高
缓解措施：
1. 阶段一评估现有频道系统能力
2. 先实现"仅应用内"模式
3. 设计适配器层，未来集成现有频道系统
4. 简化交付配置，仅支持基本功能

风险3：Cron表达式复杂性

描述：Cron表达式解析和验证复杂
影响：用户输入错误导致任务不执行
概率：低
缓解措施：
1. 使用成熟的Cron解析库（如cron-parser）
2. 提供预设调度选项，减少用户直接输入
3. 添加实时验证和预览

资源风险

风险1：开发时间不足

描述：预估工时可能低估
影响：项目延期
概率：中
缓解措施：
1. 优先实现核心功能（阶段一至三）
2. 阶段四作为后续迭代
3. 定期进度评估和调整

风险2：技能匹配问题

描述：开发人员对Vue 3或Element Plus不熟悉
影响：开发效率低下
概率：低
缓解措施：
1. 提供代码示例和参考实现
2. 复用现有组件模式
3. 代码审查和结对编程

成功标准

功能成功标准

用户可以创建、编辑、删除定时任务
任务可以按预定调度执行
用户界面直观易用
系统稳定可靠，错误处理得当

技术成功标准

代码质量高，符合项目规范
测试覆盖关键功能路径
性能满足要求
可维护性和可扩展性好

业务成功标准

功能满足用户需求
用户体验良好
与现有系统集成顺畅
为未来扩展奠定基础

下一步行动

需求确认：与相关方确认功能范围和优先级
技术评估：详细评估后端调度能力
环境准备：设置开发环境和测试数据
开始实施：按照阶段一任务开始开发

附录

A. 文件结构规划

src/
├── lib/
│   ├── cron-types.ts          # 类型定义
│   └── cron-api.ts            # API接口（可选）
├── store/
│   └── cron.ts                # Pinia store
├── pages/
│   └── cron/
│       ├── components/
│       │   ├── CronJobCard.vue
│       │   ├── CronTaskDialog.vue
│       │   └── CronStats.vue
│       ├── utils.ts           # 工具函数
│       └── index.vue          # 主页面
└── i18n/
    └── locales/
        ├── zh/
        │   └── cron.json
        ├── en/
        │   └── cron.json
        └── ja/
            └── cron.json

B. 依赖库评估

Cron解析：cron-parser（成熟、稳定、TypeScript支持）
时间处理：使用原生Date对象或day.js（如果项目已使用）
UI组件：Element Plus（项目已使用）
状态管理：Pinia（项目已使用）

C. 与现有系统集成点

用户认证：使用现有用户会话
API通信：使用现有hostApiFetch机制
错误处理：集成现有错误处理系统
主题系统：支持现有明暗主题
路由系统：集成现有路由配置

本计划将根据实际情况进行迭代更新。建议每阶段结束后进行回顾和调整。

13 KiB Raw Blame History Unescape Escape

zn-ai 定时任务（Cron）功能开发计划

项目概述

核心目标

技术约束

开发原则

阶段一：基础架构与类型定义

目标

任务清单

1.1 创建类型定义文件

1.2 创建Pinia Store

1.3 创建API接口占位

1.4 创建国际化文件

1.5 更新国际化配置

交付成果

阶段验收标准

阶段二：核心UI组件开发

目标

任务清单

2.1 创建主页面组件

2.2 创建任务卡片组件

2.3 创建任务对话框组件

2.4 创建统计卡片组件

2.5 创建工具函数

交付成果

阶段验收标准

阶段三：功能集成与数据绑定

目标

任务清单

3.1 集成Store到主页面

3.2 实现任务操作集成

3.3 实现对话框表单提交

3.4 实现调度预览功能

3.5 添加加载状态和反馈

3.6 集成路由和导航

交付成果

阶段验收标准

阶段四：测试、优化与完善

目标

任务清单

4.1 编写单元测试

4.2 添加集成测试

4.3 性能优化

4.4 可访问性改进

4.5 高级功能增强

4.6 文档编写

交付成果

阶段验收标准

时间总览

风险与缓解措施

技术风险

风险1：后端调度引擎缺失

风险2：频道系统不兼容

风险3：Cron表达式复杂性

资源风险

风险1：开发时间不足

风险2：技能匹配问题

成功标准

功能成功标准

技术成功标准

业务成功标准

下一步行动

附录

A. 文件结构规划

B. 依赖库评估

C. 与现有系统集成点

13 KiB

Raw Blame History