管家婆仓库商品库存

问题：库存信息散、表达不统一

仓库和采购日常最常被问到的，其实是一个很窄但很高频的问题：某个仓库里有什么货、有多少、值多少钱。

但在多数 ERP 场景里，这类问题并不好答：库存数据在数据库里，入口是菜单和表单；同时不同使用者对同一动作的说法并不统一。有人输入“库存”，有人写“存量”或“余量”；入库可能叫“进货”或“收货”，出库也可能叫“出货”或“发货”。如果每个问法都要人去点不同菜单，查询口径就会漂移，反馈也会变慢。

这个技能要解决的就是这件事：把“查仓库商品库存”固定成一条可路由的查询路径。

核心能力与调用路径

技能触发方式很直接：当用户用自然语言提出仓库商品信息查询时，加载本技能并执行对应 ERP 操作。例如“查看配货仓库中的商品信息”，以及“库存/存量/余量”等口语变体，都会被路由到同一个查询动作。

匹配后端服务 ReplenishmentAssistant.handle() 时，核心参数是：

• action：固定为 warehouse_products
• entities：由后端 NLPEngine.parse() 抽取，本技能只声明需要哪些实体槽位

实体抽取只要求两个槽位：warehouse 和 keyword。前者锁定查询范围，后者做商品名或关键词过滤。

拿到查询条件后，技能会请求真实数据源：默认走 H3ERP SQL Server 账套 yszt，通过 erp_core/h3erp/service.py 查询。另一个路径 erp_core/procurement/service.py 是演示数据路径，用于 H3ERP_ENABLED 未开启或暂时没有接入真实账套的调试场景。

返回值至少包含：

• reply：格式化文本，通常是 Markdown 表格或列表，用列表人工核对也直观
• action：当前执行的动作名，便于日志和路由追踪

更实用的是回复末尾会自动追加一段「📊 智能分析与建议」，由 _make_analysis() 统一生成，包含分析结论和可执行建议，而不是只丢一张原始库存表。

关键步骤

1. 识别意图并归一化表达：通过自然语言理解层识别“库存 / 存量 / 余量”这类同义表达，再进入统一查询动作。
2. 抽取实体槽位：确定 warehouse 与 keyword，缺省时按可服务范围放宽条件；时间范围也会解析成查询条件。
3. 按路径取数：真实环境查 H3ERP 账套，演示环境取 H3ERP_ENABLED=false 时的 mock 数据。
4. 格式化并分析：生成表格/列表回复，再追加库存分析建议，减少人工二次判断。

适用边界与注意点

• 所有查询接口支持 time_range 与 top_n，默认分别取最近 30 天和10 条；时间词可解析“本月”“上月”“本周”“上周”“今年”“最近 N 天”“前 N 天”等表达，但仍存在自然语言边界，极端日期组合需要显式给出。
• time_range 设置得太窄，可能掩盖长期呆滞库存；设置得太宽，又容易让回复被大量正常周转商品淹没，建议结合 top_n 控制展示量。
• 智能分析采用双模式：.env 中 AI_API_KEY 有效时走 LLM 增强分析；无效时降级为规则引擎兜底。规则兜底能保证基本可用，但分析深度有上限。
• 写操作类指令，包括开单、审批、申请，只生成草稿和预览，不直接写入 ERP 数据库；随后应逐条确认后再执行。
• 因此，生产环境必须连接真实账套，并按仓库权限控制可查范围。生产库数据可能存在延迟备份，对账时仍不建议用它替代正式盘点表。

适用场景与风险提示

• 需要“按仓库快速查看商品清单、库存数量和金额”时，这是一个合适的查询入口
• 需要口语化问库存、查存量、看余量时，可以复用同一套自然语言理解
• 适合作为日常库存盘点、配货前确认、异常库存定位的起点

风险方面要注意：库存金额依赖 accounting 口径和成本核算设置；如果仓库编码、商品名称不统一，关键词过滤可能漏检。涉及改库存、做审批的流程不要依赖本技能直接完成，它只负责查询和生成草稿。