449 lines
13 KiB
Markdown
449 lines
13 KiB
Markdown
# 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. **路由系统**：集成现有路由配置
|
||
|
||
---
|
||
|
||
*本计划将根据实际情况进行迭代更新。建议每阶段结束后进行回顾和调整。* |