# WMS AI功能开发文档

## 1. 目标说明

本文档基于 `zy-wcs-master` 的 AI 巡检思路，对当前 `wms-master` 项目进行了功能映射和实现说明。
本次实现的目标不是照搬 Spring AI + MCP 的完整体系，而是复用当前项目已有的 `rsf-server + rsf-ai-gateway + rsf-admin` 架构，以最小改动补齐以下能力：

- 通用聊天场景与系统诊断场景并存
- 一键诊断入口
- 基于库存、任务、设备站点的实时诊断上下文
- AI会话与消息持久化
- 保持现有模型配置中心和网关调用链不变

## 2. 与 `zy-wcs-master` 的映射关系

| `zy-wcs-master` 能力 | 当前项目映射方案 |
| --- | --- |
| 一键巡检 / 连续追问 | `AiController` 新增诊断场景，前端增加“一键诊断” |
| Prompt 场景中心 | 使用 `sceneCode + AiProperties + AiPromptContextProvider` 组合实现 |
| MCP 工具聚合 | 使用现有上下文提供器直接查询业务表，先实现轻量级数据工具能力 |
| 会话落库 | 新增 `sys_ai_chat_session`、`sys_ai_chat_message` |
| LLM 网关 | 继续复用 `rsf-ai-gateway` |

说明：当前版本没有直接引入 `zy-wcs-master` 的 Prompt 管理后台、MCP 挂载中心、模型路由容灾中心。这些能力保留为下一阶段增强项。

## 3. 当前实现架构

### 3.1 模块分工

- `rsf-admin`
  - AI 对话抽屉组件
  - 新增一键诊断按钮
- `rsf-server`
  - AI控制器、场景路由、上下文拼装、会话存储
  - 直接从 WMS 业务表读取诊断摘要
- `rsf-ai-gateway`
  - 统一封装 OpenAI 兼容流式接口

### 3.2 调用链路

```mermaid
flowchart LR
    A["rsf-admin AI对话组件"] --> B["rsf-server /ai/chat/stream"]
    A --> C["rsf-server /ai/diagnose/stream"]
    B --> D["AiPromptContextService"]
    C --> D
    D --> E["库存摘要"]
    D --> F["任务摘要"]
    D --> G["设备站点摘要"]
    B --> H["AiSessionService"]
    C --> H
    B --> I["rsf-ai-gateway"]
    C --> I
    I --> J["OpenAI兼容模型接口"]
```

## 4. 后端实现说明

### 4.1 场景定义

新增场景编码：

- `general_chat`：普通对话
- `system_diagnose`：系统巡检诊断

相关位置：

- `rsf-server/src/main/java/com/vincent/rsf/server/ai/constant/AiSceneCode.java`
- `rsf-server/src/main/java/com/vincent/rsf/server/ai/dto/AiChatStreamRequest.java`
- `rsf-server/src/main/java/com/vincent/rsf/server/ai/model/AiPromptContext.java`

### 4.2 控制器能力

`AiController` 当前提供两条 SSE 能力：

- `/ai/chat/stream`
  - 通用聊天
  - 支持显式传入 `sceneCode`
- `/ai/diagnose/stream`
  - 诊断快捷入口
  - 自动使用 `system_diagnose`
  - 如果前端未传消息，则使用默认巡检提示词

### 4.3 Prompt 与上下文策略

当前实现采用“基础提示词 + 场景提示词 + 数据摘要提示词”的组合方式：

1. 基础提示词来自模型配置或 `application.yml`
2. 诊断场景追加 `diagnosis-system-prompt`
3. `AiPromptContextService` 自动拼接上下文提供器内容

上下文提供器如下：

- `AiDiagnosisPromptProvider`
  - 输出诊断流程和回答结构约束
- `AiWarehouseSummaryService`
  - 汇总 `man_loc`、`man_loc_item`
- `AiTaskSummaryService`
  - 汇总 `man_task`
- `AiDeviceSiteSummaryService`
  - 汇总 `man_device_site`

### 4.4 诊断数据来源

本次实现优先接入实时业务表，不额外引入独立知识库：

- 库存与库位：`man_loc`、`man_loc_item`
- 任务：`man_task`
- 设备站点：`man_device_site`

这使得 AI 更偏向“运行态诊断助手”，而不是通用知识问答机器人。

## 5. 会话持久化设计

### 5.1 表结构

新增脚本：`version/db/20260316_ai_chat_storage.sql`

涉及两张表：

- `sys_ai_chat_session`
- `sys_ai_chat_message`

### 5.2 存储策略

`AiSessionServiceImpl` 采用“数据库优先，内存兜底”模式：

- 如果检测到两张表存在，则自动启用数据库持久化
- 如果未执行迁移脚本，则继续使用原有内存缓存逻辑

这样可以降低发布风险，适合分阶段上线。

### 5.3 上线建议

建议在正式启用前先执行以下脚本：

- `version/db/20260311_ai_param.sql`
- `version/db/20260316_ai_chat_storage.sql`

脚本执行完成后重启 `rsf-server`，使其在启动阶段检测到会话表并切换到持久化模式。

## 6. 前端交互说明

`rsf-admin/src/ai/AiChatWidget.jsx` 已增加“一键诊断”入口，入口位置包括：

- 会话顶部工具区
- 空白态引导区
- 底部输入区状态栏

点击后会向 `/ai/diagnose/stream` 发起流式请求，并自动带上：

- `sessionId`
- `modelCode`
- `sceneCode=system_diagnose`

## 7. 配置项说明

`rsf-server/src/main/resources/application.yml`

关键配置：

- `ai.system-prompt`
- `ai.diagnosis-system-prompt`
- `ai.default-model-code`
- `ai.max-context-messages`

模型接入配置仍然优先从 AI 参数管理读取，`application.yml` 主要承担默认兜底配置。

## 8. 与 `zy-wcs-master` 的差距

当前版本已经具备“可用”的诊断能力，但与 `zy-wcs-master` 相比仍有以下差距：

- 尚未实现独立的 Prompt 配置后台
- 尚未实现标准 Spring AI MCP Server / MCP Mount 聚合
- 尚未实现多模型路由、失败切换、调用日志中心
- 当前诊断依赖数据库摘要，尚未纳入日志流、设备实时线程状态等更深层数据

## 9. 下一阶段建议

如果继续向 `zy-wcs-master` 靠近，建议按以下顺序演进：

1. 抽象统一的“AI数据工具层”，替代零散的上下文提供器
2. 新增 Prompt 模板表和发布机制
3. 给 `rsf-ai-gateway` 增加调用日志、失败切换、模型路由
4. 将日志、任务异常、接口失败率纳入诊断上下文
5. 增加独立的 AI 管理页，用于诊断记录、Prompt 调优和模型切换