---
name: store-inventory
description: 库存查询、入出库、低库存、CSV 导出与补货建议。触发：查库存/入库/出库/库存不够了/导出库存/补货建议。
---

# 门店库存

## 用法

```bash
uv run {baseDir}/scripts/cli.py <子命令> ...
```

## 输出格式

stdout 单行 JSON：成功 `"ok": true`；需确认 `"error": "need_confirm"`；失败含 `"error"` 码。详见 [references/errors.md](references/errors.md)。

## 主要子命令

| 子命令 | 用途 |
|--------|------|
| stock-query | 查库存（--key / --low-stock） |
| stock-in | 入库 |
| stock-out --yes | 出库（须确认） |
| stock-log | 出入库流水 |
| stock-export | 导出 CSV（items / logs） |
| replenish-suggest | 补货建议（近 N 日消耗均值） |

## 自然语言 → 命令

| 用户说 | 命令 |
|--------|------|
| 查全部库存 | `uv run {baseDir}/scripts/cli.py stock-query` |
| 查低库存 | `uv run {baseDir}/scripts/cli.py stock-query --low-stock` |
| 商品A入库 10 盒 | `uv run {baseDir}/scripts/cli.py stock-in --key "商品A" --quantity 10` |
| 出库 2 件商品B | `uv run {baseDir}/scripts/cli.py stock-out --key "商品B" --quantity 2 --yes` |
| 导出库存 | `uv run {baseDir}/scripts/cli.py stock-export --path ./items.csv` |
| 补货建议 | `uv run {baseDir}/scripts/cli.py replenish-suggest --days 7` |

## 需要先确认的操作

- 出库须先展示确认卡片，用户确认后加 `--yes`。

## 注意事项

- 数据库：`STORE_DB_PATH`（默认 `%USERPROFILE%\.config\store-suite\store.sqlite3`）。
- 库存项 key 与产品/耗材名称一致；低库存阈值来自产品 `threshold` 字段。
- `stock-export` 导出 CSV 已对 `=+@-` 等公式前缀做转义，Excel 打开安全。
- 错误码见 [references/errors.md](references/errors.md)。

## 示例

```bash
uv run {baseDir}/scripts/cli.py stock-query --low-stock
uv run {baseDir}/scripts/cli.py stock-in --key "商品A" --quantity 10 --type purchase --remark "采购入库"
uv run {baseDir}/scripts/cli.py stock-out --key "商品B" --quantity 2 --type sale --yes
uv run {baseDir}/scripts/cli.py stock-log --key "商品A" --direction out
uv run {baseDir}/scripts/cli.py stock-export --path inv_items.csv
uv run {baseDir}/scripts/cli.py stock-export --path low_stock.csv --low-stock-only
uv run {baseDir}/scripts/cli.py replenish-suggest --days 7
```
