udmin/docs/FRONTEND_ARCHITECTURE.md

前端架构文档

概述

前端采用 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

职责: 主要页面布局

功能:

• 侧边栏导航
• 顶部导航栏
• 面包屑导航
• 用户信息显示
• 响应式布局

布局结构:

<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 定义
• 事件处理
• 样式组织

文件组织

• 目录结构
• 文件命名
• 导入导出
• 类型定义