基础资料接口文档

本文档描述 ERP 基础资料模块的管理端接口。接口实现位于 yq-erp-server/src/modules/info，前端主要通过 service.info.* 调用。

通用约定

管理端基础路径：/admin/info。
请求需要携带后台登录态和权限；列表数据默认受当前登录用户部门权限影响。
CoolAdmin 标准接口由 @CoolController 生成。除特别说明外，方法和参数如下：

方法	路径	说明	主要参数
POST	`/<资源>/add`	新增记录	body 为实体字段
POST	`/<资源>/update`	更新记录	body 至少包含 `id`，其余为要更新字段
POST	`/<资源>/delete`	删除记录	`ids: number[]`
GET/POST	`/<资源>/info`	查询单条	`id`
GET/POST	`/<资源>/list`	查询列表	资源支持的筛选字段
GET/POST	`/<资源>/page`	分页查询	`page`、`size`、筛选字段、排序字段

标准响应遵循项目统一返回格式；业务服务方法通常只返回 data 部分。分页结果包含 list、pagination 或 CoolAdmin 默认分页结构。

状态口径

客户、供应商、物料等带审核的资料共用基础状态口径，服务端枚举集中在 src/modules/info/utils.ts。

状态值	语义	常见页面行为
`0`	待审核或草稿	可编辑、可发起审核
`1`	审核中	不应重复发起审核，可查看审核详情
`2`	审核驳回	可重做审核
`100`	正常/启用/生效	可被业务单据引用
`110`	停用/失效	通常不可被新业务引用
`111`	终止类状态	保留历史，不作为正常可用资料

BOM、员工等资源有自己的状态枚举，见对应资源说明。

客户

资源路径：/admin/info/customer

接口	方法	说明
`/add`	POST	新增客户。服务会生成或校验客户编号，并规范联系人邮箱字段。
`/update`	POST	更新客户基础资料、结算资料、联系人资料。
`/delete`	POST	删除客户。业务引用存在时应谨慎使用。
`/info`	GET/POST	查询客户详情。
`/list`	GET/POST	查询客户列表，可用于下拉选择。
`/page`	GET/POST	客户分页查询，返回当前审核节点等审核元数据。
`/changeStatus`	POST	手动变更客户状态。
`/initReview`	POST	发起客户审核。
`/redoReview`	POST	重新发起客户审核或回退重做。
`/exportToExcel`	POST	导出客户资料。
`/testAdd`	POST	开发/导入辅助：按导入行结构测试新增客户。

关键字段：

字段	说明
`code`	客户编号。
`shortname`	客户简称，业务单据常用显示字段。
`name`	客户全称。
`paymentMethod`	付款方式。
`statementDay`	对账截止日。
`taxRate`	税率。
`currency`	币别。
`email`	主收件邮箱，支持 0-n 个地址，后端以文本保存。
`ccEmail`	抄送邮箱，支持 0-n 个地址。
`salesman`、`salesmanId`	业务员名称和用户 ID。
`status`	客户状态。

特殊接口参数：

json

POST /admin/info/customer/changeStatus
{
  "id": 1,
  "status": 100
}

json

POST /admin/info/customer/initReview
{
  "code": ["KH0001", "KH0002"]
}

json

POST /admin/info/customer/redoReview
{
  "code": "KH0001",
  "reverse": false
}

导出接口可传当前筛选条件，或传 ids 导出选中客户。

供应商

资源路径：/admin/info/supplier

接口	方法	说明
`/add`	POST	新增供应商，规范邮箱字段并生成/校验供应商编号。
`/update`	POST	更新供应商资料。
`/delete`	POST	删除供应商。
`/info`	GET/POST	查询供应商详情。
`/list`	GET/POST	查询供应商列表。
`/page`	GET/POST	供应商分页查询，返回绑定仓库和审核元数据。
`/changeStatus`	POST	手动变更供应商状态。
`/getEmailInfo`	GET	按供应商简称查询收件邮箱信息。
`/initReview`	POST	发起供应商审核。
`/redoReview`	POST	重新发起供应商审核或回退重做。
`/exportToExcel`	POST	导出供应商资料。
`/test-import-excel-row`	POST	开发/导入辅助：测试单行 Excel 供应商导入解析。
`/testAdd`	POST	开发/导入辅助：按导入行结构测试新增供应商。

关键字段：

字段	说明
`code`	供应商编号。
`shortname`	供应商简称。
`name`	供应商全称。
`paymentMethod`	付款方式。
`billType`	票据类型。
`taxRate`	税率。
`statementDay`	对账截止日。
`includeFreight`	是否含运费。
`isOutsource`	是否委外供应商。
`email`	主收件邮箱，采购订单通知依赖该字段。
`ccEmail`	抄送邮箱。
`warehouse`	通过仓库绑定关系返回的关联仓库。
`status`	供应商状态。

/getEmailInfo 示例：

http

GET /admin/info/supplier/getEmailInfo?shortname=耀强供应商

返回供应商主收件与抄送信息，供采购订单邮件草稿合并使用。供应商未配置主收件邮箱时，采购订单通知草稿会被后端拦截。

物料

资源路径：/admin/info/materials/base_material

接口	方法	说明
`/add`	POST	新增物料。
`/update`	POST	更新物料基础字段。
`/delete`	POST	删除物料。
`/info`	GET/POST	查询物料详情。
`/list`	GET/POST	查询物料列表，常用于选择器。
`/page`	GET/POST	物料分页查询，支持物料编码、名称、规格、类型、客户/供应商料号等筛选。
`/getMaterialExcel`	POST	导出物料资料。
`/getManuBomExcel`	POST	导出生产 BOM。
`/getCostBomExcel`	POST	导出成本 BOM。
`/initReview`	POST	发起物料审核。
`/redoReview`	POST	重新发起物料审核或回退重做。
`/upload`	POST	上传/更新物料附件 URL。
`/testAdd`	POST	开发/导入辅助：按导入行结构测试新增物料。

关键字段：

字段	说明
`code`	物料编码。
`name`	物料名称。
`model`	规格型号。
`type`、`typeId`	物料类型。
`property`	物料属性。
`defaultMeasurement`	默认计量单位。
`customerCode` / `customerMaterialCode`	物料主数据中的客户料号信息。下游销售链路应优先使用销售订单明细确认的客户料号。
`supplierCode`	供应商料号信息。
`packagingId`、`packaging`	包装方式。
`status`	物料审核/启停状态。

附件接口：

json

POST /admin/info/materials/base_material/upload
{
  "code": "WL0001",
  "urls": ["https://.../drawing.pdf", "https://.../photo.png"]
}

导出接口均支持：

json

{
  "ids": [1, 2, 3]
}

未传 ids 时按当前查询条件导出。

物料历史

资源路径：/admin/info/materials/base_material_history

标准接口：add、delete、update、info、list、page。

分页支持按 code 精确筛选，用于查看某个物料编码的历史版本或变更记录。

物料编码

编码类别

资源路径：/admin/info/materials/encode/type

标准接口：add、delete、update、info、list、page。

关键字段：

字段	说明
`name`	编码类别名称。
`length`	编码总长度。
`isProduct`	是否成品类别。
`departmentId`	所属部门。

编码位

资源路径：/admin/info/materials/encode/position

标准接口：add、delete、update、info、list、page。

关键字段：

字段	说明
`name`	码位名称。
`typeId`	所属编码类别。
`startPos`、`endPos`	起止位置。
`remark`	说明。

编码值

资源路径：/admin/info/materials/encode/code

标准接口：add、delete、update、info、list、page。

关键字段：

字段	说明
`code`	代码。
`description`	描述。
`positionId`	所属码位。

物料编码生成还会调用基础模块的 commGetSNCode 获取流水号；流水号码位通常使用 X 作为占位。

BOM

BOM 主表

资源路径：/admin/info/materials/bom

接口	方法	说明
`/add`	POST	新增 BOM 版本。
`/update`	POST	更新 BOM 主表。
`/delete`	POST	删除 BOM。
`/info`	GET/POST	查询 BOM 详情。
`/list`	GET/POST	查询 BOM 列表。
`/page`	GET/POST	BOM 分页，关联物料编码、名称、规格等信息。
`/setDefault`	POST	设置物料默认 BOM 版本。
`/changeStatus`	POST	启用或停用 BOM。
`/updateCostBomPrice`	POST	更新成本 BOM 价格。
`/commGetDirectBomMaterials`	GET	获取直接下级 BOM 用料。
`/commGetBomVersion`	GET	获取某物料所有 BOM 版本。
`/copy`	POST	从另一个 BOM 复制明细到当前 BOM。
`/testAddManuBomMaterial`	POST	开发/导入辅助：按表单结构测试新增生产 BOM 明细。

关键字段：

字段	说明
`materialId`	BOM 所属物料。
`version`	BOM 版本。
`type`	BOM 类型，常见为生产 BOM 或成本 BOM。
`isDefault`	是否默认版本。
`status`	BOM 状态。
`childrenPrice`、`calcPrice`	成本计算相关价格字段。

接口示例：

json

POST /admin/info/materials/bom/setDefault
{
  "id": 10
}

json

POST /admin/info/materials/bom/changeStatus
{
  "id": 10,
  "status": 100
}

http

GET /admin/info/materials/bom/commGetDirectBomMaterials?materialId=1&quantity=100

json

POST /admin/info/materials/bom/copy
{
  "currentBomId": 20,
  "copyFromId": 10
}

BOM 明细

资源路径：/admin/info/materials/bom_material

接口	方法	说明
`/add`	POST	新增 BOM 明细。
`/update`	POST	更新 BOM 明细。
`/delete`	POST	删除 BOM 明细。
`/info`	GET/POST	查询明细。
`/list`	GET/POST	查询明细列表。
`/page`	GET/POST	查询生产 BOM 树或成本 BOM 汇总。
`/commGetParentBoms`	GET	查询使用某物料的上级 BOM。
`/commGetRootBoms`	GET	查询某物料所在的根 BOM。

关键字段：

字段	说明
`parentBomId`	上级 BOM ID。
`materialId`	子项物料 ID。
`bomId`	子项自身 BOM ID，可为空。
`quantity`	单位用量。
`lossRatio`	损耗比。

/page 常用参数：

参数	说明
`bomId`	当前 BOM ID。
`materialId`	根物料 ID。
`type`	`MANU` 返回生产 BOM 树；`COST` 返回成本 BOM 汇总。
`skipGenerateExplosion`	是否跳过重新生成展开表。
`maxExecutionTimeMs`	可选 SQL 最大执行时间。

替代物料与检验标准

替代物料

资源路径：/admin/info/materials/substitution

标准接口：add、delete、info、list、page。

关键字段：

字段	说明
`materialId`	原物料。
`subMaterialId`	替代物料。
`description`	替代说明。

分页返回会关联原物料和替代物料的编码、名称、规格。采购请购可使用替代物料；生产排单是否可选需按业务规则限制。

检验类型

资源路径：/admin/info/materials/inspection_type

标准接口：add、delete、update、info、list、page。

字段：name、code、remark。

物料检验标准

资源路径：/admin/info/materials/inspection

标准接口：add、delete、update、info、list、page。

关键字段：inspectionTypeId、standard、upperLimit、lowerLimit、materialId、operatorId、operator、remark。

仓库

资源路径：/admin/info/warehouse

接口	方法	说明
`/add`	POST	新增仓库。
`/update`	POST	更新仓库资料或绑定关系。
`/delete`	POST	删除仓库。
`/info`	GET/POST	查询仓库详情。
`/list`	GET/POST	查询仓库树或仓库列表。
`/page`	GET/POST	分页查询仓库，返回供应商、车间、机台绑定名称。
`/setDefault`	POST	设置部门默认仓库。

关键字段：

字段	说明
`code`	仓库编号。
`name`	仓库名称。
`parentId`	上级仓库。
`departmentId`	所属部门。
`isDefault`	是否部门默认仓库。
`isTemp`	是否暂存/临时仓。
`isVirtual`	是否虚拟仓。
`supplierId`	绑定供应商。
`machineId`	绑定机台。
`workshopId`	绑定车间。

常用 list 参数：

参数	说明
`isRoot: 1`	只查询根仓库。
`noChild: 1`	查询叶子仓库或不带子级结构的数据。
`isVirtual`	按是否虚拟仓筛选。

设置默认仓库：

json

POST /admin/info/warehouse/setDefault
{
  "item": {
    "id": 1,
    "departmentId": 5
  }
}

同一部门通常只应保留一个默认仓库。采购入库、生产入库、销售出库、领料出库、退料入库等流程会优先使用部门默认仓。

车间与机台

车间

资源路径：/admin/info/workshop

标准接口：add、delete、update、info、list、page。

关键字段：

字段	说明
`code`	车间编号。
`name`	车间名称。
`departmentId`	所属部门。
`baseLaborPrice`	基础人工价格，用于工艺路线工价计算。
`warehouse`	绑定仓库名称，来自仓库关联。

生产领料/退料需要车间绑定仓库。

机台

资源路径：/admin/info/machine

接口	方法	说明
标准 CRUD	-	`add`、`delete`、`update`、`info`、`list`、`page`。
`/commGetTypeModel`	GET	获取机台类型/型号组合，用于工序或工艺路线选择。

关键字段：

字段	说明
`departmentId`	所属部门。
`type`	机台类型。
`code`	机台编号，唯一。
`model`	机台型号。
`assetId`	关联固定资产 ID。
`workshopId`、`workshop`	车间 ID 和名称。
`warehouse`	绑定虚拟仓名称。
`remark`	备注。

固定资产

资源路径：/admin/info/asset

接口	方法	说明
标准 CRUD	-	`add`、`delete`、`update`、`info`、`list`、`page`。
`/getMachineById`	GET	根据固定资产 ID 查询已关联机台。

关键字段：

字段	说明
`departmentId`	所属部门。
`name`、`code`	资产名称和编号。
`supplierId`、`supplier`	供应商。
`position`	位置。
`model`	型号。
`status`	资产状态。
`bookDate`、`useDate`	入账日期、使用日期。
`originalValue`、`netResidualValue`、`depreciation`、`netValue`	折旧和净值相关字段。
`managerId`	负责人 ID。
`isMachine`	是否机台。
`contract`、`invoice`、`payment`	合同、发票、付款单附件。

/getMachineById 示例：

http

GET /admin/info/asset/getMachineById?id=100

员工

资源路径：/admin/info/employee

接口	方法	说明
标准 CRUD	-	`add`、`delete`、`update`、`info`、`list`、`page`。
`/bindBaseSysUser`	POST	绑定员工和后台系统用户。
`/setStatus`	POST	启用/禁用员工，并同步绑定账号状态。

关键字段：

字段	说明
`code`	工号。
`name`	姓名。
`entryDate`	入职日期。
`phone`、`email`	联系方式。
`sex`	性别。
`workshopId`	所属车间。
`baseSysUserId`	绑定的 ERP 后台用户 ID。
`isPiecework`	是否参与计件。
`status`	员工状态。

绑定用户：

json

POST /admin/info/employee/bindBaseSysUser
{
  "employeeId": 1,
  "baseSysUserId": 100
}

启停员工：

json

POST /admin/info/employee/setStatus
{
  "ids": [1, 2],
  "status": 100
}

工序与工艺路线

工序

资源路径：/admin/info/manufacture/process

标准接口：add、delete、update、info、list、page。

关键字段：

字段	说明
`type`	工序类别。
`name`	工序名称。
`materialType`	适用物料类型。
`fixedLoss`	固定损耗。
`lossRatio`	损耗率。
`ratio`	工序数量比例。计件目标数量按 `work.quantity * ratio` 计算。
`workingHours`	工时。
`pieceworkUnitPrice`	计件单价。
`isCommon`	是否通用工序。

工序机台能力

资源路径：/admin/info/manufacture/process_machine

标准接口：add、delete、update、info、list、page。

字段：processId、machineTypeModel、capacity、priority。

用于按工序维护适配机台类型/型号及产能。分页可按 processId 筛选。

工序规则

资源路径：/admin/info/manufacture/process_rule

标准接口：add、delete、update、info、list、page。

用于维护工序的业务规则，字段以实体定义为准。当前主要服务工艺路线、计件和排产相关逻辑。

工艺路线

资源路径：/admin/info/manufacture/routing

标准接口：add、delete、update、info、list、page。

关键字段：

字段	说明
`materialId`	适用物料。
`workshopId`	车间。
`machineTypeModel`	机台类型/型号。
`capacity`	产能/H。
`priority`	优先级。
`speed`	开机速度。
`temperature`	温度。
`color`	颜色。
`unit`	单位。
`measurement`	计量方式。
`price`	工艺路线单价合计。

分页查询会关联物料编码、名称、规格。

工艺路线工序

资源路径：/admin/info/manufacture/routing_process

接口	方法	说明
标准 CRUD	-	`add`、`delete`、`update`、`info`、`list`、`page`。
`/testAdd`	POST	开发/导入辅助：按导入行结构测试新增工艺路线工序。

关键字段：

字段	说明
`routingId`	工艺路线 ID。
`processId`	工序 ID。
`pieceworkUnitPrice`	计件单价。
`seq`	顺序号。

分页常按 routingId 查询，并关联工序名称、比例、工时、单价等信息。

通用资料

币别

资源路径：/admin/info/currency

标准接口：add、delete、update、info、list、page。

字段：name、code、orderNum。客户、供应商、报价、采购/销售单据会引用币别。

汇率

资源路径：/admin/info/currency_rate

标准接口：add、delete、update、info、list、page。

字段：currencyId、rate。分页服务会关联币别信息。

票据类型

资源路径：/admin/info/bill_type

标准接口：add、delete、update、info、list、page。

字段：name、taxRate。客户、供应商资料会引用该字段。

付款方式

资源路径：/admin/info/payment_method

标准接口：add、delete、update、info、list、page。

字段以实体为准，主要用于客户、供应商结算信息。

计量单位类别

资源路径：/admin/info/measurement_type

标准接口：add、delete、update、info、list、page。

计量单位

资源路径：/admin/info/measurement

标准接口：add、delete、update、info、list、page。

关键字段：code、name、baseQuantity、baseMeasurement、typeId。物料、包装、BOM、库存和生产都会引用计量单位。

包装方式

资源路径：/admin/info/packaging

标准接口：add、delete、update、info、list、page。

关键字段：code、name、description、baseQuantity、baseMeasurement、unitWeight、remark。

周转类型

资源路径：/admin/info/revolve_type

标准接口：add、delete、update、info、list、page。

用于库存周转相关基础分类。

周转物料

资源路径：/admin/info/revolve_material

标准接口：add、delete、update、info、list、page。

用于维护周转物料基础信息，库存周转业务会引用。

铜价

资源路径：/admin/info/copper_price

标准接口：add、info、list、page。

关键字段：price、creatorId、creator。新增时通常记录当前制单人；服务内部提供 getPrice() 给采购铜价相关业务读取最近价格。

查询与导出建议

page 查询的排序字段应使用后端白名单支持的字段，不要从前端透传任意 SQL 字段。
下拉选择优先使用 list，大表选择器优先使用带筛选的 page。
带审核的资料进入业务单据时，应优先筛选正常状态，必要时前端显式传 status: 100 或后端服务内限定。
客户料号在下游销售到采购/生产链路中，应优先使用销售订单明细确认值 erp_sale_order_material.customerMaterialCode；物料主数据 info_base_material.customerCode 只能作为 fallback。
导出接口支持 ids 时，选中行导出传 ids；未选中行导出传当前筛选条件并由用户确认，避免误导出全量数据。

基础信息

业务流程

基础资料接口文档 ​

通用约定 ​

状态口径 ​

客户 ​

供应商 ​

物料 ​

物料历史 ​

物料编码 ​

编码类别 ​

编码位 ​

编码值 ​

BOM ​

BOM 主表 ​

BOM 明细 ​

替代物料与检验标准 ​

替代物料 ​

检验类型 ​

物料检验标准 ​

仓库 ​

车间与机台 ​

车间 ​

机台 ​

固定资产 ​

员工 ​

工序与工艺路线 ​

工序 ​

工序机台能力 ​

工序规则 ​

工艺路线 ​

工艺路线工序 ​

通用资料 ​

币别 ​

汇率 ​

票据类型 ​

付款方式 ​

计量单位类别 ​

计量单位 ​

包装方式 ​

周转类型 ​

周转物料 ​

铜价 ​

查询与导出建议 ​

基础资料接口文档

通用约定

状态口径

客户

供应商

物料

物料历史

物料编码

编码类别

编码位

编码值

BOM

BOM 主表

BOM 明细

替代物料与检验标准

替代物料

检验类型

物料检验标准

仓库

车间与机台

车间

机台

固定资产

员工

工序与工艺路线

工序

工序机台能力

工序规则

工艺路线

工艺路线工序

通用资料

币别

汇率

票据类型

付款方式

计量单位类别

计量单位

包装方式

周转类型

周转物料

铜价

查询与导出建议