# 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`，便于排查失败原因。