# 智能调度模块设计

基于里程考核数据，通过贪心优先级匹配算法，生成车辆替换建议，帮助调度员优化车队里程分布，最大化达标车辆数。

## 业务背景

公司有多批次考核车辆（40台普货、190台冷藏车等），每批次有年度里程考核目标。车辆租赁给不同客户，客户实际使用强度差异大。考核的是**车辆本身的里程**，因此需要通过替换车辆来均衡里程：
- 高里程客户的已达标车换下来，换上里程缺口大的车（让新车追赶）
- 低里程客户的无望达标车换下来给高里程客户（抢救），给低里程客户换上已达标的车

## 核心算法

### 车辆分类

从 `tab_mileage_assessment_vehicle` 获取所有考核车辆，按客户聚合计算**客户日均里程**（客户下所有车辆近 30 天日均里程的平均值），然后对每辆车计算：

```
预测年终里程 = 当前累计里程 + 客户日均里程 × 剩余天数
达标概率 = 预测年终里程 / 年度目标里程
```

分为三类：

| 类型 | 条件 | 含义 |
|------|------|------|
| qualified | `currentYearIsQualified = true` 或 达标概率 ≥ 120% | 已完成或铁定完成 |
| hopeless | 达标概率 < 60% | 按当前客户使用强度，年底肯定完不成 |
| normal | 60% ≤ 达标概率 < 120% | 有希望但不确定，暂不干预 |

### 替换建议生成

**场景 A：replace_qualified（高里程客户的已达标车辆）**
- 目标：把已达标的车换下来，换上里程缺口大的库存车
- 候选池：库存车（rent_status='在库'）+ 同车型 + 同区域
- 排序：优先选剩余缺口最大但换后仍可达标的车
- 校验：`候选车当前累计 + 客户日均 × 剩余天数 ≥ 年度目标` 才推荐

**场景 B：rescue_hopeless（低里程客户的无望达标车辆）**
- 目标：把无望车换给高里程客户抢救，给低里程客户换上已达标/库存车
- 候选池：库存中已达标或将达标的同车型同区域车辆
- 排序：优先选已达标且里程最高的车（对低里程客户无影响）

### 车型匹配规则

| 源车型 | 可替换为 | 说明 |
|--------|---------|------|
| 4.5T冷链 | 4.5T冷链、4.5T普货 | 冷链不开空调可当普货用 |
| 4.5T普货 | 4.5T普货 | 不能反向替换冷链 |
| 18T | 18T | 同型号互换 |
| 49T | 49T | 同型号互换 |
| 挂车 | 挂车 | 同型号互换 |

### 区域匹配规则

复用已有 `mapRegion()` 函数，将 province/city 映射到大区（嘉兴/广东/北京/新疆/其他）。同一大区内可替换，跨大区不推荐。

### 优先级排序

干预清单排序：
1. **hopeless + 有可行替换方案** → priority: high（最紧急，还能抢救）
2. **qualified + 高里程客户 + 有库存可换** → priority: medium（释放达标车，让新车追赶）

## 后端 API

### GET /api/scheduling/suggestions

获取调度建议列表。每次请求实时计算（不使用定时缓存），因为用户操作后需要立即看到最新结果。

**请求参数**：

| 参数 | 类型 | 说明 |
|------|------|------|
| targetId | number (可选) | 按批次筛选，不传则全部 |

**响应**：

```typescript
{
  summary: {
    qualifiedCount: number;      // 已达标车辆数
    hopelessCount: number;       // 无望达标车辆数
    suggestionCount: number;     // 可干预建议数
    estimatedGain: number;       // 预计干预后可新增达标数
  };
  suggestions: SchedulingSuggestion[];
  targets: { id: number; name: string; vehicleCount: number }[];
}
```

`SchedulingSuggestion` 结构：

```typescript
{
  id: string;                    // 建议唯一ID（如 "s-{plate}-{timestamp}"）
  priority: 'high' | 'medium';
  type: 'replace_qualified' | 'rescue_hopeless';

  currentVehicle: {
    plateNumber: string;
    targetId: number;
    targetName: string;          // 所属批次
    vehicleType: string;         // "4.5T冷链" / "18T" 等
    totalMileage: number;
    completionRate: number;      // 0-1
    yearTarget: number;          // 年度目标里程
    region: string;              // 大区（嘉兴/广东等）
    province: string;            // 原始省份
    customer: string;
    customerAvgDaily: number;    // 客户日均里程
    predictedYearEnd: number;    // 预测年终里程
    daysLeft: number;
  };

  candidates: {
    plateNumber: string;
    targetId: number | null;     // 库存车可能无批次
    targetName: string | null;
    vehicleType: string;
    totalMileage: number;
    completionRate: number;
    yearTarget: number | null;
    region: string;
    province: string;
    mileageGap: number;          // 剩余缺口
    predictedAfterSwap: number;  // 换到该客户后预测年终里程
    canQualifyAfterSwap: boolean;
  }[];

  reason: string;                // 建议原因文案
}
```

### POST /api/scheduling/notify

发送替换通知。成功后前端立即重新拉取 suggestions。

**请求体**：

```typescript
{
  suggestionId: string;
  currentPlate: string;
  candidatePlate: string;
}
```

操作人从 JWT auth 中获取。

**响应**：`{ success: boolean; message: string }`

**行为**：调用外部回调接口发送通知（具体回调 URL 后续配置）。成功后在本地记录已操作状态，后续 GET suggestions 时排除已操作的建议。

### 数据查询流程

后端一次请求聚合以下数据：
1. 所有考核车辆 — `tab_mileage_assessment_vehicle`（里程进度、达标状态）
2. 所有考核目标 — `tab_mileage_assessment_target`（批次名称、年度目标）
3. 库存车辆 — `tab_truck WHERE truck_rent_status = 0`（在库）+ 同表获取车型
4. 车辆实时位置 — `tab_truck_remote_sync_realtime_info`（province, city）
5. 合同/客户信息 — 复用 `vehicle-info.ts` 已有的 JOIN 查询
6. 客户日均里程 — 按客户聚合 `v_vehicle_daily_stats` 近 30 天均值

## 前端结构

### 文件组织

```
src/modules/scheduling/
├── SchedulingModule.tsx        // 主入口，状态管理和数据加载
├── SuggestionList.tsx          // 干预建议清单列表
├── SuggestionDetail.tsx        // 单条建议展开详情（含替换车辆对比）
├── api.ts                      // fetchSuggestions(), sendNotify()
└── types.ts                    // SchedulingSuggestion 等类型定义
```

后端：
```
src/server/routes/scheduling/
├── index.ts                    // 路由注册
├── suggestions.ts              // GET /suggestions 算法核心
└── notify.ts                   // POST /notify 回调通知
```

### 页面层级

```
智能调度 Tab
├── 顶部：批次选择器（复用里程统计的批次 tabs，默认"全部"）
├── 统计卡片区（3 个）
│   ├── 已达标车辆数（绿色）
│   ├── 无望达标车辆数（红色）
│   └── 可干预建议数 + 预计可新增达标数（蓝色）
├── 干预建议清单（主列表，按优先级排序）
│   ├── 每条：车牌、批次、客户、客户日均、完成率、区域、类型标签（已达标/无望）
│   └── 点击 → 展开干预详情
└── 干预详情（弹窗）
    ├── 当前车辆信息卡片
    ├── 推荐替换车辆列表（最多 5 辆）
    │   └── 每辆显示对比：替换前后的区域、车型、里程、预测达标
    ├── 建议原因说明
    └── 「发送替换通知」按钮 → notify 接口 → 成功后刷新列表
```

### UI 设计要求

- 以原型 `SmartSchedulingView` 组件为基础风格
- 使用 ui-ux-pro-max 优化视觉质量
- 适配移动端（竖屏卡片流）和 Web 端（landscape 横屏大表格）
- 干预详情弹窗需截图友好：完整卡片布局、替换前后对比一屏可见、关键数据醒目
- 统计卡片区保持与原型一致的三列 grid 布局
- 批次选择器横向滚动 pill 按钮样式

### 技术栈

复用项目已有：React 19 + Tailwind CSS + motion/react（动画）+ recharts（图表）+ lucide-react（图标）

## 约束与边界

- 替换仅为建议，不直接操作数据库修改车辆归属
- 不能推荐已租赁给其他客户的车辆，只从库存（在库）中推荐
- 跨批次可替换，但车型必须匹配（含冷链→普货单向规则）
- 同大区内替换，不跨大区
- notify 操作后数据立即更新（不使用定时缓存）
- 客户名称展示需使用已有的脱敏/Blur 组件