前三讲把地基打完了。这一讲是整个项目的业务核心ERP 仓储域怎么建模、AI 怎么通过工具调用读写真实数据、库存防超卖怎么保证。还有一个 8B 模型特有的坑数字参数 100% 成功字符串参数时灵时不灵。本讲复现环境与版本项版本/说明Spring AI1.0.9Tool/ToolParam/ DefaultToolCallingManager模型hermes3:latest8B踩坑期→qwen2.5:7b-instruct-q4_K_M修复后MyBatis-Plus3.5.8spring-boot3-starterPostgreSQL17.10 pgvector v0.8.5-pg17Spring Boot3.5.16 · JDK 17本讲问题均按「版本号 → 复现环境 → 真实报错 → 项目实际现象」四要素记录。业务建模15 张表WMS 仓储域的建模核心是理解单据状态机和库存三态。单据状态机入库单/出库单通用状态流转的库存联动是关键动作库存影响入库单完成quantity 实际入库量记录不存在则自动创建出库单确认lockedQuantity 申请量锁定防超卖出库单完成quantity - 实际出库量lockedQuantity - 申请量出库单作废lockedQuantity - 申请量释放锁定库存三态表清单业务表 10 张 系统表 5 张一个 SQL 设计决策我在 schema.sql 里放弃了触发器和$$函数——Spring Boot 的 ScriptUtils 不支持 PostgreSQL 的$$美元引用语法报Unterminated dollar quote。审计字段填充createTime/updateTime/createBy/updateBy全部改用 MyBatis-Plus 的MetaObjectHandler在应用层实现逻辑更清晰还避免了触发器这种看不见的逻辑带来的排查困难。关键设计ErpBusinessFacade 解耦层AI 工具类不直接注入任何 ERP Service 或 Mapper统一走 Facade 接口这个设计买到了什么AI 层与 ERP 层的单向依赖。将来 ERP 拆成独立微服务AI 层代码一行不改换个 Facade 实现就行。这里有个插曲值得说。ErpBusinessFacade接口有两个Service实现启动直接报问题档案版本Spring Boot 3.5.16Spring Framework 6.x 容器复现环境LocalErpFacadeImpl与FeignErpFacadeImpl同时贴Service任一 AI 工具类注入ErpBusinessFacade启动必现真实报错启动日志原文项目实际现象加了一个 Feign 远程调用的预留桩实现方法体全是 TODO后项目直接起不来。桩类也是类贴了 Service 就会被扫描注册因为FeignErpFacadeImpl是个预留的桩实现方法体全是 TODO也挂了 Service。解法是在LocalErpFacadeImpl上加Primary。划重点预留实现的桩类不应裸挂Service与生产实现并存。要么Primary明确主从要么桩类加Profile/ConditionalOnMissingBean控制加载条件。19 个 Tool 方法Spring AI 的工具注册非常简洁一个注解搞定完整清单8 个类 19 个方法工具类Tool 方法功能MaterialQueryToolqueryMaterial / getMaterialByCode按关键词/编码查物料MaterialManageToolcreateMaterial / updateMaterial / deleteMaterial / listEnabledMaterials物料 CRUDStockQueryToolqueryStock / checkLowStock库存查询 低库存预警InOrderCreateToolcreateInOrder创建入库单校验物料存在InOrderManageToolgetInOrderByNo / listInOrdersByStatus / confirmInOrder / cancelInOrder / completeInOrder入库单全生命周期OutOrderCreateToolcreateOutOrder创建出库单校验库存充足OutOrderManageToolgetOutOrderByNo / listOutOrdersByStatus / confirmOutOrder / cancelOutOrder / completeOutOrder出库单全生命周期KnowledgeSearchToolsearchKnowledge知识库检索无 ToolContext写 Tool 的三条经验经验 1description 是写给模型看的要具体到什么时候该用我经验 2参数名要短、要直白queryStock(String materialCodeOrId)→queryStock(String code)。模型对参数名的理解成本直接影响绑定成功率这在后面踩坑部分细说。经验 3写操作工具要把前置条件写进 description不然模型会在草稿状态就尝试完成入库然后拿到一堆业务异常。库存防超卖出库确认时锁定库存核心校验逻辑说实话这个实现在单机 事务场景够用但严格来说读-判断-写不是原子的高并发下仍有超卖窗口。要彻底解决得用数据库乐观锁version 字段或UPDATE ... WHERE quantity - locked ?条件更新。当前系统的并发量企业内部几十个用户用事务 校验已经足够但这个边界要心里有数。入库完成时记录不存在则自动创建注意erp_stock上有(material_id, warehouse_code)唯一约束兜底——并发首次入库时靠约束挡住重复创建。本讲最大的坑字符串参数绑定不稳定问题档案版本hermes3:latest8B→qwen2.5:7b-instruct-q4_K_M· Spring AI 1.0.9复现环境对话页发送「查询物料 ZL001 的库存」「查 MAT-001 库存」等含字符串编码的指令每句连测多次真实报错后端日志Spring AI 工具调用参数原文项目实际现象反问「请输入物料编码」的那几次queryStock根本没拿到参数而「查 1 号物料」这类数字 ID 指令从未失败现象用户说查询物料 ZL001 的库存AI 有时正常调用工具有时反问请输入物料编码。日志显示反问的那几次queryStock根本没被调用或者参数是null。有意思的规律传数字 ID查 1 号物料100% 成功传字符串编码查 MAT-001时好时坏。排查路径结论hermes3:latest (8B) 的 Function Calling 对字符串参数填充不可靠。修复分两步第一步简化参数名缓解有一定缓解但没根治。第二步换模型根治换完 5 次测试 0 次 paramnull问题彻底消失。敲黑板8B 级别模型的 Function Calling 能力差异很大选型时必须用自己业务的真实参数形态实测——尤其字符串编码类参数。别信模型介绍页的支持 Function Calling标签那个门槛很低。验证让 AI 真正跑一遍业务后端日志能看到完整的调用链数据库里真的多了一条记录。这一刻AI 智能体才名副其实。本讲踩坑清单#坑涉及版本根因解法1字符串参数 paramnullhermes3:latest 8B · Spring AI 1.0.9Hermes3 对字符串参数填充不可靠换 qwen2.5:7b-instruct-q4_K_M2启动报 found 2 beansBoot 3.5.16Spring 6.x桩实现裸挂 ServicePrimary 或条件注解3schema.sql 报 dollar quoteBoot 3.2/3.5 ScriptUtils PG 17不支持$$触发器逻辑改 MetaObjectHandler4草稿状态就能完成入库8B 模型不读状态机Tool description 无前置条件前置条件写进 description写在最后这一讲之后AI 已经能读写真实业务数据了。但现在的交互是一问一答——用户盯着空白屏幕等模型把整段话生成完。下一篇讲流式体验SSE 逐字输出 工具调用过程实时可视化用户能看到AI 正在查询库存…的卡片。其中 Reactor Flux 冷流的坑一个No StreamAdvisors available异常查了一晚上值得单独一讲。