工业miniAPP API接口设计说明书（赛题适配版）

昆仑杯 更新：2026-01-07 浏览：245 收藏：0 点赞：0

工业miniAPP API接口设计说明书（赛题适配版）

项目名称：工业miniAPP (IndustrialMiniAPP)
文档版本：V1.0
适配规范：iDME 1.24.090-HCS xDM-F API规范、赛题功能要求、SRS V4.0核心功能

接口类型：RESTful API（所有接口均通过xDM-F平台转发，遵循其认证与数据格式要求）

一、接口概述

1.1 接口设计原则

全量适配xDM-F：所有业务操作均通过xDM-F提供的全量数据服务API实现，无绕过平台的直接数据库操作。
功能全覆盖：接口覆盖赛题要求的设备管理、物料管理、工序管理、工艺管理及数据建模相关操作。
统一响应格式：所有接口返回结构一致，包含状态码、提示信息、业务数据及请求追踪ID。
权限强制校验：核心操作接口均需通过iDME Token认证及权限校验，确保数据安全。
错误精准映射：错误码与赛题评分规则、xDM-F平台错误体系对齐，便于问题定位。

1.2 通用信息

1.2.1 基础URL

# 业务实体操作基础URL
POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/{ENTITY_NAME}/{OPERATION}

# 公共服务接口基础URL（如权限校验）
POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/rdm/basic/api/{SERVICE_NAME}/{METHOD}

iDME_ENDPOINT：iDME平台运行态端点（如127.0.0.1:8080）
APP_ID：工业miniAPP在xDM-F平台的应用ID（如IndustrialMiniAPP）
ENTITY_NAME：实体英文名称（如Equipment、Part）
OPERATION：操作类型（如create、update、find）

1.2.2 请求头规范

请求头名称	必选	描述	示例
Content-Type	是	请求体格式	application/json
X-Auth-Token	是	认证Token（iDME平台获取，有效期24小时）	MIIPAgYJKoZIhvcNAQcCo...
X-Project-Id	否	项目ID（专属云场景必填）	8f7a6b5c4d3e2f1a0b9c...

1.2.3 通用响应格式

{
  "code": "0000",          // 状态码：0000成功，E00x系统错误，P00x业务错误，A00x权限错误
  "msg": "操作成功",        // 提示信息
  "data": {},              // 业务数据（成功时返回）
  "requestId": "uuid",     // 请求追踪ID（用于日志排查）
  "timestamp": 1699999999999, // 响应时间戳
  "xdmfErrorCode": ""      // xDM-F平台原始错误码（异常时填充）
}

1.2.4 错误码体系

错误码	错误描述	关联场景
0000	操作成功	所有接口成功响应
E001	设备状态不合法	设备状态变更为无效值
E002	设备被工艺引用，禁止停机/报废	设备状态变更为STOPPED/SCRAPPED时被引用
E003	设备编码已存在	新增设备编码重复
P001	请配置至少1道工序	工艺设计未添加任何工序
P002	非草稿状态不可编辑	工艺非Draft状态下执行修改
P003	物料分类名称已存在	新增物料分类名称重复
P004	仅已提交状态的工艺可生成路线	非Submitted状态工艺执行生成路线
P005	物料已禁用，不可使用	工艺关联已禁用的物料
P006	物料库存不足	工艺所需物料库存小于需求数量
P007	物料不存在	操作的物料在xDM-F中未找到
A001	用户未分配角色，无操作权限	未给用户分配任何角色
A002	用户无xxx权限，操作被拒绝	权限校验未通过

二、核心接口详情

2.1 设备管理模块接口

2.1.1 新增设备

接口用途：录入设备基础信息及扩展属性（赛题设备管理核心接口）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Equipment/create

请求体：

{
  "params": {
    "equipmentCode": "EQ20250001",  // 设备编码（唯一）
    "equipmentName": "五轴加工中心",
    "manufacturer": "DMG MORI",    // 生产厂家
    "brand": "DMG MORI",           // 品牌
    "specification": "CMX 50 U",   // 规格型号
    "supplier": "上海某机械有限公司",// 供应商
    "productionDate": "2025-01-01",// 生产日期（YYYY-MM-DD）
    "serviceLife": "5年",           // 使用年限
    "depreciationMethod": "平均年限法",// 折旧方式（枚举值）
    "location": "车间A区1号工位",    // 位置
    "extAttrs": {                  // 扩展属性（技术参数+备品备件）
      "technicalParams": [
        {"attrName": "功率", "attrValue": "15kW", "attrType": "文本"},
        {"attrName": "转速", "attrValue": "3000rpm", "attrType": "数值"}
      ],
      "spareParts": [
        {"partCode": "SP2025001", "partName": "轴承", "stockQuantity": 10, "unit": "个"}
      ]
    },
    "creator": "user001",           // 创建人（可选，自动填充当前用户）
    "createTime": "2025-01-01T12:00:00" // 创建时间（可选，自动生成）
  }
}

响应示例：

{
  "code": "0000",
  "msg": "设备新增成功",
  "data": {
    "id": "502903940749205504",    // xDM-F生成的设备实例ID
    "equipmentCode": "EQ20250001",
    "equipmentName": "五轴加工中心"
  },
  "requestId": "uuid123",
  "timestamp": 1700000000000,
  "xdmfErrorCode": ""
}

异常场景：
- 设备编码重复 → code: E003，msg: "设备编码已存在"
- 必填字段缺失 → code: P008，msg: "设备名称为必填字段"

2.1.2 修改设备状态

接口用途：更新设备运行状态（RUNNING/STOPPED/MAINTENANCE/SCRAPPED）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Equipment/update

请求体：

{
  "params": {
    "id": "502903940749205504",    // 设备实例ID（xDM-F返回）
    "status": "STOPPED",            // 目标状态
    "lastModifiedBy": "user001",    // 更新人
    "lastUpdateTime": "2025-01-02T10:00:00" // 更新时间（可选）
  }
}

响应示例：

{
  "code": "0000",
  "msg": "设备状态更新成功",
  "data": {
    "id": "502903940749205504",
    "status": "STOPPED",
    "lastUpdateTime": "2025-01-02T10:00:00"
  },
  "requestId": "uuid124",
  "timestamp": 1700000000001,
  "xdmfErrorCode": ""
}

异常场景：
- 设备被工艺引用 → code: E002，msg: "设备被工艺引用，禁止停机/报废"
- 状态值无效 → code: E001，msg: "设备状态不合法"

2.1.3 查询设备列表

接口用途：按条件筛选设备（支持状态、位置等筛选，赛题设备查询要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Equipment/find/20/1
URL参数：
- 20：每页条数（pageSize）
- 1：当前页码（curPage）

请求体：

{
  "params": {
    "filter": {
      "joiner": "and",
      "conditions": [
        {"conditionName": "status", "operator": "=", "conditionValues": ["RUNNING"]},
        {"conditionName": "location", "operator": "like", "conditionValues": ["车间A%"]}
      ]
    },
    "sorts": [{"orderBy": "createTime", "sort": "DESC"}], // 按创建时间倒序
    "isNeedTotal": true // 是否返回总条数
  }
}

响应示例：

{
  "code": "0000",
  "msg": "查询成功",
  "data": {
    "items": [
      {
        "id": "502903940749205504",
        "equipmentCode": "EQ20250001",
        "equipmentName": "五轴加工中心",
        "status": "RUNNING",
        "location": "车间A区1号工位",
        "brand": "DMG MORI",
        "specification": "CMX 50 U"
      }
    ],
    "pageInfo": {
      "curPage": 1,
      "pageSize": 20,
      "totalRows": 1,
      "totalPages": 1
    }
  },
  "requestId": "uuid125",
  "timestamp": 1700000000002,
  "xdmfErrorCode": ""
}

2.2 物料管理模块接口

2.2.1 新增物料

接口用途：录入物料基础信息，支持分类关联（赛题物料管理核心接口）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Part/create

请求体：

{
  "params": {
    "partCode": "P20250001",        // 物料编码（唯一）
    "partName": "高精度齿轮",
    "specification": "M1.5×30×20",  // 规格型号
    "stockQuantity": 100,           // 库存数量（≥0）
    "supplier": "深圳某精密零件厂",  // 供应商
    "categoryId": "6030...",        // 分类ID（关联PartCategory）
    "version": "1.0",               // 初始版本
    "status": "ENABLED",            // 状态（ENABLED/DISABLED）
    "extAttrs": {"material": "45号钢"}, // 扩展属性
    "creator": "user001"
  }
}

响应示例：

{
  "code": "0000",
  "msg": "物料新增成功",
  "data": {
    "id": "7040...",
    "partCode": "P20250001",
    "partName": "高精度齿轮",
    "version": "1.0",
    "status": "ENABLED"
  },
  "requestId": "uuid126",
  "timestamp": 1700000000003,
  "xdmfErrorCode": ""
}

2.2.2 物料升版（版本管理）

接口用途：创建物料新版本（赛题版本管理要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Part/saveAs

请求体：

{
  "params": {
    "sourceInstanceId": "7040...",  // 原物料实例ID
    "version": "1.1",               // 新版本号（x.x格式）
    "modifier": "user001",          // 更新人
    "specification": "M1.5×30×22"  // 新版本修改的属性（仅填变更字段）
  }
}

响应示例：

{
  "code": "0000",
  "msg": "物料升版成功",
  "data": {
    "id": "7041...",
    "partCode": "P20250001",
    "version": "1.1",
    "specification": "M1.5×30×22",
    "status": "ENABLED"
  },
  "requestId": "uuid127",
  "timestamp": 1700000000004,
  "xdmfErrorCode": ""
}

2.2.3 构建BOM（物料组成关系）

接口用途：维护物料间的层级组成关系（赛题BOM管理要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Part_BOM_Rel/create

请求体：

{
  "params": {
    "parentPartId": "P20250002",    // 父物料编码（如行星架）
    "childPartId": "P20250001",     // 子物料编码（如齿轮）
    "quantity": 3,                  // 组成数量（≥0）
    "sequence": 1,                  // 装配顺序（≥1）
    "unit": "个"                    // 计量单位
  }
}

响应示例：

{
  "code": "0000",
  "msg": "BOM关系创建成功",
  "data": {
    "id": "9050...",
    "parentPartId": "P20250002",
    "childPartId": "P20250001",
    "quantity": 3,
    "sequence": 1
  },
  "requestId": "uuid128",
  "timestamp": 1700000000005,
  "xdmfErrorCode": ""
}

2.2.4 搜索物料

接口用途：按编码、名称、分类等属性查询物料（赛题搜索要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Part/find/20/1

请求体：

{
  "params": {
    "filter": {
      "joiner": "or",
      "conditions": [
        {"conditionName": "partCode", "operator": "like", "conditionValues": ["P2025%"]},
        {"conditionName": "partName", "operator": "like", "conditionValues": ["齿轮%"]},
        {"conditionName": "categoryId", "operator": "=", "conditionValues": ["6030..."]}
      ]
    },
    "sorts": [{"orderBy": "partCode", "sort": "ASC"}],
    "isNeedTotal": true
  }
}

响应示例：同设备列表查询，data.items返回匹配的物料列表

2.3 工序及工艺管理模块接口

2.3.1 预置工序（系统初始化）

接口用途：系统启动时创建5道固定工序（赛题配置工序要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/WorkingProcedure/create

请求体（批量创建，单次创建1道，循环5次）：

{
  "params": {
    "code": "WP001",                // 工序编码（WP001-WP005）
    "name": "毛坯制造",              // 工序名称（固定5个）
    "productionSteps": "1. 铸造原料；2. 锻造成型；3. 初步打磨", // 生产步骤
    "defaultDuration": 60,          // 默认时长（分钟）
    "description": "行星减速器零件毛坯加工",
    "creator": "system"             // 系统预置标识
  }
}

响应示例：

{
  "code": "0000",
  "msg": "工序创建成功",
  "data": {
    "id": "8060...",
    "code": "WP001",
    "name": "毛坯制造"
  },
  "requestId": "uuid129",
  "timestamp": 1700000000006,
  "xdmfErrorCode": ""
}

2.3.2 新增工艺

接口用途：创建工艺基础信息，关联产品（赛题工艺管理要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/WorkingPlan/create

请求体：

{
  "params": {
    "planId": "PL20250001",         // 工艺ID（唯一）
    "planName": "中心轮加工工艺",
    "productName": "精密行星减速器", // 所属产品
    "version": "1.0",               // 工艺版本
    "description": "中心轮零件全流程加工工艺",
    "operator": "user002",          // 操作人员
    "operationTime": "2025-01-03T09:00:00",
    "status": "Draft"               // 初始状态（Draft）
  }
}

响应示例：

{
  "code": "0000",
  "msg": "工艺创建成功",
  "data": {
    "id": "1070...",
    "planId": "PL20250001",
    "planName": "中心轮加工工艺",
    "status": "Draft"
  },
  "requestId": "uuid130",
  "timestamp": 1700000000007,
  "xdmfErrorCode": ""
}

2.3.3 工艺关联工序

接口用途：绑定工艺与工序的关联关系及执行顺序（赛题工艺-工序关联要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Plan_Procedure_Rel/create

请求体（批量创建，单次创建1个关联）：

{
  "params": {
    "sourcePlanId": "PL20250001",   // 工艺ID
    "targetProcedureCode": "WP001", // 工序编码
    "sequence": 1                   // 执行顺序（1-5）
  }
}

响应示例：

{
  "code": "0000",
  "msg": "工艺-工序关联成功",
  "data": {
    "id": "1180...",
    "sourcePlanId": "PL20250001",
    "targetProcedureCode": "WP001",
    "sequence": 1
  },
  "requestId": "uuid131",
  "timestamp": 1700000000008,
  "xdmfErrorCode": ""
}

2.3.4 工序关联设备/物料

接口用途：绑定工序与资源的关联关系及数量（赛题工序-资源关联要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/Procedure_Resource_Rel/create

请求体：

{
  "params": {
    "sourceRelationId": "1180...",  // 工艺-工序关系ID
    "targetType": "DEVICE",         // 资源类型（DEVICE/PART）
    "targetId": "EQ20250001",       // 设备编码/物料编码
    "quantity": 1                   // 资源数量
  }
}

响应示例：

{
  "code": "0000",
  "msg": "工序-资源关联成功",
  "data": {
    "id": "1290...",
    "sourceRelationId": "1180...",
    "targetType": "DEVICE",
    "targetId": "EQ20250001",
    "quantity": 1
  },
  "requestId": "uuid132",
  "timestamp": 1700000000009,
  "xdmfErrorCode": ""
}

2.3.5 生成工艺路线

接口用途：基于已提交的工艺生成固定名称和版本的工艺路线（赛题核心要求）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/dynamic/api/ProcessRoute/create

请求体：

{
  "params": {
    "planName": "中心轮零件加工",    // 固定名称（赛题要求）
    "version": "1.0",               // 固定初始版本（赛题要求）
    "status": "Published",          // 默认发布状态
    "planId": "PL20250001",         // 关联工艺ID
    "creator": "user002"
  }
}

响应示例：

{
  "code": "0000",
  "msg": "工艺路线生成成功",
  "data": {
    "routeId": "1300...",
    "planName": "中心轮零件加工",
    "version": "1.0",
    "status": "Published",
    "planId": "PL20250001"
  },
  "requestId": "uuid133",
  "timestamp": 1700000000010,
  "xdmfErrorCode": ""
}

2.4 权限管理接口

2.4.1 权限校验

接口用途：校验用户是否拥有目标操作权限（所有核心接口前置校验）
请求URL：POST http://{iDME_ENDPOINT}/rdm_{APP_ID}_app/services/rdm/basic/api/AccessService/batchHasAccess

请求体：

{
  "params": {
    "userId": "user001",            // 用户ID
    "rdmExtensionType": "SystemPermission", // 权限类型
    "operations": ["EQUIPMENT_STATUS_UPDATE"], // 待校验权限编码
    "ids": ["EQUIPMENT_STATUS_UPDATE"] // 权限ID（与operations一致）
  }
}

响应示例：

{
  "code": "0000",
  "msg": "权限校验成功",
  "data": {
    "EQUIPMENT_STATUS_UPDATE": true // true有权限，false无权限
  },
  "requestId": "uuid134",
  "timestamp": 1700000000011,
  "xdmfErrorCode": ""
}

三、接口调用流程示例

3.1 工艺路线创建完整流程

预置工序：调用WorkingProcedure/create接口，创建WP001-WP005共5道工序
新增工艺：调用WorkingPlan/create接口，创建工艺（状态Draft）
工艺关联工序：调用Plan_Procedure_Rel/create接口，绑定5道工序及顺序
工序关联资源：调用Procedure_Resource_Rel/create接口，绑定设备/物料
提交工艺：调用WorkingPlan/update接口，将工艺状态更新为Submitted
生成工艺路线：调用ProcessRoute/create接口，生成“中心轮零件加工V1.0”

3.2 关键约束校验流程

设备状态变更：调用Equipment/update前，先通过batchHasAccess校验权限，再查询是否被工艺引用
工艺提交：调用WorkingPlan/update前，校验工序是否齐全、设备是否运行中、物料库存是否充足

四、接口调用清单（赛题提交要求）

功能模块	核心接口（POST）	用途	赛题对应要求
设备管理	Equipment/create	新增设备	设备信息录入
设备管理	Equipment/update	修改设备状态/信息	设备信息修改
设备管理	Equipment/find	查询设备列表	设备查询统计
设备管理	Equipment/delete	删除设备	设备删除
物料管理	Part/create	新增物料	物料信息录入
物料管理	Part/saveAs	物料升版	版本管理
物料管理	Part/find	搜索物料	物料搜索查看
物料管理	Part_BOM_Rel/create	构建BOM	BOM管理
物料管理	PartCategory/create	创建物料分类	分类管理
工序管理	WorkingProcedure/create	预置工序	配置5道工序
工艺管理	WorkingPlan/create	新增工艺	工艺配置
工艺管理	Plan_Procedure_Rel/create	工艺-工序关联	工序关联
工艺管理	Procedure_Resource_Rel/create	工序-资源关联	设备/物料关联
工艺管理	ProcessRoute/create	生成工艺路线	配置工艺路线
权限管理	AccessService/batchHasAccess	权限校验	操作权限控制

五、附录：接口调试工具与注意事项

5.1 调试工具

Postman：直接填写URL、请求头、请求体，支持Token自动携带

curl命令：适用于命令行调试，示例：

curl -X POST "http://127.0.0.1:8080/rdm_IndustrialMiniAPP_app/services/dynamic/api/Equipment/create" \ 
-H "Content-Type: application/json" \ 
-H "X-Auth-Token: MIIPAgYJKoZIhvcNAQcCo..." \ 
-d '{"params":{"equipmentCode":"EQ20250001","equipmentName":"五轴加工中心",...}}'

5.2 注意事项

所有接口均需通过xDM-F平台转发，禁止直接操作数据库
Token有效期为24小时，过期后需重新从iDME平台获取
批量操作（如批量创建工序）需循环调用单条创建接口，xDM-F暂不支持批量提交
日期格式需严格遵循ISO8601规范（如YYYY-MM-DD、YYYY-MM-DDTHH:MM:SS）
数值类型字段（如库存数量）需传入数字，禁止字符串格式

无权限

工业miniAPP API接口设计说明书（赛题适配版）

工业miniAPP API接口设计说明书（赛题适配版）

接口类型：RESTful API（所有接口均通过xDM-F平台转发，遵循其认证与数据格式要求）

一、接口概述

1.1 接口设计原则

1.2 通用信息

1.2.1 基础URL

1.2.2 请求头规范

1.2.3 通用响应格式

1.2.4 错误码体系

二、核心接口详情

2.1 设备管理模块接口

2.1.1 新增设备

2.1.2 修改设备状态

2.1.3 查询设备列表

2.2 物料管理模块接口

2.2.1 新增物料

2.2.2 物料升版（版本管理）

2.2.3 构建BOM（物料组成关系）

2.2.4 搜索物料

2.3 工序及工艺管理模块接口

2.3.1 预置工序（系统初始化）

2.3.2 新增工艺

2.3.3 工艺关联工序

2.3.4 工序关联设备/物料

2.3.5 生成工艺路线

2.4 权限管理接口

2.4.1 权限校验

三、接口调用流程示例

3.1 工艺路线创建完整流程

3.2 关键约束校验流程

四、接口调用清单（赛题提交要求）

五、附录：接口调试工具与注意事项

5.1 调试工具

5.2 注意事项

评论

￥{{ payArticleData.total_amount }}

￥{{ payArticleData.total_amount }}

登录 / Login

社交账号登录