feat: 新增定时任务功能

Cron-Development-Plan.md

@@ -0,0 +1,449 @@
+# zn-ai 定时任务（Cron）功能开发计划
+
+## 项目概述
+
+基于ClawX项目的定时任务功能分析，制定zn-ai项目的功能迁移开发计划。目标是在zn-ai项目中实现类似的定时任务管理功能，保持核心功能一致性，同时适配zn-ai的技术栈（Vue 3 + Element Plus + Pinia + Tailwind CSS）。
+
+## 核心目标
+
+1. **实现定时任务管理**：创建、编辑、删除、启用/禁用定时任务
+2. **支持调度配置**：预设调度和自定义Cron表达式
+3. **提供基础交付模式**：至少支持"仅应用内"模式
+4. **集成现有架构**：与zn-ai现有状态管理、API通信、国际化系统集成
+5. **保持UI一致性**：使用Element Plus和现有设计模式
+
+## 技术约束
+
+- **前端框架**：Vue 3 Composition API
+- **状态管理**：Pinia
+- **UI组件库**：Element Plus + Tailwind CSS
+- **国际化**：Vue I18n
+- **API通信**：现有`hostApiFetch` IPC机制
+- **后端集成**：需评估现有任务调度能力，必要时实现简化版本
+
+## 开发原则
+
+1. **分阶段实施**：优先核心功能，逐步增强
+2. **渐进式增强**：先实现基本功能，再添加高级特性
+3. **代码复用**：尽可能复用现有组件和工具函数
+4. **类型安全**：使用TypeScript确保类型安全
+5. **测试驱动**：关键功能编写单元测试
+
+## 阶段一：基础架构与类型定义
+
+### 目标
+建立定时任务功能的基础架构，包括类型定义、状态管理和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. 代码审查和结对编程
+
+## 成功标准
+
+### 功能成功标准
+1. 用户可以创建、编辑、删除定时任务
+2. 任务可以按预定调度执行
+3. 用户界面直观易用
+4. 系统稳定可靠，错误处理得当
+
+### 技术成功标准
+1. 代码质量高，符合项目规范
+2. 测试覆盖关键功能路径
+3. 性能满足要求
+4. 可维护性和可扩展性好
+
+### 业务成功标准
+1. 功能满足用户需求
+2. 用户体验良好
+3. 与现有系统集成顺畅
+4. 为未来扩展奠定基础
+
+## 下一步行动
+
+1. **需求确认**：与相关方确认功能范围和优先级
+2. **技术评估**：详细评估后端调度能力
+3. **环境准备**：设置开发环境和测试数据
+4. **开始实施**：按照阶段一任务开始开发
+
+## 附录
+
+### 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. 依赖库评估
+
+1. **Cron解析**：`cron-parser`（成熟、稳定、TypeScript支持）
+2. **时间处理**：使用原生Date对象或`day.js`（如果项目已使用）
+3. **UI组件**：Element Plus（项目已使用）
+4. **状态管理**：Pinia（项目已使用）
+
+### C. 与现有系统集成点
+
+1. **用户认证**：使用现有用户会话
+2. **API通信**：使用现有`hostApiFetch`机制
+3. **错误处理**：集成现有错误处理系统
+4. **主题系统**：支持现有明暗主题
+5. **路由系统**：集成现有路由配置
+
+---
+
+*本计划将根据实际情况进行迭代更新。建议每阶段结束后进行回顾和调整。*