# SCMTracker

**Repository Path**: SCMtracker/scmtracker

## Basic Information

- **Project Name**: SCMTracker
- **Description**: 一个模拟型供应链平台，用于实时跟踪货物运输状态、处理异步事件通知（如货物状态更新或延误警报），并进行自动化监控。该系统强调事件驱动架构（Event-Driven Architecture），聚焦于性能优化和系统扩展性。(Demo)
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2025-05-30
- **Last Updated**: 2025-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot

## README

# SCMtracker - 中下游供应链管理跟踪系统（Demo）

## 项目简介

SCMtracker（Supply Chain Management Tracking System）是一个现代化的供应链管理跟踪系统，专注于实时跟踪货物运输状态、处理异步事件通知（如货物状态更新或延误警报），并提供自动化监控功能。本系统采用事件驱动架构（Event-Driven Architecture），特别注重性能优化和系统扩展性。

## 🚀 主要功能

- **实时货运跟踪**：支持多种运输方式的实时状态跟踪
- **智能仪表盘**：提供数据可视化和统计分析
- **权限管理**：基于角色的细粒度权限控制
- **导入导出**：支持Excel、CSV、JSON等格式的批量数据处理
- **异步处理**：使用消息队列处理耗时操作
- **缓存优化**：Redis缓存提升系统性能
- **安全认证**：JWT令牌认证和权限验证

## 🛠 技术栈

### 后端技术

- **基础框架**：JDK 21 + Spring Boot 3.x
- **数据存储**：MySQL + Redis（缓存）
- **消息队列**：RabbitMQ（事件处理）
- **安全框架**：Spring Security + JWT
- **API文档**：OpenAPI 3.0（Swagger UI）
- **开发工具**：Lombok、Spring Validation

### 前端技术

- **框架**：Nuxt.js 3
- **UI组件**：Element Plus
- **状态管理**：Pinia
- **类型检查**：TypeScript
- **样式处理**：CSS3 + 响应式设计
- **图表组件**：ECharts

## 🚀 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` | 死信处理 | 记录异常、人工干预 | 直接确认，避免循环 |

### 事件驱动流程

#### 1. 状态变更流程

```text
货运状态更新 → Spring事件 → ShipmentEventListener → RabbitMQ消息 → MessageListener → 业务处理
```

#### 2. 紧急处理流程

```text
异常状态检测 → 同步紧急通知 → 异步告警处理 → 监控系统推送 → 人工干预
```

#### 3. 延迟任务流程

```text
终态状态到达 → 延迟消息生成 → 定时任务执行 → 归档/调查处理
```

### 业务场景覆盖

#### 货运状态管理

- **创建阶段**：CREATED → 初始化跟踪
- **处理阶段**：PROCESSING → 开始处理流程
- **发货阶段**：SHIPPED → 启动运输跟踪
- **运输阶段**：IN_TRANSIT → 位置更新、ETA计算
- **送达阶段**：DELIVERED → 完成流程、客户调查
- **异常处理**：EXCEPTION/LOST → 紧急响应、风险控制

#### 通知体系

- **实时通知**：状态变更立即通知相关方
- **紧急告警**：异常状态触发多渠道告警
- **延迟提醒**：客户满意度调查、归档提醒
- **批量处理**：大批量状态更新的异步处理

#### 监控体系

- **健康检查**：队列状态、处理成功率监控
- **性能指标**：消息吞吐量、处理延迟统计
- **异常检测**：失败率阈值告警、死信分析
- **业务指标**：状态分布、处理趋势分析

### 可靠性保证

#### 消息确认机制

- **生产端确认**：使用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缓存热点数据，减轻数据库压力
- **虚拟线程**：采用JDK 21虚拟线程提升并发处理能力
- **懒加载策略**：JPA关联关系采用懒加载，避免不必要的数据加载
- **异步处理**：耗时操作采用异步处理，提高系统响应速度

### API接口示例

#### 货运管理接口

| 功能 | HTTP方法 | 接口路径 | 描述 |
|-----|---------|--------|------|
| 创建货运 | POST | /shipment | 创建新的货运记录 |
| 查询货运 | GET | /shipment/{id} | 根据ID查询货运详情 |
| 更新状态 | PATCH | /shipment/{id}/status | 更新货运状态 |
| 批量导入 | POST | /shipment/batch | 批量导入货运数据 |

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.8+
- MySQL 8.0+
- Redis 6.0+
- RabbitMQ 3.8+

### 一键启动（推荐）

项目提供了自动化启动脚本，可以自动检查环境并处理常见问题：

**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

REM 开发模式启动
start.bat --dev

REM 清理队列后启动
start.bat --clean-queues

REM 仅检查环境
start.bat --check-only
```

### 手动启动

如果需要手动控制启动过程：

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    # 生产环境配置
```

## 技术特点

- **状态机模式**：使用枚举类型和状态转移规则实现货运状态管理
- **事件驱动设计**：采用事件发布机制解耦系统组件
- **缓存策略**：多级缓存策略，提高数据访问速度
- **异步处理**：使用Spring的异步注解和消息队列处理耗时操作
- **虚拟线程**：利用JDK 21的虚拟线程提升系统并发能力

## 开发团队

- **主要维护者**：talentestors

## 许可证

本项目采用 [MIT](LICENSE) 许可证。

## 🔧 快速故障排除

### RabbitMQ 队列配置冲突

如果启动时遇到以下错误：

```text
PRECONDITION_FAILED - inequivalent arg 'x-dead-letter-exchange' for queue
```

**快速解决方案：**

1. **开发环境自动修复**：

   ```bash
   # 使用dev配置启动，会自动修复队列冲突
   java -jar SCMtracker.jar --spring.profiles.active=dev
   ```

2. **手动删除冲突队列**：

   ```bash
   # 连接到RabbitMQ服务器
   sudo rabbitmqctl delete_queue shipment.status.queue
   sudo rabbitmqctl delete_queue shipment.notification.queue
   ```

3. **RabbitMQ管理界面**：
   - 访问 <http://localhost:15672>
   - 进入Queues页面，删除冲突的队列
   - 重启应用，队列会自动重新创建

4. **跳过队列修复**：

   ```bash
   # 如果需要跳过自动修复
   java -jar SCMtracker.jar --skip-rabbitmq-repair
   ```

### 监控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
```

## 📚 参考文档

- [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/)