# Novalon 管理系统 - 系统架构设计文档

## 1. 系统概述

Novalon 管理系统是一个企业级后台管理系统，采用前后端分离架构，基于 Spring WebFlux 响应式编程模型。

## 2. 技术架构

### 2.1 后端架构

- **框架**: Spring Boot 3.4.1
- **编程模型**: 响应式 WebFlux
- **数据库**: PostgreSQL 15 + R2DBC
- **认证**: JWT + Spring Security
- **缓存**: Caffeine
- **文档**: SpringDoc OpenAPI 3.0
- **构建工具**: Maven 3.9
- **JDK**: Java 21

### 2.2 前端架构

- **框架**: Vue 3 + TypeScript 5.0
- **UI 组件**: Ant Design Vue 4.0
- **状态管理**: Pinia
- **路由**: Vue Router 4.0
- **构建工具**: Vite 5.0
- **HTTP 客户端**: Axios

### 2.3 基础设施

- **容器化**: Docker
- **编排**: Docker Compose
- **CI/CD**: Woodpecker
- **监控**: Prometheus + Grafana
- **日志**: 结构化日志 (SLF4J)

## 3. 分层架构

```
┌─────────────────────────────────────┐
│         Frontend (Vue 3)           │
│    - TypeScript                     │
│    - Ant Design Vue               │
│    - Pinia State                  │
└──────────────┬──────────────────────┘
               │ HTTP/WebSocket
┌──────────────▼──────────────────────┐
│         Handler Layer               │
│    (Functional WebFlux Routes)      │
│    - Request Validation             │
│    - Response Formatting            │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Service Layer               │
│      (Business Logic)              │
│    - @Cacheable                  │
│    - Transaction Management        │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         DAO Layer                   │
│   (Data Access Object)             │
│    - Repository Pattern            │
│    - R2DBC Operations           │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Entity Layer                │
│   (Database Entities)              │
│    - MapStruct Mappers           │
│    - Domain Objects              │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Database (PostgreSQL)      │
│    - Connection Pool (HikariCP)    │
│    - Indexes                     │
└─────────────────────────────────────┘
```

## 4. 核心模块

### 4.1 用户管理 (User Management)
- 用户 CRUD 操作
- 用户认证与授权
- 密码管理 (BCrypt 加密)
- 角色分配
- 用户状态管理 (启用/禁用)
- 逻辑删除与恢复

### 4.2 角色管理 (Role Management)
- 角色定义与维护
- 权限配置
- 菜单关联
- 角色排序
- 角色状态管理

### 4.3 菜单管理 (Menu Management)
- 菜单树结构
- 路由配置
- 权限控制
- 菜单类型 (目录/菜单/按钮)
- 图标配置

### 4.4 字典管理 (Dictionary Management)
- 字典类型管理
- 字典数据管理
- 字典缓存
- 字典查询优化

### 4.5 系统配置 (System Configuration)
- 系统参数配置
- 配置管理
- 配置缓存
- 配置类型分类

### 4.6 审计日志 (Audit Logs)
- 操作日志记录
- 登录日志记录
- 异常日志记录
- 日志查询与导出

### 4.7 通知中心 (Notification Center)
- 通知公告管理
- 用户消息管理
- WebSocket 实时推送
- 消息状态跟踪

### 4.8 文件管理 (File Management)
- 文件上传 (Multipart)
- 文件下载
- 文件预览
- 文件类型限制
- 文件大小限制

## 5. 数据流

### 5.1 请求流程

```
1. 前端发送 HTTP 请求
   ↓
2. Handler 层接收请求并解析参数
   ↓
3. Service 层处理业务逻辑
   - 缓存检查
   - 数据验证
   ↓
4. DAO 层访问数据库
   - R2DBC 非阻塞查询
   ↓
5. 数据库返回结果
   ↓
6. 逐层返回给前端
   - Mono/Flux 响应式流
```

### 5.2 响应式数据流

```
Frontend Request
    ↓
Handler (Mono/Flux)
    - ServerRequest → Mono<ServerResponse>
    ↓
Service (Mono/Flux)
    - @Cacheable 缓存拦截
    - 业务逻辑处理
    ↓
DAO (Mono/Flux)
    - R2DBC 非阻塞 I/O
    ↓
Database (R2DBC Driver)
    - 异步数据库操作
    ↓
Response (Mono/Flux)
    - 响应式流返回
    ↓
Frontend
```

## 6. 安全设计

### 6.1 认证机制
- JWT Token 认证
- Token 刷新机制
- 密码 BCrypt 加密存储
- 登录失败次数限制
- Token 过期时间控制

### 6.2 授权机制
- 基于角色的访问控制 (RBAC)
- API 级别权限控制
- 菜单级别权限控制
- 数据级权限控制

### 6.3 审计机制
- 操作日志记录 (CRUD 操作)
- 登录日志记录 (成功/失败)
- 异常日志记录
- 敏感操作审计

### 6.4 数据安全
- SQL 注入防护 (R2DBC 参数化查询)
- XSS 防护 (输入验证)
- CSRF 防护 (Token 验证)
- 文件上传安全 (类型/大小限制)

## 7. 性能优化

### 7.1 响应式编程优势
- 非阻塞 I/O 操作
- 背压机制 (Backpressure)
- 异步处理能力
- 高并发支持

### 7.2 缓存策略
- Caffeine 本地缓存
- 缓存预热
- 缓存失效策略 (TTL 30 分钟)
- 缓存命中率监控

### 7.3 数据库优化
- 索引优化 (单列/复合索引)
- 查询优化 (EXPLAIN ANALYZE)
- 连接池配置 (HikariCP)
- 慢查询监控

### 7.4 性能指标
- P95 响应时间 < 500ms
- P99 响应时间 < 1000ms
- 并发支持 > 50 QPS
- 数据库连接池利用率 < 80%

## 8. 监控与运维

### 8.1 健康检查
- Spring Boot Actuator 端点
- 数据库连接检查
- 缓存状态检查
- 磁盘空间检查

### 8.2 指标监控
- Prometheus 指标采集
- Grafana 可视化
- JVM 内存使用
- HTTP 请求指标
- 数据库连接池状态
- 缓存命中率

### 8.3 日志管理
- 结构化日志 (JSON 格式)
- 日志级别控制 (DEBUG/INFO/WARN/ERROR)
- 日志归档策略
- ELK 集成 (可选)

### 8.4 告警规则
- 响应时间 > 1s 告警
- 错误率 > 1% 告警
- 数据库连接池耗尽告警
- JVM 内存使用 > 80% 告警

## 9. 部署架构

### 9.1 容器化部署
- Docker 镜像构建 (多阶段构建)
- Docker Compose 编排
- 环境变量配置
- 数据持久化卷

### 9.2 CI/CD 流水线
- Woodpecker CI 配置
- 自动化测试 (单元/集成/E2E)
- 代码覆盖率检查 (JaCoCo >= 80%)
- 静态代码分析 (SpotBugs)
- 安全扫描 (OWASP Dependency Check)
- 自动化部署

### 9.3 环境配置
- 开发环境 (localhost)
- 测试环境 (staging)
- 生产环境 (production)
- 配置文件分离

## 10. 扩展性设计

### 10.1 水平扩展
- 无状态设计 (Stateless)
- 负载均衡 (Nginx)
- 会话共享 (JWT 无状态)
- 数据库读写分离 (可选)

### 10.2 垂直扩展
- 资源优化 (CPU/内存)
- 连接池调优
- 缓存容量扩展
- 数据库分表 (可选)

## 11. 技术债务与改进

### 11.1 当前技术债务
- 部分 Mapper 警告 (MapStruct 未映射字段)
- WebSocket 未检查操作警告
- 测试覆盖率需提升 (当前 10%，目标 80%)

### 11.2 改进计划
- 修复 Mapper 映射问题
- 添加 WebSocket 类型安全
- 补充单元测试提升覆盖率
- 集成测试覆盖关键业务流程
- E2E 测试覆盖用户主要路径

## 12. 附录

### 12.1 相关文档
- [部署指南](../deployment/deployment-guide.md)
- [API 文档](http://localhost:8080/swagger-ui.html)
- [数据库设计](../database/database-schema.md)

### 12.2 联系方式
- 技术支持: support@novalon.cn
- 文档地址: https://docs.novalon.cn