# 设备优先前缀配置说明

## 功能概述

设备优先前缀配置允许管理员指定在空闲设备选择时的优先级规则，优先选择特定前缀的设备，实现更灵活的设备分配策略。

## 配置项

**配置键**: `device.priority_prefixes`  
**配置类型**: STRING  
**默认值**: 空字符串（全随机）  
**格式**: 逗号分隔的前缀列表

## 使用方法

### 1. 配置优先前缀

通过系统配置接口设置 `device.priority_prefixes` 的值。

**示例配置值**:
```
xx,yy,zz
```

这表示：
- 第1优先级：`xx` 开头的设备
- 第2优先级：`yy` 开头的设备
- 第3优先级：`zz` 开头的设备
- 最低优先级：其他所有设备

### 2. 选择逻辑

设备分配时会按照以下逻辑进行：

1. **过滤占用设备**：排除被其他任务占用的设备
2. **按前缀分组**：根据配置的前缀将设备分成不同优先级组
3. **组内随机**：每个优先级组内的设备随机打乱
4. **顺序尝试**：按优先级从高到低依次尝试分配，直到成功

**特点**：
- ✅ 优先使用指定前缀的设备
- ✅ 同优先级内随机选择，避免总是选中同一台设备
- ✅ 实现负载均衡和优先级控制的平衡
- ✅ 支持冷却机制和并发安全

### 3. 示例场景

#### 场景1：无配置（默认行为）
```
device.priority_prefixes = ""
```
**效果**：所有设备完全随机选择，与原有逻辑一致

#### 场景2：优先使用xx设备
```
device.priority_prefixes = "xx"
```
**假设可用设备**：`xx1, xx2, yy1, yy2, zz1`

**选择顺序**：
1. 优先在 `xx1, xx2` 中随机选择
2. 如果 xx 设备都在冷却期或被占用，再从 `yy1, yy2, zz1` 中随机选择

#### 场景3：多级优先级
```
device.priority_prefixes = "xx,yy"
```
**假设可用设备**：`xx1, xx2, yy1, yy2, zz1, zz2`

**选择顺序**：
1. 第1优先级：在 `xx1, xx2` 中随机选择
2. 第2优先级：如果 xx 都不可用，在 `yy1, yy2` 中随机选择
3. 第3优先级：如果 xx、yy 都不可用，在 `zz1, zz2` 中随机选择

## API使用示例

### 查询当前配置
```bash
GET /api/admin/config/key/device.priority_prefixes
```

### 更新配置
```bash
PUT /api/admin/config

{
  "configKey": "device.priority_prefixes",
  "configValue": "xx,yy,zz",
  "configType": "STRING",
  "description": "设备选择优先前缀（逗号分隔）"
}
```

### 批量更新（推荐）
```bash
PUT /api/admin/config/batch

[
  {
    "configKey": "device.priority_prefixes",
    "configValue": "xx,yy"
  }
]
```

## 日志输出

启用该功能后，日志中会输出相关信息：

```
[INFO] 使用设备优先前缀配置：[xx, yy]
[DEBUG] 优先级0（前缀=xx）：2 台设备
[DEBUG] 优先级1（前缀=yy）：3 台设备
[DEBUG] 无优先级设备：5 台
[INFO] 设备列表已按优先级排序并随机化：[xx2, xx1, yy3, yy1, yy2, zz1, aa1, bb1, cc1, dd1]
[INFO] 设备分配成功：设备=xx2, 任务ID=123, 原因=首次选区
```

## 注意事项

1. **前缀匹配**：使用 `startsWith()` 进行前缀匹配，例如配置 `xx` 会匹配 `xx1`、`xx2`、`xxabc` 等
2. **大小写敏感**：前缀匹配区分大小写
3. **空格处理**：配置值会自动去除前后空格，`"xx, yy"` 会被处理为 `["xx", "yy"]`
4. **空配置**：如果配置为空或不存在，系统会退化到原有的完全随机选择逻辑
5. **优先级顺序**：前缀在配置字符串中的顺序决定优先级，越靠前优先级越高
6. **实时生效**：配置修改后立即生效，无需重启服务

## 数据库迁移

执行以下 SQL 脚本添加配置项：

```sql
-- 位置: db_migration_device_priority_prefixes.sql
INSERT INTO system_config (config_key, config_value, config_type, description, is_system, created_at, updated_at)
VALUES (
    'device.priority_prefixes',
    '',
    'STRING',
    '设备选择优先前缀（逗号分隔），例如：xx,yy,zz。优先选择匹配前缀的设备，同优先级内随机。为空则全随机',
    1,
    NOW(3),
    NOW(3)
)
ON DUPLICATE KEY UPDATE
    config_type = 'STRING',
    description = '设备选择优先前缀（逗号分隔），例如：xx,yy,zz。优先选择匹配前缀的设备，同优先级内随机。为空则全随机',
    updated_at = NOW(3);
```

## 相关代码

- **配置服务**: `SystemConfigService.getDevicePriorityPrefixes()`
- **分配服务**: `DeviceAllocationService.allocateDevice()`
- **排序逻辑**: `DeviceAllocationService.sortByPrefixPriority()`

## 测试建议

1. **无配置测试**：不配置前缀，验证随机选择是否正常
2. **单前缀测试**：配置单个前缀，验证是否优先选择该前缀设备
3. **多前缀测试**：配置多个前缀，验证优先级顺序是否正确
4. **负载均衡测试**：多次分配，验证同优先级内是否随机分布
5. **冷却期测试**：验证高优先级设备在冷却期时，能否正确选择低优先级设备