# Batch 1: WMS API 模块建设 - 前端修改文档

## 涉及页面

- 新增页面：库存预留管理页面
- 修改页面：库存查询页面（新增预留数量显示）

---

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /wms/inventory-reserve/page | 库存预留分页查询 |
| POST | /wms/inventory-reserve/release | 释放库存预留 |
| GET | /wms/inventory-reserve/get | 获取预留详情 |

**请求参数（分页查询）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo | Integer | 是 | 页码 |
| pageSize | Integer | 是 | 每页数量 |
| reserveNo | String | 否 | 预留单号 |
| bizType | Integer | 否 | 业务类型 |
| bizNo | String | 否 | 业务单据号 |
| status | Integer | 否 | 状态 |

**响应：**

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "reserveNo": "RES202606260001",
        "bizType": 10,
        "bizTypeName": "销售预留",
        "bizId": 100,
        "bizNo": "SO202606260001",
        "skuId": 1,
        "skuName": "商品A-红色-L",
        "warehouseId": 1,
        "warehouseName": "主仓库",
        "reserveQuantity": 100.00,
        "usedQuantity": 0.00,
        "status": 0,
        "statusName": "预留中",
        "expireTime": "2026-06-30 00:00:00",
        "createTime": "2026-06-26 10:00:00"
      }
    ],
    "total": 1
  }
}
```

---

## 前端修改点

### 1. 新增库存预留管理页面

**文件路径：** `src/views/wms/inventory/reserve/index.vue`

```vue
<template>
  <ContentWrap>
    <!-- 搜索 -->
    <el-form
      class="-mb-15px"
      :model="queryParams"
      :inline="true"
      label-width="68px"
    >
      <el-form-item label="预留单号" prop="reserveNo">
        <el-input
          v-model="queryParams.reserveNo"
          placeholder="请输入预留单号"
          clearable
          @keyup.enter="handleQuery"
          class="!w-240px"
        />
      </el-form-item>
      <el-form-item label="业务类型" prop="bizType">
        <el-select
          v-model="queryParams.bizType"
          placeholder="请选择业务类型"
          clearable
          class="!w-240px"
        >
          <el-option
            v-for="dict in getIntDictOptions(DICT_TYPE.WMS_RESERVE_BIZ_TYPE)"
            :key="dict.value"
            :label="dict.label"
            :value="dict.value"
          />
        </el-select>
      </el-form-item>
      <el-form-item label="状态" prop="status">
        <el-select
          v-model="queryParams.status"
          placeholder="请选择状态"
          clearable
          class="!w-240px"
        >
          <el-option
            v-for="dict in getIntDictOptions(DICT_TYPE.WMS_RESERVE_STATUS)"
            :key="dict.value"
            :label="dict.label"
            :value="dict.value"
          />
        </el-select>
      </el-form-item>
      <el-form-item>
        <el-button @click="handleQuery"><Icon icon="ep:search" class="mr-5px" />搜索</el-button>
        <el-button @click="resetQuery"><Icon icon="ep:refresh" class="mr-5px" />重置</el-button>
      </el-form-item>
    </el-form>
  </ContentWrap>

  <!-- 列表 -->
  <ContentWrap class="mt-10px">
    <el-table v-loading="loading" :data="list" :stripe="true">
      <el-table-column label="预留单号" align="center" prop="reserveNo" width="180" />
      <el-table-column label="业务类型" align="center" prop="bizTypeName" width="100" />
      <el-table-column label="业务单据号" align="center" prop="bizNo" width="180" />
      <el-table-column label="商品SKU" align="center" prop="skuName" width="200" />
      <el-table-column label="仓库" align="center" prop="warehouseName" width="120" />
      <el-table-column label="预留数量" align="center" prop="reserveQuantity" width="100" />
      <el-table-column label="已使用数量" align="center" prop="usedQuantity" width="100" />
      <el-table-column label="状态" align="center" prop="statusName" width="100">
        <template #default="scope">
          <dict-tag :type="DICT_TYPE.WMS_RESERVE_STATUS" :value="scope.row.status" />
        </template>
      </el-table-column>
      <el-table-column
        label="过期时间"
        align="center"
        prop="expireTime"
        :formatter="dateFormatter"
        width="180"
      />
      <el-table-column label="操作" align="center" fixed="right" width="100">
        <template #default="scope">
          <el-button
            link
            type="primary"
            @click="handleRelease(scope.row)"
            v-hasPermi="['wms:inventory-reserve:release']"
            v-if="scope.row.status === 0 || scope.row.status === 1"
          >
            释放
          </el-button>
        </template>
      </el-table-column>
    </el-table>
    <!-- 分页 -->
    <Pagination
      :total="total"
      v-model:page="queryParams.pageNo"
      v-model:limit="queryParams.pageSize"
      @pagination="getList"
    />
  </ContentWrap>
</template>

<script setup lang="ts">
import { dateFormatter } from '@/utils/formatTime'
import { DICT_TYPE, getIntDictOptions } from '@/utils/dict'
import * as ReserveApi from '@/api/wms/inventory/reserve'

defineOptions({ name: 'WmsInventoryReserve' })

const loading = ref(true)
const list = ref([])
const total = ref(0)
const queryParams = reactive({
  pageNo: 1,
  pageSize: 10,
  reserveNo: undefined,
  bizType: undefined,
  bizNo: undefined,
  status: undefined
})

/** 查询列表 */
const getList = async () => {
  loading.value = true
  try {
    const data = await ReserveApi.getInventoryReservePage(queryParams)
    list.value = data.list
    total.value = data.total
  } finally {
    loading.value = false
  }
}

/** 搜索按钮操作 */
const handleQuery = () => {
  queryParams.pageNo = 1
  getList()
}

/** 重置按钮操作 */
const resetQuery = () => {
  queryParams.reserveNo = undefined
  queryParams.bizType = undefined
  queryParams.bizNo = undefined
  queryParams.status = undefined
  handleQuery()
}

/** 释放预留 */
const handleRelease = async (row: any) => {
  try {
    await message.delConfirm(`确认释放预留单号【${row.reserveNo}】的库存预留？`)
    await ReserveApi.releaseInventoryReserve(row.id)
    message.success('释放成功')
    await getList()
  } catch {}
}

/** 初始化 */
onMounted(() => {
  getList()
})
</script>
```

### 2. 新增 API 接口文件

**文件路径：** `src/api/wms/inventory/reserve/index.ts`

```typescript
import request from '@/config/axios'

// 库存预留分页查询
export const getInventoryReservePage = async (params: any) => {
  return await request.get({ url: '/wms/inventory-reserve/page', params })
}

// 获取库存预留详情
export const getInventoryReserve = async (id: number) => {
  return await request.get({ url: '/wms/inventory-reserve/get?id=' + id })
}

// 释放库存预留
export const releaseInventoryReserve = async (id: number) => {
  return await request.post({ url: '/wms/inventory-reserve/release?id=' + id })
}
```

### 3. 字典类型新增

**文件路径：** `src/utils/dict.ts`

在 `DICT_TYPE` 中新增：

```typescript
WMS_RESERVE_BIZ_TYPE = 'wms_reserve_biz_type',
WMS_RESERVE_STATUS = 'wms_reserve_status',
WMS_TRANSACTION_TYPE = 'wms_transaction_type'
```

---

## 注意事项

1. 本批次主要新增库存预留功能，前端改动较小
2. 库存预留页面提供预留查询和手动释放功能
3. 后续批次（ERP/MES 集成）会自动调用预留 API，无需前端干预
4. 建议先执行数据库脚本，再部署后端代码，最后更新前端

---

## 后端新增文件清单

```
yudao-module-wms/src/main/java/cn/iocoder/yudao/module/wms/
├── api/inventory/
│   ├── WmsInventoryApi.java
│   ├── WmsInventoryApiImpl.java
│   └── dto/
│       ├── WmsInventoryQueryReqDTO.java
│       ├── WmsInventoryRespDTO.java
│       ├── WmsReceiptReqDTO.java
│       ├── WmsReceiptResultDTO.java
│       ├── WmsReserveReqDTO.java
│       ├── WmsShipmentReqDTO.java
│       ├── WmsShipmentResultDTO.java
│       └── WmsUseReserveReqDTO.java
├── controller/admin/inventory/
│   ├── WmsInventoryReserveController.java
│   └── vo/
│       ├── WmsInventoryReservePageReqVO.java
│       └── WmsInventoryReserveRespVO.java
├── dal/dataobject/inventory/
│   ├── WmsInventoryReserveDO.java
│   └── WmsInventoryTransactionDO.java
├── dal/mysql/inventory/
│   ├── WmsInventoryReserveMapper.java
│   └── WmsInventoryTransactionMapper.java
├── enums/inventory/
│   ├── WmsInventoryBizTypeEnum.java
│   ├── WmsReserveBizTypeEnum.java
│   ├── WmsReserveStatusEnum.java
│   └── WmsTransactionTypeEnum.java
└── service/inventory/
    ├── WmsInventoryReserveService.java
    ├── WmsInventoryReserveServiceImpl.java
    ├── WmsInventoryTransactionService.java
    └── WmsInventoryTransactionServiceImpl.java
```

---

**文档版本**: v1.0
**创建日期**: 2026-06-26