Files

panchengyong 442bc4f028 readd mom-backend dir

2026-03-06 02:12:34 +08:00

12 KiB

Raw Blame History

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

响应示例：

{
  "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 表头主键

响应示例：

{
  "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`

请求体示例：

{
  "bomCode": "BOM002",
  "bomName": "新BOM",
  "itemId": 100,
  "itemCode": "ITEM01",
  "itemName": "产品A",
  "unitName": "台",
  "baseQty": 1,
  "version": "V1.0",
  "versionDesc": "初版",
  "status": "DRAFT",
  "enableFlag": "Y",
  "remark": "备注"
}

响应示例：

{
  "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。

响应示例：

{
  "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`

请求体：

{
  "bomId": 1
}

响应示例：

{
  "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`

请求体：

{
  "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	否	每页条数

响应示例：

{
  "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`

请求体示例：

{
  "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. 建议测试顺序

列表：GET /mes/md/bom/list（无参、带 status、带 itemCode）。
详情：GET /mes/md/bom/{bomId}，校验含 lines。
新增：POST /mes/md/bom，再查列表/详情确认。
修改：PUT /mes/md/bom。
审核/反审核：PUT /mes/md/bom/approve、PUT /mes/md/bom/reject，再查详情校验 status。
导出：GET /mes/md/bom/export，保存为 Excel 并打开。
明细：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 后设置环境变量再执行脚本。

执行方式：

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：

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

12 KiB Raw Blame History Unescape Escape

EBOM / 产品BOM 后端 API 测试文档

1. 约定说明

2. BOM 表头接口（MdBomController）

2.1 查询 BOM 列表（分页）

2.2 获取 BOM 详情（含明细行）

2.3 新增 BOM 表头

2.4 修改 BOM 表头

2.5 删除 BOM 表头

2.6 审核 EBOM

2.7 反审核 EBOM

2.8 导出 BOM 列表（GET）

3. BOM 明细行接口（MdProductBomController）

3.1 查询 BOM 明细列表（分页）

3.2 获取单条 BOM 明细

3.3 新增 BOM 明细

3.4 修改 BOM 明细

3.5 删除 BOM 明细

4. 前端与后端接口对照表

5. 生产计划单场景联调要点

6. 建议测试顺序

7. 测试脚本执行说明

12 KiB

Raw Blame History