From fc52fd16c904dbab7f91c393222f860f761f4d13 Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Fri, 20 Jun 2025 08:42:53 +0000 Subject: [PATCH] Update README.md --- README.md | 637 +++++++++++++++++------------------------------------- 1 file changed, 199 insertions(+), 438 deletions(-) diff --git a/README.md b/README.md index 2ce48b0..b0e5cf6 100644 --- a/README.md +++ b/README.md @@ -1,505 +1,266 @@ + + # SCMtracker - 中下游供应链管理跟踪系统（Demo） ## 项目简介 - -SCMtracker（Supply Chain Management Tracking System）是一个现代化的供应链管理跟踪系统，专注于实时跟踪货物运输状态、处理异步事件通知（如货物状态更新或延误警报），并提供自动化监控功能。本系统采用事件驱动架构（Event-Driven Architecture），特别注重性能优化和系统扩展性。 +SCMtracker 是一个供应链管理跟踪系统，专注于中下游物流跟踪与管理。系统采用事件驱动架构，通过消息队列实现异步处理，支持货运状态跟踪、通知体系、监控体系等核心功能。 ## 🚀 主要功能 - -- **实时货运跟踪**：支持多种运输方式的实时状态跟踪 -- **智能仪表盘**：提供数据可视化和统计分析 -- **权限管理**：基于角色的细粒度权限控制 -- **导入导出**：支持Excel、CSV、JSON等格式的批量数据处理 -- **异步处理**：使用消息队列处理耗时操作 -- **缓存优化**：Redis缓存提升系统性能 -- **安全认证**：JWT令牌认证和权限验证 +- **货运状态跟踪**：实时更新和管理货物运输状态 +- **通知体系**：支持紧急、普通和延迟通知 +- **监控体系**：提供消息处理统计、队列状态和系统健康检查 +- **数据一致性**：通过消息确认机制和事务处理保证数据可靠性 +- **权限管理**：细粒度的权限控制和访问管理 +- **批量导入导出**：支持Excel/CSV格式的货运数据导入和导出 +- **运输网络管理**：维护运输路径和网络配置 ## 🛠 技术栈 ### 后端技术 - -- **基础框架**：JDK 21 + Spring Boot 3.x -- **数据存储**：MySQL + Redis（缓存） -- **消息队列**：RabbitMQ（事件处理） -- **安全框架**：Spring Security + JWT -- **API文档**：OpenAPI 3.0（Swagger UI） -- **开发工具**：Lombok、Spring Validation +- **Java 11+** +- **Spring Boot** +- **Spring Data JPA** +- **RabbitMQ** +- **Redis** +- **JWT** +- **Maven** +- **MySQL** ### 前端技术 +- **Nuxt 3** +- **Vue 3** +- **TypeScript** +- **Tailwind CSS** +- **ESLint + Prettier** +- **Day.js** -- **框架**：Nuxt.js 3 -- **UI组件**：Element Plus -- **状态管理**：Pinia -- **类型检查**：TypeScript -- **样式处理**：CSS3 + 响应式设计 -- **图表组件**：ECharts - -## 🚀 RabbitMQ 业务流程架构 +## 🐇 RabbitMQ 业务流程架构 ### 消息队列体系 - -SCMtracker采用完整的RabbitMQ事件驱动架构，实现异步解耦和可靠通知： - -```mermaid -graph TB - subgraph "业务层" - A[货运状态变更] --> B[Spring事件发布] - end - - subgraph "事件监听层" - B --> C[ShipmentEventListener] - C --> D[消息分发逻辑] - end - - subgraph "RabbitMQ层" - D --> E[shipment.exchange] - D --> F[urgent.exchange] - E --> G[shipment.status.queue] - E --> H[shipment.notification.queue] - E --> I[delay.processing.queue] - F --> J[urgent.notification.queue] - G --> K[dead.letter.queue] - end - - subgraph "消息消费层" - G --> L[状态更新处理] - H --> M[通知处理] - I --> N[延迟任务处理] - J --> O[紧急通知处理] - K --> P[死信处理] - end - - subgraph "业务处理层" - L --> Q[数据库更新] - M --> R[邮件/短信通知] - N --> S[归档/跟进/调查] - O --> T[告警/监控] - P --> U[人工干预] - end -``` - -### 核心队列说明 - -| 队列名称 | 用途 | 处理逻辑 | 重试策略 | -|---------|------|---------|----------| -| `shipment.status.queue` | 处理货运状态更新 | 更新数据库，触发后续事件 | 失败直接丢弃，避免循环 | -| `shipment.notification.queue` | 普通通知消息 | 邮件通知、前端推送 | 失败重新入队，最多3次 | -| `urgent.notification.queue` | 紧急通知消息 | 立即告警、短信通知 | 失败直接丢弃，避免延迟 | -| `delay.processing.queue` | 延迟处理任务 | 归档、跟进、客户调查 | 失败重新入队重试 | -| `dead.letter.queue` | 死信处理 | 记录异常、人工干预 | 直接确认，避免循环 | +- **SHIPMENT_EXCHANGE** - 主交换机（Direct Exchange） +- **URGENT_EXCHANGE** - 紧急交换机 +- **SHIPMENT_STATUS_QUEUE** - 状态更新队列 +- **SHIPMENT_NOTIFICATION_QUEUE** - 通知队列 +- **URGENT_NOTIFICATION_QUEUE** - 紧急通知队列 +- **DELAY_PROCESSING_QUEUE** - 廱от +- **DEAD_LETTER_QUEUE** - 死信队列 ### 事件驱动流程 -#### 1. 状态变更流程 - -```text -货运状态更新 → Spring事件 → ShipmentEventListener → RabbitMQ消息 → MessageListener → 业务处理 -``` - -#### 2. 紧急处理流程 - -```text -异常状态检测 → 同步紧急通知 → 异步告警处理 → 监控系统推送 → 人工干预 -``` - -#### 3. 延迟任务流程 +1. **状态变更流程**： + - 状态更新 -> 发送至 SHIPMENT_EXCHANGE + - 消费者处理 -> 更新数据库 -> 发送监控事件 -```text -终态状态到达 → 延迟消息生成 → 定时任务执行 → 归档/调查处理 -``` - -### 业务场景覆盖 - -#### 货运状态管理 - -- **创建阶段**：CREATED → 初始化跟踪 -- **处理阶段**：PROCESSING → 开始处理流程 -- **发货阶段**：SHIPPED → 启动运输跟踪 -- **运输阶段**：IN_TRANSIT → 位置更新、ETA计算 -- **送达阶段**：DELIVERED → 完成流程、客户调查 -- **异常处理**：EXCEPTION/LOST → 紧急响应、风险控制 - -#### 通知体系 - -- **实时通知**：状态变更立即通知相关方 -- **紧急告警**：异常状态触发多渠道告警 -- **延迟提醒**：客户满意度调查、归档提醒 -- **批量处理**：大批量状态更新的异步处理 - -#### 监控体系 - -- **健康检查**：队列状态、处理成功率监控 -- **性能指标**：消息吞吐量、处理延迟统计 -- **异常检测**：失败率阈值告警、死信分析 -- **业务指标**：状态分布、处理趋势分析 +2. **紧急处理流程**： + - 紧急消息 -> 发送至 URGENT_EXCHANGE + - 紧急通知队列 -> 高优先级处理 -### 可靠性保证 +3. **延迟任务流程**： + - 任务 -> 发送至 SHIPMENT_EXCHANGE + - 延迟队列 -> 延迟处理 -> 状态更新 -#### 消息确认机制 - -- **生产端确认**：使用CorrelationData确保消息发送成功 -- **消费端确认**：手动ACK机制，确保消息处理完成 -- **失败处理**：区分业务失败和系统失败，采用不同策略 - -#### 重试与死信 - -- **智能重试**：根据消息类型采用不同重试策略 -- **死信队列**：处理最终失败的消息，记录供人工干预 -- **监控告警**：实时监控队列深度和处理状态 - -#### 数据一致性 - -- **事务事件**：使用@TransactionalEventListener确保数据库事务提交后再发送消息 -- **幂等处理**：消息处理逻辑具备幂等性，避免重复处理问题 -- **补偿机制**：异常情况下的数据修复和状态回滚 +## 📦 业务场景覆盖 +- **货运状态管理**：支持多状态流转和验证 +- **通知体系**：包括普通通知、紧急通知和延迟通知 +- **监控体系**：提供消息统计、队列状态和系统健康检查 +- **可靠性保证**：通过消息确认机制、重试策略和死信处理 +- **数据一致性**：结合事务监听和缓存同步保障数据一致性 ## 🔍 消息处理监控 -### 监控API接口 - -系统提供完整的监控API，用于实时查看RabbitMQ业务流程状态： - -| 接口路径 | 功能 | 描述 | -|---------|------|------| -| `GET /api/monitor/statistics` | 获取统计信息 | 消息发送、接收、处理成功率等详细统计 | -| `GET /api/monitor/queues/status` | 队列状态 | 各队列的处理状态和积压情况 | -| `GET /api/monitor/health` | 健康检查 | 系统健康状态和异常检测 | -| `GET /api/monitor/realtime` | 实时监控 | 实时的消息处理监控数据 | -| `GET /api/monitor/business-flow` | 业务流程概览 | RabbitMQ业务流程的整体状况 | -| `POST /api/monitor/statistics/reset` | 重置统计 | 重置所有统计数据 | - -### 监控指标说明 +### 基础指标 +- 总消息发送数 +- 总消息接收数 +- 成功处理数 +- 失败处理数 -#### 基础指标 +### 队列状态 +- 队列消息数量 +- 队列错误率 +- 队列健康状态 -- **消息发送总数**：系统发送的消息总量 -- **消息接收总数**：系统接收处理的消息总量 -- **处理成功率**：消息处理成功的百分比 -- **处理失败率**：消息处理失败的百分比 - -#### 队列状态 - -- **NORMAL**：队列处理正常，积压少于10条 -- **MEDIUM_PENDING**：队列有一定积压，10-100条消息待处理 -- **HIGH_PENDING**：队列积压严重，超过100条消息待处理 - -#### 业务指标 - -- **状态更新分布**：各种状态（CREATED、SHIPPED、DELIVERED等）的处理量 -- **紧急事件统计**：异常、丢失、损坏等紧急状态的处理情况 -- **延迟任务统计**：归档、调查、跟进等延迟任务的执行情况 - -### 使用示例 - -#### 1. 查看系统健康状态 - -```bash -curl -X GET "http://localhost:8080/api/monitor/health" \ - -H "accept: application/json" -``` - -响应示例： - -```json -{ - "status": "UP", - "hasAnomalies": false, - "statistics": { - "totalMessagesSent": 1250, - "totalMessagesReceived": 1248, - "totalMessagesProcessed": 1245, - "totalMessagesFailed": 3, - "successRatePercent": 99.76 - } -} -``` - -#### 2. 获取详细统计信息 - -```bash -curl -X GET "http://localhost:8080/api/monitor/statistics" \ - -H "accept: application/json" -``` - -#### 3. 查看队列状态 - -```bash -curl -X GET "http://localhost:8080/api/monitor/queues/status" \ - -H "accept: application/json" -``` - -响应示例： - -```json -{ - "shipment.status.queue": "NORMAL", - "shipment.notification.queue": "NORMAL", - "urgent.notification.queue": "NORMAL", - "delay.processing.queue": "MEDIUM_PENDING" -} -``` +### 业务指标 +- 不同状态更新类型处理统计 +- 通知类型处理统计 +- 消息处理延迟 +- 死信队列积压 ## 📋 系统架构 -```mermaid -graph LR - subgraph "用户端" - A["用户/客户端"] - end - - subgraph "应用层" - B["API 控制器"] - C["服务层处理"] - end - - subgraph "数据存储" - D["数据库 MySQL"] - G["Redis缓存"] - end - - subgraph "消息处理" - E["RabbitMQ 队列"] - end - - A -->|" 用户请求 "| B - B -->|" 处理请求 "| C - C -->|" 数据访问 "| D - C -->|" 缓存访问 "| G - G -->|" 缓存响应 "| C - C -->|" 消息发送 "| E - E -->|" 异步通知 "| A - D -->|" 查询响应 "| C - - style A fill: #f9f, stroke: #333, stroke-width: 2px - style B fill: #bbf, stroke: #333, stroke-width: 2px - style C fill: #bbf, stroke: #333, stroke-width: 2px - style D fill: #ddf, stroke: #333, stroke-width: 2px - style E fill: #bbf, stroke: #333, stroke-width: 2px - style G fill: #fdd, stroke: #333, stroke-width: 2px -``` - ### 功能模块设计 - -```mermaid -graph TD - A[用户接口层] --> B[业务逻辑层] - B --> C[数据访问层] - B --> D[消息服务层] - D --> E[定时任务层] - C --> F[数据存储层] - E --> B - style A fill: #F9E79F, stroke: #F1C40F - style B fill: #AED6F1, stroke: #3498DB - style C fill: #ABEBC6, stroke: #27AE60 - style D fill: #F5B7B1, stroke: #E74C3C - style E fill: #D7BDE2, stroke: #9B59B6 - style F fill: #EDBB99, stroke: #E67E22 -``` - -## 核心功能 - -### 货运跟踪管理 - -- **货运创建**：提供货运信息注册接口，生成唯一跟踪号 -- **状态查询**：实时查询货运状态，支持多维度查询 -- **状态更新**：支持货运状态变更，采用状态机模式确保状态转换合法性 -- **批量导入**：支持大批量货运数据导入，采用异步处理 -- **事件通知**：货运状态变更时，触发事件通知相关方 +- **货运管理**：创建、更新、删除货运信息 +- **状态管理**：状态定义、验证和展示 +- **权限管理**：角色、用户和权限控制 +- **监控模块**：消息处理统计和队列状态监控 +- **缓存管理**：Redis 缓存处理与统计 +- **数据初始化**：系统数据初始化与维护 ### 性能优化特性 +- 使用 Redis 缓存高频查询数据 +- 异步任务处理（@Async） +- 虚拟线程优化（Virtual Thread） +- 数据库连接池优化 +- 消息批量处理 -- **分布式缓存**：使用Redis缓存热点数据，减轻数据库压力 -- **虚拟线程**：采用JDK 21虚拟线程提升并发处理能力 -- **懒加载策略**：JPA关联关系采用懒加载，避免不必要的数据加载 -- **异步处理**：耗时操作采用异步处理，提高系统响应速度 - -### API接口示例 +## 📦 API 接口示例 -#### 货运管理接口 +### 货运管理接口 +- `POST /api/v1/shipments` - 创建货运 +- `GET /api/v1/shipments` - 查询货运 +- `GET /api/v1/shipments/{id}` - 查询特定货运 +- `PATCH /api/v1/shipments/{id}/status` - 更新货运状态 +- `DELETE /api/v1/shipments/{id}` - 删除货运 -| 功能 | HTTP方法 | 接口路径 | 描述 | -|-----|---------|--------|------| -| 创建货运 | POST | /shipment | 创建新的货运记录 | -| 查询货运 | GET | /shipment/{id} | 根据ID查询货运详情 | -| 更新状态 | PATCH | /shipment/{id}/status | 更新货运状态 | -| 批量导入 | POST | /shipment/batch | 批量导入货运数据 | +### 监控接口 +- `GET /api/monitor/statistics` - 获取消息处理统计 +- `GET /api/monitor/queues/status` - 获取队列状态 +- `GET /api/monitor/health` - 系统健康检查 +- `POST /api/monitor/statistics/reset` - 重置统计信息 -## 快速开始 +## 🚀 快速开始 ### 环境要求 - -- JDK 21+ -- Maven 3.8+ -- MySQL 8.0+ +- Java 11 或更高版本 +- RabbitMQ 服务器 - Redis 6.0+ -- RabbitMQ 3.8+ +- MySQL 8.0+ +- Node.js 16+（前端） ### 一键启动（推荐） - -项目提供了自动化启动脚本，可以自动检查环境并处理常见问题： - -**Linux/macOS:** - ```bash -# 赋予执行权限 chmod +x start.sh - -# 正常启动 ./start.sh - -# 开发模式启动（自动修复队列配置冲突） -./start.sh --dev - -# 清理RabbitMQ队列后启动 -./start.sh --clean-queues - -# 仅检查环境 -./start.sh --check-only ``` -**Windows:** - -```cmd -REM 正常启动 -start.bat +### 正常启动 +```bash +./mvnw spring-boot:run +``` -REM 开发模式启动 -start.bat --dev +### 开发模式启动（自动修复队列配置冲突） +```bash +./mvnw spring-boot:run -Dspring.profiles.active=dev +``` -REM 清理队列后启动 -start.bat --clean-queues +### 清理 RabbitMQ 队列后启动 +```bash +./start.sh clean +``` -REM 仅检查环境 -start.bat --check-only +### 仅检查环境 +```bash +./start.sh check ``` ### 手动启动 - -如果需要手动控制启动过程： - -1. 克隆项目到本地： - - ```bash - git clone https://github.com/yourusername/SCMtracker.git - cd SCMtracker - ``` - -2. 配置数据库连接（修改 application-dev.yml）： - - ```yaml - spring: - datasource: - url: jdbc:mysql://localhost:3306/scmtracker?useSSL=false - username: your_username - password: your_password - ``` - -3. 配置Redis和RabbitMQ（根据实际环境修改） - -4. 编译运行： - - ```bash - ./mvnw spring-boot:run - ``` - -5. 访问Swagger文档： - - ```url - http://localhost:8080/swagger-ui.html - ``` - -### 生产环境部署 - -生产环境部署请参考 `docs/deployment.md` 文档。 - -## 项目结构 - -```text -src/ - main/ - java/ - cn/ - stazxr/ - scmtracker/ - config/ # 配置类 - controller/ # 控制器 - dto/ # 数据传输对象 - entity/ # 实体类 - repository/ # 数据访问层 - service/ # 业务逻辑层 - utils/ # 工具类 - resources/ - application.yml # 主配置文件 - application-dev.yml # 开发环境配置 - application-prod.yml # 生产环境配置 +```bash +./mvnw package +java -jar target/*.jar ``` -## 技术特点 - -- **状态机模式**：使用枚举类型和状态转移规则实现货运状态管理 -- **事件驱动设计**：采用事件发布机制解耦系统组件 -- **缓存策略**：多级缓存策略，提高数据访问速度 -- **异步处理**：使用Spring的异步注解和消息队列处理耗时操作 -- **虚拟线程**：利用JDK 21的虚拟线程提升系统并发能力 - -## 开发团队 - -- **主要维护者**：talentestors - -## 许可证 - -本项目采用 [MIT](LICENSE) 许可证。 - -## 🔧 快速故障排除 - -### RabbitMQ 队列配置冲突 - -如果启动时遇到以下错误： - -```text -PRECONDITION_FAILED - inequivalent arg 'x-dead-letter-exchange' for queue +### 生产环境部署 +```bash +docker-compose -f docker-compose.prod.yml up -d ``` -**快速解决方案：** - -1. **开发环境自动修复**： +## 🧪 使用示例 +1. **查看系统健康状态**： ```bash - # 使用dev配置启动，会自动修复队列冲突 - java -jar SCMtracker.jar --spring.profiles.active=dev + curl -X GET http://localhost:8443/api/test/health ``` -2. **手动删除冲突队列**： - +2. **获取详细统计信息**： ```bash - # 连接到RabbitMQ服务器 - sudo rabbitmqctl delete_queue shipment.status.queue - sudo rabbitmqctl delete_queue shipment.notification.queue + curl -X GET http://localhost:8443/api/monitor/statistics ``` -3. **RabbitMQ管理界面**： - - 访问 - - 进入Queues页面，删除冲突的队列 - - 重启应用，队列会自动重新创建 - -4. **跳过队列修复**： - +3. **查看队列状态**： ```bash - # 如果需要跳过自动修复 - java -jar SCMtracker.jar --skip-rabbitmq-repair + curl -X GET http://localhost:8443/api/monitor/queues/status ``` -### 监控API快速验证 - -启动成功后，可通过以下API验证系统状态： - -```bash -# 检查系统健康状态 -curl http://localhost:8080/api/monitor/health - -# 查看消息处理统计 -curl http://localhost:8080/api/monitor/statistics +## 🔧 快速故障排除 -# 检查队列状态 -curl http://localhost:8080/api/monitor/queues/status +### RabbitMQ 队列配置冲突 +- **解决方案**：使用 `start.sh clean` 脚本清理队列 +- 或连接 RabbitMQ 管理界面，手动删除冲突队列 +- 或使用 rabbitmqctl 命令行工具 + +### 消息积压 +- 检查消费者处理性能 +- 优化消息处理逻辑 +- 增加消费者并发数 + +### 监控 API 快速验证 +- **检查系统健康状态**： + ```bash + curl -X GET http://localhost:8443/api/test/health + ``` + +- **查看消息处理统计**： + ```bash + curl -X GET http://localhost:8443/api/monitor/statistics + ``` + +- **检查队列状态**： + ```bash + curl -X GET http://localhost:8443/api/monitor/queues/status + ``` + +## 📚 文档 +- [What-is-a-supply-chain.md](docs/What-is-a-supply-chain.md) - 什么是供应链？ +- [domain-model.md](docs/architecture/domain-model.md) - 领域模型设计 +- [event-driven-design.md](docs/architecture/event-driven-design.md) - 事件驱动架构设计 +- [deployment-guide.md](docs/deployment-guide.md) - 部署指南 +- [localdatetime-fix.md](docs/localdatetime-fix.md) - LocalDateTime 序列化问题修复 +- [progress-report.md](docs/progress-report.md) - 项目完善进度报告 + +## 📁 项目结构 +``` +├── frontend/ # 前端代码（Nuxt 3） +├── src/ # 后端Java代码 +│ └── main/ +│ └── java/ +│ └── cn.stazxr.scmtacker/ +│ ├── config/ # 配置类 +│ ├── controller/ # API 控制器 +│ ├── service/ # 业务服务接口与实现 +│ ├── repository/ # 数据访问层 +│ ├── component/ # 系统组件 +│ ├── entity/ # 数据实体 +│ ├── event/ # 事件定义 +│ ├── exception/ # 异常处理 +│ └── utils/ # 工具类 +├── docker-compose.prod.yml # 生产环境部署配置 +├── Dockerfile # Docker 镜像构建文件 +├── README.md +├── pom.xml # Maven 项目配置 +└── .env.example # 环境变量示例 ``` + +## 📜 项目许可证 +本项目采用 [MIT License](LICENSE)，详情请参阅 [许可证文件](LICENSE)。 + +## 📌 开发团队 +- 供应链管理核心系统开发团队 +- 物流信息化项目组 + +## 📝 贡献指南 +欢迎贡献代码和改进。请遵循以下步骤： +1. Fork 本项目 +2. 创建新分支 (`git checkout -b feature/your-feature`) +3. 提交更改 (`git commit -am 'Add new feature'`) +4. 推送分支 (`git push origin feature/your-feature`) +5. 创建 Pull Request + +## 📬 联系信息 +- 项目负责人：stazxr +- 邮箱：stazxr@scmtracker.cn +- 论坛：[Gitee 项目讨论](https://gitee.com/stazxr/SCMtracker) + +## 📚 参考文档 +- [Spring Boot 官方文档](https://docs.spring.io/spring-boot/docs/current/reference/html/) +- [RabbitMQ 官方文档](https://www.rabbitmq.com/documentation.html) +- [Nuxt 3 文档](https://nuxt.com/docs) +- [Redis 官方文档](https://redis.io/documentation/) \ No newline at end of file -- Gitee