504 lines
12 KiB
Markdown
504 lines
12 KiB
Markdown
# EBOM / 产品BOM 后端 API 测试文档
|
||
|
||
> 依据前端 `erp-frontend-vue/src/api/rd/ebom.ts` 与后端 `MdBomController`、`MdProductBomController` 编写，用于接口联调与测试。
|
||
> 生产计划单「选择EBOM单」弹窗依赖本组接口（见《mom系统生产计划单-页面开发说明文档》7.6.4、7.6.5）。
|
||
|
||
---
|
||
|
||
## 1. 约定说明
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 基础路径 | 网关/应用根路径 + 下表 path（如 `http://host:port/mes/md/bom`） |
|
||
| 认证 | 需登录态，请求头带 Token（如 `Authorization: Bearer xxx`） |
|
||
| 分页 | 列表接口支持 `pageNum`、`pageSize`，响应含 `rows`、`total` |
|
||
| 通用响应 | 非分页接口通常为 `{ code, msg, data }`，code=200 表示成功 |
|
||
|
||
---
|
||
|
||
## 2. BOM 表头接口（MdBomController）
|
||
|
||
**Base path:** `/mes/md/bom`
|
||
|
||
### 2.1 查询 BOM 列表（分页）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `listEbom(query)` / `listEbomDetail(query)` |
|
||
| 方法 | GET |
|
||
| 路径 | `/mes/md/bom/list` |
|
||
| 权限 | 无特殊注解，依赖全局或菜单权限 |
|
||
|
||
**请求参数（Query，与 EbomQuery 对应）：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| bomCode | string | 否 | BOM 编码，模糊 |
|
||
| itemCode | string | 否 | 产品/物料编码，模糊 |
|
||
| itemName | string | 否 | 产品/物料名称，模糊 |
|
||
| itemTypeId | number | 否 | 物料分类 ID |
|
||
| status | string | 否 | 单据状态：DRAFT / APPROVED |
|
||
| businessStatus | string | 否 | 业务状态 |
|
||
| beginDate | string | 否 | 开始日期 YYYY-MM-DD（映射 params.beginDate） |
|
||
| endDate | string | 否 | 结束日期 YYYY-MM-DD |
|
||
| pageNum | number | 否 | 页码，默认 1 |
|
||
| pageSize | number | 否 | 每页条数，默认 10 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"rows": [
|
||
{
|
||
"bomId": 1,
|
||
"bomCode": "BOM001",
|
||
"bomName": "示例BOM",
|
||
"itemId": 100,
|
||
"itemCode": "ITEM01",
|
||
"itemName": "产品A",
|
||
"version": "V1.0",
|
||
"versionDesc": "初版",
|
||
"status": "DRAFT",
|
||
"baseQty": 1,
|
||
"createTime": "2026-01-01 10:00:00"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- 无参数：返回分页列表，total 与 rows 长度一致或 total 为总条数。
|
||
- 传 `status=APPROVED`：仅返回已审核 BOM。
|
||
- 传 `itemCode` / `itemName`：按物料编码或名称筛选。
|
||
- 传 `beginDate`、`endDate`：按创建日期范围筛选。
|
||
|
||
---
|
||
|
||
### 2.2 获取 BOM 详情（含明细行）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `getEbom(bomId)` |
|
||
| 方法 | GET |
|
||
| 路径 | `/mes/md/bom/{bomId}` |
|
||
| 权限 | `mes:md:bom:query` |
|
||
|
||
**路径参数：**
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| bomId | long | BOM 表头主键 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"bomId": 1,
|
||
"bomCode": "BOM001",
|
||
"bomName": "示例BOM",
|
||
"itemId": 100,
|
||
"itemCode": "ITEM01",
|
||
"itemName": "产品A",
|
||
"version": "V1.0",
|
||
"versionDesc": "初版",
|
||
"status": "DRAFT",
|
||
"baseQty": 1,
|
||
"lines": [
|
||
{
|
||
"bomId": 101,
|
||
"bomCode": "BOM001",
|
||
"bomItemId": 201,
|
||
"bomItemCode": "MAT01",
|
||
"bomItemName": "物料1",
|
||
"quantity": 2,
|
||
"unitName": "个",
|
||
"lineNo": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- 存在 bomId：返回表头 + `lines` 数组（按 bomCode 关联的 md_product_bom 行）。
|
||
- 不存在 bomId：返回 404 或 code≠200。
|
||
- 用于生产计划单「选择EBOM单」确定后展示、或「查看」EBOM 详情。
|
||
|
||
---
|
||
|
||
### 2.3 新增 BOM 表头
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `addEbom(data)` |
|
||
| 方法 | POST |
|
||
| 路径 | `/mes/md/bom` |
|
||
| Content-Type | application/json |
|
||
| 权限 | `mes:md:bom:add` |
|
||
|
||
**请求体示例：**
|
||
|
||
```json
|
||
{
|
||
"bomCode": "BOM002",
|
||
"bomName": "新BOM",
|
||
"itemId": 100,
|
||
"itemCode": "ITEM01",
|
||
"itemName": "产品A",
|
||
"unitName": "台",
|
||
"baseQty": 1,
|
||
"version": "V1.0",
|
||
"versionDesc": "初版",
|
||
"status": "DRAFT",
|
||
"enableFlag": "Y",
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": { "bomId": 2 }
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- bomCode 重复：应返回业务错误提示。
|
||
- 必填项缺失（如 bomCode、itemId 等）：返回参数校验错误。
|
||
|
||
---
|
||
|
||
### 2.4 修改 BOM 表头
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `updateEbom(data)` |
|
||
| 方法 | PUT |
|
||
| 路径 | `/mes/md/bom` |
|
||
| Content-Type | application/json |
|
||
| 权限 | `mes:md:bom:edit` |
|
||
|
||
**请求体：** 与新增类似，需带 `bomId`。
|
||
|
||
**测试要点：**
|
||
|
||
- 仅更新传入字段；审核后是否允许修改依业务配置。
|
||
|
||
---
|
||
|
||
### 2.5 删除 BOM 表头
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `deleteEbom(ids)` |
|
||
| 方法 | DELETE |
|
||
| 路径 | `/mes/md/bom/{bomIds}` |
|
||
| 权限 | `mes:md:bom:remove` |
|
||
|
||
**路径参数：** `bomIds` 为多个时逗号分隔，如 `1,2,3`。
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- 单条：`DELETE /mes/md/bom/1`。
|
||
- 多条：`DELETE /mes/md/bom/1,2,3`。
|
||
- 逻辑删除（del_flag=1）时，列表不再返回已删记录。
|
||
|
||
---
|
||
|
||
### 2.6 审核 EBOM
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `approveEbom(bomId)` |
|
||
| 方法 | PUT |
|
||
| 路径 | `/mes/md/bom/approve` |
|
||
| Content-Type | application/json |
|
||
| 权限 | `mes:md:bom:edit` |
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"bomId": 1
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- 成功：对应 BOM 的 `status` 更新为 `APPROVED`。
|
||
- 缺少 bomId：返回「bomId 不能为空」或 code≠200。
|
||
|
||
---
|
||
|
||
### 2.7 反审核 EBOM
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `unapproveEbom(bomId)` |
|
||
| 方法 | PUT |
|
||
| 路径 | `/mes/md/bom/reject` |
|
||
| Content-Type | application/json |
|
||
| 权限 | `mes:md:bom:edit` |
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"bomId": 1
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- 成功：对应 BOM 的 `status` 更新为 `DRAFT`。
|
||
|
||
---
|
||
|
||
### 2.8 导出 BOM 列表（GET）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `exportEbom(query)` |
|
||
| 方法 | GET |
|
||
| 路径 | `/mes/md/bom/export` |
|
||
| 权限 | `mes:md:bom:export` |
|
||
|
||
**请求参数：** 与 2.1 列表查询一致（bomCode、itemCode、status、beginDate、endDate 等）。
|
||
|
||
**响应：** 二进制流（Excel），`Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` 或类似；前端使用 `responseType: 'blob'`。
|
||
|
||
**测试要点：**
|
||
|
||
- 带与列表相同的查询条件，返回 Excel 文件且可打开。
|
||
- 无权限时返回 403。
|
||
|
||
---
|
||
|
||
## 3. BOM 明细行接口（MdProductBomController）
|
||
|
||
**Base path:** `/mes/md/bom/line`
|
||
|
||
### 3.1 查询 BOM 明细列表（分页）
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `listEbomLines(query)` |
|
||
| 方法 | GET |
|
||
| 路径 | `/mes/md/bom/line/list` |
|
||
|
||
**请求参数（Query）：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| bomCode | string | 否 | BOM 编码，精确或模糊（依后端实现） |
|
||
| pageNum | number | 否 | 页码 |
|
||
| pageSize | number | 否 | 每页条数 |
|
||
|
||
**响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"rows": [
|
||
{
|
||
"bomId": 101,
|
||
"bomCode": "BOM001",
|
||
"bomItemId": 201,
|
||
"bomItemCode": "MAT01",
|
||
"bomItemName": "物料1",
|
||
"quantity": 2,
|
||
"unitName": "个",
|
||
"lineNo": 1,
|
||
"supplyType": "PRODUCE"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- 按 `bomCode` 筛选某 BOM 下的所有明细行。
|
||
|
||
---
|
||
|
||
### 3.2 获取单条 BOM 明细
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 方法 | GET |
|
||
| 路径 | `/mes/md/bom/line/{bomId}` |
|
||
| 权限 | `mes:md:mditem:query` |
|
||
|
||
**说明：** 此处 `bomId` 为明细表主键（md_product_bom 行 ID）。前端 EBOM 模块未单独调用该接口，详情通过 2.2 表头详情中的 `lines` 获取。
|
||
|
||
---
|
||
|
||
### 3.3 新增 BOM 明细
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `addEbomLine(data)` |
|
||
| 方法 | POST |
|
||
| 路径 | `/mes/md/bom/line` |
|
||
| Content-Type | application/json |
|
||
| 权限 | `mes:md:mditem:add` |
|
||
|
||
**请求体示例：**
|
||
|
||
```json
|
||
{
|
||
"bomCode": "BOM001",
|
||
"itemId": 100,
|
||
"bomItemId": 201,
|
||
"bomItemCode": "MAT01",
|
||
"bomItemName": "物料1",
|
||
"quantity": 2,
|
||
"unitOfMeasure": "个",
|
||
"lineNo": 1,
|
||
"supplyType": "PRODUCE"
|
||
}
|
||
```
|
||
|
||
**测试要点：**
|
||
|
||
- `bomItemId == itemId`（产品作为自身 BOM 物料）：后端应返回「产品不能作为自身的BOM物料！」。
|
||
|
||
---
|
||
|
||
### 3.4 修改 BOM 明细
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `updateEbomLine(data)` |
|
||
| 方法 | PUT |
|
||
| 路径 | `/mes/md/bom/line` |
|
||
| Content-Type | application/json |
|
||
| 权限 | `mes:md:mditem:edit` |
|
||
|
||
**请求体：** 需带明细主键（如 `bomId` 在 line 表中表示行 ID）。
|
||
|
||
---
|
||
|
||
### 3.5 删除 BOM 明细
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 前端方法 | `deleteEbomLine(ids)` |
|
||
| 方法 | DELETE |
|
||
| 路径 | `/mes/md/bom/line/{bomIds}` |
|
||
| 权限 | `mes:md:mditem:remove` |
|
||
|
||
**路径参数：** 多个 ID 逗号分隔，如 `101,102`。此处为明细行主键（md_product_bom 表 PK）。
|
||
|
||
---
|
||
|
||
## 4. 前端与后端接口对照表
|
||
|
||
| 前端 API（ebom.ts） | 方法 | 后端路径 |
|
||
|---------------------|------|----------|
|
||
| listEbom / listEbomDetail | GET | /mes/md/bom/list |
|
||
| getEbom(bomId) | GET | /mes/md/bom/{bomId} |
|
||
| addEbom(data) | POST | /mes/md/bom |
|
||
| updateEbom(data) | PUT | /mes/md/bom |
|
||
| deleteEbom(ids) | DELETE | /mes/md/bom/{bomIds} |
|
||
| approveEbom(bomId) | PUT | /mes/md/bom/approve |
|
||
| unapproveEbom(bomId) | PUT | /mes/md/bom/reject |
|
||
| exportEbom(query) | GET | /mes/md/bom/export |
|
||
| listEbomLines(query) | GET | /mes/md/bom/line/list |
|
||
| addEbomLine(data) | POST | /mes/md/bom/line |
|
||
| updateEbomLine(data) | PUT | /mes/md/bom/line |
|
||
| deleteEbomLine(ids) | DELETE | /mes/md/bom/line/{bomIds} |
|
||
|
||
---
|
||
|
||
## 5. 生产计划单场景联调要点
|
||
|
||
- **选择EBOM单弹窗（7.6.4）**：打开弹窗时调用 `GET /mes/md/bom/list`，建议带 `status=APPROVED`、可选 `itemCode`（引入产品）筛选；选中一条后点确定，前端将 `bomCode`/`version`/`versionDesc` 回填表头。
|
||
- **EBOM 详情查看（7.6.5）**：点击「查看」时调用 `GET /mes/md/bom/{bomId}`，展示表头 + `lines`（子件明细）。
|
||
- **列表分页与导出**：列表使用 `pageNum`、`pageSize`；导出使用 GET `/mes/md/bom/export` 且响应为 blob，与前端 `exportEbom` 一致。
|
||
|
||
---
|
||
|
||
## 6. 建议测试顺序
|
||
|
||
1. 列表：GET `/mes/md/bom/list`（无参、带 status、带 itemCode）。
|
||
2. 详情：GET `/mes/md/bom/{bomId}`，校验含 `lines`。
|
||
3. 新增：POST `/mes/md/bom`，再查列表/详情确认。
|
||
4. 修改：PUT `/mes/md/bom`。
|
||
5. 审核/反审核：PUT `/mes/md/bom/approve`、PUT `/mes/md/bom/reject`，再查详情校验 status。
|
||
6. 导出：GET `/mes/md/bom/export`，保存为 Excel 并打开。
|
||
7. 明细：GET `/mes/md/bom/line/list?bomCode=xxx`，POST/PUT/DELETE 明细，再查表头详情校验 `lines`。
|
||
|
||
---
|
||
|
||
## 7. 测试脚本执行说明
|
||
|
||
已提供脚本 **`run-ebom-api-tests.sh`**（与本文档同目录），按上述顺序自动调用各接口并汇总通过/失败。
|
||
|
||
**前置条件：**
|
||
|
||
- 后端已启动（如 `mvn spring-boot:run -pl ktg-admin`），且数据库、Redis 可用。
|
||
- 若系统开启验证码，需在管理端关闭验证码，或先登录获取 Token 后设置环境变量再执行脚本。
|
||
|
||
**执行方式：**
|
||
|
||
```bash
|
||
cd mom-backend/docs/Testing
|
||
./run-ebom-api-tests.sh
|
||
```
|
||
|
||
**环境变量（可选）：**
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| BASE_URL | http://localhost:8080 | 后端根地址 |
|
||
| TOKEN | （空则自动登录） | 若已持有 Token，可直接设置，跳过登录 |
|
||
| USERNAME | admin | 自动登录时的用户名 |
|
||
| PASSWORD | admin123 | 自动登录时的密码 |
|
||
| RESULT_DIR | ./test-results | 响应与报告输出目录 |
|
||
|
||
**示例：指定地址与 Token：**
|
||
|
||
```bash
|
||
export BASE_URL=http://192.168.8.66:8080
|
||
export TOKEN=eyJhbGciOiJIUzUxMiJ9...
|
||
./run-ebom-api-tests.sh
|
||
```
|
||
|
||
**输出：**
|
||
|
||
- 控制台与 `RESULT_DIR` 下时间戳报告文件（如 `ebom-api-test-20260126-214351.txt`）中会打印每条用例的 **PASS/FAIL** 及最终 **PASS/FAIL 数量**。
|
||
- 各接口响应 JSON 保存在 `RESULT_DIR/response_<用例名>.json`，便于排查失败原因。
|