water/server/docs/WATER_INVENTORY.md

库存管理看板（2026-09-11）

库存页 saiadmin-artd/src/views/water/inventory/index.vue 按用户参考图改为四项统计、分规格表格、七日趋势和库存构成。InventoryForm.vue 负责规格、入库及盘点交互，inventory.scss 限定在本页面。库存流水继续使用 WaterLedgerDrawer.vue。

数据口径

• 顶部统计、库存构成、七日趋势始终取全量数据，不随搜索和翻页变化。搜索仅影响规格表和规格导出。
• 可用满桶、锁定、在途直接累计 SKU 对应字段；总库存是三者之和，不含现场满桶、空桶、破损隔离满桶。
• 空桶资产 = 仓库空桶 + 企业现场空桶 + 配送任务车载待交接空桶。车载空桶须履约返仓交接后才进入仓库。
• 实物统计包含停用 SKU 的库存。库存预警只统计启用且 available <= safety_stock 的规格，数量为规格数；未添加没有业务依据的“偏低”阈值。
• 七日范围为服务器业务时区今天及前六天，缺失日期补零。入库累计 inbound 与 delivery_return（仅完好退回）；出库累计 depart。不包含库存冻结、签收、盘点、现场换桶、空桶交接等其他流水。
• 破损隔离满桶和累计空桶损失在右侧摘要、规格详情和导出中保留。

接口与维护

• GET /core/water/inventory/dashboard：keyword（最多120字）、page、limit（1–100）；返回 summary、trend、list、updated_at。
• POST /core/water/inventory/export：同关键词筛选，忽略分页，导出全部匹配规格 XLSX；最多50,000条，超出明确拒绝。临时文件自动清理，商品名公式前缀转义。
• 两接口复用 water:inventory:read 权限。控制器仅做权限、参数接收和响应，读模型在 WaterInventory 服务，数据库通过 Eloquent 模型访问。
• 写入仍走既有 POST /core/water/inventory 和 WaterBusiness 的事务、行锁与重复凭据校验，不增加独立库存写入路径。
• 盘点数必须主动填写，切换规格、企业或调整类型时清空盘点值；允许盘点为0。保存中禁用表单和关闭入口，错误时保留输入与凭据。
• 现场盘点只调整实物；现场换桶将满桶转为空桶，不再次扣减套餐权益。已使用规格的容量修改仍由后端拒绝。
• 无需本次数据库迁移；依赖已完成的履约字段迁移（damaged_qty、empty_lost_qty、empty_in_vehicle）。

验证与限制

• php -d extension=mbstring tests/water_inventory_test.php --http：50项，覆盖全量聚合、分页、阈值、七日边界、空桶归属、原库存操作、重复凭据、XLSX内容和权限，以及本地真实HTTP看板/导出。事务测试全部回滚；HTTP仅查询及导出。
• php -d extension=mbstring tests/water_business_test.php：69项通过，测试记录全部回滚。
• 新增/修改PHP语法、前端ESLint、vue-tsc与Vite构建验证。既有系统菜单静态/动态导入警告保留。
• 浏览器工具启动仍报 failed to start Node runtime: 系统找不到指定的路径。 (os error 3)，本次未完成视觉截图及浏览器交互验收；不可将构建或HTTP检查表述为视觉验收通过。4173预览服务可访问。

回退界面可将库存入口恢复为 <WaterWorkspace module="inventory" />，原操作服务未更换，新增读接口可继续保留。