scottpan/my-mom-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7bdad2daca18eec60ba1c95e41a4aa06d1bd48b7
my-mom-system/mom-backend/docs/Testing/采购计划单-API测试文档.md

710 lines
20 KiB
Markdown
Raw Normal View History

readd mom-backend dir
2026-03-06 02:12:34 +08:00
# 采购计划单 后端 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 (或类似) | ✅ 已有 |
Reference in New Issue Copy Permalink