docs: 添加项目文档包括总览、架构、流程引擎和服务层
新增以下文档文件： - PROJECT_OVERVIEW.md 项目总览文档 - BACKEND_ARCHITECTURE.md 后端架构文档 - FRONTEND_ARCHITECTURE.md 前端架构文档 - FLOW_ENGINE.md 流程引擎文档 - SERVICES.md 服务层文档 - ERROR_HANDLING.md 错误处理模块文档 文档内容涵盖项目整体介绍、技术架构、核心模块设计和实现细节
This commit is contained in:
439
docs/FRONTEND_ARCHITECTURE.md
Normal file
439
docs/FRONTEND_ARCHITECTURE.md
Normal file
@ -0,0 +1,439 @@
|
||||
# 前端架构文档
|
||||
|
||||
## 概述
|
||||
|
||||
前端采用 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 定义
|
||||
- 事件处理
|
||||
- 样式组织
|
||||
|
||||
### 文件组织
|
||||
- 目录结构
|
||||
- 文件命名
|
||||
- 导入导出
|
||||
- 类型定义
|
||||
Reference in New Issue
Block a user