# 库存管理看板（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" />`，原操作服务未更换，新增读接口可继续保留。