# 库存查询 — 功能需求说明

> 本文档在《库存查询功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》** v1.6、平台侧 **《订单管理功能需求》** v1.0.1、**《商品管理功能需求》** v1.3.3、**《店铺管理功能需求》** v1.3.2，以及商家侧 **《商品列表功能需求》**、《商品入库功能需求》** v1.0.1、《商品出库功能需求》** v1.0.1、《库存日志功能需求》** v1.0、《库存调整功能需求-草稿》、《售后管理功能需求》** v1.0、《商家端店铺上下文接口说明》** 做边界与流程对齐。  
> 范围：**店铺经营管理端 · 库存管理 · 库存查询** 对 **当前店铺** 下 **商品/规格实时可用库存** 的 **列表展示**、**关键词检索**，以及 **按规格查看出入库明细**；**不含** 在本页直接改库存、创建入/出库单。  
> **说明：** 本文档 **仅描述功能需求与业务规则**；不涉及数据库结构、接口定义及技术实现细节。  
> **命名区分：** **库存查询** 展示 **当前可用库存快照** + **单规格流水明细**；**商品入库/出库/调整** 为 **写库存入口**；**库存日志** 为 **全店流水汇总** 的并列只读模块。

---

## 1. 模块定位

### 1.1 业务目标

在农资商城 **店铺经营管理端（Web）· 库存管理** 提供 **库存查询** 能力，使 **店铺管理员**（商户经营账号及已授权子管理员）能够：

- 浏览 **当前店铺** 下各 **商品/规格** 的 **实时可用库存**；
- 通过 **关键词检索** 按 **商品名称、商品规格** 快速定位库存行；
- 查看 **成本** 列（有数据则展示，无则 **—**，见 §4.1）；
- 对任意库存行 **查看出入库明细**：展示 **该商品/规格** 在 **库存日志** 中的 **全部流水**（类型、数量、时间），用于 **对账与追溯**；
- 与 **商品列表、入/出库、调整、订单** 协作：库存数字 **由其他模块写入**，本模块 **只读展示**。

**不包含（本期或与它模块分工）：**

| 能力 | 说明 |
|------|------|
| **直接修改库存** | 见 **库存调整**；或 **商品入库 / 商品出库** |
| **创建入库单 / 出库单** | 见 **商品入库、商品出库** |
| **全店库存流水列表** | 见 **库存日志** |
| **按单号查入库/出库单** | 见 **商品入库、商品出库** 专册 |
| **维护成本价** | **非本期**；无成本数据源时列表展示 **—** |
| **平台代查商家库存** | **平台管理端** **无** 本菜单 |
| **导出 / 打印** | **非本期** |

### 1.2 与草稿的对应关系

| 草稿条目 | 定稿处理 |
|----------|----------|
| §1 实时库存列表字段 | §4 |
| §2 高级检索（关键词） | §5 |
| §3 查看出入库明细 | §6 |
| §4 按当前店铺查询 | §1.4、§2.9 |
| §5 店铺上下文 | §2.9、§10 |
| §6 异常返回 | **不纳入** |
| §7 技术栈 | **不纳入** |

### 1.3 在库存链中的位置

```text
【写库存 · 并行】
    商品列表 · 保存/发品          → 写入初始可用库存
    商品入库 · 手工/自动留痕      → 增库存（或仅留痕）
    商品出库 · 手工/支付/删规格   → 减库存（或仅留痕）
    库存调整 · 确认               → 改库存
    订单 · 支付扣减 / 关单回滚    → 减/增库存
            ↓
【本模块 · 只读】
    读当前可用库存 → 库存查询列表
    读库存日志     → 出入库明细（按规格）
            ↓
【并列只读】
    库存日志 · 全店时间序流水
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| **商品列表** | **库存来源** | 发品/编辑时的 **库存** 字段即 **可用库存**；**新增规格** 写入初始值 |
| **商品入库** | 上游写入 | 手工入库 **增库存**；明细弹窗 **含入库类** 流水 |
| **商品出库** | 上游写入 | 手工/支付/删规格 **减库存或留痕**；明细 **含出库类** 流水 |
| **库存调整** | 上游写入 | **库存编辑** 改库存；明细 **含对应方向** 流水 |
| **库存日志** | **同源明细** | 明细数据与 **库存日志** **同一套流水**；本模块 **按规格过滤** |
| **全部订单 / 平台订单** | 间接 | **支付扣减、关单回滚** 反映于 **可用库存** 与 **明细** |
| **售后管理** | 间接 | 退货 **不自动** 改库存；商家 **退货入库** 后 **库存与明细** 更新 |

### 1.4 数据范围

- **列表纳入：** 请求上下文 **当前店铺** 下 **未逻辑删除** 的 **商品/规格** 及其 **当前可用库存**；
- **列表排除：** 其他店铺商品；**已逻辑删除** 的商品/规格（**不在列表展示**；其 **历史明细** 若需追溯见 **库存日志**）；
- **明细纳入：** 所选 **商品/规格** 在 **库存日志** 中的 **全部已产生** 流水；
- **上下文：** 页头展示 **当前店铺名称**（只读）；切换店铺后 **整页刷新**。

### 1.5 使用端与角色

| 端 | 可操作角色 | 能力 |
|----|------------|------|
| **店铺经营管理端** | **商户经营账号** | 列表、检索、**查看出入库明细**（只读） |
| **店铺经营管理端** | 员工（子管理员） | 由 **角色管理** 决定菜单是否可见 |
| **平台管理端** | 平台管理员 | **无** 本模块 |
| **C 端** | 买家/访客 | **不可** 访问 |

---

## 2. 关联需求分析

### 2.1 与《关联需求分析》— 供给链与用户链

| 编号 / 关联点 | 平台规则 | 本模块体现 |
|---------------|----------|------------|
| **§11 可下单四条件** | 库存 **> 0** 方可下单 | 列表展示 **当前可用库存**；**0** 仍 **展示**（便于补货决策） |
| **O4 / O-P4** | 支付成功 **扣库存** | **可用库存** 减少；明细含 **下单扣减库存** |
| **§10.1 关单回滚** | 已支付关单 **回滚库存** | **可用库存** 增加；明细含 **取消订单返库存**（若实现） |
| **§9.1 经营账号** | 登录后 **切换当前店铺** | 列表 **仅当前店铺** |
| **§13 非本期** | 多 SKU 完整能力 | 按 **商品 + 规格** 一行；**首期** 单规格商品规格列 **可为「—」** |

### 2.2 与平台《订单管理功能需求》

| 项 | 定稿 |
|----|------|
| 支付成功 O4 | **扣减** 后列表 **可用库存** 即时减少；明细 **出库类 · 下单扣减库存** |
| 待支付关闭 O8 | **未扣** 库存 → 列表 **不变**；**无** 对应明细 |
| 已支付关单 §10.1 | **回滚** 后库存增加；明细 **入库类 · 取消订单返库存** |
| 发货 O5 / O6 | **不重复** 扣库存 → 明细 **不产生** 额外出库行 |

### 2.3 与平台《商品管理功能需求》/ 商家《商品列表功能需求》

| 项 | 定稿 |
|----|------|
| 库存字段 | 商品表单 **库存** = **可用库存**；与本列表 **同一口径** |
| 商品状态 | **任意状态**（草稿/出售中/下架等）**未删除** 商品 **均可** 出现在列表 |
| 规格 | **多规格** 时 **一行一规格**；无规格文案时展示 **—** |
| 主图/名称 | 列表 **商品信息** 取 **当前商品** 主图、名称（与商品列表一致） |
| 删商品 | 逻辑删除后 **移出** 本列表；历史流水仍在 **库存日志** |

### 2.4 与商家《商品入库功能需求》v1.0.1

| 项 | 定稿 |
|----|------|
| 库存更新 | **手工入库** 确认后 **可用库存** **即时增加** |
| 自动留痕 | **新增商品规格** 自动入库 **不改库存**（已在商品保存写入）；明细仍 **展示** 对应流水 |
| 明细类型 | **采购入库、退货入库、其他入库、新增商品规格** 等，文案与 **库存日志** **一致** |
| 成本 | 入库 **不要求录入成本**；本模块 **成本列** **无数据则 —** |

### 2.5 与商家《商品出库功能需求》v1.0.1

| 项 | 定稿 |
|----|------|
| 库存更新 | **手工出库** 确认后 **可用库存** **即时减少** |
| 支付/删规格 | **支付扣减** 改库存 + 留痕；**删除规格** 留痕 **变化量 0** |
| 明细类型 | **下单扣减库存、订单出库、过期出库、其他出库、删除产品规格** 等，与 **库存日志** **一致** |
| 命名 | **「下单扣减库存」** 与 **「订单出库」** **不可混用** |

### 2.6 与商家《库存日志功能需求》v1.0

| 项 | 定稿 |
|----|------|
| 明细数据源 | **与库存日志同一套流水**；**不得** 另建一套明细 |
| 差异 | **库存日志** = 全店、时间序；**本模块明细** = **单规格** 过滤 |
| 类型文案 | **出入库类型** = **库存日志 · 变化原因**（§3.2、§3.3 **同名**） |
| 数量口径 | 日志列表为 **非负变化量**；本模块明细为 **带符号出入库数量**（§6.2） |
| 时间 | **出入库时间** = 日志 **操作时间** |

### 2.7 与商家《库存调整功能需求-草稿》

| 项 | 定稿 |
|----|------|
| 改库存 | 调整确认后 **可用库存** 变更；明细含 **库存编辑** |
| 入口 | **不在** 本模块提供调整按钮；须至 **库存调整** |

### 2.8 与商家《售后管理功能需求》

| 项 | 定稿 |
|----|------|
| 售后 | **不自动** 改库存 |
| 退货 | 商家 **手工退货入库** 后，列表库存 **增加**，明细 **含退货入库** |

### 2.9 与《商家端店铺上下文接口说明》

| 项 | 定稿（功能口径） |
|----|------------------|
| 数据隔离 | 列表、明细 **仅当前店铺** |
| 默认店铺 | 经营账号 **默认最早有效店铺**；员工 **绑定店铺** |
| 切换店铺 | 切换后 **整页刷新** |
| 跨店 | **禁止** 查看其他店铺库存 |

---

## 3. 可用库存语义

### 3.1 定义

| 项 | 定稿 |
|----|------|
| **可用库存** | 当前可售、可出库的 **实物库存数量**（与 **商品列表** 库存字段、C 端下单校验 **一致**） |
| **实时性** | 列表每次加载/read 时展示 **最新值**；入/出库/调整/支付/回滚 **确认后立即反映** |
| **粒度** | **商品/规格** 一行；首期单规格 **一行一商品** |

### 3.2 库存变化来源（功能视角）

| 来源 | 对可用库存的影响 | 明细是否可见 |
|------|------------------|--------------|
| 商品保存（新增/初始库存） | **写入/变更** | **新增商品规格** 等 |
| 商品入库 · 手工 | **增加** | **是** |
| 商品出库 · 手工 | **减少** | **是** |
| 支付成功 · 下单扣减 | **减少** | **是** |
| 商品列表 · 删除规格留痕 | **不变**（变化量 0） | **是** |
| 库存调整 · 库存编辑 | **增/减/覆盖** | **是** |
| 已支付关单 · 回滚 | **增加**（若实现） | **是** |
| 待支付关单 | **不变** | **否** |

### 3.3 本模块不做的事

- **不** 在本页 **编辑** 可用库存；
- **不** 在本页 **创建** 入库单/出库单/调整单；
- **不** 参与 C 端 **下单扣减** 执行（仅 **展示结果**）。

---

## 4. 实时库存列表

### 4.1 列表字段

| 列名 | 说明 |
|------|------|
| **商品信息** | **主图缩略图** + **商品名称**（与 UI 一致；名称过长 **省略展示**，悬停可看全文） |
| **商品规格** | 规格文案；无规格时展示 **—** |
| **可用库存** | **当前** 可用库存 **非负整数** |
| **成本** | 商品/规格 **成本价**；**本期无成本数据源** 时统一展示 **—**；**不在本模块维护** |
| **操作** | **出入库明细**（链接或按钮，见 §6） |

**默认排序：** 建议 **商品更新时间倒序** 或 **商品 ID 倒序**（与商品列表习惯 **一致**；**非** 按库存数量排序，除非产品另定）。

**库存为 0：** **仍展示** 于列表（便于发现缺货并 **去入库**）。

### 4.2 列表能力边界

| 能力 | 定稿 |
|------|------|
| 分页 | **支持** 分页 |
| 行内改库存 | **禁止** |
| 跳转商品编辑 | **非本期**（可后续从名称链至 **商品列表**） |

---

## 5. 检索

### 5.1 关键词检索

| 条件 | 类型 | 说明 |
|------|------|------|
| **库存搜索** | 文本 | 模糊匹配 **商品名称** 或 **商品规格**（与草稿 §2、UI 占位「请输入商品名称/商品规格」一致） |

**操作按钮：** **搜索**、**重置**（清空关键词并恢复默认列表）。

### 5.2 规则

| 规则 | 说明 |
|------|------|
| 空关键词 | 展示 **当前店铺** 全部 **未删除** 商品/规格（分页） |
| 无结果 | 空列表 + 友好提示 |
| 规格为 — | 关键词 **仍匹配商品名称** |

---

## 6. 查看出入库明细

### 6.1 入口与形态

| 项 | 定稿 |
|----|------|
| 入口 | 列表行 **「出入库明细」** |
| 形态 | **弹窗** 或 **抽屉**（与 UI 稿一致）；标题 **「出入库明细」** |
| 范围 | **仅** 当前点击行的 **商品/规格** |
| 能力 | **只读**；**无** 编辑、删除、补录 |

### 6.2 明细列表字段

| 列名 | 说明 |
|------|------|
| **商品名称** | 与库存行一致（或流水 **快照** 名称，以 **库存日志** 为准） |
| **出入库类型** | 与 **《库存日志功能需求》变化原因** **同名**（如 **采购入库、下单扣减库存、取消订单返库存、库存编辑** 等）；**不** 用笼统「入库增加库存」**替代** 全部入库类 |
| **商品规格** | 规格文案；无则 **—** |
| **出入库数量** | **带符号整数**：**入库类为正值**，**出库类为负值**；**删除产品规格** 等 **变化量为 0** 的记录展示 **0** |
| **出入库时间** | 流水 **操作时间**；格式 **yyyy-MM-dd HH:mm:ss** |

**默认排序：** **出入库时间倒序**（最新在前）。

**空明细：** 该规格 **从未产生** 流水时，展示 **空列表** + 提示（如「暂无出入库记录」）。

### 6.3 与库存日志的数量展示差异

| 模块 | 数量展示 |
|------|----------|
| **库存日志** | **变化量** 为 **非负整数**；方向由 **入库/出库 Tab** 区分 |
| **本模块明细** | **出入库数量** **带符号**（入库 **+**、出库 **−**），与 UI 稿 **−5、+100** 一致 |
| **换算** | 同一笔流水：`出入库数量 = ±变化量`（入库取 **+**，出库取 **−**；**0** 仍为 **0**） |

### 6.4 明细须覆盖的流水类型

与 **《库存日志功能需求》§3.2、§3.3** **完整一致**，包括但不限于：

**入库类：** 新增商品规格、采购入库、退货入库、其他入库、取消订单返库存、库存编辑（调增）。  
**出库类：** 下单扣减库存、删除产品规格、订单出库、过期出库、其他出库、库存编辑（调减）。

---

## 7. 业务流程

### 7.1 查询实时库存

```text
进入 库存管理 → 库存查询
    → 加载当前店铺商品/规格及可用库存
    → （可选）输入关键词 → 搜索
    → 分页浏览列表
```

### 7.2 查看单规格明细

```text
列表行 → 点击「出入库明细」
    → 打开弹窗
    → 加载该商品/规格在库存日志中的流水
    → 展示：类型、带符号数量、时间
    → 关闭弹窗返回列表
```

### 7.3 与其他模块协作（商家作业链）

```text
发现可用库存不足
    → 本模块仅查看
    → 转至 商品入库 补货 / 商品列表 改初始库存（新规格）

发现库存账实不符
    → 转至 库存调整

需看全店流水
    → 转至 库存日志
```

---

## 8. 权限与菜单

| 项 | 定稿 |
|----|------|
| 菜单路径 | **库存管理 → 库存查询**（与 UI 一致） |
| 权限粒度 | **菜单可见**、**列表与明细查看** 可由 **角色管理** 分配；**无** 写操作权限 |
| 数据权限 | **仅当前店铺** |

---

## 9. 异常与空态（功能口径）

| 场景 | 期望表现 |
|------|----------|
| 店铺无商品 | 空列表 + 提示 |
| 关键词无匹配 | 空列表 + 提示 |
| 明细无流水 | 空明细 + 提示 |
| 非当前店铺 | **无权** 查看（与其他库存模块一致） |
| 切换店铺 | 列表 **清空并重新加载** |

---

## 10. 店铺上下文（功能口径）

与 **《商家端店铺上下文接口说明》** 一致：

```text
登录 → GET 店铺上下文 → 默认 shopId
    → 请求头携带当前 shopId
    → 本模块列表/明细均按该 shopId 过滤
经营账号切换店铺 → 更新 shopId → 本页刷新
员工账号 → 固定绑定店铺，不可切换
```

---

## 11. 非本期与待建设

| 项 | 说明 |
|----|------|
| **成本价** 录入与核算 | **非本期**；列 **预留**，无数据 **—** |
| 列表 **导出 / 打印** | **非本期** |
| **按库存区间** 筛选（如仅看库存=0） | **非本期** |
| **按商品状态** 筛选 | **非本期** |
| 明细跳转 **入库单/出库单/订单** | **非本期** |
| 列表跳转 **商品编辑** | **非本期** |
| 平台端 **代查库存** | **不做** |
| **批次 / 效期 / 多仓库** | **非本期** |

---

## 12. 业务规则汇总

| 编号 | 规则 |
|------|------|
| **QRY-A1** | 本模块 **只读**；**禁止** 在列表/明细 **改库存** |
| **QRY-A2** | 数据范围 **仅当前店铺**；**未逻辑删除** 商品/规格 |
| **QRY-A3** | **可用库存** 与 **商品列表、C 端下单** **同一口径** |
| **QRY-A4** | 库存 **=0** **仍展示** 于列表 |
| **QRY-A5** | 关键词检索 **商品名称、商品规格** |
| **QRY-A6** | 明细与 **库存日志同源**；类型文案 **同名** |
| **QRY-A7** | 明细 **出入库数量带符号**（入库 **+**、出库 **−**） |
| **QRY-A8** | 明细默认 **时间倒序** |
| **QRY-A9** | **成本** 无数据源时展示 **—**；**不在本模块维护** |
| **QRY-A10** | 入/出库/调整/支付/回滚 **确认后** 列表库存 **即时更新** |
| **QRY-A11** | **删除产品规格** 明细 **数量展示 0** |

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：对齐草稿 §1～§4；补全列表/检索/出入库明细/成本占位/与库存日志·入出库·商品·订单边界；《库存查询功能需求-草稿》**保持不变** |

---

*文档版本：v1.0（定稿）· 关联《关联需求分析.md》v1.6、平台/商家库存管理相关需求 · 草稿《库存查询功能需求-草稿.md》保持不变。*
