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 的 Prompt 管理后台、MCP 挂载中心、模型路由容灾中心。这些能力保留为下一阶段增强项。

3. 当前实现架构

3.1 模块分工

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

3.2 调用链路

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 调优和模型切换