---
name: inventory
description: Inventory management and stock monitoring. Set stock to exact values, adjust stock incrementally, check low stock alerts, view history, reserve stock. Use when user needs to set/update stock, replenish inventory, monitor low stock, or manage reservations. Two key commands - `inventory set` (set to exact number) and `inventory adjust` (add/remove incrementally).
---

# Commerce CLI - Inventory Management

库存管理模块，用于监控库存水平、补货、预留和历史跟踪。

## 典型场景

### ⚠️ set vs adjust — 必须区分！

| 命令 | 作用 | 示例 | 效果 |
|------|------|------|------|
| `inventory set --id XX --quantity 18` | **设置为**目标值 | 当前库存13，设为18 | 库存变为 18 |
| `inventory adjust --id XX --quantity 5` | **增加**库存 | 当前库存13，加5 | 库存变为 18 |
| `inventory adjust --id XX --quantity -3` | **减少**库存 | 当前库存13，减3 | 库存变为 10 |

**判断用哪个**：
- 用户说"库存设置为/设为/改为 N" → `inventory set`
- 用户说"补货/加 N 个" → `inventory adjust`（正数）
- 用户说"扣减/减 N 个" → `inventory adjust`（负数）

### 场景决策表

| 用户需求 | 推荐命令 | 关键注意点 |
|---------|---------|-----------|
| 设置库存为 N | `inventory set --id XX --quantity N` | 直接设为目标值 |
| 查看低库存 | `inventory low-stock --threshold 10` | 阈值根据品类和销售速度设定 |
| 补货操作 | `inventory adjust --id XX --quantity N` | 增量补货（+=） |
| 盘点调整 | `inventory set --id XX --quantity N` | 以实际盘点数量为准 |
| 预留库存 | `inventory reserve --id XX --quantity N` | 订单创建时立即预留，避免超卖 |
| 查看历史 | `inventory history --id XX` | 分析库存变化趋势，优化补货策略 |

### 1. 查看低库存预警

**场景**：每日检查需要补货的商品

```bash
# 用户说："查看库存低于5的商品"
commerce inventory low-stock --threshold 5
```

### 2. 补货操作

**场景**：根据销售速度和品类特性进行科学补货

```bash
# 用户说："商品prod_123补货100个"（增量）
commerce inventory adjust --id prod_123 --quantity 100

# 根据销售数据决定补货量
commerce inventory adjust --id prod_hot --quantity 500
commerce inventory adjust --id prod_normal --quantity 100
commerce inventory adjust --id prod_slow --quantity 20
```

### 3. 预留库存

**场景**：订单创建时立即预留库存，防止超卖

```bash
# 用户说："为订单预留5个商品"
commerce inventory reserve --id prod_123 --quantity 5
```

**库存预留机制**：
- **订单创建时预留** - 避免超卖，保证订单可履行
- **发货后扣减** - 商品发货后从可用库存扣减

### 4. 盘点调整

**场景**：定期盘点发现账实差异，需要调整库存

```bash
# 实际库存95，直接设置为实际数量
commerce inventory set --id prod_123 --quantity 95
```

### 5. 处理超卖

**场景**：发现库存不足以满足所有订单

**预防措施**：
- 订单创建时立即预留库存
- 使用实时库存同步机制

**发生后处理**：
1. 优先处理早期订单，确保先到先得
2. 联系后续客户协商延期或退款
3. 紧急补货，缩短等待时间

**长期优化**：
- 检查库存同步机制，修复bug
- 加强预留机制的可靠性
- 设置安全库存缓冲

### 6. 查看库存历史

**场景**：分析库存变化趋势，优化补货策略

```bash
# 用户说："查看商品prod_123的库存变更记录"
commerce inventory history --id prod_123
```

## 卓越标准

### 库存管理质量指标
- **库存准确率**: 账实相符率 ≥ 98%，定期盘点验证
- **低库存预警响应**: 检测到低库存后24小时内补货
- **缺货率**: < 2%，避免影响客户体验和转化率
- **超卖率**: 0%，通过预留机制和实时同步防止超卖
- **库存周转率**: 根据品类优化，畅销品 > 6次/年，滞销品及时清理

### 库存管理原则
- **实时同步**: 订单创建时立即预留库存，发货后扣减，取消后释放
- **安全库存**: 设置合理的低库存阈值（畅销品 > 30天销量，滞销品 > 7天销量）
- **先进先出**: 先入库的商品优先出库，减少积压和过期
- **定期盘点**: 每月盘点核对账实差异，及时调整
- **历史追踪**: 所有库存变更必须记录原因，便于审计

### 日常库存监控流程
1. **查看低库存** - 每日 `commerce inventory low-stock --threshold 10`
2. **分析销售趋势** - 结合订单数据判断补货优先级
3. **制定补货计划** - 畅销品加大补货量，滞销品谨慎补货
4. **执行补货** - `commerce inventory adjust --id XX --quantity YY`
5. **验证更新** - `commerce product get --id XX` 确认库存正确
6. **定期盘点** - 每月实地盘点，调整账面库存

## 常见问题

### ❌ 问题1：批量补货不分析，造成库存积压

**错误做法**：
```bash
# 不分析就盲目补货，可能造成库存积压
for product_id in $(commerce inventory low-stock --json | jq -r '.[].id'); do
  commerce inventory adjust --id $product_id --quantity 100
done
```

**✅ 正确做法**：
```bash
# 先分析低库存商品，按销售速度分级补货
commerce inventory low-stock --threshold 10

# 根据销售数据决定补货量
commerce inventory adjust --id prod_hot --quantity 500      # 畅销品大量补货
commerce inventory adjust --id prod_normal --quantity 100   # 常规补货
commerce inventory adjust --id prod_slow --quantity 20      # 滞销品少量补货
```

### ❌ 问题2：库存差异超过5%未深入调查

**场景**：定期盘点发现差异

**处理流程**：
1. 核实实际库存，调整账面库存
2. 记录差异原因（损耗、盗窃、系统错误等）
3. 差异率 > 5%需要深入调查根本原因

```bash
# 盘点调整：实际95，直接设为95
commerce inventory set --id prod_123 --quantity 95
```

### ❌ 问题3：滞销商品长期占用库存

**滞销商品处理策略**：

| 滞销时长 | 处理方式 | 命令示例 |
|---------|---------|---------|
| 库存周转率低 | 降价促销、捆绑销售 | 调整价格，增加曝光 |
| 3个月未动销 | 考虑清仓处理 | 大幅降价或买一送一 |
| 6个月未动销 | 下架并清理库存 | 捐赠、报废或转移 |

```bash
# 查看库存历史判断是否滞销
commerce inventory history --id prod_slow
```

### ❌ 问题4：不分析销售数据就补货

**错误做法**：直接设置固定数量，不考虑销售速度

**✅ 正确做法**：
```bash
# 根据销售数据决定补货量（如上周销量50，预计2周销量）
commerce inventory adjust --id prod_123 --quantity 100
```

### ❌ 问题5：超卖后处理不当

**预防措施**：
- 订单创建时立即预留库存
- 使用实时库存同步机制

**发生后正确处理**：
1. ✅ 优先处理早期订单（先到先得）
2. ✅ 主动联系后续客户，提供补偿方案
3. ✅ 紧急补货，缩短等待时间
4. ❌ 不要直接取消订单不解释
5. ❌ 不要让客户长时间等待无反馈

## 命令参考

### 自然语言映射

当用户说：
- "库存设置为/设为/改为 N" → `commerce inventory set --id XX --quantity N`
- "商品XX补货50个" → `commerce inventory adjust --id XX --quantity 50`
- "扣减库存5个" → `commerce inventory adjust --id XX --quantity -5`
- "查看库存低于10的商品" → `commerce inventory low-stock --threshold 10`
- "预留库存" → `commerce inventory reserve --id XX --quantity YY`
- "查看库存历史" → `commerce inventory history --id XX`

### 核心功能

- `commerce inventory set` - 设置库存为目标值（覆盖当前值）
- `commerce inventory adjust` - 增减库存（增量 +=/-=）
- `commerce inventory low-stock` - 查看低库存商品
- `commerce inventory history` - 查看库存变更历史
- `commerce inventory reserve` - 预留库存

## 详细示例

### 查看低库存预警
```bash
# 用户说："查看库存低于5的商品"
commerce inventory low-stock --threshold 5
```

### 设置库存
```bash
# 用户说："商品prod_123库存设为100"
commerce inventory set --id prod_123 --quantity 100
```

### 补货操作
```bash
# 用户说："商品prod_123补货100个"（在现有基础上增加100）
commerce inventory adjust --id prod_123 --quantity 100
```

### 预留库存
```bash
# 用户说："为订单预留5个商品"
commerce inventory reserve \
  --id prod_123 \
  --quantity 5
```

### 查看库存历史
```bash
# 用户说："查看商品prod_123的库存变更记录"
commerce inventory history --id prod_123
```

## 变体库存管理（重要）

**这是最常见的库存管理错误，务必理解！**

### 核心规则

| 产品类型 | 库存设置方式 | 说明 |
|---------|-------------|------|
| **有变体的产品** | 必须设置**变体库存** | 产品库存 = 所有变体库存之和（自动计算） |
| **无变体的产品** | 直接设置**产品库存** | 正常更新即可 |

### 正确的库存更新流程

```bash
# 1. 先查看产品是否有变体
commerce product get --id prod_123

# 2. 如果 variants 数组不为空，逐个设置变体库存
commerce inventory set --id var_abc --quantity 10  # 变体1
commerce inventory set --id var_def --quantity 10  # 变体2
commerce inventory set --id var_ghi --quantity 10  # 变体3

# 3. 如果没有变体，直接设置产品库存
commerce inventory set --id prod_123 --quantity 30
```

### ❌ 常见错误

```bash
# 错误1：直接设置有变体产品的产品级库存（会被 API 拒绝）
commerce inventory set --id prod_123 --quantity 30

# 错误2：想设为18，却用了 adjust（结果是当前值+18）
commerce inventory adjust --id var_abc --quantity 18  # ❌ 增加了18，不是设为18
```

### ✅ 正确做法

```bash
# 用户说："把所有变体库存都设置为10"

# 1. 先获取产品和变体信息
commerce product get --id prod_123

# 2. 逐个设置变体库存
commerce inventory set --id var_abc --quantity 10
commerce inventory set --id var_def --quantity 10
commerce inventory set --id var_ghi --quantity 10

# 产品总库存会自动变为 30（10+10+10）
```

### 批量设置变体库存

当用户说"所有变体库存设置为 N"时：

1. 先用 `commerce product get --id XX` 获取变体列表
2. 遍历每个变体，用 `commerce inventory set --id <variant_id> --quantity N` 设置
3. 确认更新成功后，产品总库存会自动计算

## 重要提示

- **`inventory set`** 设为目标值，**`inventory adjust`** 增减库存 — 务必区分
- **有变体的产品必须设置变体库存，不能直接设置产品库存**（会被 API 拒绝）
- 库存变更会自动记录历史
- 预留库存不会减少可用库存数量
- 低库存阈值可自定义（默认5）
- 使用 `--help` 查看命令详细参数
