docs: 添加项目文档包括总览、架构、流程引擎和服务层

新增以下文档文件:
- PROJECT_OVERVIEW.md 项目总览文档
- BACKEND_ARCHITECTURE.md 后端架构文档
- FRONTEND_ARCHITECTURE.md 前端架构文档
- FLOW_ENGINE.md 流程引擎文档
- SERVICES.md 服务层文档
- ERROR_HANDLING.md 错误处理模块文档

文档内容涵盖项目整体介绍、技术架构、核心模块设计和实现细节
This commit is contained in:
2025-09-24 20:21:45 +08:00
parent 6ff587dc23
commit a3f2f99a68
13 changed files with 11803 additions and 0 deletions

137
docs/PROJECT_OVERVIEW.md Normal file
View File

@ -0,0 +1,137 @@
# UdminAI 项目总览
## 项目简介
UdminAI 是一个基于 Rust + React 的现代化流程管理和自动化平台,提供可视化流程编辑、定时任务调度、用户权限管理等功能。
## 技术架构
### 后端技术栈
- **框架**: Axum (异步 Web 框架)
- **数据库**: SeaORM (支持 MySQL/PostgreSQL/SQLite)
- **缓存**: Redis
- **认证**: JWT + Argon2 密码哈希
- **定时任务**: tokio-cron-scheduler
- **流程引擎**: 自研流程执行引擎
- **实时通信**: WebSocket + SSE
### 前端技术栈
- **框架**: React 18 + TypeScript
- **UI 库**: Semi Design + Ant Design
- **流程编辑器**: @flowgram.ai 系列组件
- **状态管理**: React Context
- **路由**: React Router v6
- **HTTP 客户端**: Axios
## 项目结构
```
udmin_ai/
├── backend/ # Rust 后端服务
│ ├── src/
│ │ ├── flow/ # 流程引擎核心
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务逻辑层
│ │ ├── routes/ # API 路由
│ │ ├── middlewares/ # 中间件
│ │ └── utils/ # 工具函数
│ └── migration/ # 数据库迁移
├── frontend/ # React 前端应用
│ └── src/
│ ├── flows/ # 流程编辑器
│ ├── pages/ # 页面组件
│ ├── components/ # 通用组件
│ └── utils/ # 工具函数
├── docs/ # 项目文档
├── scripts/ # 部署脚本
└── README.md
```
## 核心功能模块
### 1. 用户权限管理
- 用户管理 (Users)
- 角色管理 (Roles)
- 菜单权限 (Menus)
- 部门管理 (Departments)
- 职位管理 (Positions)
### 2. 流程管理
- 可视化流程编辑器
- 流程执行引擎
- 流程运行日志
- 多种节点类型支持 (HTTP、数据库、脚本、条件等)
### 3. 定时任务
- Cron 表达式支持
- 任务调度管理
- 执行状态监控
### 4. 系统监控
- 请求日志记录
- 系统运行状态
- 实时通信支持
## 部署架构
### 服务端口分配
- **HTTP API**: 9898 (可配置)
- **WebSocket**: 8877 (可配置)
- **SSE**: 8866 (可配置)
- **前端开发服务器**: 8888
### 环境配置
- 开发环境: `.env`
- 生产环境: `.env.prod`
- 测试环境: `.env.staging`
## 开发指南
### 后端开发
```bash
cd backend
cargo run # 开发模式
cargo build --release # 生产构建
```
### 前端开发
```bash
cd frontend
npm install
npm run dev # 开发服务器
npm run build # 生产构建
```
### 数据库迁移
```bash
cd backend/migration
cargo run
```
## API 文档
项目集成了 Swagger UI启动后端服务后可访问
- Swagger UI: `http://localhost:9898/swagger-ui/`
- OpenAPI JSON: `http://localhost:9898/api-docs/openapi.json`
## 安全特性
- JWT 令牌认证
- Argon2 密码哈希
- CORS 跨域保护
- 请求日志记录
- 权限中间件验证
## 扩展性设计
- 模块化架构,易于扩展新功能
- 插件化流程节点,支持自定义执行器
- 微服务友好的设计
- 支持水平扩展
## 监控和日志
- 结构化日志 (tracing)
- 请求链路追踪
- 性能监控
- 错误处理和报告