# 商品入库 — 功能需求说明

> 本文档在《商品入库功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》**、平台侧 **《订单管理功能需求》** v1.0.1、**《商品管理功能需求》** v1.3.3、**《店铺管理功能需求》** v1.3.2，以及商家侧 **《商品列表功能需求》**、《商品出库功能需求-草稿》、《库存调整功能需求-草稿》、《库存查询功能需求-草稿》、《库存日志功能需求-草稿》、《售后管理功能需求》** v1.0、《商家端店铺上下文接口说明》** 做边界与流程对齐。  
> 范围：**店铺经营管理端 · 库存管理 · 商品入库** 对 **当前店铺** 下 **入库单** 的列表、检索、**手工创建入库**、**详情查看**，以及由 **商品发品/新增规格** 触发的 **自动入库** 记录展示。  
> **说明：** 本文档 **仅描述功能需求与业务规则**；不涉及数据库结构、接口定义及技术实现细节。  
> **命名区分：** **入库** 指 **可用库存增加** 及 **入库单** 留痕；**出库、库存调整、库存查询、库存日志** 为 **并列子模块**，职责见 §1.1。

---

## 1. 模块定位

### 1.1 业务目标

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

- 浏览 **当前店铺** 全部 **入库单**（含 **手工入库** 与 **系统自动入库**）；
- 通过 **高级检索** 按单号、商品、类型、时间、经办人等 **定位** 历史入库；
- **手工创建入库单**：对 **一个或多个商品规格** 批量执行 **采购入库 / 退货入库 / 其他入库**，系统 **生成入库单号** 并 **增加可用库存**；
- **查看入库单详情**（基本信息、入库明细行）；
- 与 **商品列表** 协作：商家 **新增商品规格** 时，若填写 **初始库存 > 0**，系统 **自动生成一张入库单**（多行明细，**仅留痕**；库存由 **商品保存** 写入，§5.4）。

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

| 能力 | 说明 |
|------|------|
| **商品出库** | 见 **商品出库**；含 **支付扣减**、**手工出库** 等 **减库存** 场景 |
| **库存调整** | 见 **库存调整**；直接 **增/减/覆盖** 库存，变化原因记 **库存编辑** |
| **库存查询列表** | 见 **库存查询**；展示 **实时可用库存**；可从库存行 **查看出入库明细** |
| **库存日志统一列表** | 见 **库存日志**；汇总 **全部** 出入库变化；本模块 **写入** 入库类记录 |
| **买家退货自动加库存** | **不自动**；买家退货、售后完结 **不联动** 本模块；商家须 **手工选择「退货入库」** 录入 |
| **订单支付扣库存 / 关单回滚库存** | 见 **订单管理** §12.2、§10；属 **出库/系统回滚** 口径，**非** 本模块操作入口 |
| **平台代商家入库** | **平台管理端** **无** 本菜单 |
| **入库单编辑 / 作废 / 反审** | **本期不做**；入库单 **确认提交后不可修改** |

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

| 草稿条目 | 定稿处理 |
|----------|----------|
| §1 新增规格自动入库 | §5、§9 |
| §2 手工批量入库（采购/退货/其他） | §6～§8 |
| §3 按当前店铺查询 | §1.4、§2.5 |
| §4 店铺上下文 | §2.5、§12 |
| §5 异常返回 | **不纳入** |
| §6 技术栈 | **不纳入** |

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

```text
【商家 · 商品列表】新增/编辑商品 → 新增规格且初始库存>0
            ↓
【商品保存】可用库存写入商品表（唯一写入口）
            ↓
【自动】生成入库单（新增商品规格，仅留痕）→ 库存日志
            ↓
【商家 · 本模块】手工入库（采购/退货/其他）→ 生成入库单 → 可用库存增加
            ↓
【商家 · 库存查询】展示实时库存；可查看该规格出入库明细
            ↓
【商家 · 库存日志】统一展示全部变化（含本模块与其他模块写入项）
            ↓
【并行 · 非本模块】
    支付成功 → 商品出库（下单扣减库存）
    手工出库 / 库存调整 / 删除规格 等 → 对应模块写入
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| **商品列表** | **上游触发** | **新增规格** 且 **初始库存 > 0** → **自动生成入库单（留痕）**；**可用库存由商品保存写入**，入库单 **不再重复加库存**（§5.4） |
| **商品出库** | 并列 | **减库存**；支付扣减、线下出库等 **不在** 本模块 |
| **库存调整** | 并列 | **库存编辑** 不走入库单；**不替代** 采购/退货等 **业务入库** |
| **库存查询** | 下游只读 | 入库成功后 **可用库存** 即时增加；明细弹窗 **可读** 本模块入库记录 |
| **库存日志** | 下游展示 | 本模块确认入库后 **写入** 日志；原因见 §3.2 |
| **全部订单 / 发货管理** | 间接 | 支付 **扣库存**（出库侧）；**取消/关单回滚** **非** 本模块自动入库 |
| **售后管理** | 协作口径 | 退货退款 **不自动** 加库存；商家验收后 **手工「退货入库」** |
| **平台 · 订单管理** | 规则一致 | O-P4 支付扣库存；§10 关单回滚 **在订单/商品协作层**，**不** 替代商家 **退货入库** 作业 |

### 1.4 数据范围

- **纳入：** 请求上下文 **当前店铺** 下全部 **已确认** 的入库单（含 **系统自动** 与 **手工**）；
- **排除：** 其他店铺入库单；**尚未提交** 的入库草稿（若前端本地暂存，**不上屏** 至列表）；
- **上下文：** 页头展示 **当前店铺名称**（只读）；切换店铺后列表 **整页刷新**。

### 1.5 使用端与角色

| 端 | 可操作角色 | 能力 |
|----|------------|------|
| **店铺经营管理端** | **商户经营账号** | 本模块全部能力 |
| **店铺经营管理端** | 员工（子管理员） | 由 **角色管理** 决定菜单与按钮（列表/入库/详情） |
| **平台管理端** | 平台管理员 | **无** 本模块 |
| **C 端** | 买家/访客 | **不可** 访问 |

---

## 2. 关联需求分析

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

| 编号 / 关联点 | 平台规则 | 本模块体现 |
|---------------|----------|------------|
| **§11 可下单四条件** | 库存 **> 0** 方可下单 | 本模块 **增加** 可用库存；**不保证** 商品为 **出售中**（库存与上架状态 **独立**） |
| **O-P4** | 支付成功 **扣库存** | **扣减** 在 **出库** 侧；与本模块 **对称留痕** |
| **§13 非本期** | 多 SKU 完整能力 | 草稿与 UI 按 **商品 + 规格** 管理；**首期** 可与商品列表 **单规格** 并存，规格列 **可为「—」** |
| **§9.1 经营账号** | 登录后 **切换当前店铺** | 本模块 **仅操作当前店铺** 库存 |

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

| 项 | 定稿 |
|----|------|
| 支付成功 O4 | **扣减** 商品库存；生成 **出库** 类记录（**商品出库** / **库存日志**） |
| 待支付关闭 | **未扣** 库存，**无** 入库 |
| 已支付关单 §10 | 若运营关闭，**回滚库存** 在 **订单协作** 层；**不等同** 商家 **退货入库** 单 |
| 库存日志中的「取消订单返库存」 | 若系统实现 **关单/取消回滚**，在 **库存日志** 展示；**非** 本模块 **手工入库** 入口 |

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

| 项 | 定稿 |
|----|------|
| 商品归属 | **仅当前店铺** 下 **未逻辑删除** 的商品/规格可被选入入库明细 |
| 发品/编辑库存字段 | 商品表单中的 **库存** 为 **可用库存**；**新增规格** 时填写 **初始库存**；**保存商品时直接写入** 该值 |
| 新增规格自动入库 | 保存商品时 **新增规格** 且 **该规格初始库存 > 0** → **自动** 生成 **一张** 入库单（**多规格多行明细**，§5.4）；类型记 **新增商品规格**；**仅留痕，不再加库存** |
| 修改已有规格库存 | **直接改数字** 属于 **库存调整（库存编辑）**，**不** 走本模块 **手工入库** |
| 商品状态 | **未上架 / 待审核 / 出售中 / 已下架** 均可 **入库**（只要商品/规格 **存在** 且 **未删除**） |
| 条码 | 发品可填 **商品条码**；本模块 **支持条码录入** 快速添加明细行 |

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

| 项 | 定稿 |
|----|------|
| 退货退款 | 售后 **不自动** 回滚库存（§8.3） |
| 商家作业 | 收到退货并验收后，在本模块 **手工创建「退货入库」** |
| 关联单据 | **本期** 入库单 **不强制** 关联售后单号；备注中 **可说明** 来源 |

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

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

### 2.6 与库存管理兄弟模块（草稿口径对齐）

| 模块 | 与本模块关系 |
|------|--------------|
| **商品出库** | 出库单 / 支付扣减 **减库存**；与入库单 **独立编号** |
| **库存调整** | **库存编辑** 不产生 **采购/退货/其他** 入库单；日志原因 **库存编辑** |
| **库存查询** | 读 **实时库存**；「查看出入库明细」**聚合** 入/出库记录 |
| **库存日志** | **全量** 变化流水；本模块写入 **入库** 类及原因（§3.2） |

---

## 3. 入库类型与库存变化

### 3.1 入库单类型（手工）

| 类型 | 适用场景 | 默认 |
|------|----------|------|
| **采购入库** | 向供应商采购到货、补货入库 | **是**（新建表单默认选中） |
| **退货入库** | 买家退货验收后 **手工** 将商品加回库存 | 否 |
| **其他入库** | 盘盈、赠品入库等 **无法归类** 于上述场景 | 否 |

> **说明：** 草稿明确 **买家退货返库存须手工录入**；**不** 与售后单 **自动联动**。

### 3.2 变化原因（库存日志口径）

本模块及相关协作写入 **库存日志** 时，**入库类** 原因包括：

| 变化原因 | 来源 | 是否入库单 | 是否改库存 |
|----------|------|------------|------------|
| **新增商品规格** | **商品列表** 保存时 **自动** | **是**（系统自动单） | **否**（库存由 **商品保存** 写入；入库单 **仅留痕**） |
| **采购入库** | 本模块 **手工** | **是** | **是** |
| **退货入库** | 本模块 **手工** | **是** | **是** |
| **其他入库** | 本模块 **手工** | **是** | **是** |
| **库存编辑** | **库存调整** 模块 | **否**（调整明细） | **是** |

### 3.3 库存变化规则

| 规则 | 说明 |
|------|------|
| **方向** | **手工入库** **仅增加** 对应 **商品规格** 的 **可用库存**；**自动入库（新增商品规格）** **不改库存**（§5.4） |
| **数量** | 明细行入库数量须为 **正整数** |
| **原子性** | 一张入库单 **要么全部成功，要么全部失败**；**不允许** 部分成功 |
| **幂等** | 同一入库单 **不可重复提交** |
| **不可撤销** | 确认后 **不可编辑、删除、反审**；纠错须走 **库存调整** 或 **其他出库** 等 **另模块** |

---

## 4. 入库单号

| 项 | 定稿 |
|----|------|
| 生成时机 | 入库单 **确认提交** 时（含 **系统自动入库**） |
| 唯一性 | **全平台唯一** |
| 展示 | 列表、详情 **均展示**；支持按单号 **检索** |
| 格式 | **系统生成**；具体编码规则 **不在本文档定义** |

---

## 5. 自动入库（新增商品规格）

### 5.1 触发条件

同时满足时 **自动** 生成入库单：

1. 操作发生在 **商品列表** **添加商品** 或 **编辑商品** **保存成功**；
2. 相对上次保存 **新增** 至少一条 **商品规格**（统一规格视为 **一条**）；
3. 至少一个 **新增规格** 的 **初始库存 > 0**。

**单据规则：** 同一次保存中，所有满足条件的 **新增规格** 合并为 **一张入库单、多行明细**（§5.2）。

### 5.2 业务规则

| 项 | 定稿 |
|----|------|
| 入库类型/原因 | 记 **新增商品规格** |
| 单据粒度 | **一次商品保存** 仅生成 **一张** 入库单；其下 **多行明细**，**一行** 对应 **一个新增规格** |
| 明细数量 | 每行入库数量 = 该规格填写的 **初始库存** |
| 经办人 | **当前保存商品的操作人** |
| 备注 | **可为空**；系统 **可不填** |
| 列表可见 | **在本模块列表展示**；与手工入库单 **同一列表** |
| 初始库存 = 0 | **不纳入** 该次入库单明细；若本次 **无任何** 新增且库存>0 的规格，**不生成** 入库单 |
| 仅修改名称/价格等 | **不触发** |
| 编辑已有规格 **改大库存** | **不触发** 本规则 → 应走 **库存调整** |

### 5.3 流程

```text
商品列表 → 添加/编辑 → 填写规格明细（含初始库存）
    → 保存成功
        → 商品模块：将各规格 **初始库存写入可用库存**（唯一写入口）
        → 若存在「新增且库存>0」的规格：
              生成 **一张** 入库单（类型：新增商品规格）
              每个此类规格占 **一行明细**（数量 = 初始库存）
              写入库存日志（留痕；**不再对库存做 +=**）
    → 本模块列表可查询该自动单
```

### 5.4 库存写入口径（v1.0.1 定稿）

| 场景 | 谁写入可用库存 | 入库单作用 |
|------|----------------|------------|
| **新增商品规格**（自动入库） | **商品列表保存** 时 **直接写入** 表单中的初始库存 | **仅留痕**：记录类型、数量、经办人、时间；**提交后不再增加库存** |
| **手工入库**（采购/退货/其他） | **本模块确认提交** 时 **增加** 可用库存 | **留痕 + 改库存** |

**说明：**

- 自动入库单在 **库存日志** 中仍展示 **变化前/后库存、变化量**，数值须与 **商品保存前后** 的实际库存 **一致**，但 **加库存动作只发生一次**（在商品保存）。
- **禁止** 商品保存与自动入库单 **各加一遍** 导致 **重复加库存**。

---

## 6. 入库单列表

### 6.1 列表字段

| 列名 | 说明 |
|------|------|
| **入库单号** | 系统生成的唯一单号 |
| **入库类型** | 新增商品规格 / 采购入库 / 退货入库 / 其他入库 |
| **入库时间** | 确认提交时间；格式 **yyyy-MM-dd HH:mm:ss** |
| **备注** | 手工入库时填写；无则展示 **—** |
| **经办人** | 提交操作人 **登录名** 或 **姓名**（与账号管理展示一致） |
| **操作** | **详情** |

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

### 6.2 高级检索

| 条件 | 类型 | 说明 |
|------|------|------|
| **入库搜索** | 关键词 | 匹配 **入库单号** 或 **明细中的商品名称**（模糊） |
| **入库时间** | 日期区间 | **开始日期**～**结束日期**（含边界，按 **入库时间** 过滤） |
| **入库类型** | 下拉 | 全部 / 新增商品规格 / 采购入库 / 退货入库 / 其他入库 |
| **经办人** | 下拉 | 全部 / 当前店铺下有入库记录的操作人列表 |

**操作按钮：** **搜索**、**重置**。

### 6.3 列表操作

| 操作 | 说明 |
|------|------|
| **商品入库** | 打开 **手工入库** 表单（§7） |
| **详情** | 进入 **入库单详情**（§8） |

---

## 7. 手工创建入库单

### 7.1 入口与表单结构

**入口：** 列表页 **「商品入库」** 按钮 → 弹窗或独立页（与 UI 稿一致）。

**区块一：基本信息**

| 字段 | 必填 | 说明 |
|------|------|------|
| **入库类型** | 是 | 单选：**采购入库**（默认）/ **退货入库** / **其他入库** |
| **备注** | 否 | 多行文本；**最多 200 字**；占位「请输入备注」 |

**区块二：入库商品**

| 能力 | 说明 |
|------|------|
| **选择商品** | 打开 **商品选择器**；仅 **当前店铺**、**未删除** 商品及其 **规格** |
| **导入商品** | 按 **模板文件** 批量导入明细（**规格、数量** 等）；失败行 **整批提示** 或 **跳过失败行** 由实现定，**须** 在导入结果中 **明确失败原因** |
| **条码录入** | 输入框「请输入商品条码」+ **确定**（支持 **Enter**）；按条码 **匹配** 商品/规格并 **追加** 至明细 |
| **明细表格** | 已选商品列表；**至少一行** 方可提交 |

**明细行建议字段（定稿）：**

| 字段 | 说明 |
|------|------|
| 商品信息 | **主图缩略图** + **商品名称** |
| **商品规格** | 规格文案；单规格无规格名时展示 **—** |
| **当前可用库存** | 只读，便于核对 |
| **入库数量** | 必填；**正整数** |
| **操作** | **删除** 该行 |

> **成本：** 《库存查询-草稿》含 **成本** 列；**本期入库表单不要求录入成本**；若后续成本模块建设，**另版** 需求补充。

### 7.2 商品选择器规则

| 规则 | 说明 |
|------|------|
| 店铺范围 | **仅当前店铺** |
| 商品范围 | **未逻辑删除** 的商品 |
| 规格 | **多规格** 须 **选到规格粒度**；**统一规格** 选商品即可 |
| 重复 | **同一规格** 在一张单内 **不可重复** 多行；再次选择 **合并数量** 或 **提示已存在**（二选一，**须前后一致**） |
| 状态 | **任意商品状态** 均可选（见 §2.3） |

### 7.3 条码录入规则

| 规则 | 说明 |
|------|------|
| 匹配 | 在当前店铺商品中按 **条码** 精确匹配 |
| 未匹配 | 提示 **未找到对应商品**；**不** 静默失败 |
| 匹配多个 | 若条码 **不唯一**，须 **弹出规格选择** 或 **提示** 用户改用手选 |

### 7.4 提交与取消

| 操作 | 说明 |
|------|------|
| **确认** | 校验通过后：生成 **入库单号**、**增加库存**、写入 **库存日志**、关闭表单并 **刷新列表** |
| **取消** | 放弃本次编辑；**不** 产生入库单 |

### 7.5 校验规则

| 编号 | 规则 |
|------|------|
| **IN1** | 入库类型 **必选** |
| **IN2** | 明细 **至少一行** |
| **IN3** | 每行入库数量 **≥ 1** 的 **整数** |
| **IN4** | 备注 **≤ 200** 字 |
| **IN5** | 明细商品/规格须 **属于当前店铺** 且 **未删除** |
| **IN6** | 提交时若规格 **已被删除**，**整单失败** 并提示 |

### 7.6 手工入库流程

```text
列表 → 商品入库
    → 选择入库类型、填写备注（可选）
    → 添加入库商品（选择 / 导入 / 条码）
    → 填写各行入库数量
    → 确认
        → 校验 IN1～IN6
        → 生成入库单号；库存 += 数量；写日志
    → 返回列表
```

---

## 8. 入库单详情

### 8.1 基本信息

| 字段 | 说明 |
|------|------|
| 入库单号 | 同列表 |
| 入库类型 | 同列表 |
| 入库时间 | 同列表 |
| 备注 | 同列表 |
| 经办人 | 同列表 |

### 8.2 入库明细

| 列 | 说明 |
|----|------|
| 商品信息 | 主图 + 名称 |
| 商品规格 | 规格文案 |
| 入库数量 | 本行 **增加** 的数量 |

**操作：** **仅查看**；**无** 编辑、删除、打印 **本期要求**（打印 **非本期**）。

---

## 9. 与库存查询 / 库存日志的协作

### 9.1 库存查询

| 项 | 定稿 |
|----|------|
| 实时库存 | **手工入库** 确认后 **可用库存** 增加；**自动入库** 的库存变化 **已在商品保存时完成** |
| 出入库明细 | 库存查询行操作 **查看出入库明细** 时，**须包含** 本模块产生的 **入库** 记录（类型、数量、时间） |

### 9.2 库存日志

| 项 | 定稿 |
|----|------|
| 记录类型 | **入库** |
| 展示字段 | 商品名称、规格、变化前库存、变化后库存、变化量、**变化原因**、操作时间 |
| 变化原因 | 与 §3.2 一致 |
| 检索 | 日志模块 **关键词** 可搜到本模块涉及的商品 |

---

## 10. 权限与菜单

| 项 | 定稿 |
|----|------|
| 菜单路径 | **库存管理 → 商品入库**（与 UI 一致） |
| 权限粒度 | **菜单可见**、**商品入库（创建）**、**详情查看** 可由 **角色管理** 分配 |
| 数据权限 | **仅当前店铺**；**无** 跨店入库 |

---

## 11. 异常与提示（功能口径）

| 场景 | 期望提示（示例） |
|------|------------------|
| 未选商品提交 | 请添加入库商品 |
| 数量为空或 ≤0 | 请输入正确的入库数量 |
| 备注超长 | 备注不能超过 200 字 |
| 商品不存在/已删除 | 商品已不存在，请移除后重试 |
| 条码未匹配 | 未找到该条码对应的商品 |
| 非当前店铺 | 无权操作其他店铺库存 |
| 提交成功 | 入库成功（或等价文案） |

---

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

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

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

---

## 13. 非本期与待建设

| 项 | 说明 |
|----|------|
| 入库单 **编辑 / 作废 / 反审** | 确认后 **不可改** |
| 关联 **采购单 / 售后单 / 订单号** | **不强制** 关联 |
| 入库录入 **成本 / 批次 / 效期** | **非本期** |
| **退货入库** 自动关联物流验收 | **非本期** |
| 入库单 **打印 / 导出** | **非本期** |
| 平台端 **代入库** | **不做** |

---

## 14. 业务规则汇总

| 编号 | 规则 |
|------|------|
| **IN-A1** | **手工入库** **只增不减** 可用库存；**自动入库单仅留痕** |
| **IN-A2** | 一张入库单 **全成或全败** |
| **IN-A3** | 入库单 **确认后不可修改** |
| **IN-A4** | 数据范围 **仅当前店铺** |
| **IN-A5** | **新增规格** 且 **初始库存>0** → **一张** 自动入库单（**多行明细**）；**库存由商品保存写入**，入库单 **仅留痕** |
| **IN-A6** | **退货** 须 **手工退货入库**；**不** 随售后 **自动** |
| **IN-A7** | **改库存数字**（非新增规格）→ **库存调整**，**非** 本模块 |
| **IN-A8** | 支付扣减、手工出库 → **商品出库** 等 **他模块** |
| **IN-A9** | 入库记录 **同步** 至 **库存日志**；**库存查询** 可 **反查明细** |

---

## 15. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：对齐草稿 §1～§4；补全列表/检索/手工入库/自动入库/详情/兄弟模块与平台订单·商品·售后边界；《商品入库功能需求-草稿》**保持不变** |
| **v1.0.1** | §5.4：**商品保存写库存、自动入库单仅留痕**；**一次保存一张入库单、多规格多行明细** |

---

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