# 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-react/router/index.tsx`、`src-react/router/routes.ts`、`src-react/components/layout/Sidebar.tsx`
- **内容**：
  - 在 React 路由表中添加定时任务页面入口
  - 更新 `NAV_ITEMS` / 侧边栏导航项
  - 如需鉴权，沿用 `src-react/router/auth.tsx` 中的路由守卫
- **依赖**：主页面组件
- **预估工时**：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. **路由系统**：集成现有路由配置

---

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