# 库存查询 — 技术方案

> **依据：** 《库存查询功能需求.md》v1.0  
> **关联：** 《关联需求分析.md》v1.6；商家《商品入库技术方案》v1.0、《商品出库技术方案》v1.0、《库存日志技术方案》v1.0、《库存调整功能需求-草稿》、《商家端店铺上下文接口说明》  
> **范围：** 商家端 **库存管理 · 库存查询** — **只读** 实时库存分页列表、**关键词** 检索、**按商品查看出入库明细**；**不含** 改库存、成本维护。  
> **原则：** `X-Shop-Id` 店铺隔离；列表读 **`biz_goods.stock`**；明细复用 **`IStockLogService.selectByGoodsId`**；明细数量 **带符号**。

---

## 1. 技术架构

| 项 | 选型 |
|----|------|
| 基础框架 | RuoYi **v3.9.2**（`springboot2` 分支） |
| 数据库 | **MySQL 5.7.39**；**无新建表** |
| 列表数据源 | **`biz_goods`**（`del_flag='0'`） |
| 明细数据源 | **`biz_stock_log`**（经 `IStockLogService`） |
| 规格文案 | `StockSupport.buildSpecText(goodsId)` 列表富化 |
| 成本 | **无字段**；VO 返回 `null`，前端展示 **—** |

### 1.1 与兄弟模块边界

| 维度 | 本模块 | 协作 |
|------|--------|------|
| 路径 | **`/agri/seller/stock/query`** | 日志 `/log`、入库 `/inbound`、出库 `/outbound` |
| 改库存 | **无** | 入库/出库/调整/订单 |
| 明细 | **GET `/{goodsId}/logs`** | 与 **库存日志** **同源** |

### 1.2 数据流

```text
GET /list
    → BizGoodsMapper.selectStockQueryList
    → StockSupport.buildSpecText 富化规格
    → StockQueryListRowVO（stock=可用库存，cost=null）

GET /{goodsId}/logs
    → 校验商品归属店铺
    → IStockLogService.selectByGoodsId
    → 转换为 StockQueryLogRowVO（ioQty 带符号）
```

### 1.3 模块落位

```text
stock/
├── controller/SellerStockQueryController.java
├── service/IStockQueryService.java
├── service/impl/StockQueryServiceImpl.java
├── dto/StockQueryQuery.java
├── vo/StockQueryListRowVO.java
├── vo/StockQueryLogRowVO.java
goods/mapper/BizGoodsMapper.java          # +selectStockQueryList
resources/mapper/goods/BizGoodsMapper.xml

sql/biz_stock_query_menu.sql              # 6530
```

---

## 2. 接口设计

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

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/list` | `agri:seller:stock:query:list` | 实时库存列表 |
| GET | `/{goodsId}/logs` | `agri:seller:stock:query:list` | 出入库明细 |

### 2.1 列表 Query

| 参数 | 说明 |
|------|------|
| pageNum, pageSize | 分页 |
| keyword | 商品名称 **或** 规格值（`biz_goods_attr.attr_type=2`）模糊 |

**排序：** `update_time DESC, goods_id DESC`

### 2.2 列表 Row（StockQueryListRowVO）

| 字段 | 来源 |
|------|------|
| goodsId | biz_goods |
| goodsName, mainPic, stock | biz_goods |
| specText | StockSupport |
| cost | **null**（预留） |

### 2.3 明细 Row（StockQueryLogRowVO）

| 字段 | 说明 |
|------|------|
| goodsName, specText | 流水快照 |
| ioTypeText | `changeReasonText` |
| ioQty | 入库 **+qty**；出库 **−qty**（0 仍为 0） |
| ioTime | create_time |

---

## 3. Mapper SQL 要点

**selectStockQueryList：**

```sql
SELECT goods_id, goods_name, main_pic, stock
FROM biz_goods g
WHERE shop_id = #{shopId} AND del_flag = '0'
  AND (keyword 空 OR goods_name LIKE …
       OR EXISTS (SELECT 1 FROM biz_goods_attr a
                  WHERE a.goods_id = g.goods_id AND a.attr_type = '2'
                    AND a.value_text LIKE …))
ORDER BY update_time DESC, goods_id DESC
```

---

## 4. 权限与菜单

| 权限 | 说明 |
|------|------|
| `agri:seller:stock:query:list` | 列表 + 明细 |

菜单：**库存管理 → 库存查询**（`6530`，`path=query`）。

---

## 5. 实现清单

| # | 项 | 状态 |
|---|-----|------|
| 1 | DTO/VO + Service + Controller | 待建 |
| 2 | BizGoodsMapper.selectStockQueryList | 待建 |
| 3 | sql/biz_stock_query_menu.sql | 待建 |
| 4 | 单元测试 | 待建 |

---

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