scottpan/my-mom-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fcff3903df236f95377c8a7f71fe4ba93e649919
my-mom-system/mom-backend/docs/Testing/EBOM-API测试文档.md

504 lines
12 KiB
Markdown
Raw Normal View History

readd mom-backend dir
2026-03-06 02:12:34 +08:00
# 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`，便于排查失败原因。
Reference in New Issue Copy Permalink