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