# 库存日志 — 功能需求说明

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

---

## 1. 模块定位

### 1.1 业务目标

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

- 在 **单一列表** 中浏览 **当前店铺** 下 **全部** 商品规格的 **库存变化流水**（含 **入库类** 与 **出库类**）；
- 通过 **方向筛选**（全部 / 入库 / 出库）与 **关键词检索** 快速 **定位** 某商品或规格的历史变化；
- 查看每条记录的 **变化前库存、变化后库存、变化量、变化原因、操作时间**，用于 **对账、追溯、审计**；
- 与 **商品入库、商品出库、库存调整、订单关单回滚** 等模块 **协作**：上述模块在 **确认变更库存** 或 **留痕** 时 **写入** 日志，本模块 **只读展示**。

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

| 能力 | 说明 |
|------|------|
| **手工创建 / 编辑 / 删除日志** | **不做**；日志由业务模块 **自动生成** |
| **商品入库 / 出库 / 调整操作入口** | 见各 **写入来源** 模块；本模块 **无** 创建单据按钮 |
| **入库单 / 出库单 / 调整单详情页** | 见 **商品入库、商品出库、库存调整** 专册 |
| **实时可用库存列表** | 见 **库存查询** |
| **按单号查入库单 / 出库单** | 见 **商品入库、商品出库** 列表检索 |
| **平台代查商家库存日志** | **平台管理端** **无** 本菜单 |
| **导出 / 打印** | **非本期**（UI 勾选框 **预留**，见 §13） |

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

| 草稿条目 | 定稿处理 |
|----------|----------|
| §1 出入库记录类型 | §3.1、§5.2 |
| §2 列表字段 | §4 |
| §3 高级检索（关键词） | §5 |
| §4 变化原因 | §3.2～§3.4 |
| §5 按当前店铺查询 | §1.4、§2.5 |
| §6 店铺上下文 | §2.5、§9 |
| §7 异常返回 | **不纳入** |
| §8 技术栈 | **不纳入** |

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

```text
【写入来源 · 并行】
    商品保存（新增规格）     → 自动入库留痕     → 写日志（入库类）
    商品入库 · 手工确认       → 增库存           → 写日志（入库类）
    商品出库 · 手工确认       → 减库存           → 写日志（出库类）
    支付成功 · 下单扣减       → 减库存（支付层） → 写日志（出库类，留痕）
    商品列表 · 删除规格       → 自动出库留痕     → 写日志（出库类，变化量 0）
    库存调整 · 确认           → 改库存           → 写日志（方向视增减）
    已支付关单 · 回滚库存     → 增库存（订单层） → 写日志（入库类）
            ↓
【本模块 · 只读】
    库存日志统一列表 ← 聚合展示全部流水
            ↓
【下游只读 · 并列】
    库存查询 · 查看出入库明细 ← 按 **单商品/规格** 聚合 **同源** 流水（展示口径一致）
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| **商品入库** | **写入来源** | 手工入库、**新增商品规格** 自动留痕 → **入库类** 日志；原因见 §3.2 |
| **商品出库** | **写入来源** | 手工出库、**下单扣减**、**删除产品规格** → **出库类** 日志；原因见 §3.3 |
| **库存调整** | **写入来源** | **库存编辑** → 日志方向 **随实际增减**；**不产生** 入/出库单 |
| **库存查询** | 下游只读 | 行级 **查看出入库明细** 与本模块 **同源**；本模块为 **全店维度** 时间序列表 |
| **全部订单 / 平台订单** | 间接写入 | **支付扣减**、**关单回滚** 经协作层写日志；**非** 本模块操作 |
| **商品列表** | 间接写入 | **新增规格**、**删除规格** 触发自动入/出库留痕 → 日志 |
| **售后管理** | **不写入** | 退货 **不自动** 改库存；商家 **手工退货入库** 后由 **商品入库** 写日志 |

### 1.4 数据范围

- **纳入：** 请求上下文 **当前店铺** 下 **全部已产生** 的库存变化流水（含 **系统自动** 与 **商家手工** 触发的写入来源）；
- **排除：** 其他店铺流水；**尚未发生** 的库存变化（无预生成、无草稿态日志）；
- **上下文：** 页头展示 **当前店铺名称**（只读）；切换店铺后列表 **整页刷新**。

### 1.5 使用端与角色

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

---

## 2. 关联需求分析

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

| 编号 / 关联点 | 平台规则 | 本模块体现 |
|---------------|----------|------------|
| **§11 可下单四条件** | 库存 **> 0** 方可下单 | 日志 **记录** 库存变化结果；**不** 参与下单校验 |
| **O4 / O-P4** | 支付成功 **扣库存** | 写入 **出库类 · 下单扣减库存** 流水 |
| **§10.1 关单回滚** | 已支付关单 **回滚库存** | 写入 **入库类 · 取消订单返库存** 流水（若系统实现回滚） |
| **§9.1 经营账号** | 登录后 **切换当前店铺** | 本模块 **仅展示当前店铺** 流水 |
| **§13 非本期** | 多 SKU 完整能力 | 按 **商品 + 规格** 展示；**首期** 单规格商品规格列 **可为「—」** |

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

| 项 | 定稿 |
|----|------|
| 支付成功 O4 | **扣减** 库存后，本模块展示 **下单扣减库存**（**出库类**） |
| 待支付关闭 O8 | **未扣** 库存 → **无** 对应日志 |
| 已支付关单 §10.1 | **回滚** 库存 → **取消订单返库存**（**入库类**）；**非** 商家 **手工入库** |
| 发货 O5 / O6 | **不重复** 扣库存 → **不产生** 额外出库日志 |
| 与入库/出库单 | 线上下单触发的流水 **可关联** 系统自动出库单（详情在 **商品出库**）；本列表 **仅展示变化维度**，**不强制** 跳转订单/单据 |

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

| 项 | 定稿 |
|----|------|
| 库存语义 | 日志中的库存均为 **可用库存**（与商品表库存字段一致） |
| 新增规格 | 商品保存写库存 + **新增商品规格** 自动入库留痕 → **入库类** 日志 |
| 删除规格 | 逻辑删除 + **删除产品规格** 自动出库留痕 → **出库类** 日志，**变化量 = 0** |
| 直接改库存数字 | **库存调整（库存编辑）** 写日志；**不走** 入/出库单 |
| 已删除商品 | 历史日志 **保留展示**；商品名称等 **按写入时点快照** 展示 |

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

| 项 | 定稿 |
|----|------|
| 写入时机 | **手工入库确认**、**新增规格自动留痕** 均写 **入库类** 日志 |
| 变化原因 | **新增商品规格、采购入库、退货入库、其他入库** 与本模块 §3.2 **一致** |
| 留痕不加库存 | **新增商品规格** 类日志仍展示 **变化前/后/变化量**，与商品保存 **一致**；**不在此重复加库存** |
| 检索 | 本模块关键词 **可命中** 上述流水涉及的商品名称、规格 |

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

| 项 | 定稿 |
|----|------|
| 写入时机 | **手工出库确认**、**支付下单扣减留痕**、**删除规格留痕** 均写 **出库类** 日志 |
| 变化原因 | **下单扣减库存、删除产品规格、订单出库、过期出库、其他出库** 与本模块 §3.3 **一致** |
| 命名 | **「下单扣减库存」** 与 **「订单出库」** **不可混用**（与出库专册一致） |
| 删除规格 | **变化量展示 0**；变化前/后库存 **相同** |
| 留痕不减库存 | **下单扣减** 类日志的 **减库存** 已在 **支付** 完成；日志 **仅展示** |

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

| 项 | 定稿 |
|----|------|
| 写入 | 调整 **增加** 库存 → **入库类 · 库存编辑**；**减少** → **出库类 · 库存编辑**；**覆盖** 后较原值 **增** 记入库类、**减** 记出库类 |
| 单据 | **不产生** 入库单/出库单；**仅** 写日志 + 调整明细（调整模块专册） |
| 与手工入出库 | **库存编辑** **不替代** 采购/退货/过期等业务入出库 |

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

| 项 | 定稿 |
|----|------|
| 数据源 | **同一套** 库存变化流水 |
| 差异 | **库存查询** = 按 **商品/规格** 聚合明细；**本模块** = **全店** 按 **操作时间倒序** 平铺 |
| 字段 | 出入库类型、数量、时间与 **本模块变化原因、变化量** **口径一致** |
| 实时库存 | **库存查询** 展示 **当前** 可用库存；**本模块** **不展示** 成本等查询专字段 |

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

| 项 | 定稿 |
|----|------|
| 售后完结 | **不自动** 写日志 |
| 退货验收 | 商家 **手工退货入库** → 由 **商品入库** 写 **退货入库** 日志 |
| 仅退款 | **不经** 本模块；关单/退款/回滚见 **订单** 专册 |

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

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

---

## 3. 记录类型与变化原因

### 3.1 记录类型（方向）

| 类型 | 含义 | 筛选 |
|------|------|------|
| **入库** | 该次操作导致 **可用库存增加**（或留痕类入库写入） | 列表 Tab **「入库」** |
| **出库** | 该次操作导致 **可用库存减少**（或留痕类出库写入） | 列表 Tab **「出库」** |
| **全部** | 不区分方向 | 列表 Tab **「全部」**（默认） |

> **说明：** **删除产品规格** 虽记 **出库类**，但 **变化量为 0**，变化前/后库存 **相等**。

### 3.2 入库类 — 变化原因

| 变化原因 | 写入来源 | 是否改库存 | 典型变化量 |
|----------|----------|------------|------------|
| **新增商品规格** | **商品列表** 保存（自动入库留痕） | **否**（库存由 **商品保存** 写入） | 初始库存（与保存一致） |
| **采购入库** | **商品入库** 手工 | **是** | 正整数 |
| **退货入库** | **商品入库** 手工 | **是** | 正整数 |
| **其他入库** | **商品入库** 手工 | **是** | 正整数 |
| **取消订单返库存** | **订单协作** 关单回滚（若实现） | **是** | 正整数（回滚数量） |
| **库存编辑** | **库存调整**（调增或覆盖后增加） | **是** | 正整数 |

### 3.3 出库类 — 变化原因

| 变化原因 | 写入来源 | 是否改库存 | 典型变化量 |
|----------|----------|------------|------------|
| **下单扣减库存** | **支付成功** 自动（出库留痕） | **否**（库存已在 **支付** 扣减） | 订单明细数量 |
| **删除产品规格** | **商品列表** 删除（自动出库留痕） | **否** | **0** |
| **订单出库** | **商品出库** 手工（线下等） | **是** | 正整数 |
| **过期出库** | **商品出库** 手工 | **是** | 正整数 |
| **其他出库** | **商品出库** 手工 | **是** | 正整数 |
| **库存编辑** | **库存调整**（调减或覆盖后减少） | **是** | 正整数 |

> **UI 展示：** 列表「操作」列展示 **变化原因** 文案；如 **取消订单返库存** 在界面可简写为 **「取消订单返库」**，语义 **等价**。

### 3.4 变化量与前后库存展示规则

| 规则 | 说明 |
|------|------|
| **变化前库存** | 该次变化 **生效前** 的 **可用库存** |
| **变化后库存** | 该次变化 **生效后** 的 **可用库存** |
| **变化量** | 一般展示 **本次变化的绝对数量**（UI 为 **非负整数**）；**入库类** 满足 `变化后 ≥ 变化前`；**出库类** 满足 `变化后 ≤ 变化前` |
| **删除产品规格** | **变化量 = 0**；**变化前 = 变化后** |
| **留痕类（新增规格 / 下单扣减）** | 前后库存、变化量须与 **实际写库存时点** **一致**；**不在日志页重复执行** 加减 |
| **一致性** | 任意时刻，按时间 **顺序回放** 日志，**变化后库存** 应与 **下一笔变化前库存** **衔接**（同一规格） |
| **规格粒度** | **一行日志对应一个商品规格** 的一次变化；一张入/出库单 **多行明细** → **多行日志** |

---

## 4. 库存日志列表

### 4.1 列表字段

| 列名 | 说明 |
|------|------|
| **商品名称** | 变化发生时商品名称 **快照**；可含 **商品编号** 等辅助信息（与 UI 一致） |
| **商品规格** | 规格文案；无规格时展示 **—** |
| **变化前库存** | 见 §3.4 |
| **变化后库存** | 见 §3.4 |
| **变化量** | 见 §3.4 |
| **操作** | 展示 **变化原因**（§3.2、§3.3）；**非** 可点击业务操作按钮 |
| **操作时间** | 库存变化 **生效时间**；格式 **yyyy-MM-dd HH:mm:ss** |

**默认排序：** 操作时间 **倒序**（最新在前）。

**行选择：** 列表左侧 **复选框** 为 **预留**（导出等 **非本期**）；**无** 批量删除、批量调整等操作。

### 4.2 列表能力边界

| 能力 | 定稿 |
|------|------|
| 分页 | **支持** 分页浏览（与商家端列表通用规范一致） |
| 详情页 | **本期无** 独立日志详情页；完整单据信息见 **入/出库单详情** |
| 跳转 | **非本期** 从日志行跳转订单/入库单/出库单 |
| 编辑/删除 | **禁止** |

---

## 5. 检索与筛选

### 5.1 关键词检索（高级检索）

| 条件 | 类型 | 说明 |
|------|------|------|
| **关键词** | 文本 | 模糊匹配 **商品名称** 或 **商品规格**（与草稿 §3 一致） |

**操作按钮：** **搜索**（或输入框旁搜索图标）、**重置**（清空关键词并恢复默认列表）。

### 5.2 方向筛选

| 条件 | 类型 | 说明 |
|------|------|------|
| **记录类型** | Tab | **全部**（默认）/ **入库** / **出库**（与草稿 §1、UI 一致） |

### 5.3 组合规则

| 规则 | 说明 |
|------|------|
| **叠加** | 关键词与方向 Tab **同时生效**（AND） |
| **空关键词** | 仅按方向 Tab 与默认排序展示 |
| **无结果** | 展示 **空列表** 及友好提示（如「暂无库存日志」） |

---

## 6. 写入协作流程（功能视角）

### 6.1 手工入库 → 日志

```text
商家 · 商品入库 → 确认手工入库
    → 可用库存增加
    → 写入库存日志（入库类 · 采购/退货/其他）
    → 本模块列表可见
```

### 6.2 手工出库 → 日志

```text
商家 · 商品出库 → 确认手工出库
    → 可用库存减少
    → 写入库存日志（出库类 · 订单/过期/其他）
    → 本模块列表可见
```

### 6.3 支付下单扣减 → 日志

```text
C 端支付成功
    → 订单协作扣减可用库存
    → 自动生成出库单（留痕）
    → 写入库存日志（出库类 · 下单扣减库存）
    → 本模块列表可见
```

### 6.4 关单回滚 → 日志

```text
平台/订单协作 · 已支付订单关闭
    → 回滚可用库存
    → 写入库存日志（入库类 · 取消订单返库存）
    → 本模块列表可见
（若业务未实现关单回滚，则 **不产生** 此类日志）
```

### 6.5 库存调整 → 日志

```text
商家 · 库存调整 → 确认
    → 可用库存按调整方式变更
    → 写入库存日志（入库或出库类 · 库存编辑）
    → 本模块列表可见
```

### 6.6 商品发品 / 删规格 → 日志

```text
【新增】商品保存 · 新增规格且初始库存>0
    → 商品保存写库存
    → 自动入库单留痕
    → 写入库存日志（入库类 · 新增商品规格）

【删除】商品列表 · 逻辑删除规格
    → 自动出库单留痕
    → 写入库存日志（出库类 · 删除产品规格，变化量 0）
```

---

## 7. 与库存查询的协作

| 项 | 定稿 |
|----|------|
| 数据同源 | 两模块读取 **同一套** 流水 |
| 视角 | **本模块**：全店、时间序；**库存查询**：单规格、明细弹窗 |
| 字段一致 | 类型（入/出库）、数量、时间、原因 **不得矛盾** |
| 实时库存 | 仅 **库存查询** 展示 **当前** 可用库存；本模块 **不替代** 库存查询 |

---

## 8. 权限与菜单

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

---

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

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

---

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

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

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

---

## 11. 非本期与待建设

| 项 | 说明 |
|----|------|
| 日志 **导出 / 打印** | **非本期** |
| 列表 **批量操作**（勾选） | **预留**；**非本期** |
| **按操作时间区间** 筛选 | 草稿 **未要求**；**非本期** |
| **按变化原因** 下拉筛选 | **非本期**（可后续与高级检索一并建设） |
| 跳转 **入库单 / 出库单 / 订单** | **非本期** |
| 平台端 **代查日志** | **不做** |
| 日志 **修正 / 冲销** | **不做**；纠错须走 **库存调整** 或 **业务入出库** |

---

## 12. 业务规则汇总

| 编号 | 规则 |
|------|------|
| **LOG-A1** | 本模块 **只读**；**禁止** 手工增删改日志 |
| **LOG-A2** | 数据范围 **仅当前店铺** |
| **LOG-A3** | **全部** 库存变化须由 **写入来源模块** 产生日志；**不得遗漏** 已确认的业务入出库、调整、支付扣减、删规格留痕 |
| **LOG-A4** | **变化原因** 枚举与 §3.2、§3.3 **一致**；与 **入/出库专册** **同名** |
| **LOG-A5** | **删除产品规格** 日志 **变化量 = 0** |
| **LOG-A6** | **留痕类** 日志须展示 **真实前后库存**；**不重复** 执行库存加减 |
| **LOG-A7** | **库存编辑** 方向 **随实际增减**；**入库、出库** Tab 均可出现 |
| **LOG-A8** | 关键词检索 **商品名称、商品规格**；方向 Tab **全部/入库/出库** |
| **LOG-A9** | 默认按 **操作时间倒序** |
| **LOG-A10** | **取消订单返库存** 仅 **关单回滚** 场景；**非** 商家 **退货入库** |
| **LOG-A11** | 与 **库存查询 · 出入库明细** **同源同口径** |

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：对齐草稿 §1～§5；补全列表/检索/变化原因/写入协作/兄弟模块与平台订单·商品·入出库边界；《库存日志功能需求-草稿》**保持不变** |

---

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