udmin/docs/BACKEND_ARCHITECTURE.md

# 后端架构文档

## 概述

后端采用 Rust + Axum 构建，遵循分层架构设计，包含数据访问层、业务逻辑层、路由层和中间件层。

## 核心模块

### 1. 应用入口 (main.rs)

**职责**: 应用启动、服务配置、中间件注册

**主要功能**:
- 数据库连接初始化
- Redis 连接配置
- CORS 跨域设置
- 多端口服务启动 (HTTP/WebSocket/SSE)
- 日志中间件注册

**服务端口**:
- HTTP API: 9898 (默认)
- WebSocket: 8877 (默认)
- SSE: 8866 (默认)

### 2. 数据库层 (db.rs)

**职责**: 数据库连接管理和配置

**特性**:
- 支持多种数据库 (MySQL/PostgreSQL/SQLite)
- 连接池管理
- 事务支持
- 自动迁移

### 3. 错误处理 (error.rs)

**职责**: 统一错误类型定义和处理

**错误类型**:
- `DatabaseError`: 数据库操作错误
- `ValidationError`: 数据验证错误
- `AuthenticationError`: 认证错误
- `AuthorizationError`: 授权错误
- `NotFoundError`: 资源不存在
- `InternalServerError`: 内部服务器错误

### 4. 响应格式 (response.rs)

**职责**: 统一 API 响应格式

**响应结构**:
```rust
pub struct ApiResponse<T> {
    pub code: i32,
    pub message: String,
    pub data: Option<T>,
}

pub struct PageResponse<T> {
    pub items: Vec<T>,
    pub total: u64,
    pub page: u64,
    pub page_size: u64,
}
```

## 业务模块

### Models (数据模型层)

**位置**: `src/models/`

**模型列表**:
- `user.rs`: 用户模型
- `role.rs`: 角色模型
- `menu.rs`: 菜单模型
- `department.rs`: 部门模型
- `position.rs`: 职位模型
- `flow.rs`: 流程模型
- `schedule_job.rs`: 定时任务模型
- `flow_run_log.rs`: 流程运行日志
- `request_log.rs`: 请求日志
- `refresh_token.rs`: 刷新令牌

**特性**:
- 使用 SeaORM 宏自动生成
- 支持关联查询
- 自动时间戳管理
- 软删除支持

### Services (业务逻辑层)

**位置**: `src/services/`

**服务列表**:
- `auth_service.rs`: 认证服务
- `user_service.rs`: 用户管理服务
- `role_service.rs`: 角色管理服务
- `menu_service.rs`: 菜单管理服务
- `department_service.rs`: 部门管理服务
- `position_service.rs`: 职位管理服务
- `flow_service.rs`: 流程管理服务
- `schedule_job_service.rs`: 定时任务服务
- `flow_run_log_service.rs`: 流程日志服务
- `log_service.rs`: 系统日志服务

**设计原则**:
- 单一职责原则
- 依赖注入
- 异步处理
- 事务管理

### Routes (路由层)

**位置**: `src/routes/`

**路由模块**:
- `auth.rs`: 认证相关路由
- `users.rs`: 用户管理路由
- `roles.rs`: 角色管理路由
- `menus.rs`: 菜单管理路由
- `departments.rs`: 部门管理路由
- `positions.rs`: 职位管理路由
- `flows.rs`: 流程管理路由
- `schedule_jobs.rs`: 定时任务路由
- `flow_run_logs.rs`: 流程日志路由
- `logs.rs`: 系统日志路由
- `dynamic_api.rs`: 动态 API 路由

**路由特性**:
- RESTful API 设计
- 参数验证
- 权限检查
- 分页支持
- 错误处理

### Middlewares (中间件层)

**位置**: `src/middlewares/`

**中间件列表**:
- `jwt.rs`: JWT 认证中间件
- `logging.rs`: 请求日志中间件
- `http_client.rs`: HTTP 客户端中间件
- `ws.rs`: WebSocket 服务中间件
- `sse.rs`: SSE 服务中间件

**功能特性**:
- 请求/响应拦截
- 认证授权
- 日志记录
- 跨域处理
- 实时通信

### Utils (工具模块)

**位置**: `src/utils/`

**工具列表**:
- `ids.rs`: ID 生成器 (Snowflake 算法)
- `password.rs`: 密码哈希工具
- `scheduler.rs`: 任务调度器

**特性**:
- 分布式 ID 生成
- 安全密码处理
- 定时任务管理

## 流程引擎

**位置**: `src/flow/`

### 核心组件

#### 1. 领域模型 (domain.rs)
- `ChainDef`: 流程链定义
- `NodeDef`: 节点定义
- `LinkDef`: 连接定义
- `NodeKind`: 节点类型枚举

#### 2. DSL 解析 (dsl.rs)
- `FlowDSL`: 流程 DSL 结构
- `NodeDSL`: 节点 DSL 结构
- `DesignSyntax`: 设计语法结构
- 校验和构建函数

#### 3. 执行引擎 (engine.rs)
- `FlowEngine`: 流程执行引擎
- `TaskRegistry`: 任务注册表
- `DriveOptions`: 执行选项
- 并发执行支持

#### 4. 执行器 (executors/)
- `http.rs`: HTTP 请求执行器
- `db.rs`: 数据库操作执行器
- `condition.rs`: 条件判断执行器
- `script_js.rs`: JavaScript 脚本执行器
- `script_python.rs`: Python 脚本执行器
- `script_rhai.rs`: Rhai 脚本执行器
- `variable.rs`: 变量操作执行器

#### 5. 上下文管理 (context.rs)
- `StreamEvent`: 流事件定义
- 执行上下文管理
- 事件流处理

#### 6. 日志处理 (log_handler.rs)
- 流程执行日志
- 错误日志记录
- 性能监控

## 数据库设计

### 核心表结构

#### 用户权限相关
- `users`: 用户表
- `roles`: 角色表
- `menus`: 菜单表
- `departments`: 部门表
- `positions`: 职位表
- `user_roles`: 用户角色关联表
- `role_menus`: 角色菜单关联表
- `user_departments`: 用户部门关联表
- `user_positions`: 用户职位关联表

#### 流程相关
- `flows`: 流程表
- `flow_run_logs`: 流程运行日志表
- `schedule_jobs`: 定时任务表

#### 系统相关
- `request_logs`: 请求日志表
- `refresh_tokens`: 刷新令牌表

### 索引策略
- 主键索引
- 外键索引
- 查询优化索引
- 复合索引

## 安全机制

### 认证授权
- JWT 令牌机制
- 刷新令牌支持
- 权限中间件验证
- 角色基础访问控制 (RBAC)

### 数据安全
- Argon2 密码哈希
- SQL 注入防护
- XSS 防护
- CSRF 防护

### 通信安全
- HTTPS 支持
- CORS 配置
- 请求限流
- 日志审计

## 性能优化

### 数据库优化
- 连接池管理
- 查询优化
- 索引策略
- 分页查询

### 缓存策略
- Redis 缓存
- 查询结果缓存
- 会话缓存

### 并发处理
- 异步 I/O
- 任务队列
- 连接复用
- 资源池管理

## 监控和日志

### 日志系统
- 结构化日志 (tracing)
- 分级日志记录
- 请求链路追踪
- 错误堆栈记录

### 监控指标
- 请求响应时间
- 数据库连接状态
- 内存使用情况
- 错误率统计

## 部署配置

### 环境变量
- 数据库连接配置
- Redis 连接配置
- JWT 密钥配置
- 服务端口配置
- CORS 配置

### 容器化
- Docker 支持
- 多阶段构建
- 健康检查
- 资源限制