mirror of https://github.com/allinssl/allinssl
194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
|
||
# 多功能任务同步工作流管理平台项目文档
|
||
|
||
|
||
## 一、项目概述
|
||
|
||
### 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 插件，适配中英文界面。
|
||
|
||
|
||
|
||
通过以上设计，项目实现了多类型任务的统一管理与高效执行，结合现代技术栈确保了开发效率与用户体验，适用于中小型团队及个人用户的自动化任务场景。 |