# 库存调整 — 技术方案

> **依据：** 《库存调整功能需求.md》v1.0  
> **关联：** 《关联需求分析.md》v1.6；商家《商品入库技术方案》v1.0、《商品出库技术方案》v1.0、《库存日志技术方案》v1.0、《库存查询技术方案》v1.0、《商家端店铺上下文接口说明》  
> **范围：** 商家端 **库存管理 · 库存调整** — 商品列表检索、**单规格库存调整**（增量/覆盖）、**按规格查看调整明细**；**不产生** 入/出库单。  
> **原则：** `X-Shop-Id` 店铺隔离；写 **`biz_goods.stock`** + **`biz_stock_adjust`** + **`biz_stock_log`**（`STOCK_EDIT`）。

---

## 1. 技术架构

| 项 | 选型 |
|----|------|
| 基础框架 | RuoYi **v3.9.2**（`springboot2` 分支） |
| 数据库 | **MySQL 5.7.39**；新建 **`biz_stock_adjust`**；复用 **`biz_stock_log`** |
| 列表数据源 | **`biz_goods`**（与库存查询 **同 SQL**） |
| 明细数据源 | **`biz_stock_adjust`** |
| 流水 | `IStockLogService.insertLog`；`ref_type=ADJUST` |

### 1.1 与兄弟模块边界

| 维度 | 本模块 | 协作 |
|------|--------|------|
| 路径 | **`/agri/seller/stock/adjust`** | 查询 `/query`、日志 `/log` |
| 改库存 | **POST `/{goodsId}`** | 入/出库/订单 **不经** 本模块 |
| 单据 | **无** 入/出库单 | 仅 **调整明细表** |
| 日志 | `change_reason=STOCK_EDIT` | 库存日志/查询明细 **可读** |

### 1.2 数据流

```text
GET /list
    → BizGoodsMapper.selectStockQueryList（复用）
    → StockSupport.buildSpecText 富化规格

POST /{goodsId}
    → selectByIdAndShopForUpdate
    → 计算 stockBefore/stockAfter、adjustType
    → setStockForAdjust
    → insert biz_stock_adjust
    → insertLog（STOCK_EDIT）

GET /{goodsId}/records
    → BizStockAdjustMapper.selectByGoodsId
    → enrich adjustTypeText
```

### 1.3 模块落位

```text
stock/
├── controller/SellerStockAdjustController.java
├── service/IStockAdjustService.java
├── service/impl/StockAdjustServiceImpl.java
├── domain/BizStockAdjust.java
├── mapper/BizStockAdjustMapper.java
├── dto/StockAdjustQuery.java
├── dto/StockAdjustCreateDTO.java
├── dto/StockAdjustRecordQuery.java
├── vo/StockAdjustListRowVO.java
├── vo/StockAdjustRecordRowVO.java
goods/mapper/BizGoodsMapper.java          # +setStockForAdjust
resources/mapper/stock/BizStockAdjustMapper.xml

sql/biz_stock_adjust.sql
sql/biz_stock_adjust_menu.sql             # 6540
```

---

## 2. 数据库设计

### 2.1 调整明细表 `biz_stock_adjust`

| 字段 | 类型 | 说明 |
|------|------|------|
| adjust_id | bigint PK | 明细 ID |
| shop_id | bigint | 店铺 |
| goods_id | bigint | 商品/规格 |
| goods_name | varchar(200) | 名称快照 |
| spec_text | varchar(256) | 规格文案（`—`） |
| adjust_mode | char(1) | `1` 增量 / `2` 覆盖 |
| adjust_type | char(1) | `1` 增加 / `2` 减少 / `3` 覆盖 |
| adjust_qty | int | 表单填写数量（增量可为负） |
| stock_before | int | 调整前 |
| stock_after | int | 调整后 |
| operator_id | bigint | 操作人 |
| operator_name | varchar(64) | 操作账号快照 |
| create_time | datetime | 创建时间 |

**索引：** `idx_shop_goods_time (shop_id, goods_id, create_time)`。

### 2.2 库存日志关联

| 字段 | 值 |
|------|-----|
| change_reason | `STOCK_EDIT` |
| ref_type | `ADJUST` |
| ref_id | adjust_id |
| direction | 净增 `1` / 净减 `2` / 不变 `1`（变化量 0） |
| change_qty | `abs(stock_after - stock_before)` |

---

## 3. 接口设计

**基路径：** `/agri/seller/stock/adjust`

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/list` | `agri:seller:stock:adjust:list` | 可调整商品列表 |
| POST | `/{goodsId}` | `agri:seller:stock:adjust:edit` | 确认调整 |
| GET | `/{goodsId}/records` | `agri:seller:stock:adjust:list` | 调整记录 |

### 3.1 列表 Query（StockAdjustQuery）

| 参数 | 说明 |
|------|------|
| pageNum, pageSize | 分页 |
| keyword | 商品名称或规格模糊（同库存查询） |

### 3.2 调整 Body（StockAdjustCreateDTO）

| 字段 | 说明 |
|------|------|
| adjustMode | `1` 增量 / `2` 覆盖 |
| adjustQty | 增量：非零整数，可负；覆盖：≥0 整数 |

### 3.3 记录 Query（StockAdjustRecordQuery）

| 参数 | 说明 |
|------|------|
| adjustType | 空=全部；`1` 增加 / `2` 减少 / `3` 覆盖 |

### 3.4 响应

**POST 成功 data：**

| 字段 | 说明 |
|------|------|
| adjustId | 明细 ID |
| stockBefore / stockAfter | 前后库存 |
| adjustType / adjustTypeText | 明细类型 |

---

## 4. 业务规则（实现）

| 编号 | 规则 |
|------|------|
| ADJ1 | `selectByIdAndShopForUpdate` + 事务 |
| ADJ2 | 增量：`stockAfter = before + qty`，qty≠0 |
| ADJ3 | 覆盖：`stockAfter = qty`，qty≥0 |
| ADJ4 | `stockAfter >= 0`，否则 `ServiceException` |
| ADJ5 | `setStockForAdjust(goodsId, shopId, stockAfter)` |
| ADJ6 | 日志与明细 **同一事务** |

---

## 5. 权限与菜单

| 权限 | 说明 |
|------|------|
| `agri:seller:stock:adjust:list` | 列表 + 记录 |
| `agri:seller:stock:adjust:edit` | 确认调整 |

菜单：**库存管理 → 库存调整**（`parent_id=6500`，`menu_id=6540`，`path=adjust`）。  
脚本：`sql/biz_stock_adjust_menu.sql`。

---

## 6. 实现清单

| # | 项 | 状态 |
|---|-----|------|
| 1 | DDL `sql/biz_stock_adjust.sql` | 待执行 |
| 2 | Domain / Mapper / XML | 待建 |
| 3 | `StockConstants` / `StockSupport` 扩展 | 待建 |
| 4 | `StockAdjustServiceImpl` | 待建 |
| 5 | `SellerStockAdjustController` | 待建 |
| 6 | `BizGoodsMapper.setStockForAdjust` | 待建 |
| 7 | 菜单 SQL + 单元测试 | 待建 |

---

## 7. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：对齐需求 v1.0；增量/覆盖、调整明细、库存日志协作 |

---

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