ayou
a3f2f99a68
新增以下文档文件： - PROJECT_OVERVIEW.md 项目总览文档 - BACKEND_ARCHITECTURE.md 后端架构文档 - FRONTEND_ARCHITECTURE.md 前端架构文档 - FLOW_ENGINE.md 流程引擎文档 - SERVICES.md 服务层文档 - ERROR_HANDLING.md 错误处理模块文档 文档内容涵盖项目整体介绍、技术架构、核心模块设计和实现细节
439 lines
8.5 KiB
Markdown
439 lines
8.5 KiB
Markdown
# 前端架构文档
|
|
|
|
## 概述
|
|
|
|
前端采用 React 18 + TypeScript 构建，使用现代化的组件化架构，集成了强大的流程可视化编辑器。
|
|
|
|
## 技术栈
|
|
|
|
### 核心框架
|
|
- **React 18**: 前端框架，支持并发特性
|
|
- **TypeScript**: 类型安全的 JavaScript 超集
|
|
- **Vite**: 现代化构建工具
|
|
|
|
### UI 组件库
|
|
- **Semi Design**: 主要 UI 组件库
|
|
- **Ant Design**: 补充 UI 组件
|
|
- **Styled Components**: CSS-in-JS 样式解决方案
|
|
|
|
### 流程编辑器
|
|
- **@flowgram.ai/free-layout-editor**: 自由布局编辑器核心
|
|
- **@flowgram.ai/form-materials**: 表单物料组件
|
|
- **@flowgram.ai/runtime-js**: 流程运行时
|
|
- **@flowgram.ai/minimap-plugin**: 小地图插件
|
|
- **@flowgram.ai/panel-manager-plugin**: 面板管理插件
|
|
|
|
### 状态管理和路由
|
|
- **React Context**: 状态管理
|
|
- **React Router v6**: 客户端路由
|
|
- **Axios**: HTTP 客户端
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
frontend/src/
|
|
├── App.tsx # 应用根组件
|
|
├── main.tsx # 应用入口
|
|
├── vite-env.d.ts # Vite 类型声明
|
|
├── assets/ # 静态资源
|
|
├── components/ # 通用组件
|
|
├── flows/ # 流程编辑器模块
|
|
├── layouts/ # 布局组件
|
|
├── pages/ # 页面组件
|
|
├── styles/ # 全局样式
|
|
└── utils/ # 工具函数
|
|
```
|
|
|
|
## 核心模块
|
|
|
|
### 1. 应用入口 (main.tsx)
|
|
|
|
**职责**: 应用初始化和根组件渲染
|
|
|
|
**功能**:
|
|
- React 18 严格模式启用
|
|
- 路由配置
|
|
- 全局样式导入
|
|
- 错误边界设置
|
|
|
|
### 2. 应用根组件 (App.tsx)
|
|
|
|
**职责**: 应用路由配置和布局管理
|
|
|
|
**功能**:
|
|
- 路由定义和保护
|
|
- 认证状态管理
|
|
- 全局错误处理
|
|
- 主题配置
|
|
|
|
### 3. 布局系统 (layouts/)
|
|
|
|
#### MainLayout.tsx
|
|
**职责**: 主要页面布局
|
|
|
|
**功能**:
|
|
- 侧边栏导航
|
|
- 顶部导航栏
|
|
- 面包屑导航
|
|
- 用户信息显示
|
|
- 响应式布局
|
|
|
|
**布局结构**:
|
|
```tsx
|
|
<Layout>
|
|
<Sider>侧边栏</Sider>
|
|
<Layout>
|
|
<Header>顶部导航</Header>
|
|
<Content>页面内容</Content>
|
|
<Footer>页脚</Footer>
|
|
</Layout>
|
|
</Layout>
|
|
```
|
|
|
|
### 4. 页面组件 (pages/)
|
|
|
|
#### 管理页面
|
|
- `Dashboard.tsx`: 仪表板页面
|
|
- `Users.tsx`: 用户管理页面
|
|
- `Roles.tsx`: 角色管理页面
|
|
- `Menus.tsx`: 菜单管理页面
|
|
- `Departments.tsx`: 部门管理页面
|
|
- `Positions.tsx`: 职位管理页面
|
|
- `Permissions.tsx`: 权限管理页面
|
|
|
|
#### 流程相关页面
|
|
- `FlowList.tsx`: 流程列表页面
|
|
- `FlowRunLogs.tsx`: 流程运行日志页面
|
|
- `ScheduleJobs.tsx`: 定时任务页面
|
|
|
|
#### 系统页面
|
|
- `Login.tsx`: 登录页面
|
|
- `Logs.tsx`: 系统日志页面
|
|
|
|
**页面特性**:
|
|
- 统一的 CRUD 操作
|
|
- 表格分页和搜索
|
|
- 表单验证
|
|
- 权限控制
|
|
- 响应式设计
|
|
|
|
### 5. 通用组件 (components/)
|
|
|
|
#### PageHeader.tsx
|
|
**职责**: 页面头部组件
|
|
|
|
**功能**:
|
|
- 页面标题显示
|
|
- 面包屑导航
|
|
- 操作按钮区域
|
|
- 统一样式
|
|
|
|
### 6. 工具函数 (utils/)
|
|
|
|
#### axios.ts
|
|
**职责**: HTTP 客户端配置
|
|
|
|
**功能**:
|
|
- 请求/响应拦截器
|
|
- 自动 Token 添加
|
|
- 错误统一处理
|
|
- 请求重试机制
|
|
|
|
#### token.ts
|
|
**职责**: 令牌管理
|
|
|
|
**功能**:
|
|
- Token 存储和获取
|
|
- Token 过期检查
|
|
- 自动刷新机制
|
|
- 登出清理
|
|
|
|
#### permission.tsx
|
|
**职责**: 权限控制
|
|
|
|
**功能**:
|
|
- 权限检查组件
|
|
- 路由权限保护
|
|
- 按钮级权限控制
|
|
- 角色权限验证
|
|
|
|
#### sse.ts
|
|
**职责**: 服务端推送事件
|
|
|
|
**功能**:
|
|
- SSE 连接管理
|
|
- 事件监听
|
|
- 自动重连
|
|
- 错误处理
|
|
|
|
#### datetime.ts
|
|
**职责**: 日期时间处理
|
|
|
|
**功能**:
|
|
- 日期格式化
|
|
- 时区转换
|
|
- 相对时间显示
|
|
- 日期计算
|
|
|
|
#### config.ts
|
|
**职责**: 应用配置
|
|
|
|
**功能**:
|
|
- 环境变量管理
|
|
- API 端点配置
|
|
- 应用常量定义
|
|
- 功能开关
|
|
|
|
## 流程编辑器模块
|
|
|
|
**位置**: `src/flows/`
|
|
|
|
### 核心组件
|
|
|
|
#### 1. 编辑器入口 (editor.tsx)
|
|
**职责**: 流程编辑器主组件
|
|
|
|
**功能**:
|
|
- 编辑器初始化
|
|
- 插件注册
|
|
- 事件处理
|
|
- 数据同步
|
|
|
|
#### 2. 应用容器 (app.tsx)
|
|
**职责**: 编辑器应用容器
|
|
|
|
**功能**:
|
|
- 编辑器配置
|
|
- 工具栏管理
|
|
- 侧边栏控制
|
|
- 快捷键支持
|
|
|
|
#### 3. 初始数据 (initial-data.ts)
|
|
**职责**: 编辑器初始化数据
|
|
|
|
**功能**:
|
|
- 默认节点配置
|
|
- 画布初始状态
|
|
- 工具栏配置
|
|
- 插件配置
|
|
|
|
### 节点系统 (nodes/)
|
|
|
|
#### 节点类型
|
|
- `start/`: 开始节点
|
|
- `end/`: 结束节点
|
|
- `condition/`: 条件节点
|
|
- `http/`: HTTP 请求节点
|
|
- `db/`: 数据库操作节点
|
|
- `code/`: 代码执行节点
|
|
- `variable/`: 变量操作节点
|
|
- `loop/`: 循环节点
|
|
- `comment/`: 注释节点
|
|
- `group/`: 分组节点
|
|
|
|
#### 节点特性
|
|
- 可视化配置界面
|
|
- 参数验证
|
|
- 实时预览
|
|
- 拖拽支持
|
|
- 连接点管理
|
|
|
|
### 组件系统 (components/)
|
|
|
|
#### 核心组件
|
|
- `base-node/`: 基础节点组件
|
|
- `node-panel/`: 节点配置面板
|
|
- `sidebar/`: 侧边栏组件
|
|
- `tools/`: 工具栏组件
|
|
- `testrun/`: 测试运行组件
|
|
|
|
#### 交互组件
|
|
- `add-node/`: 添加节点组件
|
|
- `node-menu/`: 节点菜单
|
|
- `line-add-button/`: 连线添加按钮
|
|
- `selector-box-popover/`: 选择框弹窗
|
|
|
|
### 表单系统 (form-components/)
|
|
|
|
#### 表单组件
|
|
- `form-header/`: 表单头部
|
|
- `form-content/`: 表单内容
|
|
- `form-inputs/`: 表单输入组件
|
|
- `form-item/`: 表单项组件
|
|
- `feedback.tsx`: 反馈组件
|
|
|
|
### 插件系统 (plugins/)
|
|
|
|
#### 插件列表
|
|
- `context-menu-plugin/`: 右键菜单插件
|
|
- `runtime-plugin/`: 运行时插件
|
|
- `variable-panel-plugin/`: 变量面板插件
|
|
|
|
### 快捷键系统 (shortcuts/)
|
|
|
|
#### 快捷键功能
|
|
- `copy/`: 复制功能
|
|
- `paste/`: 粘贴功能
|
|
- `delete/`: 删除功能
|
|
- `select-all/`: 全选功能
|
|
- `zoom-in/`: 放大功能
|
|
- `zoom-out/`: 缩小功能
|
|
- `collapse/`: 折叠功能
|
|
- `expand/`: 展开功能
|
|
|
|
### 上下文管理 (context/)
|
|
|
|
#### 上下文类型
|
|
- `node-render-context.ts`: 节点渲染上下文
|
|
- `sidebar-context.ts`: 侧边栏上下文
|
|
|
|
### Hooks 系统 (hooks/)
|
|
|
|
#### 自定义 Hooks
|
|
- `use-editor-props.tsx`: 编辑器属性 Hook
|
|
- `use-is-sidebar.ts`: 侧边栏状态 Hook
|
|
- `use-node-render-context.ts`: 节点渲染上下文 Hook
|
|
- `use-port-click.ts`: 端口点击 Hook
|
|
|
|
### 工具函数 (utils/)
|
|
|
|
#### 工具函数
|
|
- `yaml.ts`: YAML 处理工具
|
|
- `on-drag-line-end.ts`: 拖拽连线结束处理
|
|
- `toggle-loop-expanded.ts`: 循环节点展开切换
|
|
|
|
## 状态管理
|
|
|
|
### Context 设计
|
|
|
|
#### 全局状态
|
|
- 用户认证状态
|
|
- 权限信息
|
|
- 主题配置
|
|
- 语言设置
|
|
|
|
#### 页面状态
|
|
- 表格数据
|
|
- 分页信息
|
|
- 搜索条件
|
|
- 选中项
|
|
|
|
#### 编辑器状态
|
|
- 画布数据
|
|
- 选中节点
|
|
- 编辑模式
|
|
- 工具栏状态
|
|
|
|
### 状态更新模式
|
|
- 不可变更新
|
|
- 批量更新
|
|
- 异步状态处理
|
|
- 错误状态管理
|
|
|
|
## 路由设计
|
|
|
|
### 路由结构
|
|
```
|
|
/
|
|
├── /login # 登录页面
|
|
├── /dashboard # 仪表板
|
|
├── /users # 用户管理
|
|
├── /roles # 角色管理
|
|
├── /menus # 菜单管理
|
|
├── /departments # 部门管理
|
|
├── /positions # 职位管理
|
|
├── /permissions # 权限管理
|
|
├── /flows # 流程列表
|
|
├── /flows/:id/edit # 流程编辑
|
|
├── /flows/logs # 流程日志
|
|
├── /schedule-jobs # 定时任务
|
|
└── /logs # 系统日志
|
|
```
|
|
|
|
### 路由保护
|
|
- 认证检查
|
|
- 权限验证
|
|
- 角色控制
|
|
- 重定向处理
|
|
|
|
## 样式系统
|
|
|
|
### CSS 架构
|
|
- 全局样式 (`global.css`)
|
|
- 组件样式 (CSS Modules)
|
|
- 主题变量
|
|
- 响应式断点
|
|
|
|
### 设计系统
|
|
- 颜色规范
|
|
- 字体规范
|
|
- 间距规范
|
|
- 组件规范
|
|
|
|
## 性能优化
|
|
|
|
### 代码分割
|
|
- 路由级别分割
|
|
- 组件懒加载
|
|
- 动态导入
|
|
- Bundle 分析
|
|
|
|
### 渲染优化
|
|
- React.memo 使用
|
|
- useMemo 缓存
|
|
- useCallback 优化
|
|
- 虚拟滚动
|
|
|
|
### 资源优化
|
|
- 图片懒加载
|
|
- 资源压缩
|
|
- CDN 加速
|
|
- 缓存策略
|
|
|
|
## 测试策略
|
|
|
|
### 测试类型
|
|
- 单元测试
|
|
- 集成测试
|
|
- E2E 测试
|
|
- 视觉回归测试
|
|
|
|
### 测试工具
|
|
- Jest: 单元测试框架
|
|
- React Testing Library: 组件测试
|
|
- Cypress: E2E 测试
|
|
- Storybook: 组件文档
|
|
|
|
## 构建和部署
|
|
|
|
### 构建配置
|
|
- Vite 配置优化
|
|
- 环境变量管理
|
|
- 代码分割策略
|
|
- 资源优化
|
|
|
|
### 部署策略
|
|
- 静态资源部署
|
|
- CDN 配置
|
|
- 缓存策略
|
|
- 版本管理
|
|
|
|
## 开发规范
|
|
|
|
### 代码规范
|
|
- ESLint 配置
|
|
- Prettier 格式化
|
|
- TypeScript 严格模式
|
|
- 提交规范
|
|
|
|
### 组件规范
|
|
- 组件命名
|
|
- Props 定义
|
|
- 事件处理
|
|
- 样式组织
|
|
|
|
### 文件组织
|
|
- 目录结构
|
|
- 文件命名
|
|
- 导入导出
|
|
- 类型定义 |