# 库存调整 — 前端技术方案

> **依据：** 《库存调整功能需求.md》v1.0、《库存调整技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端** 当前店铺商品列表、关键词检索、**单规格库存调整**（增量/覆盖）、**调整记录**（只读）；**不含** 入/出库单、批量调整、平台端。  
> **实现状态：** `index.vue`、`api/agri/seller/stock/adjust.js` **已按 v1.0 落地**；待菜单配置及 `/agri/seller/stock/adjust` 联调。

---

## 1. 技术栈与写法约定

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` + `sellerShopHeaders()` 携带 **`X-Shop-Id`** |
| 参考页面 | `agri/seller/stock/query/index.vue`（列表检索）、弹窗交互 |
| 布局 | 检索 `el-card` + `<br/>` + 列表 `el-card` + `border` 表格 |
| 调整/记录 | `el-dialog`（`append-to-body`） |
| 图片 | 全局 `image-preview` |
| 店铺切换 | **仅 Navbar**；业务页禁止展示店铺选择器 |

---

## 2. 业务要点（前端需体现）

| 项 | 说明 |
|----|------|
| 写库存入口 | **库存编辑** 场景唯一入口；**不产生** 入/出库单 |
| 列表 | **未删除** 商品/规格；**不展示** 可用库存列（UI 稿） |
| 调整方式 | `1` 增量（默认）/ `2` 覆盖 |
| 调整数量 | 增量：**非零整数、可负**；覆盖：**≥0 整数** |
| 明细类型 | 后端判定：增加(1)/减少(2)/覆盖(3)，记录在「记录」弹窗 |
| 不可撤销 | 确认后不可改；再次纠错须 **新一次调整** |
| 与商品列表 | **已有规格改库存** 须走本模块（商品编辑页库存已 disabled） |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/seller/stock/adjust/index.vue` | 商品列表 + 调整弹窗 + 记录弹窗 |
| 调整 API | `ruoyi-ui/src/api/agri/seller/stock/adjust.js` | list、confirm、records |
| 店铺上下文 | `api/agri/seller/context.js` + `utils/sellerShop.js` | X-Shop-Id |

**组件 name（keep-alive）：** `AgriSellerStockAdjust`

**不提供：** 批量调整、调整单号列表、备注字段、导入、撤销、列表内改库存。

---

## 4. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 库存调整 | `agri/seller/stock/adjust/index` | `seller/stock/adjust` | `agri:seller:stock:adjust:list` |

**上级菜单：** 店铺经营管理端 → **库存管理**

| 按钮权限 | 标识 | 页面落点 |
|----------|------|----------|
| 列表 + 记录 | `agri:seller:stock:adjust:list` | 进入页面、「记录」 |
| 确认调整 | `agri:seller:stock:adjust:edit` | 「调整」、POST 提交 |

---

## 5. 页面结构（与代码一致）

```text
库存调整 index.vue
├── 检索区 search-card
│   ├── 库存搜索 keyword（商品名称/规格模糊）
│   └── 重置
├── 列表区 table-card
│   ├── right-toolbar
│   ├── el-table border
│   │   ├── 商品名称（主图 + 名称）
│   │   ├── 商品规格
│   │   └── 操作：调整 | 记录
│   └── pagination
├── 库存调整弹窗 el-dialog width=560px
│   ├── 商品摘要（主图 + 名称 + 规格）
│   ├── 调整方式 adjustMode（增量/覆盖 + 说明文案）
│   ├── 调整数量 adjustQty（默认 1；覆盖 min=0）
│   └── 取消 / 确认
└── 记录弹窗 el-dialog width=760px
    ├── 调整类型筛选 adjustType（全部/增加/减少/覆盖）
    └── el-table：类型、调整前、调整后、操作账号、创建时间
```

---

## 6. 库存调整弹窗

### 6.1 提交 payload

```json
{
  "adjustMode": "1",
  "adjustQty": 5
}
```

| adjustMode | 含义 | adjustQty 规则 |
|------------|------|----------------|
| `1` | 增量更新 | 非零整数，可为负 |
| `2` | 覆盖更新 | ≥0 整数 |

### 6.2 前端校验

| 规则 | 说明 |
|------|------|
| ADJ1 | 调整方式必选 |
| ADJ2 | 调整数量必填 |
| ADJ3 | 增量时 qty ≠ 0 |
| ADJ4 | 覆盖时 qty ≥ 0 |
| 切换覆盖 | 若当前 qty 为负，自动置 0 |

后端另校验 **调整后库存 ≥ 0**（ADJ5）。

成功：`msgSuccess('调整成功')` → 关闭弹窗。

---

## 7. 调整记录弹窗

**接口：** `GET /{goodsId}/records?adjustType=`

| adjustType | 筛选 |
|------------|------|
| 空 | 全部 |
| `1` | 增加库存 |
| `2` | 减少库存 |
| `3` | 覆盖库存 |

**空态：** 「暂无数据」/ 有筛选无结果时友好提示。

**只读：** 无编辑、删除。

---

## 8. 店铺上下文（X-Shop-Id）

| 步骤 | 说明 |
|------|------|
| `created` | `GET /agri/seller/context` → `setSellerShopContext` |
| 全部 API | `sellerShopHeaders()` |
| Navbar 切店 | `location.reload()` 整页刷新 |

---

## 9. API 封装

**模块：** `@/api/agri/seller/stock/adjust.js`

| 方法 | HTTP | 路径 | 权限 |
|------|------|------|------|
| `listSellerStockAdjust` | GET | `/list` | list |
| `confirmSellerStockAdjust` | POST | `/{goodsId}` | edit |
| `listSellerStockAdjustRecords` | GET | `/{goodsId}/records` | list |

---

## 10. 空状态与错误提示

| 场景 | 文案 |
|------|------|
| 列表无数据 | 「暂无可调整商品」 |
| 检索无结果 | 「未找到符合条件的商品」 |
| 记录无数据 | 「暂无数据」 |
| qty 为空 | 「请输入调整数量」 |
| 增量 qty=0 | 「调整数量不能为 0」 |
| 覆盖 qty 为负 | 「请输入正确的库存数量」 |
| 提交成功 | 「调整成功」 |
| 后端负库存 | 「调整后库存不能小于 0」等 |

---

## 11. 与兄弟模块边界（前端）

| 模块 | 关系 |
|------|------|
| **商品列表** | 编辑页库存 disabled；改数走本模块 |
| **商品入库/出库** | 业务入出库 **不走** 本模块 |
| **库存查询** | 调整后可用库存即时更新；查询页 **无** 调整按钮 |
| **库存日志** | 每次确认写入「库存编辑」流水 |

---

## 12. 联调检查清单

- [ ] 菜单挂载 `agri/seller/stock/adjust/index`
- [ ] 列表仅当前店铺未删除商品
- [ ] 增量 +N / −N、覆盖 M 三种场景
- [ ] 增量调减导致负库存时后端拒绝
- [ ] 记录弹窗类型筛选与明细字段正确
- [ ] 权限：无 `edit` 不显示「调整」
- [ ] Navbar 切店后列表刷新

---

## 13. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：列表/检索/调整弹窗/记录弹窗/API 封装；对齐需求 v1.0 与 UI 稿 |

---

*文档版本：v1.0 · 依据《库存调整功能需求.md》v1.0、《库存调整技术方案.md》v1.0*
