# SCMTracker

**Repository Path**: zjnblll/scmtracker

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-06-05
- **Last Updated**: 2025-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 供应链管理跟踪系统

## 介绍

供应链管理跟踪系统（Supply Chain Management Tracking System）：一个模拟型供应链平台，用于实时跟踪货物运输状态、处理异步事件通知（如货物状态更新或延误警报），并进行自动化监控。该系统强调事件驱动架构（Event-Driven Architecture），聚焦于性能优化和系统扩展性。

## 软件架构

- JDK 21
- SpringBoot 3（虚拟线程）

```mermaid
graph LR
    subgraph "用户端"
        A["用户/客户端"]
    end

    subgraph "应用层"
        B["API 控制器"]
        C["服务层处理"]
    end

    subgraph "数据存储"
        D["数据库 MySQL"]
    end

    subgraph "消息处理"
        E["RabbitMQ 队列"]
    end

    A -->|"用户请求"| B
    B -->|"处理请求"| C
    C -->|"数据访问"| D
    C -->|"消息发送"| E
    E -->|"异步通知"| A
    D -->|"查询响应"| B

    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

    %% 此注释用于文档说明：A 到 B 表示用户请求流程
```

### 功能模块设计总览

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

#### 模块 1：用户接口层（Spring Boot REST API）

| **功能**         | **接口设计**                    | **技术实现**                                                 |
| ---------------- | ------------------------------- | ------------------------------------------------------------ |
| 货物创建         | POST /cargo<br>参数：货物DTO    | `@RestController` + Spring Validation<br>调用`CargoService.create()` |
| 状态查询         | GET /cargo/{id}<br>返回：货物VO | 集成Redis缓存：<br>`@Cacheable(key = "#id")`<br>缓存穿透处理：空值缓存 |
| 批量导入         | POST /cargo/batch<br>参数：文件 | 异步处理：<br>`@Async` + RabbitMQ消息队列                    |
| 状态更新（内部） | PUT /cargo/status<br>权限：内部 | Spring Security 内部认证<br>触发RabbitMQ事件通知             |

#### 模块 2：业务逻辑层（领域服务）

##### 货物管理服务 `CargoService`

```java
@Service
public class CargoService {
    // 状态机核心逻辑（运输中 -> 已签收/异常）
    public void updateStatus(String cargoId, CargoStatus newStatus) {
        Cargo cargo = cargoRepository.findById(cargoId);
        // 状态校验（使用状态机模式）
        if (!cargo.canTransitionTo(newStatus)) {
            throw new IllegalStateException("状态转换无效");
        }
        cargo.setStatus(newStatus);
        // 触发事件（解耦通知逻辑）
        eventPublisher.publishStatusEvent(cargo);
    }
}
```
**关键技术**：
- 状态机模式：使用 `Enum` + 状态转移规则
- 事件发布：`ApplicationEventPublisher` 发送领域事件

#### 模块 3：消息服务层（RabbitMQ 集成）

##### 消息架构设计

```mermaid
graph LR
    Producer[服务层] -->|发布事件| Exchange[状态事件交换机]
    Exchange -->|路由键: status.update| Queue1[状态更新队列]
    Exchange -->|路由键: delay.alert| Queue2[延误警报队列]
    Queue1 --> Consumer1[通知服务]
    Queue2 --> Consumer2[预警服务]
```

##### 关键配置

```java
@Configuration
public class RabbitConfig {
    // 定义状态事件交换机（Direct模式）
    @Bean
    public DirectExchange statusExchange() {
        return new DirectExchange("cargo.status.exchange");
    }
  
    // 延时消息队列（TTL=1小时）
    @Bean
    public Queue delayQueue() {
        return QueueBuilder.durable("delay.alert.queue")
               .ttl(3600000) // 1小时TTL
               .deadLetterExchange("") // 死信直连主队列
               .build();
    }
}
```

#### 模块 4：定时任务层（Spring Schedule）

##### 核心任务清单

| **任务**     | **触发规则**              | **功能**                       | **容错机制**               |
| ------------ | ------------------------- | ------------------------------ | -------------------------- |
| 库存日报生成 | 每天 08:00 (0 0 8 * * *)  | 查询Redis缓存数据生成PDF       | `@Retryable` 最大重试3次   |
| 运输时效监控 | 每30分钟 (0 */30 * * * *) | 扫描运输中超24小时货物触发警报 | 分布式锁防止多实例重复执行 |
| 缓存数据预热 | 系统启动时执行            | 加载热点货物数据到Redis        | 失败后记录日志不影响启动   |

**任务示例**：

```java
@Scheduled(cron = "0 */30 * * * *")
@SchedulerLock(name = "MonitorTask_lock", lockAtMostFor = "29m")
public void monitorTransportDelay() {
    List<Cargo> delayedCargos = cargoRepository.findDelayedCargos(24);
    delayedCargos.forEach(cargo -> 
        rabbitTemplate.convertAndSend("ALERT_QUEUE", cargo)
    );
}
```

#### 模块 5：数据访问层（Spring Data JPA + Redis）

##### 双存储架构

```mermaid
graph TB
    Service[业务服务] -->|高频读取| Redis[Redis缓存]
    Service -->|持久化| JPA[MySQL/H2]
    Redis -->|缓存策略| Policy["缓存策略：
    读写穿透（Caffeine）
    失效：主动更新+TTL"]
```

##### 缓存注解示例

```java
@Repository
public class CargoRepositoryImpl implements CargoCache {
  
    @Cacheable(value = "cargo", key = "#id", 
               unless = "#result == null") // 空值不缓存
    public Cargo getById(String id) {
        return jpaRepository.findById(id);
    }
  
    @CacheEvict(value = "cargo", key = "#cargo.id")
    public void update(Cargo cargo) {
        jpaRepository.save(cargo);
    }
}
```

#### 模块 6：安全与监控层

1. **安全控制**
   - API 鉴权：Spring Security + JWT
   - 敏感操作审计：`@Audited` 注解记录操作日志
2. **监控指标**
   - Prometheus 监控端点：`/actuator/prometheus`
   - 关键指标：
     - RabbitMQ 积压消息数
     - 缓存命中率（Redis）
     - API 平均响应时间

---

#### 关键设计决策说明

1. **事件驱动优先**
   状态变更全部通过 RabbitMQ 异步通知，确保核心链路高可用（即使通知服务宕机不影响主业务）

2. **缓存双策略**
   - 静态数据：Caffeine 本地缓存（减少 Redis 压力）
   - 动态数据：Redis 分布式缓存（保证一致性）

3. **定时任务容错**
   集成 [ShedLock](https://github.com/lukas-krecan/ShedLock) 避免多实例任务重复执行

4. **简化持久化**
   MVP 阶段使用 H2 内存数据库，节省部署成本（生产环境可无缝切 MySQL）

## 加入团队

[点击加入](https://gitee.com/organizations/java-hnuit/invite?invite=b07d73cb939d0bab49853d35a1c7b131dca094eb15896a69e67a7010cd42d36ea584c1196390b6bf5f318cd36bbddc3a)