# MES 质检 AI 功能 - 前端联调方案

## 涉及页面

- 来料检验单详情页（IQC）
- 过程检验单详情页（IPQC）
- 出货检验单详情页（OQC）
- 退货检验单详情页（RQC）
- 质检标准知识库管理页（可选）

---

## 功能一：AI 辅助判定检验结果

### 业务流程

```
检验员录入指标检测值 + 缺陷记录
    → 点击"AI 辅助判定"按钮
    → 调用 AI 接口获取判定建议
    → 弹窗展示 AI 建议（判定结果 + 推理依据 + 关注点）
    → 检验员参考建议，手动选择最终判定结果
    → 点击"完成检验"
```

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/qc/ai/suggest-result` | AI 辅助判定 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| qcId | Long | 是 | 质检单 ID |
| qcType | Integer | 是 | 质检类型：1=来料 2=过程 3=出货 4=退货 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| suggestedResult | Integer | 建议判定编码：1合格 2特采 3不合格退货 4不合格报废 |
| suggestedResultName | String | 建议判定名称 |
| reasoning | String | AI 推理依据（文本） |
| keyPoints | List\<String\> | 关键关注点清单 |

**响应示例：**
```json
{
  "code": 0,
  "data": {
    "suggestedResult": 1,
    "suggestedResultName": "合格",
    "reasoning": "所有检测指标均在允许范围内，缺陷数量未超过上限，建议判定为合格。",
    "keyPoints": ["外观检查指标接近上限，建议加强来料外观管控"]
  }
}
```

### 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| suggestedResultName | 弹窗顶部醒目显示（用颜色区分：绿色=合格、橙色=特采、红色=不合格） | 判定建议 |
| reasoning | 弹窗正文区域 | 推理依据，展示为段落文本 |
| keyPoints | 弹窗底部，列表展示 | 关注点以 icon + 文本展示 |

### 业务规则

| 场景 | 规则 |
|------|------|
| 点击按钮 | 按钮显示 loading 状态，**不可重复点击** |
| AI 返回成功 | 弹窗展示结果，检验员自行决定是否采纳 |
| AI 返回失败 | 提示"AI 判定暂时不可用，请人工判定"，不影响正常检验流程 |
| AI 判定超时 | 设置 30 秒超时，超时后提示用户重试 |
| 未录入检测值 | 允许调用 AI，AI 会基于已有缺陷记录给出建议 |
| 已完成检验 | 不需要展示 AI 判定按钮（已完成状态隐藏） |

### 按钮放置位置

在检验单详情页的"完成检验"按钮旁边，新增 `AI 辅助判定` 按钮。按钮仅在质检单状态为"草稿"时展示。

---

## 功能二：质检标准知识库 RAG 检索

### 业务流程

```
管理员：上传质检标准文档 → 系统自动分段+向量化
检验员：在质检页面右侧"质检助手"面板输入问题 → 检索相关标准段落 → 展示参考内容
```

### API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/ai/knowledge/segment/search` | 向量检索知识库分段 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| knowledgeId | Long | 是 | 质检标准知识库 ID |
| content | String | 是 | 检索查询文本（自然语言问题） |
| topK | Integer | 否 | 返回数量，默认取知识库配置值（建议 3~5） |
| similarityThreshold | Double | 否 | 相似度阈值 0~1，建议 0.5~0.7 |

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 分段 ID |
| content | String | 匹配的分段文本内容 |
| score | Double | 相似度得分 |
| documentName | String | 来源文档名称 |
| documentId | Long | 来源文档 ID |

**响应示例：**
```json
{
  "code": 0,
  "data": [
    {
      "id": 10,
      "content": "外观检验标准：表面应光滑平整，无裂纹、气泡、毛刺、锈蚀等缺陷...",
      "score": 0.85,
      "documentName": "来料检验作业指导书_v2.pdf",
      "documentId": 5
    }
  ]
}
```

### 前置准备

1. 在 AI 知识库管理中创建名称为"质检标准知识库"的知识库
2. 上传质检相关文档（国标、企标、作业指导书等）
3. 记录知识库 ID，前端配置为常量或通过接口获取

### 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| content | 结果卡片正文 | 高亮命中关键词 |
| score | 结果卡片底部小字 | 格式化为百分比，如"相似度 85%" |
| documentName | 结果卡片顶部 | 点击可跳转到文档预览页 |

---

## 注意事项

### AI 判定
- AI 建议仅作**参考**，最终判定由检验员决定，不自动写入
- AI 响应时间可能较长（5~15 秒），前端需显示 loading 状态
- `qcType` 取值：IQC 详情页传 1、IPQC 详情页传 2、OQC 详情页传 3、RQC 详情页传 4
- `qcId` 取当前质检单的 `id` 字段

### 知识库检索
- 知识库 ID 需先创建知识库并上传文档后才能使用
- 如果检索无结果（空数组），展示"未找到相关标准，请尝试其他关键词"
- 建议在质检录入页面右侧用可折叠面板展示，不影响主操作区域
- 检索输入框建议 placeholder："输入问题，如：外观检验标准是什么？"