# 库存查询 — 前端技术方案

> **依据：** 《库存查询功能需求.md》v1.0、《库存查询技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端** 当前店铺 **实时可用库存** 列表、关键词检索、**按商品查看出入库明细**（只读）；**不含** 改库存、创建入/出库单、成本维护、平台端。  
> **实现状态：** `index.vue`、`api/agri/seller/stock/query.js` **已按 v1.0 落地**；待菜单配置及 `/agri/seller/stock/query` 联调。

---

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

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

---

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

| 项 | 说明 |
|----|------|
| 只读 | **无** 编辑库存、创建入/出库/调整单 |
| 列表数据 | **未删除** 商品/规格的 **当前可用库存**（`biz_goods.stock`） |
| 库存为 0 | **仍展示**；可用库存列可标红提示 |
| 成本 | 后端 `cost` 为 null 时展示 **—**（本期无成本数据源） |
| 明细同源 | `GET /{goodsId}/logs` 与 **库存日志** 同一套 `biz_stock_log` |
| 明细数量 | **带符号**：入库 **+qty**、出库 **−qty**、0 仍为 0 |
| 明细类型 | 展示 `ioTypeText`（变化原因文案），**不用** 笼统「入库增加库存」 |

---

## 3. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/seller/stock/query/index.vue` | 库存列表 + 出入库明细弹窗 |
| 查询 API | `ruoyi-ui/src/api/agri/seller/stock/query.js` | list、logs |
| 店铺上下文 | `api/agri/seller/context.js` + `utils/sellerShop.js` | X-Shop-Id |

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

**不提供：** 独立明细页、分页明细（后端一次返回全量）、导出、跳转商品编辑。

---

## 4. 菜单与路由

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

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

| 按钮权限 | 标识 | 页面落点 |
|----------|------|----------|
| 列表 + 明细 | `agri:seller:stock:query:list` | 进入页面、「出入库明细」 |

---

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

```text
库存查询 index.vue
├── 检索区 search-card
│   ├── 库存搜索 keyword（商品名称/规格模糊，Enter 或搜索图标）
│   └── 重置
├── 列表区 table-card
│   ├── right-toolbar
│   ├── el-table border（empty-text 动态）
│   │   ├── 商品信息（主图 + 名称）
│   │   ├── 商品规格 specText（空则 —）
│   │   ├── 可用库存 stock（0 可标红）
│   │   ├── 成本 cost（null → —）
│   │   └── 操作：出入库明细
│   └── pagination
└── 出入库明细弹窗 el-dialog
    ├── 商品摘要（主图 + 名称 + 规格 + 当前库存）
    └── el-table border
        ├── 商品名称
        ├── 出入库类型 ioTypeText
        ├── 商品规格
        ├── 出入库数量 ioQty（+绿 / −红）
        └── 出入库时间 ioTime
```

---

## 6. 出入库明细交互

```text
列表行 → 出入库明细
    → 记录 currentRow（展示摘要）
    → GET /{goodsId}/logs
    → 表格展示（时间倒序由后端保证）
    → 关闭弹窗清空状态
```

| 场景 | 文案 |
|------|------|
| 列表无数据 | 「暂无库存数据」 |
| 检索无结果 | 「未找到符合条件的库存记录」 |
| 明细无流水 | 「暂无出入库记录」 |

---

## 7. 数量展示规则

| ioQty | 展示 | 样式 |
|-------|------|------|
| > 0 | `+N` | 绿色 `.qty-in` |
| < 0 | `N`（自带负号） | 红色 `.qty-out` |
| 0 | `0` | 默认色 |

与 **库存日志** 模块差异：日志列表为 **非负变化量**；本模块明细为 **带符号出入库数量**（需求 §6.3）。

---

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

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

---

## 9. API 封装

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

| 方法 | HTTP | 路径 | 权限 |
|------|------|------|------|
| `listSellerStockQuery` | GET | `/list` | query:list |
| `listSellerStockQueryLogs` | GET | `/{goodsId}/logs` | query:list |

**列表 Query：** `pageNum`、`pageSize`、`keyword`。

**列表 Row：** `goodsId`、`goodsName`、`mainPic`、`specText`、`stock`、`cost`。

**明细 Row：** `goodsName`、`specText`、`ioTypeText`、`ioQty`、`ioTime`。

---

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

| 模块 | 关系 |
|------|------|
| **商品入库 / 出库** | 改库存后列表 `stock` 即时变化；明细含对应流水 |
| **库存调整** | 调整后明细含「库存编辑」 |
| **库存日志** | 全店时间序；本模块为 **单商品** 过滤同源数据 |
| **商品列表** | 库存字段与列表 **同一口径**；本页不提供编辑入口 |

---

## 11. 联调检查清单

- [ ] 菜单挂载 `agri/seller/stock/query/index`
- [ ] 列表展示当前店铺未删除商品，含 stock=0 行
- [ ] 关键词匹配商品名称、规格
- [ ] 成本列无数据时为 —
- [ ] 出入库明细：类型文案与库存日志一致
- [ ] 明细数量正负号与方向正确
- [ ] 支付扣减、手工入出库、删规格留痕等流水可见
- [ ] Navbar 切店后列表刷新

---

## 12. 版本记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版：实时库存列表、关键词检索、出入库明细弹窗、API 封装；对齐需求 v1.0 与 UI 稿 |

---

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