# 采购计划单 后端 API 测试文档

> 依据 PRD《mom系统采购计划单-页面开发说明文档》与后端 `MpPurchaseController` 编写，用于接口联调与测试。  
> 采购计划单为扁平表结构（erp_mp_purchase），同一 purchase_code 下可有多条物料记录。

---

## 1. 约定说明

| 项目 | 说明 |
|------|------|
| 基础路径 | 网关/应用根路径 + 下表 path（如 `http://host:port/erp/mp/purchase`） |
| 认证 | 需登录态，请求头带 Token（如 `Authorization: Bearer xxx`） |
| 分页 | 列表接口支持 `pageNum`、`pageSize`，响应含 `rows`、`total` |
| 通用响应 | 非分页接口通常为 `{ code, msg, data }`，code=200 表示成功 |
| 单据状态 | PREPARE=开立/草稿, APPROVED=已审核, REJECTED=退回 |
| 业务状态 | NORMAL=正常, PAUSE=暂停, CANCEL=取消, COMPLETED=完成 |

---

## 2. 接口总览

| 序号 | 功能 | 方法 | 路径 | 说明 |
|------|------|------|------|------|
| 1 | 明细视图列表 | GET | `/erp/mp/purchase/list` | 扁平列表，每行一条物料 |
| 2 | 单据视图列表 | GET | `/erp/mp/purchase/docList` | 按 purchase_code 聚合 |
| 3 | 底部汇总 | GET | `/erp/mp/purchase/summary` | 采购数量/已订数量合计 |
| 4 | 获取详情(ID) | GET | `/erp/mp/purchase/{purchaseId}` | 按 ID 获取单条记录 |
| 5 | 获取详情(编码) | GET | `/erp/mp/purchase/detail/{purchaseCode}` | 表头+明细行聚合 |
| 6 | 生成编码 | GET | `/erp/mp/purchase/genCode` | 生成 CGJH000XXX |
| 7 | 新增 | POST | `/erp/mp/purchase` | 创建采购计划 |
| 8 | 修改 | PUT | `/erp/mp/purchase` | 更新采购计划 |
| 9 | 删除(ID) | DELETE | `/erp/mp/purchase/{purchaseIds}` | 按 ID 删除（支持多个） |
| 10 | 删除(编码) | DELETE | `/erp/mp/purchase/byCode/{purchaseCode}` | 按编码删除整单 |
| 11 | 审核 | PUT | `/erp/mp/purchase/approve/{purchaseIds}` | 批量审核 |
| 12 | 反审核 | PUT | `/erp/mp/purchase/unapprove/{purchaseIds}` | 批量反审核 |
| 13 | 导出 | POST | `/erp/mp/purchase/export` | 导出 Excel |
| 14 | 从MBOM生成 | POST | `/erp/mp/purchase/generate/{mbomId}` | 根据物料清单生成 |

---

## 3. 接口详细说明

### 3.1 明细视图列表（GET /erp/mp/purchase/list）

**请求参数（Query）：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | integer | 否 | 页码，默认 1 |
| pageSize | integer | 否 | 每页条数，默认 100 |
| salesOrderCode | string | 否 | 销售订单号/跟单单号（模糊） |
| purchaseCode | string | 否 | 单据编码（模糊） |
| itemCode | string | 否 | 物料编码（模糊） |
| itemName | string | 否 | 物料名称（模糊） |
| needType | integer | 否 | 用料需求：0=订单用料，1=库存备料 |
| params[beginDate] | string | 否 | 开始日期 yyyy-MM-dd |
| params[endDate] | string | 否 | 结束日期 yyyy-MM-dd |
| params[itemTypeId] | string | 否 | 物料分类ID（快捷筛选） |

**响应示例：**

```json
{
  "total": 70,
  "rows": [
    {
      "purchaseId": 31,
      "purchaseCode": "CGJH000033",
      "purchaseDate": "2026-02-06",
      "status": "APPROVED",
      "businessType": "原材料",
      "businessStatus": "NORMAL",
      "needType": 0,
      "salesOrderCode": "XSDD000091",
      "deliveryDate": "2026-02-27",
      "planCode": "SCJH000096",
      "itemId": 100,
      "itemCode": "1000000002",
      "itemName": "微星 MAG B760M MORTAR WIFI DDR5 主板",
      "specification": "",
      "unitName": "台",
      "demandQty": 60.00,
      "availableQty": -30.00,
      "purchaseQty": 60.00,
      "orderedQty": 0.00,
      "operatorName": "admin"
    }
  ],
  "code": 200,
  "msg": "查询成功"
}
```

**curl 测试命令：**

```bash
# 明细视图 - 基本查询
curl -X GET "http://localhost:8080/erp/mp/purchase/list?pageNum=1&pageSize=100&needType=0" \
  -H "Authorization: Bearer {token}"

# 明细视图 - 按销售订单号搜索
curl -X GET "http://localhost:8080/erp/mp/purchase/list?salesOrderCode=XSDD000091&pageNum=1&pageSize=100" \
  -H "Authorization: Bearer {token}"

# 明细视图 - 按物料编码搜索
curl -X GET "http://localhost:8080/erp/mp/purchase/list?itemCode=1000000002&pageNum=1&pageSize=100" \
  -H "Authorization: Bearer {token}"

# 明细视图 - 按日期范围搜索
curl -X GET "http://localhost:8080/erp/mp/purchase/list?params%5BbeginDate%5D=2026-02-01&params%5BendDate%5D=2026-02-28&pageNum=1&pageSize=100" \
  -H "Authorization: Bearer {token}"
```

---

### 3.2 单据视图列表（GET /erp/mp/purchase/docList）

**请求参数（Query）：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | integer | 否 | 页码，默认 1 |
| pageSize | integer | 否 | 每页条数，默认 100 |
| purchaseCode | string | 否 | 单据编码（模糊） |
| status | string | 否 | 单据状态：PREPARE/APPROVED/REJECTED |
| businessStatus | string | 否 | 业务状态：NORMAL/PAUSE/CANCEL/COMPLETED |
| needType | integer | 否 | 用料需求 |
| params[beginDate] | string | 否 | 开始日期 |
| params[endDate] | string | 否 | 结束日期 |

**响应示例：**

```json
{
  "total": 31,
  "rows": [
    {
      "purchaseId": 31,
      "purchaseCode": "CGJH000033",
      "purchaseDate": "2026-02-06",
      "status": "APPROVED",
      "businessType": "原材料",
      "businessStatus": "NORMAL",
      "deptName": "采购部",
      "operatorName": "admin",
      "approverName": "admin",
      "approveDate": "2026-02-06 14:30:00",
      "purchaseQty": 180.00,
      "orderedQty": 60.00
    }
  ],
  "code": 200,
  "msg": "查询成功"
}
```

**curl 测试命令：**

```bash
# 单据视图 - 基本查询
curl -X GET "http://localhost:8080/erp/mp/purchase/docList?pageNum=1&pageSize=100" \
  -H "Authorization: Bearer {token}"

# 单据视图 - 按状态筛选（仅草稿）
curl -X GET "http://localhost:8080/erp/mp/purchase/docList?status=PREPARE&pageNum=1&pageSize=100" \
  -H "Authorization: Bearer {token}"

# 单据视图 - 按业务状态筛选
curl -X GET "http://localhost:8080/erp/mp/purchase/docList?businessStatus=NORMAL&pageNum=1&pageSize=100" \
  -H "Authorization: Bearer {token}"
```

---

### 3.3 底部汇总（GET /erp/mp/purchase/summary）

返回当前查询条件下的采购数量和已订数量合计。查询条件与明细视图列表一致。

**响应示例：**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "totalPurchaseQty": 15084075.00,
    "totalOrderedQty": 68549.00
  }
}
```

**curl 测试命令：**

```bash
# 汇总 - 全量
curl -X GET "http://localhost:8080/erp/mp/purchase/summary" \
  -H "Authorization: Bearer {token}"

# 汇总 - 带搜索条件
curl -X GET "http://localhost:8080/erp/mp/purchase/summary?salesOrderCode=XSDD000091" \
  -H "Authorization: Bearer {token}"
```

---

### 3.4 获取详情 - 按 ID（GET /erp/mp/purchase/{purchaseId}）

返回单条采购计划记录（扁平结构，对应一个物料行）。

**curl 测试命令：**

```bash
curl -X GET "http://localhost:8080/erp/mp/purchase/31" \
  -H "Authorization: Bearer {token}"
```

---

### 3.5 获取详情 - 按编码（GET /erp/mp/purchase/detail/{purchaseCode}）

按 purchaseCode 聚合返回表头+物料明细行，用于查看/编辑页面。

**响应示例：**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "purchaseCode": "CGJH000032",
    "purchaseDate": "2026-02-07",
    "status": "PREPARE",
    "businessType": "原材料",
    "businessStatus": "NORMAL",
    "needType": 0,
    "planId": 96,
    "planCode": "SCJH000096",
    "salesOrderId": 81,
    "salesOrderCode": "XSDD000081",
    "salesUserName": "周桂东",
    "deliveryDate": "2026-01-23",
    "deptId": null,
    "deptName": null,
    "operatorId": 1,
    "operatorName": "admin",
    "operatorName2": null,
    "approverId": null,
    "approverName": null,
    "approveDate": null,
    "totalQuantity": 170,
    "remark": null,
    "headerItemCode": "0103000002",
    "headerItemName": "组装电脑5400",
    "lines": [
      {
        "purchaseId": 101,
        "purchaseCode": "CGJH000032",
        "itemCode": "1000000001",
        "itemName": "英特尔Core i5-14600KF",
        "specification": "",
        "unitName": "台",
        "demandDate": "2026-02-18",
        "demandQty": 10.00,
        "availableQty": -30.00,
        "purchaseQty": 170.00,
        "orderedQty": 0.00,
        "remark": ""
      },
      {
        "purchaseId": 102,
        "purchaseCode": "CGJH000032",
        "itemCode": "1000000002",
        "itemName": "微星 MAG B760M 主板",
        "specification": "",
        "unitName": "台",
        "demandDate": "2026-02-18",
        "demandQty": 10.00,
        "availableQty": 5.00,
        "purchaseQty": 5.00,
        "orderedQty": 0.00,
        "remark": ""
      }
    ]
  }
}
```

**curl 测试命令：**

```bash
curl -X GET "http://localhost:8080/erp/mp/purchase/detail/CGJH000032" \
  -H "Authorization: Bearer {token}"
```

---

### 3.6 生成编码（GET /erp/mp/purchase/genCode）

自动生成下一个采购计划编码，格式：CGJH + 6位流水号。

**响应示例：**

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

**curl 测试命令：**

```bash
curl -X GET "http://localhost:8080/erp/mp/purchase/genCode" \
  -H "Authorization: Bearer {token}"
```

---

### 3.7 新增采购计划（POST /erp/mp/purchase）

新增单条物料的采购计划记录。若需创建包含多条物料的单据，需多次调用此接口使用相同的 purchaseCode。

**请求体：**

```json
{
  "purchaseCode": "CGJH000034",
  "purchaseDate": "2026-02-07",
  "businessType": "原材料",
  "businessStatus": "NORMAL",
  "needType": 0,
  "planId": 96,
  "planCode": "SCJH000096",
  "salesOrderId": 81,
  "salesOrderCode": "XSDD000081",
  "salesUserName": "周桂东",
  "deliveryDate": "2026-01-23",
  "itemId": 201,
  "itemCode": "1000000001",
  "itemName": "英特尔Core i5-14600KF",
  "specification": "",
  "unitName": "台",
  "demandQty": 170.00,
  "demandDate": "2026-02-18",
  "availableQty": -30.00,
  "purchaseQty": 170.00,
  "totalQuantity": 170,
  "remark": ""
}
```

**响应示例：**

```json
{
  "code": 200,
  "msg": "操作成功",
  "purchaseId": 201
}
```

**curl 测试命令：**

```bash
curl -X POST "http://localhost:8080/erp/mp/purchase" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseCode": "CGJH000034",
    "purchaseDate": "2026-02-07",
    "businessType": "原材料",
    "needType": 0,
    "planCode": "SCJH000096",
    "salesOrderCode": "XSDD000081",
    "itemCode": "1000000001",
    "itemName": "英特尔Core i5-14600KF",
    "unitName": "台",
    "demandQty": 170.00,
    "purchaseQty": 170.00
  }'
```

---

### 3.8 修改采购计划（PUT /erp/mp/purchase）

更新单条采购计划记录，必须包含 purchaseId。

**请求体：**

```json
{
  "purchaseId": 201,
  "purchaseQty": 200.00,
  "demandDate": "2026-02-20",
  "remark": "修改采购数量"
}
```

**curl 测试命令：**

```bash
curl -X PUT "http://localhost:8080/erp/mp/purchase" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseId": 201,
    "purchaseQty": 200.00,
    "remark": "修改采购数量"
  }'
```

---

### 3.9 删除 - 按 ID（DELETE /erp/mp/purchase/{purchaseIds}）

批量删除（逻辑删除）。仅允许草稿(PREPARE)和退回(REJECTED)状态。

**路径参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| purchaseIds | Long[] | 采购计划ID，多个用逗号分隔 |

**curl 测试命令：**

```bash
# 单条删除
curl -X DELETE "http://localhost:8080/erp/mp/purchase/201" \
  -H "Authorization: Bearer {token}"

# 批量删除
curl -X DELETE "http://localhost:8080/erp/mp/purchase/201,202,203" \
  -H "Authorization: Bearer {token}"
```

**错误场景测试：**

```bash
# 尝试删除已审核状态的记录（应返回错误）
curl -X DELETE "http://localhost:8080/erp/mp/purchase/31" \
  -H "Authorization: Bearer {token}"
# 预期: {"code": 500, "msg": "编码为[CGJH000033]的单据不是草稿/退回状态，不允许删除!"}
```

---

### 3.10 删除 - 按编码（DELETE /erp/mp/purchase/byCode/{purchaseCode}）

按采购计划编码删除同一单据下所有物料行（单据视图使用）。

**curl 测试命令：**

```bash
curl -X DELETE "http://localhost:8080/erp/mp/purchase/byCode/CGJH000034" \
  -H "Authorization: Bearer {token}"
```

---

### 3.11 审核（PUT /erp/mp/purchase/approve/{purchaseIds}）

批量审核采购计划。支持逗号分隔的 ID 字符串。同一 purchaseCode 下所有行同时审核。

**路径参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| purchaseIds | String | 采购计划ID，多个用逗号分隔 |

**前置条件：** 单据状态必须为 PREPARE（草稿）

**curl 测试命令：**

```bash
# 单条审核
curl -X PUT "http://localhost:8080/erp/mp/purchase/approve/201" \
  -H "Authorization: Bearer {token}"

# 批量审核
curl -X PUT "http://localhost:8080/erp/mp/purchase/approve/201,202,203" \
  -H "Authorization: Bearer {token}"
```

**响应示例：**

```json
{
  "code": 200,
  "msg": "成功审核 3 条单据"
}
```

**错误场景测试：**

```bash
# 尝试审核已审核的记录
curl -X PUT "http://localhost:8080/erp/mp/purchase/approve/31" \
  -H "Authorization: Bearer {token}"
# 预期: {"code": 500, "msg": "编码为[CGJH000033]的单据不是草稿状态，不能审核!"}
```

---

### 3.12 反审核（PUT /erp/mp/purchase/unapprove/{purchaseIds}）

批量反审核采购计划。支持逗号分隔的 ID 字符串。同一 purchaseCode 下所有行同时反审核。

反审核后状态变为 PREPARE（草稿），清空审核员和审核日期。

**路径参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| purchaseIds | String | 采购计划ID，多个用逗号分隔 |

**前置条件：** 单据状态必须为 APPROVED（已审核）

**curl 测试命令：**

```bash
# 单条反审核
curl -X PUT "http://localhost:8080/erp/mp/purchase/unapprove/31" \
  -H "Authorization: Bearer {token}"

# 批量反审核
curl -X PUT "http://localhost:8080/erp/mp/purchase/unapprove/31,32,33" \
  -H "Authorization: Bearer {token}"
```

**响应示例：**

```json
{
  "code": 200,
  "msg": "成功反审核 1 条单据"
}
```

**错误场景测试：**

```bash
# 尝试反审核草稿状态的记录
curl -X PUT "http://localhost:8080/erp/mp/purchase/unapprove/201" \
  -H "Authorization: Bearer {token}"
# 预期: {"code": 500, "msg": "编码为[CGJH000034]的单据不是已审核状态，不能反审核!"}
```

---

### 3.13 导出（POST /erp/mp/purchase/export）

导出采购计划列表到 Excel 文件。请求参数与明细视图列表一致。

**curl 测试命令：**

```bash
curl -X POST "http://localhost:8080/erp/mp/purchase/export" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -o "采购计划单.xlsx"
```

---

### 3.14 从 MBOM 生成采购计划（POST /erp/mp/purchase/generate/{mbomId}）

根据物料清单(MBOM)中供应方式为"采购"的物料，自动生成采购计划。

**路径参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| mbomId | Long | 物料清单ID |

**curl 测试命令：**

```bash
curl -X POST "http://localhost:8080/erp/mp/purchase/generate/1" \
  -H "Authorization: Bearer {token}"
```

**响应示例：**

```json
{
  "code": 200,
  "msg": "成功生成 5 条采购计划"
}
```

---

## 4. 典型测试流程

### 4.1 完整业务流程测试

```bash
# 步骤1: 生成编码
curl -X GET "http://localhost:8080/erp/mp/purchase/genCode" -H "Authorization: Bearer {token}"
# 记录返回的编码，如 CGJH000034

# 步骤2: 新增采购计划（第一条物料）
curl -X POST "http://localhost:8080/erp/mp/purchase" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseCode": "CGJH000034",
    "purchaseDate": "2026-02-07",
    "businessType": "原材料",
    "needType": 0,
    "itemCode": "1000000001",
    "itemName": "英特尔Core i5-14600KF",
    "unitName": "台",
    "demandQty": 170.00,
    "purchaseQty": 170.00
  }'
# 记录返回的 purchaseId

# 步骤3: 新增同单据第二条物料
curl -X POST "http://localhost:8080/erp/mp/purchase" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purchaseCode": "CGJH000034",
    "purchaseDate": "2026-02-07",
    "businessType": "原材料",
    "needType": 0,
    "itemCode": "1000000002",
    "itemName": "微星 MAG B760M 主板",
    "unitName": "台",
    "demandQty": 170.00,
    "purchaseQty": 170.00
  }'

# 步骤4: 查询明细视图，验证新增数据
curl -X GET "http://localhost:8080/erp/mp/purchase/list?purchaseCode=CGJH000034" \
  -H "Authorization: Bearer {token}"

# 步骤5: 查询单据视图，验证聚合
curl -X GET "http://localhost:8080/erp/mp/purchase/docList?purchaseCode=CGJH000034" \
  -H "Authorization: Bearer {token}"

# 步骤6: 查询详情
curl -X GET "http://localhost:8080/erp/mp/purchase/detail/CGJH000034" \
  -H "Authorization: Bearer {token}"

# 步骤7: 查询汇总
curl -X GET "http://localhost:8080/erp/mp/purchase/summary?purchaseCode=CGJH000034" \
  -H "Authorization: Bearer {token}"

# 步骤8: 审核
curl -X PUT "http://localhost:8080/erp/mp/purchase/approve/{purchaseId}" \
  -H "Authorization: Bearer {token}"

# 步骤9: 验证审核后状态
curl -X GET "http://localhost:8080/erp/mp/purchase/detail/CGJH000034" \
  -H "Authorization: Bearer {token}"
# 预期: status=APPROVED, approverName 不为空

# 步骤10: 反审核
curl -X PUT "http://localhost:8080/erp/mp/purchase/unapprove/{purchaseId}" \
  -H "Authorization: Bearer {token}"

# 步骤11: 验证反审核后状态
curl -X GET "http://localhost:8080/erp/mp/purchase/detail/CGJH000034" \
  -H "Authorization: Bearer {token}"
# 预期: status=PREPARE, approverName=null

# 步骤12: 删除
curl -X DELETE "http://localhost:8080/erp/mp/purchase/byCode/CGJH000034" \
  -H "Authorization: Bearer {token}"
```

### 4.2 边界条件测试

| 测试点 | 操作 | 预期结果 |
|--------|------|----------|
| 删除已审核单据 | DELETE /erp/mp/purchase/{已审核ID} | 返回错误：不允许删除 |
| 审核非草稿单据 | PUT /approve/{非PREPARE的ID} | 返回错误：不是草稿状态 |
| 反审核非审核单据 | PUT /unapprove/{非APPROVED的ID} | 返回错误：不是已审核状态 |
| 查询不存在的编码 | GET /detail/CGJH999999 | 返回错误：采购计划单不存在 |
| 重复编码新增 | POST 使用已存在的编码 | 返回错误：编码已存在 |
| 空列表汇总 | GET /summary?purchaseCode=不存在 | 返回 {totalPurchaseQty: 0, totalOrderedQty: 0} |

---

## 5. PRD 对照验证

| PRD 接口要求 | 后端实现 | 状态 |
|-------------|----------|------|
| 查询采购计划列表 (明细视图) | GET /erp/mp/purchase/list | ✅ 已实现 |
| 查询采购计划列表 (单据视图) | GET /erp/mp/purchase/docList | ✅ 已实现 |
| 底部汇总统计 | GET /erp/mp/purchase/summary | ✅ 已实现 |
| 获取详情 (按ID) | GET /erp/mp/purchase/{purchaseId} | ✅ 已实现 |
| 获取详情 (按编码, 表头+明细) | GET /erp/mp/purchase/detail/{purchaseCode} | ✅ 已实现 |
| 生成采购计划编码 | GET /erp/mp/purchase/genCode | ✅ 已实现 |
| 新增采购计划 | POST /erp/mp/purchase | ✅ 已实现 |
| 修改采购计划 | PUT /erp/mp/purchase | ✅ 已实现 |
| 删除采购计划 (按ID) | DELETE /erp/mp/purchase/{purchaseIds} | ✅ 已实现 |
| 删除采购计划 (按编码) | DELETE /erp/mp/purchase/byCode/{purchaseCode} | ✅ 已实现 |
| 审核采购计划 (支持批量) | PUT /erp/mp/purchase/approve/{purchaseIds} | ✅ 已实现 |
| 反审核采购计划 (支持批量) | PUT /erp/mp/purchase/unapprove/{purchaseIds} | ✅ 已实现 |
| 导出 | POST /erp/mp/purchase/export | ✅ 已实现 |
| 从MBOM生成 | POST /erp/mp/purchase/generate/{mbomId} | ✅ 已实现 |
| 生产计划列表 (引入用) | 复用 GET /erp/mp/plan/list | ✅ 已有 |
| 物料选择 | 复用 GET /md/item/list (或类似) | ✅ 已有 |