# 多功能任务同步工作流管理平台项目文档


## 一、项目概述

### 1. 项目目标
打造一个可视化、可扩展的任务同步工作流管理平台，支持多种主流任务执行类型的配置、管理与自动化执行，帮助用户高效管理跨平台、跨工具的任务流程，提升开发、运维及文件处理效率。


### 2. 核心价值
- **统一管理**：通过标准化界面管理文件同步、项目编译、代码同步等多类型任务，避免工具碎片化。  
- **灵活配置**：支持动态添加任务类型，每种任务类型提供专属配置表单，适配不同场景需求。  
- **高效执行**：集成主流协议（SFTP/FTP）、开发工具（TurboRepo、Git）及本地操作，一键触发任务执行并实时反馈状态。  


### 3. 技术架构
#### 后端
- **框架**：Egg.js（Node.js 企业级框架，支持高性能 API 开发与插件扩展）  
- **数据库**：SQLite（轻量级文件型数据库，适合快速原型与小型部署）  
- **任务执行**：通过 Node.js 原生模块（如 `child_process`）调用系统命令，集成 SFTP/FTP 客户端库（如 `ssh2-sftp-client`）、Git 工具库（如 `simple-git`）实现任务逻辑。  

#### 前端
- **构建工具**：Vite 6（极速开发服务器与优化构建）  
- **框架**：Svelte 5（轻量响应式 UI 框架，组件化开发）  
- **UI 组件库**：Shadcn-Svelte（现代风格、可自定义的组件集合，含表单、表格、模态框等）  
- **状态管理**：Svelte 原生响应式系统 + 轻量表单库（如 `svelte-forms-library`）  


### 4. 适用场景
- **开发团队**：管理项目编译、代码同步（Git）、微服务架构下的项目分离（TurboRepo）。  
- **运维/文件处理**：批量配置文件本地同步、跨服务器 SFTP/FTP 上传任务。  
- **自动化场景**：通过定时触发或手动执行，减少重复性操作。  


## 二、核心功能模块

### 1. 工作流基础管理
#### （1）工作流列表
- **展示字段**：任务名称、类型（文件同步/SFTP上传等）、状态（待执行/进行中/成功/失败）、创建时间、操作（编辑/删除/立即执行）。  
- **交互功能**：  
  - 搜索过滤：支持按任务名称、类型关键词搜索。  
  - 排序功能：按创建时间、执行状态升/降序排列。  
  - 批量操作：可选删除多个任务（需二次确认）。  

#### （2）增删改查操作
- **添加任务**：  
  1. 选择任务类型（下拉菜单，含 5 种预设类型，预留扩展接口）。  
  2. 动态加载该类型专属配置表单（见下文各类型详情）。  
  3. 提交后生成任务记录，状态默认「待执行」。  
- **编辑任务**：支持修改配置参数，保存后不影响历史执行记录。  
- **删除任务**：物理删除数据库记录，关联执行日志可选择保留或清除。  


### 2. 任务类型与配置详情

#### （1）文件本地同步
- **核心功能**：将本地文件/目录从源路径复制到目标路径，支持增量同步（可选）。  
- **配置参数**：  
  - 任务名称（必填）  
  - 入口文件地址：文件/目录选择组件（支持系统文件弹窗选择，显示绝对路径）  
  - 出口文件地址：同上  
  - 同步模式：立即同步/定时同步（可选，需后续扩展定时模块）  

#### （2）文件 SFTP/FTP 上传
- **核心功能**：通过 SFTP（安全传输）或 FTP 协议将本地文件上传至远程服务器。  
- **配置参数**：  
  - 任务名称（必填）  
  - 入口文件地址：本地文件/目录选择  
  - 协议类型：单选按钮（SFTP/FTP，默认 SFTP）  
  - 远程服务器信息：  
    - IP 地址（必填）  
    - 端口（选填，SFTP 默认为 22，FTP 默认为 21）  
    - 用户名（必填）  
    - 密码（必填，输入框掩码处理）  

#### （3）项目编译
- **核心功能**：在指定项目路径执行自定义编译命令（如 `npm run build`、`make` 等）。  
- **配置参数**：  
  - 任务名称（必填）  
  - 项目路径：选择项目根目录（文件选择组件，校验是否存在 `package.json` 等标识文件）  
  - 编译命令：文本输入框（支持多行，如分步骤执行命令，用 `&&` 分隔）  
  - 环境变量：选填（可配置编译所需的环境参数，如 `NODE_ENV=production`）  

#### （4）Git 项目同步
- **核心功能**：克隆、拉取或推送 Git 仓库，支持代码同步与版本控制。  
- **配置参数**：  
  - 任务名称（必填）  
  - Git 项目地址：输入框（支持 `http`/`https`/`ssh` 协议，如 `git@github.com:user/repo.git`）  
  - 本地存储路径：选填（默认克隆至系统临时目录，可自定义本地存放路径）  
  - 操作类型：单选（克隆/拉取/推送，默认拉取）  

#### （5）项目分离（TurboRepo）
- **核心功能**：基于 TurboRepo 架构分离 monorepo 中的子项目，支持独立构建或发布。  
- **配置参数**：  
  - 任务名称（必填）  
  - 分离的项目名称：输入框（需与 TurboRepo 配置中的 `name` 字段匹配）  
  - 根项目路径：选择 TurboRepo 根目录（校验是否存在 `turbo.json` 配置文件）  
  - 操作类型：单选（分离并构建/仅分离，默认分离并构建）  


### 3. 任务执行与反馈
- **触发方式**：  
  - 手动触发：列表页「立即执行」按钮。  
  - 定时触发：后续扩展（需添加 cron 表达式配置字段）。  
- **执行状态**：  
  - 进行中：显示加载动画，禁用编辑/删除操作。  
  - 成功：记录执行时间，可查看日志详情（如同步文件数量、编译输出）。  
  - 失败：显示错误原因（如网络异常、权限不足），支持重试。  
- **日志系统**：  
  - 记录每次执行的开始/结束时间、状态、关键参数及错误信息。  
  - 日志详情页支持关键词搜索、导出为文本文件。  


## 三、技术实现细节

### 1. 后端（Egg.js + SQLite）
#### （1）数据模型设计
`Workflow` 表字段：  
| 字段名         | 类型         | 说明                                                                 |  
|----------------|--------------|----------------------------------------------------------------------|  
| id             | INTEGER      | 自增主键                                                             |  
| name           | VARCHAR(50)  | 任务名称（唯一）                                                     |  
| type           | VARCHAR(20)  | 任务类型（file_local, sftp_ftp, compile, git, turborepo）             |  
| config         | TEXT         | 配置参数（JSON 字符串，存储各类型专属字段，如 SFTP 的 IP、端口等）   |  
| status         | VARCHAR(20)  | 状态（pending/running/success/failed，默认 pending）                 |  
| create_time    | DATETIME     | 创建时间（默认当前时间）                                             |  

#### （2）API 接口设计
- **列表接口**：`GET /workflows`，支持分页、搜索、排序（返回包含状态、类型、操作按钮的列表数据）。  
- **创建/编辑接口**：`POST /workflows`、`PUT /workflows/:id`，接收包含 `type` 和 `config` 的 JSON 数据。  
- **执行接口**：`POST /workflows/:id/execute`，触发任务执行逻辑，返回执行任务 ID 用于状态轮询。  
- **日志接口**：`GET /workflows/:id/logs`，获取该任务历史执行日志。  

#### （3）任务执行逻辑
- 基于 `child_process.spawn` 执行本地命令（如编译、Git 操作），通过流处理实时捕获输出日志。  
- SFTP/FTP 上传使用 `ssh2-sftp-client` 库，支持连接池管理与错误重试（3 次失败后终止）。  
- 任务执行时通过 Egg.js 插件（如 `egg-redis`）实现分布式锁（后续扩展多实例部署）。  


### 2. 前端（Svelte 5 + Shadcn-Svelte）
#### （1）组件结构
- **核心组件**：  
  - `WorkflowList.svelte`：任务列表，包含搜索栏、操作按钮，集成 `shadcn-svelte` 的 `Table`、`Button` 组件。  
  - `WorkflowForm.svelte`：动态表单，根据 `type` 渲染不同字段（如 SFTP 表单包含 IP/端口输入，Git 表单包含仓库地址输入）。  
  - `FileSelect.svelte`：封装文件/目录选择组件，基于原生 `<input type="file">` 扩展目录选择（需浏览器支持 `webkitdirectory` 属性）。  
- **状态管理**：  
  - 使用 Svelte 响应式变量（`let config = {}`）存储表单数据，通过 `bind:value` 绑定输入框。  
  - 表单提交前校验必填字段（如 SFTP 的 IP、用户名），错误信息通过 `shadcn-svelte` 的 `Alert` 组件提示。  

#### （2）动态表单实现
```svelte
{#if type === 'sftp_ftp'}
  <SFTPConfigForm bind:config />
{:else if type === 'compile'}
  <CompileConfigForm bind:config />
{:else if type === 'git'}
  <GitConfigForm bind:config />
{/if}
```
每个类型对应独立子组件，封装专属字段逻辑，提升可维护性。  

#### （3）执行状态交互
- 点击「立即执行」按钮后，禁用按钮并显示加载状态，通过 WebSocket（后续扩展）或轮询接口（`GET /workflows/:id/status`）实时更新任务状态。  
- 失败状态显示红色警告，附带「重试」按钮，一键重新提交执行请求。  


## 四、技术栈文档索引
1. **Egg.js 框架**  
   - 官网：[https://www.eggjs.org/zh-CN](https://www.eggjs.org/zh-CN)  
   - 核心功能：插件机制、中间件、ORM 集成（本项目使用 SQLite 原生驱动）。  

2. **Shadcn-Svelte**  
   - 官网：[https://next.shadcn-svelte.com/](https://next.shadcn-svelte.com/)  
   - 组件列表：按钮、表单、模态框、表格等，支持完全自定义样式（基于 Tailwind CSS）。  

3. **Svelte 5**  
   - 官网：[https://svelte.dev/](https://svelte.dev/)  
   - 特性：组件化开发、响应式系统、编译时优化，适合构建高性能前端界面。  

4. **Vite 6**  
   - 官网：[https://cn.vitejs.dev/](https://cn.vitejs.dev/)  
   - 优势：极速冷启动、按需编译、支持 Svelte 单文件组件（.svelte）热更新。  


## 五、后续扩展方向
1. **定时任务**：添加 cron 表达式配置，支持按计划执行任务（如每天凌晨同步文件）。  
2. **可视化工作流编辑器**：允许用户通过拖拽节点配置多步骤任务流程（如先编译项目，再同步至服务器）。  
3. **权限管理**：区分管理员与普通用户，控制任务创建、编辑权限。  
4. **多语言支持**：集成 i18n 插件，适配中英文界面。  

 

通过以上设计，项目实现了多类型任务的统一管理与高效执行，结合现代技术栈确保了开发效率与用户体验，适用于中小型团队及个人用户的自动化任务场景。