# multi-instruction-plugin

**Repository Path**: chenqian1995/multi-instruction-plugin

## Basic Information

- **Project Name**: multi-instruction-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多指令下发插件

> 可插拔的车辆 CAN 文件串行下发系统 - 零侵入集成

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-8+-green.svg)](https://openjdk.java.net/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.x-brightgreen.svg)](https://spring.io/projects/spring-boot)

## 项目简介

多指令下发插件是一个**独立可插拔**的 Maven 模块，为车辆 TSP 系统提供：
- ✅ 批量指令串行执行（一次一条）
- ✅ 9 种指令状态管理
- ✅ Redis ZSet 超时调度（3 分钟/2 小时/24 小时）
- ✅ 分布式锁防止并发
- ✅ 定时任务轮询（每 3 秒）
- ✅ 零侵入集成（只需添加依赖和注解）

## 快速开始

### 1. Maven 依赖

```xml
<dependency>
    <groupId>com.cloudplatform</groupId>
    <artifactId>multi-instruction-plugin</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 启用插件

```java
@SpringBootApplication
@EnableMultiInstructionPlugin  // ← 添加此注解
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}
```

### 3. 配置文件

```yaml
multi-instruction:
  enabled: true
  scheduler-interval-ms: 3000
  command-exec-timeout-ms: 180000
  offline-interrupt-threshold-ms: 7200000
  global-issue-timeout-ms: 86400000
  redis:
    key-prefix: "plugin:cmd:"
```

### 4. 使用示例

```java
@Service
public class YourService {
    
    @Autowired
    private MultiCommandPluginService pluginService;
    
    public void issueFiles() {
        pluginService.issueCommands(
            "VIN123456",
            Arrays.asList("/file1.can", "/file2.can")
        );
    }
}
```

## 核心特性

### 指令状态机

```
INIT(0) → WAIT_TRANSFER(3) → FILE_TRANSFERRING(4) → SUCCESS(1)/FAIL(2)
                                ↓
                    TRANSFER_PAUSED_OFFLINE(5)
                                ↓
                    TRANSFER_INTERRUPTED_OFFLINE_2H(6)
                                ↓
                    TRANSFER_INTERRUPTED_TIMEOUT(7)
                                ↓
                    ISSUE_TIMEOUT_24H(8)
```

### 超时管理

| 类型 | 时间 | 说明 |
|------|------|------|
| 3 分钟超时 | 180s | 指令执行超时，设备响应超时 |
| 2 小时离线 | 7200s | 设备离线超过 2 小时，指令中断 |
| 24 小时全局 | 86400s | 指令排队等待超过 24 小时 |

## 技术栈

- **Java**: 8+
- **Spring Boot**: 2.7.x
- **MyBatis**: 2.3.1
- **Redis**: 5.0+
- **Redisson**: 3.21.3

## 文档

- [集成指南](INTEGRATION_GUIDE.md) - 详细集成步骤
- [配置说明](INTEGRATION_GUIDE.md#配置说明) - 所有配置项说明
- [故障排查](INTEGRATION_GUIDE.md#故障排查) - 常见问题解决

## 项目结构

```
multi-instruction-plugin/
├── src/main/java/com/cloudplatform/plugin/multiinstruction/
│   ├── autoconfig/          # 自动配置
│   ├── core/                # 核心调度逻辑
│   ├── service/             # 服务层
│   ├── mapper/              # MyBatis Mapper
│   ├── entity/              # 实体类
│   └── util/                # 工具类
└── src/main/resources/
    └── mapper/              # MyBatis XML
```

## 自定义扩展

### 自定义在线检测

```java
@Configuration
public class YourConfig {
    
    @Bean
    public VehicleOnlineChecker vehicleOnlineChecker() {
        return vin -> {
            // 实现你的在线检测逻辑
            return yourMqttService.isOnline(vin);
        };
    }
}
```

### 禁用插件

```yaml
multi-instruction:
  enabled: false
```

## 与其他方案对比

| 特性 | 插件版本 | 原项目代码 |
|------|---------|-----------|
| 侵入性 | 零侵入 | 需修改代码 |
| 可插拔 | ✅ 是 | ❌ 否 |
| 独立升级 | ✅ 是 | ❌ 否 |
| 跨项目复用 | ✅ 简单 | ❌ 困难 |

## 开发计划

- [ ] 增加指令优先级支持
- [ ] 增加指令重试机制
- [ ] 增加指令执行日志
- [ ] 支持更多超时策略
- [ ] 提供管理接口（暂停/恢复/取消指令）

## 贡献

欢迎提交 Issue 和 Pull Request！

## License

MIT License

---

**Gitee**: https://gitee.com/chenqian1995/multi-instruction-plugin

## 模块结构

```
cloud-platform-multiple-instruction-plugin/
├── pom.xml
├── README.md
└── src/
    ├── main/
    │   ├── java/com/cloudplatform/plugin/multiinstruction/
    │   │   ├── autoconfig/          # 自动配置
    │   │   │   ├── MultiInstructionAutoConfiguration.java
    │   │   │   └── RedisConfig.java
    │   │   ├── core/                # 核心逻辑
    │   │   │   ├── CommandScheduler.java
    │   │   │   ├── CommandExecutor.java
    │   │   │   └── TimeoutHandler.java
    │   │   ├── service/             # 服务层
    │   │   │   ├── MultiCommandPluginService.java
    │   │   │   └── VehicleOnlineChecker.java
    │   │   ├── mapper/              # MyBatis Mapper
    │   │   │   └── CommandMapper.java
    │   │   ├── entity/              # 实体类
    │   │   │   └── CommandEntity.java
    │   │   └── util/                # 工具类
    │   │       ├── TimeoutManager.java
    │   │       └── StatusRemarkBuilder.java
    │   └── resources/
    │       ├── mapper/
    │       │   └── CommandMapper.xml
    │       └── application-plugin.yml  # 插件配置模板
    └── test/
        └── java/.../
            └── PluginIntegrationTest.java
```

## 集成方式

### 方式 1：Maven 依赖（推荐）

**原项目 pom.xml 添加依赖**：
```xml
<dependency>
    <groupId>com.cloudplatform</groupId>
    <artifactId>multi-instruction-plugin</artifactId>
    <version>1.0.0</version>
</dependency>
```

**原项目启动类添加注解**：
```java
@SpringBootApplication
@EnableMultiInstructionPlugin  // 启用插件
public class OriginalApplication {
    public static void main(String[] args) {
        SpringApplication.run(OriginalApplication.class, args);
    }
}
```

**原项目 application.yml 添加配置**：
```yaml
multi-instruction:
  enabled: true
  scheduler-interval-ms: 3000
  # ... 其他配置
```

### 方式 2：源码复制

将 `src/main/java/com/cloudplatform/plugin/multiinstruction` 整个目录复制到原项目的 `src/main/java` 下。

## 插件功能

### 1. 自动配置

```java
@Configuration
@ConditionalOnProperty(prefix = "multi-instruction", name = "enabled", havingValue = "true")
@EnableScheduling
public class MultiInstructionAutoConfiguration {
    
    @Bean
    public CommandScheduler commandScheduler() {
        return new CommandScheduler();
    }
    
    @Bean
    public TimeoutManager timeoutManager() {
        return new TimeoutManager();
    }
    
    // ... 其他 Bean
}
```

### 2. 可配置项

```yaml
multi-instruction:
  enabled: true                    # 是否启用插件
  scheduler-interval-ms: 3000      # 定时任务间隔
  command-exec-timeout-ms: 180000  # 3 分钟执行超时
  offline-interrupt-threshold-ms: 7200000  # 2 小时离线中断
  global-issue-timeout-ms: 86400000  # 24 小时全局超时
  redis:
    key-prefix: "plugin:cmd:"      # Redis key 前缀
```

### 3. 接口调用

```java
@Service
public class BusinessService {
    
    @Autowired
    private MultiCommandPluginService pluginService;
    
    public void doSomething() {
        // 下发指令
        pluginService.issueCommands("VIN123", Arrays.asList("/file1.can", "/file2.can"));
        
        // 查询状态
        List<CommandEntity> commands = pluginService.listByVin("VIN123");
    }
}
```

## 依赖关系

```xml
<dependencies>
    <!-- Spring Boot -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
        <version>2.7.18</version>
        <scope>provided</scope>
    </dependency>
    
    <!-- MyBatis -->
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>2.3.1</version>
        <scope>provided</scope>
    </dependency>
    
    <!-- Redis -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-redis</artifactId>
        <version>2.7.18</version>
        <scope>provided</scope>
    </dependency>
    
    <!-- Redisson -->
    <dependency>
        <groupId>org.redisson</groupId>
        <artifactId>redisson-spring-boot-starter</artifactId>
        <version>3.21.3</version>
        <scope>compile</scope>
    </dependency>
</dependencies>
```

## 优势

1. **零侵入** - 原项目只需添加依赖和配置
2. **可插拔** - 配置 `enabled: false` 即可禁用
3. **独立测试** - 插件有独立的测试用例
4. **版本管理** - 插件可独立升级
5. **复用性强** - 其他项目也可以引用

## 下一步

1. 创建独立插件模块
2. 迁移核心代码到插件
3. 编写插件集成测试
4. 发布到 Maven 仓库（或本地安装）