# ERP 后端接口文档参考

> 来源：`http://localhost:8081/erp/v3/api-docs`（Swagger OpenAPI 3.0）
> 更新日期：2026-05-27

## 基础路径

```
http://localhost:8081/erp
```

## 通用响应结构

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

## 关键 DTO 字段

### StockPageDTO — 库存/物料选择器返回结构

用于接口：`/im/inbound/material-selector`、`/im/outbound/material-selector`

```json
{
  "id": "int64",
  "warehouseId": "int64",
  "warehouseName": "string",
  "materialId": "int64",
  "materialCode": "string",
  "materialName": "string",
  "spec": "string",
  "unit": "string",
  "categoryId": "int64",
  "categoryName": "string",
  "materialType": "string",
  "materialTypeName": "string",
  "quantity": "number",        // ← 库存数量（关键字段！）
  "minSafeQty": "number",       // 安全库存
  "isLowStock": "boolean"       // 是否低库存预警
}
```

### MaterialPageDTO — 物料分页返回结构

接口：`/md/material/page`

```json
{
  "id": "int64",
  "materialCode": "string",
  "materialName": "string",
  "spec": "string",
  "unit": "string",
  "categoryId": "int64",
  "categoryName": "string",
  "materialType": "string",
  "materialTypeName": "string",
  "stockQty": "number",         // ← 库存数量（这里的字段名不一样！）
  "price": "number",
  "status": "int32",
  "remark": "string"
}
```

## 前端字段映射对照

| 场景 | 接口 | 库存字段 |
|------|------|---------|
| 物料选择器（入库/出库） | `/im/*/material-selector` | `quantity` |
| 库存列表页面 | `/im/stock/page` | `quantity` |
| 物料管理分页 | `/md/material/page` | `stockQty` |
| 安全库存设置 | `/im/stock/safe-qty` | `minSafeQty` |

## 涉及改动的页面

- `pages/inbound/production.vue` — 生产入库物料选择
- `pages/inbound/purchase.vue` — 采购入库物料选择
- `pages/outbound/material.vue` — 领料出库物料选择
- `pages/outbound/sales.vue` — 销售出库物料选择

以上 4 个页面库存字段已统一改为 `item.quantity`。