# 生产模块 AI 辅助增强 - 前端联调方案

## 涉及页面

- 生产工单详情页（MesProWorkOrder）

---

## 功能一：AI 物料短缺预测

### 业务流程

```
在工单详情页
    → 点击"AI 物料预测"按钮
    → 后端收集 BOM + 库存数据，调用 AI
    → 弹窗展示物料风险分析（整体风险等级 + 各物料明细）
```

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/pro/ai/predict-material` | AI 物料短缺预测 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| workOrderId | Long | 是 | 工单 ID |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| riskLevel | Integer | 整体风险等级：1=低风险 2=中风险 3=高风险 |
| reasoning | String | AI 综合分析 |
| riskItems | List\<RiskItem\> | 物料风险明细 |

**RiskItem 子字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| itemCode | String | 物料编码 |
| itemName | String | 物料名称 |
| requiredQuantity | BigDecimal | 需求量 |
| availableQuantity | BigDecimal | 库存可用量 |
| shortageQuantity | BigDecimal | 短缺数量 |
| riskLevel | String | 风险等级：充足/紧张/短缺 |
| suggestion | String | 建议措施 |

---

## 功能二：AI 生产时长预测

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/pro/ai/predict-duration` | AI 生产时长预测 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| predictedTotalHours | BigDecimal | 预测总时长（小时） |
| standardTotalHours | BigDecimal | 标准总时长（小时） |
| reasoning | String | AI 推理分析 |
| keyPoints | List\<String\> | 关键关注点 |
| processBreakdown | List\<ProcessTimeBreakdown\> | 各工序时长明细 |

**ProcessTimeBreakdown 子字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| processName | String | 工序名称 |
| sort | Integer | 工序顺序 |
| standardPrepareTime | Integer | 标准准备时间（分钟） |
| standardWaitTime | Integer | 标准等待时间（分钟） |
| standardProductionTime | BigDecimal | 标准生产时间（小时） |
| predictedProductionTime | BigDecimal | 预测生产时间（小时） |

---

## 功能三：AI 生产风险预测

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/pro/ai/predict-risk` | AI 生产风险预测 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| overallRiskLevel | Integer | 整体风险等级：1=低风险 2=中风险 3=高风险 |
| reasoning | String | AI 综合分析 |
| keyPoints | List\<String\> | 关键关注点 |
| risks | List\<RiskItem\> | 风险明细列表 |

**RiskItem 子字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| category | String | 风险类别：质量/设备/物料/工艺瓶颈 |
| description | String | 风险描述 |
| severity | String | 严重程度：高/中/低 |
| suggestion | String | 建议措施 |

---

## 功能四：AI 是否能按时交付

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/pro/ai/predict-delivery` | AI 按时交付预测 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| onTime | Boolean | 是否能按时交付 |
| confidence | Double | 置信度（0-100） |
| reasoning | String | AI 推理分析 |
| delayFactors | List\<String\> | 延期因素 |
| progressPercent | BigDecimal | 生产进度百分比 |
| remainingDays | Integer | 距离需求日期剩余天数 |

---

## 字段展示规则

### 物料预测弹窗

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| riskLevel | 弹窗顶部醒目显示（颜色：绿色=低风险、橙色=中风险、红色=高风险） | 整体风险等级 |
| reasoning | 弹窗正文区域 | 段落文本 |
| riskItems | 弹窗中部表格 | 物料明细列表 |

### 时长预测弹窗

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| predictedTotalHours | 弹窗顶部醒目显示，对比 standardTotalHours | 预测 vs 标准 |
| reasoning | 弹窗正文区域 | 段落文本 |
| keyPoints | 弹窗底部 | icon + 文本列表 |
| processBreakdown | 弹窗中部表格 | 每道工序的时长分解 |

### 风险预测弹窗

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| overallRiskLevel | 弹窗顶部醒目显示 | 颜色区分 |
| reasoning | 弹窗正文区域 | 段落文本 |
| keyPoints | 弹窗中部 | 关注点列表 |
| risks | 弹窗底部表格 | 按类别分组展示 |

### 交付预测弹窗

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| onTime | 弹窗顶部醒目显示（绿色=可交付、红色=不可交付） | 是否按时 |
| confidence | onTime 旁边 | 置信度百分比 |
| progressPercent | 进度条 | 可视化进度 |
| remainingDays | 进度条右侧 | 剩余天数 |
| reasoning | 弹窗正文区域 | 段落文本 |
| delayFactors | 弹窗底部 | 延期因素列表（仅不可交付时显示） |

---

## 业务规则

| 场景 | 规则 |
|------|------|
| 点击按钮 | 按钮显示 loading 状态，不可重复点击 |
| AI 返回成功 | 弹窗展示结果，仅作参考 |
| AI 返回失败 | 弹窗显示"AI 分析暂时不可用，请稍后重试"，不影响正常操作 |
| 工单状态为草稿/已取消 | 仍可调用 AI 预测（用于生产前评估） |
| 无 BOM 数据 | 物料预测返回空风险项 |
| 未排产（无任务） | 时长预测仅返回标准时间估算 |

### 按钮放置位置

在工单详情页的操作区域新增 4 个 AI 辅助按钮。建议放在"确认/完成/取消"按钮区域的上方，用分隔线隔开：

```
[AI 物料预测] [AI 时长预测] [AI 风险预测] [AI 交付评估]
────────────────────────────────────
[确认工单] [完成工单] [取消工单]
```

4 个 AI 按钮在工单状态为"草稿"和"已确认"时均可点击。

---

## 注意事项

- AI 分析建议仅作参考，不自动修改工单数据
- AI 响应时间可能较长（5-15 秒），务必显示 loading 状态
- 4 个 AI 端点独立调用，前端可按需调用其中一个或多个
- `workOrderId` 取当前工单详情页的 `id` 字段
- 所有端点权限为 `mes:pro-work-order:query`，当前用户需有生产工单查询权限
- 响应中的字段均为可选（AI 解析失败时可能为空），前端需做防御性判断
- 物料/时长/风险/交付 4 个分析可独立使用，无先后依赖