Files

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

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

文档内容涵盖项目整体介绍、技术架构、核心模块设计和实现细节

2025-09-24 20:21:45 +08:00

6.2 KiB

Raw Blame History

后端架构文档

概述

后端采用 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 响应格式

响应结构:

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 支持
多阶段构建
健康检查
资源限制

6.2 KiB Raw Blame History