# 前端架构文档

## 概述

前端采用 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 定义
- 事件处理
- 样式组织

### 文件组织
- 目录结构
- 文件命名
- 导入导出
- 类型定义