makemd/docs/01_Architecture_Design.md

# 架构设计

## 1. 架构概述

Crawlful Hub 采用分层架构设计，确保系统的可维护性、可扩展性和可测试性。系统分为控制器层、服务层、仓库层和模型层，各层之间通过依赖注入进行解耦，实现了高内聚、低耦合的设计目标。

## 2. 分层架构

### 2.1 控制器层（Controller）

控制器层负责处理 HTTP 请求，包括请求参数的验证、调用服务层的方法、处理异常和返回响应。控制器层不包含业务逻辑，只负责请求和响应的处理。

**主要职责**：
- 接收 HTTP 请求
- 验证请求参数
- 调用服务层处理业务逻辑
- 处理异常
- 返回 HTTP 响应

**核心控制器**：
- `AuthController`：处理认证相关的请求
- `UserController`：处理用户管理相关的请求
- `ProductController`：处理商品管理相关的请求
- `OrderController`：处理订单管理相关的请求
- `PaymentController`：处理支付管理相关的请求
- `LogisticsController`：处理物流管理相关的请求
- `MonitoringController`：处理监控相关的请求
- `AlertController`：处理告警相关的请求
- `AuditController`：处理审计相关的请求
- `ConfigController`：处理配置相关的请求
- `DataController`：处理数据相关的请求
- `ReportController`：处理报表相关的请求

### 2.2 服务层（Service）

服务层是业务逻辑的核心，负责实现业务规则、处理业务流程和协调多个仓库的操作。服务层通过依赖注入使用仓库层的方法，实现业务逻辑的封装和复用。

**主要职责**：
- 实现业务逻辑
- 处理业务流程
- 协调多个仓库的操作
- 管理事务
- 处理异常

**核心服务**：
- `AuthService`：处理认证相关的业务逻辑
- `UserService`：处理用户管理相关的业务逻辑
- `ProductService`：处理商品管理相关的业务逻辑
- `OrderService`：处理订单管理相关的业务逻辑
- `PaymentService`：处理支付管理相关的业务逻辑
- `LogisticsService`：处理物流管理相关的业务逻辑
- `MonitoringService`：处理监控相关的业务逻辑
- `AlertService`：处理告警相关的业务逻辑
- `AuditService`：处理审计相关的业务逻辑
- `ConfigService`：处理配置相关的业务逻辑
- `DataService`：处理数据相关的业务逻辑
- `ReportService`：处理报表相关的业务逻辑

### 2.3 仓库层（Repository）

仓库层负责数据访问，包括数据库的 CRUD 操作。仓库层通过 Spring Data JPA 实现，提供了简洁的数据库操作接口。

**主要职责**：
- 实现数据库的 CRUD 操作
- 提供查询方法
- 管理数据库事务

**核心仓库**：
- `UserRepository`：处理用户数据的访问
- `ProductRepository`：处理商品数据的访问
- `OrderRepository`：处理订单数据的访问
- `PaymentRepository`：处理支付数据的访问
- `LogisticsRepository`：处理物流数据的访问
- `AlertRepository`：处理告警数据的访问
- `AuditRepository`：处理审计数据的访问
- `ConfigRepository`：处理配置数据的访问

### 2.4 模型层（Model）

模型层定义了数据结构，包括实体类和 DTO（数据传输对象）。实体类对应数据库表，DTO 用于在不同层之间传递数据。

**主要职责**：
- 定义数据结构
- 映射数据库表
- 提供数据访问方法

**核心模型**：
- `User`：用户模型
- `Product`：商品模型
- `Order`：订单模型
- `Payment`：支付模型
- `Logistics`：物流模型
- `Alert`：告警模型
- `Audit`：审计模型
- `Config`：配置模型

## 3. 核心流程

### 3.1 用户认证流程

1. **用户注册**：用户提交注册信息，`AuthController` 调用 `AuthService` 的 `register` 方法，验证输入数据，创建用户并返回用户信息。
2. **用户登录**：用户提交登录信息，`AuthController` 调用 `AuthService` 的 `login` 方法，验证用户名和密码，生成 JWT 令牌并返回。
3. **令牌验证**：请求携带 JWT 令牌，`SecurityConfig` 验证令牌的有效性，确保用户已认证。

### 3.2 商品管理流程

1. **创建商品**：用户提交商品信息，`ProductController` 调用 `ProductService` 的 `create` 方法，验证输入数据，创建商品并返回商品信息。
2. **查询商品**：用户请求商品列表，`ProductController` 调用 `ProductService` 的 `getAll` 方法，根据过滤条件查询商品并返回。
3. **更新商品**：用户提交商品更新信息，`ProductController` 调用 `ProductService` 的 `update` 方法，验证输入数据，更新商品并返回更新后的商品信息。
4. **删除商品**：用户请求删除商品，`ProductController` 调用 `ProductService` 的 `delete` 方法，删除商品并返回成功信息。

### 3.3 订单管理流程

1. **创建订单**：用户提交订单信息，`OrderController` 调用 `OrderService` 的 `createOrder` 方法，验证输入数据，创建订单并返回订单信息。
2. **查询订单**：用户请求订单列表，`OrderController` 调用 `OrderService` 的 `getOrders` 方法，根据过滤条件查询订单并返回。
3. **更新订单**：用户提交订单更新信息，`OrderController` 调用 `OrderService` 的 `updateOrder` 方法，验证输入数据，更新订单并返回更新后的订单信息。
4. **订单状态流转**：用户请求更新订单状态，`OrderController` 调用 `OrderService` 的 `transitionOrderStatus` 方法，更新订单状态并返回成功信息。

### 3.4 支付管理流程

1. **创建支付**：用户提交支付信息，`PaymentController` 调用 `PaymentService` 的 `create` 方法，验证输入数据，创建支付并返回支付信息。
2. **查询支付**：用户请求支付列表，`PaymentController` 调用 `PaymentService` 的 `getAll` 方法，根据过滤条件查询支付并返回。
3. **更新支付**：用户提交支付更新信息，`PaymentController` 调用 `PaymentService` 的 `update` 方法，验证输入数据，更新支付并返回更新后的支付信息。

### 3.5 物流管理流程

1. **创建物流**：用户提交物流信息，`LogisticsController` 调用 `LogisticsService` 的 `create` 方法，验证输入数据，创建物流并返回物流信息。
2. **查询物流**：用户请求物流列表，`LogisticsController` 调用 `LogisticsService` 的 `getAll` 方法，根据过滤条件查询物流并返回。
3. **更新物流**：用户提交物流更新信息，`LogisticsController` 调用 `LogisticsService` 的 `update` 方法，验证输入数据，更新物流并返回更新后的物流信息。

### 3.6 监控与告警流程

1. **系统健康检查**：用户请求系统健康状态，`MonitoringController` 调用 `MonitoringService` 的 `getSystemHealth` 方法，返回系统健康状态。
2. **性能指标获取**：用户请求系统性能指标，`MonitoringController` 调用 `MonitoringService` 的 `getPerformanceMetrics` 方法，返回系统性能指标。
3. **告警创建**：系统检测到异常，`AlertService` 创建告警并存储到数据库。
4. **告警处理**：用户请求处理告警，`AlertController` 调用 `AlertService` 的 `resolveAlert` 方法，更新告警状态为已解决。

## 4. 技术实现细节

### 4.1 数据库设计

- **用户表**：存储用户信息，包括用户名、密码、邮箱、角色等。
- **商品表**：存储商品信息，包括标题、描述、价格、数量等。
- **订单表**：存储订单信息，包括订单号、状态、总金额等。
- **支付表**：存储支付信息，包括支付方式、金额、状态等。
- **物流表**：存储物流信息，包括物流方式、跟踪号、状态等。
- **告警表**：存储告警信息，包括告警类型、严重程度、状态等。
- **审计表**：存储审计日志，包括操作类型、资源类型、操作人等。
- **配置表**：存储系统配置，包括配置键、配置值、配置类型等。

### 4.2 缓存实现

使用 Redis 作为缓存存储，缓存高频访问的数据，如用户信息、商品信息等，提高系统的响应速度。

### 4.3 安全实现

- **JWT 认证**：使用 JWT 进行身份验证，确保 API 安全。
- **CSRF 保护**：实现 CSRF 令牌验证，防止 CSRF 攻击。
- **速率限制**：限制 API 请求频率，防止恶意请求。
- **密码加密**：使用 BCrypt 加密用户密码，确保密码安全。

### 4.4 国际化实现

使用 Spring 的国际化支持，提供英文和中文的资源文件，根据请求的 Accept-Language 头自动切换语言。

### 4.5 监控与告警实现

- **系统健康检查**：实现系统健康状态检查，包括数据库连接、缓存状态等。
- **性能指标监控**：实现系统性能指标监控，包括响应时间、请求次数等。
- **告警管理**：实现告警的创建、查询、更新和处理，及时发现和处理系统异常。

## 5. 扩展性设计

- **模块化设计**：系统采用模块化设计，各模块之间通过接口进行通信，便于功能扩展和代码维护。
- **依赖注入**：使用 Spring 的依赖注入，实现组件的解耦，便于单元测试和功能扩展。
- **配置化**：系统的配置通过 application.yml 文件进行配置，便于环境切换和参数调整。
- **插件化**：系统支持插件化开发，可以通过插件扩展系统功能。

## 6. 总结

Crawlful Hub 采用分层架构设计，实现了高内聚、低耦合的系统结构。系统通过控制器层、服务层、仓库层和模型层的划分，实现了业务逻辑的封装和复用，提高了系统的可维护性、可扩展性和可测试性。同时，系统通过缓存、安全、国际化等技术的应用，提高了系统的性能和用户体验。