适用范围： 中大型制造型企业 iPaaS 集成平台
规范类型： 对外 API URL 命名与设计规范
状态： 建议实施标准
1. 编制目的
为规范中大型制造型企业 iPaaS（Integration Platform as a Service，集成平台）对外 API 接口设计，建立统一、标准化、可扩展、易维护的企业业务 API 体系，制定本规范。
通过统一 URL 命名和接口设计标准，实现：
- 业务统一： 不同业务系统使用统一的业务领域和资源命名。
- 系统解耦： 对外 API 不暴露 MES、ERP、WMS、SAP 等底层系统名称。
- 标准化： 统一 URL 结构、HTTP 方法、资源命名和业务动作。
- 可扩展： 支持企业业务扩展、新系统接入及多租户部署。
- 易集成： 降低第三方系统、合作伙伴和 AI Agent 的接口调用成本。
- 统一治理： 支持 API 注册、发布、授权、监控、版本管理和生命周期管理。
本规范适用于所有通过 iPaaS 对外发布的业务 API，包括企业内部系统集成接口、第三方应用接口、数据服务接口和智能体调用接口。
2. 总体设计原则
2.1 业务领域优先原则
URL 应体现企业业务领域，而不是底层业务系统。
推荐：
/manufacturing/v1/work-orders
/equipment/v1/equipments
/warehouse/v1/inventory禁止：
/mes/api/work-order/list
/erp/sap/purchase-order/query
/wms/interface/inventory/get无论底层使用 MES、ERP、WMS、SAP、用友、金蝶或企业自研系统，对外均应提供统一的业务 API。
2.2 资源导向原则
API 应围绕业务资源进行组织，资源名称应体现真实的企业业务对象。
例如：
- work-orders：生产工单
- equipments：设备
- materials：物料
- inventory：库存
- suppliers：供应商
- alarms：报警
- telemetry：工业时序数据
2.3 统一命名原则
所有 API 应统一采用小写英文命名，单词之间使用连字符 - 分隔。
推荐：
/production-plans
/equipment-alarms
/maintenance-records禁止：
/ProductionPlans
/productionPlans
/production_plans2.4 系统解耦原则
对外 URL 不允许包含底层业务系统名称、厂商名称、服务器名称、数据库名称和具体连接器名称。
底层系统映射由 iPaaS 内部连接器和路由配置完成。
2.5 兼容性原则
已正式发布的 API 不得随意改变资源含义、请求结构和响应结构。
不兼容变更必须通过新版本发布。
3. URL 总体结构
3.1 标准格式
统一采用以下 URL 结构：
/{domain}/{version}/{resource}对于需要执行明确业务动作的接口，采用：
/{domain}/{version}/{resource}/{id}/{action}对于资源子对象，采用：
/{domain}/{version}/{resource}/{id}/{sub-resource}例如：
GET /manufacturing/v1/work-orders
GET /manufacturing/v1/work-orders/WO20260001
POST /manufacturing/v1/work-orders
POST /manufacturing/v1/work-orders/WO20260001/release
GET /manufacturing/v1/work-orders/WO20260001/materials3.2 URL 各组成部分定义
| 组成部分 | 名称 | 规范 | 示例 |
|---|---|---|---|
| domain | 业务领域 | 小写英文 | manufacturing |
| version | API 版本 | v + 主版本号 | v1 |
| resource | 业务资源 | 小写复数英文 | work-orders |
| id | 资源标识 | 业务主键或统一资源 ID | WO20260001 |
| action | 业务动作 | 小写英文 | release |
| sub-resource | 子资源 | 小写复数英文 | materials |
3.3 域名规范
生产环境建议采用独立 API 域名：
https://api.example.com开发、测试、生产环境应使用独立域名或明确的环境隔离机制。
例如：
https://api-dev.example.com
https://api-test.example.com
https://api.example.com域名不得包含具体底层业务系统名称。
4. 业务领域（Domain）命名规范
4.1 领域定义
领域是企业业务能力的一级分类，也是 API 资源的顶层组织单位。
领域名称应采用稳定、通用的英文业务术语，不应直接以业务系统名称命名。
4.2 标准业务领域目录
| 序号 | Domain | 中文名称 | 主要业务范围 |
|---|---|---|---|
| 1 | master-data | 基础数据 | 组织、人员、物料、产品、BOM |
| 2 | procurement | 采购管理 | 采购申请、采购订单、供应商 |
| 3 | supply-chain | 供应链管理 | 供应链协同、供应商交付 |
| 4 | manufacturing | 生产制造 | 生产计划、工单、工序、报工 |
| 5 | equipment | 设备资产 | 设备台账、维修、巡检、保养 |
| 6 | warehouse | 仓储管理 | 仓库、库存、入库、出库 |
| 7 | logistics | 物流管理 | 配送、运输、发货 |
| 8 | quality | 质量管理 | 检验、缺陷、不合格品、追溯 |
| 9 | iot | 工业物联网 | 设备接入、测点、遥测、报警 |
| 10 | automation | 工业自动化 | PLC、SCADA、控制系统 |
| 11 | energy | 能源管理 | 能耗、能源计量、能源统计 |
| 12 | environment | 环保管理 | 环境监测、排放、环保报警 |
| 13 | engineering | 研发工程 | 图纸、工艺文件、工程变更 |
| 14 | sales | 销售管理 | 客户、销售订单、报价 |
| 15 | finance | 财务管理 | 凭证、发票、付款、预算 |
| 16 | costing | 成本管理 | 产品成本、生产成本 |
| 17 | hr | 人力资源 | 员工、考勤、排班、培训 |
| 18 | administration | 行政管理 | 公告、会议室、行政文档 |
| 19 | workflow | 流程管理 | 流程实例、审批、待办 |
| 20 | collaboration | 协同办公 | 消息、通知、工作日志 |
| 21 | analytics | 数据分析 | 指标、数据集、看板、报表 |
| 22 | intelligence | 智能分析 | 预测、诊断、异常检测、智能体 |
| 23 | security | 安全管理 | 权限、审计、访问策略 |
| 24 | platform | 平台管理 | API、订阅、集成任务、Webhook |
以上领域为标准目录，不要求每家企业全部实施。可根据企业业务实际情况扩展，但不得随意重复定义同一业务领域。
5. 资源（Resource）命名规范
5.1 命名要求
- 使用英文名词。
- 统一采用小写字母。
- 多个单词使用连字符
-连接。 - 默认使用复数形式。
- 不使用动词作为资源名称。
- 不使用底层系统表名、数据库表名和厂商专有术语。
- 同一业务资源在全平台必须保持名称一致。
- 子资源必须具有明确的业务从属关系。
正确示例：
work-orders
production-plans
equipment-alarms
maintenance-records
purchase-orders
energy-consumption错误示例：
getWorkOrder
tb_work_order
mesWorkOrder
work_order_list
query-equipment5.2 各领域标准资源目录
5.2.1 基础数据
| Resource | 中文名称 |
|---|---|
| organizations | 组织机构 |
| departments | 部门 |
| employees | 员工 |
| users | 用户 |
| roles | 角色 |
| permissions | 权限 |
| materials | 物料 |
| products | 产品 |
| product-categories | 产品分类 |
| units | 计量单位 |
| bom | 产品 BOM |
| routings | 工艺路线 |
| factories | 工厂 |
| workshops | 车间 |
| production-lines | 生产线 |
| work-centers | 工作中心 |
| dictionaries | 数据字典 |
5.2.2 采购与供应链
| Resource | 中文名称 |
|---|---|
| purchase-requests | 采购申请 |
| purchase-orders | 采购订单 |
| purchase-contracts | 采购合同 |
| suppliers | 供应商 |
| supplier-quotes | 供应商报价 |
| supplier-evaluations | 供应商评价 |
| purchase-receipts | 采购收货单 |
| delivery-notices | 送货通知 |
5.2.3 生产制造
| Resource | 中文名称 |
|---|---|
| work-orders | 生产工单 |
| production-plans | 生产计划 |
| production-schedules | 生产排程 |
| production-tasks | 生产任务 |
| production-reports | 生产报工 |
| production-records | 生产记录 |
| production-batches | 生产批次 |
| process-routes | 工艺路线 |
| process-parameters | 工艺参数 |
| process-records | 工艺记录 |
| workstations | 生产工位 |
| production-operations | 生产工序 |
| material-consumptions | 物料消耗 |
| production-capacities | 生产产能 |
| production-efficiencies | 生产效率 |
5.2.4 设备资产
| Resource | 中文名称 |
|---|---|
| equipments | 设备台账 |
| equipment-types | 设备类型 |
| equipment-groups | 设备分组 |
| equipment-parts | 设备部件 |
| equipment-status | 设备状态 |
| equipment-parameters | 设备参数 |
| equipment-alarms | 设备报警 |
| maintenance-plans | 维护计划 |
| maintenance-tasks | 维护任务 |
| maintenance-records | 维护记录 |
| repair-orders | 维修工单 |
| inspection-plans | 巡检计划 |
| inspection-tasks | 巡检任务 |
| inspection-records | 巡检记录 |
| spare-parts | 设备备件 |
| equipment-health | 设备健康度 |
| failure-events | 故障事件 |
| fault-diagnoses | 故障诊断 |
| predictive-maintenance | 预测性维护 |
5.2.5 仓储物流
| Resource | 中文名称 |
|---|---|
| warehouses | 仓库 |
| storage-areas | 库区 |
| storage-bins | 库位 |
| inventory | 库存 |
| inventory-transactions | 库存流水 |
| inbound-orders | 入库单 |
| outbound-orders | 出库单 |
| transfer-orders | 调拨单 |
| stocktaking-orders | 盘点单 |
| material-picking | 领料单 |
| material-returns | 退料单 |
| shipments | 发货单 |
| deliveries | 配送任务 |
| transport-orders | 运输订单 |
| carriers | 承运商 |
5.2.6 质量管理
| Resource | 中文名称 |
|---|---|
| inspection-plans | 检验计划 |
| inspection-tasks | 检验任务 |
| inspection-records | 检验记录 |
| inspection-standards | 检验标准 |
| nonconformities | 不合格品 |
| defects | 缺陷记录 |
| corrective-actions | 纠正措施 |
| preventive-actions | 预防措施 |
| quality-complaints | 质量投诉 |
| quality-costs | 质量成本 |
| quality-reports | 质量报告 |
| traceability | 产品追溯 |
5.2.7 工业物联网与自动化
| Resource | 中文名称 |
|---|---|
| devices | IoT 设备 |
| gateways | 边缘网关 |
| points | 数据测点 |
| point-groups | 测点分组 |
| telemetry | 实时遥测数据 |
| historical-data | 历史时序数据 |
| data-collections | 数据采集任务 |
| data-sources | 数据源 |
| protocols | 通信协议 |
| data-quality | 数据质量 |
| data-anomalies | 数据异常 |
| alarm-rules | 报警规则 |
| alarms | 实时报警 |
| alarm-events | 报警事件 |
| commands | 设备控制命令 |
| control-points | 控制点 |
| device-logs | 设备日志 |
| plc-programs | PLC 程序 |
| control-systems | 控制系统 |
| scada-tags | SCADA 标签 |
5.2.8 能源与环保
| Resource | 中文名称 |
|---|---|
| energy-meters | 能源仪表 |
| energy-consumption | 能源消耗 |
| energy-statistics | 能源统计 |
| energy-balances | 能源平衡 |
| energy-budgets | 能源预算 |
| energy-targets | 能源指标 |
| energy-reports | 能源报告 |
| environmental-meters | 环保仪表 |
| emissions | 排放数据 |
| environmental-alerts | 环保报警 |
| environmental-reports | 环保报告 |
5.2.9 研发工程
| Resource | 中文名称 |
|---|---|
| engineering-changes | 工程变更 |
| drawings | 图纸 |
| technical-documents | 技术文档 |
| product-versions | 产品版本 |
| process-documents | 工艺文件 |
| technical-specifications | 技术规范 |
| engineering-boms | 研发 BOM |
| change-orders | 变更单 |
5.2.10 销售与财务
| Resource | 中文名称 |
|---|---|
| customers | 客户 |
| sales-orders | 销售订单 |
| sales-forecasts | 销售预测 |
| quotations | 销售报价 |
| delivery-orders | 销售发货单 |
| customer-complaints | 客户投诉 |
| customer-feedback | 客户反馈 |
| accounts | 会计科目 |
| vouchers | 财务凭证 |
| invoices | 发票 |
| payments | 付款单 |
| receipts | 收款单 |
| budgets | 财务预算 |
| expense-claims | 费用报销 |
| product-costs | 产品成本 |
| material-costs | 材料成本 |
| production-costs | 生产成本 |
| cost-reports | 成本报表 |
5.2.11 人力资源与行政
| Resource | 中文名称 |
|---|---|
| attendance | 考勤 |
| shifts | 班次 |
| shift-schedules | 排班 |
| leave-requests | 请假申请 |
| overtime-requests | 加班申请 |
| training-records | 培训记录 |
| announcements | 公告 |
| documents | 行政文档 |
| meeting-rooms | 会议室 |
5.2.12 流程与协同
| Resource | 中文名称 |
|---|---|
| processes | 流程定义 |
| process-instances | 流程实例 |
| tasks | 待办任务 |
| approvals | 审批记录 |
| comments | 流程意见 |
| notifications | 消息通知 |
| messages | 站内消息 |
| attachments | 附件 |
| worklogs | 工作日志 |
5.2.13 数据分析与智能制造
| Resource | 中文名称 |
|---|---|
| metrics | 业务指标 |
| dashboards | 数据看板 |
| reports | 分析报表 |
| datasets | 数据集 |
| data-models | 数据模型 |
| data-queries | 数据查询 |
| kpis | KPI 指标 |
| predictions | 预测结果 |
| anomalies | 异常检测结果 |
| diagnoses | 诊断结果 |
| recommendations | 智能建议 |
| models | AI 模型 |
| agents | 智能体 |
| agent-tasks | 智能体任务 |
| knowledge-bases | 知识库 |
| knowledge-documents | 知识文档 |
5.2.14 安全与平台管理
| Resource | 中文名称 |
|---|---|
| api-keys | API 密钥 |
| access-policies | 访问策略 |
| audit-logs | 审计日志 |
| login-logs | 登录日志 |
| data-permissions | 数据权限 |
| api-services | API 服务 |
| api-subscriptions | API 订阅 |
| api-applications | API 应用 |
| api-credentials | API 凭证 |
| webhooks | Webhook |
| event-subscriptions | 事件订阅 |
| integration-jobs | 集成任务 |
| integration-logs | 集成日志 |
| sync-tasks | 数据同步任务 |
| sync-records | 同步记录 |
6. HTTP Method 设计规范
基础 CRUD 操作必须优先使用 HTTP Method 表达，不得将 list、create、update、delete 全部设计为 URL 动作。
| HTTP Method | 用途 | 说明 |
|---|---|---|
| GET | 查询 | 查询列表、详情、状态 |
| POST | 创建、执行 | 创建资源或执行业务动作 |
| PUT | 完整更新 | 替换资源 |
| PATCH | 部分更新 | 更新资源部分字段 |
| DELETE | 删除 | 删除资源或解除关联 |
6.1 基础 CRUD 示例
| 请求 | URL | 说明 |
|---|---|---|
| GET | /manufacturing/v1/work-orders | 查询工单列表 |
| GET | /manufacturing/v1/work-orders/10001 | 查询工单详情 |
| POST | /manufacturing/v1/work-orders | 创建工单 |
| PUT | /manufacturing/v1/work-orders/10001 | 完整更新工单 |
| PATCH | /manufacturing/v1/work-orders/10001 | 部分更新工单 |
| DELETE | /manufacturing/v1/work-orders/10001 | 删除工单 |
6.2 业务动作示例
对于具有明确业务含义、状态流转或执行行为的操作，可以使用 URL 动作。
POST /manufacturing/v1/work-orders/10001/release
POST /manufacturing/v1/work-orders/10001/pause
POST /manufacturing/v1/work-orders/10001/resume
POST /manufacturing/v1/work-orders/10001/close
POST /procurement/v1/purchase-orders/10001/approve
POST /procurement/v1/purchase-orders/10001/reject
POST /equipment/v1/maintenance-tasks/10001/complete
POST /iot/v1/commands
POST /iot/v1/alarms/10001/acknowledge6.3 统一动作词典
| Action | HTTP Method | 中文含义 |
|---|---|---|
| submit | POST | 提交 |
| approve | POST | 审批通过 |
| reject | POST | 审批拒绝 |
| release | POST | 下达、发布 |
| publish | POST | 发布 |
| revoke | POST | 撤销 |
| cancel | POST | 取消 |
| close | POST | 关闭 |
| start | POST | 启动 |
| stop | POST | 停止 |
| pause | POST | 暂停 |
| resume | POST | 恢复 |
| execute | POST | 执行 |
| complete | POST | 完成 |
| assign | POST | 分配 |
| transfer | POST | 转交 |
| acknowledge | POST | 确认 |
| clear | POST | 清除 |
| retry | POST | 重试 |
| calculate | POST | 计算 |
| analyze | POST | 分析 |
| predict | POST | 预测 |
| diagnose | POST | 诊断 |
| generate | POST | 生成 |
| validate | POST | 校验 |
| import | POST | 导入 |
| export | POST | 导出 |
| sync | POST | 同步 |
| trace | GET/POST | 追溯 |
| subscribe | POST | 订阅 |
| unsubscribe | DELETE | 取消订阅 |
| read | GET | 读取 |
| write | POST | 写入 |
动作应遵循统一词典。新增动作必须经过 API 规范评审，避免同一含义出现多个命名。
7. 子资源与关联资源规范
当资源之间存在明确从属关系时，可以采用嵌套 URL。
标准格式：
/{domain}/{version}/{resource}/{id}/{sub-resource}示例：
GET /manufacturing/v1/work-orders/10001/materials
GET /manufacturing/v1/work-orders/10001/operations
GET /equipment/v1/equipments/10001/maintenance-records
GET /equipment/v1/equipments/10001/repair-orders
GET /warehouse/v1/warehouses/10001/storage-bins
GET /quality/v1/inspection-tasks/10001/inspection-records嵌套层级原则上不超过三级资源关系。
对于跨领域的关联对象，应优先使用独立资源 API，避免过深的 URL 嵌套。
8. 查询参数规范
列表和查询接口应统一参数命名。
| 参数 | 类型 | 说明 | 示例 |
|---|---|---|---|
| page | Integer | 页码，从 1 开始 | 1 |
| pageSize | Integer | 每页数量 | 20 |
| sortBy | String | 排序字段 | createdTime |
| sortOrder | String | 排序方向 | desc |
| keyword | String | 关键字 | WO10001 |
| status | String | 状态过滤 | running |
| startTime | String | 开始时间 | 2026-11-01T00:00:00+08:00 |
| endTime | String | 结束时间 | 2026-11-07T00:00:00+08:00 |
示例：
GET /manufacturing/v1/work-orders?page=1&pageSize=20&status=running复杂查询应使用 POST，并通过 JSON Body 传递查询条件。
POST /iot/v1/telemetry/query{
"pointIds": ["P001", "P002"],
"startTime": "2026-11-01T00:00:00+08:00",
"endTime": "2026-11-07T00:00:00+08:00",
"interval": "1m",
"aggregation": "avg"
}查询接口应支持合理的最大返回数量限制，避免大规模数据查询影响平台稳定性。
9. 多租户与组织隔离规范
iPaaS 应支持多租户、多工厂、多车间和多组织的数据隔离。
租户信息原则上通过认证上下文或请求头传递，不应直接写入 URL。
推荐：
GET /manufacturing/v1/work-orders
Authorization: Bearer {access_token}
X-Tenant-Id: tenant001
X-Factory-Id: factory001租户和组织标识必须经过服务端身份授权验证，不能仅凭客户端传入的请求头决定访问权限。
对于面向外部合作伙伴的接口，应使用明确的应用授权和数据访问范围控制。
10. API 版本管理规范
10.1 版本命名
版本号采用：
v1
v2
v3版本号放在领域之后、资源之前。
例如：
/manufacturing/v1/work-orders
/manufacturing/v2/work-orders10.2 版本升级原则
以下情况属于不兼容变更，必须发布新主版本：
- 删除已有字段。
- 修改已有字段的数据类型。
- 修改已有字段的业务含义。
- 修改接口请求参数的必填规则，导致旧调用失败。
- 修改响应结构，导致旧调用方无法正常解析。
- 修改原有业务动作的执行语义。
新增非必填字段、新增资源、新增独立动作等向后兼容变更，原则上可以在当前版本内迭代。
10.3 版本生命周期
每个版本应具有：
- 开发中（Draft）
- 已发布（Published）
- 已弃用（Deprecated）
- 已停止服务（Retired）
停止服务前应提前通知订阅应用，并提供迁移时间窗口。
11. 接口响应规范
统一使用 JSON 作为默认数据交换格式。
成功响应：
{
"code": 0,
"message": "success",
"data": {
"items": [],
"total": 100,
"page": 1,
"pageSize": 20
},
"traceId": "trace-20261107-001"
}详情响应：
{
"code": 0,
"message": "success",
"data": {
"id": "WO10001",
"workOrderNo": "WO10001",
"status": "running"
},
"traceId": "trace-20261107-002"
}错误响应：
{
"code": 40001,
"message": "Invalid request parameters",
"data": null,
"traceId": "trace-20261107-003"
}具体错误码由平台统一维护，至少覆盖参数错误、身份认证失败、权限不足、资源不存在、业务状态冲突、系统异常和下游连接异常。
12. 异步任务规范
对于数据导出、批量同步、模型预测、复杂计算、报告生成等耗时操作，应采用异步任务模式。
创建任务：
POST /analytics/v1/reports/generate响应：
{
"code": 0,
"message": "Task accepted",
"data": {
"taskId": "TASK10001",
"status": "pending"
}
}查询任务：
GET /platform/v1/integration-jobs/TASK10001任务状态统一采用：
- pending：等待执行
- running：执行中
- succeeded：成功
- failed：失败
- cancelled：已取消
长时间运行的任务应支持超时控制、取消、重试和结果获取。
13. 安全规范
所有对外 API 必须遵循以下安全要求：
- 生产环境必须使用 HTTPS。
- 使用 OAuth 2.0、OIDC 或平台统一认证机制。
- 支持 API Key、访问令牌等应用级认证方式。
- 按领域、资源和动作实施细粒度授权。
- 支持租户和组织级数据隔离。
- 敏感操作必须记录审计日志。
- 写操作应支持幂等控制，建议使用
Idempotency-Key。 - 实施请求频率限制、并发限制和流量控制。
- 对外接口不得直接暴露数据库连接信息和底层系统地址。
- 涉及 PLC、DCS、SCADA 等 OT 控制操作时，必须执行独立的设备权限、安全策略、操作审计及必要的联锁校验。
14. iPaaS API 元数据标准
所有对外发布的 API 必须在 iPaaS 平台进行注册和管理。
每个 API 至少包含以下元数据：
| 字段 | 类型 | 说明 |
|---|---|---|
| apiId | String | API 唯一标识 |
| domain | String | 业务领域 |
| version | String | API 版本 |
| resource | String | 业务资源 |
| action | String | 业务动作 |
| httpMethod | String | HTTP 方法 |
| path | String | 完整 URL 路径 |
| name | String | API 名称 |
| description | String | API 说明 |
| requestSchema | JSON | 请求参数结构 |
| responseSchema | JSON | 响应数据结构 |
| connectorId | String | 内部连接器标识 |
| targetService | String | 底层服务映射 |
| permission | String | 调用权限 |
| tenantScope | String | 租户数据范围 |
| timeout | Integer | 超时时间 |
| rateLimit | Integer | 请求频率限制 |
| idempotent | Boolean | 是否支持幂等 |
| status | String | API 生命周期状态 |
iPaaS 应通过 API 元数据实现接口注册、自动发布、参数映射、底层系统路由、权限控制、监控及 OpenAPI 文档生成。
底层连接器、系统地址和厂商实现信息属于内部配置，不得泄露给外部调用方。
15. 完整接口设计示例
15.1 生产制造
GET /manufacturing/v1/work-orders
GET /manufacturing/v1/work-orders/10001
POST /manufacturing/v1/work-orders
PATCH /manufacturing/v1/work-orders/10001
POST /manufacturing/v1/work-orders/10001/release
POST /manufacturing/v1/work-orders/10001/close
GET /manufacturing/v1/production-plans
POST /manufacturing/v1/production-reports15.2 设备管理
GET /equipment/v1/equipments
GET /equipment/v1/equipments/10001
GET /equipment/v1/equipments/10001/status
GET /equipment/v1/equipments/10001/maintenance-records
GET /equipment/v1/equipment-alarms
POST /equipment/v1/equipment-alarms/10001/acknowledge
POST /equipment/v1/maintenance-tasks/10001/complete
GET /equipment/v1/equipment-health/1000115.3 工业物联网
GET /iot/v1/devices
GET /iot/v1/points
GET /iot/v1/points/10001/latest
POST /iot/v1/telemetry/query
POST /iot/v1/telemetry/aggregate
GET /iot/v1/alarms
POST /iot/v1/commands
GET /iot/v1/commands/10001
GET /iot/v1/data-anomalies
POST /iot/v1/data-collections/10001/start15.4 仓储与质量
GET /warehouse/v1/inventory
POST /warehouse/v1/inbound-orders
POST /warehouse/v1/outbound-orders
GET /quality/v1/inspection-records
POST /quality/v1/nonconformities
GET /quality/v1/traceability15.5 能源管理
GET /energy/v1/energy-meters
GET /energy/v1/energy-consumption
POST /energy/v1/energy-consumption/aggregate
GET /energy/v1/energy-targets
POST /energy/v1/energy-reports/generate15.6 AI 与智能制造
POST /intelligence/v1/predictions
POST /intelligence/v1/anomalies/detect
POST /intelligence/v1/diagnoses
POST /intelligence/v1/recommendations
GET /intelligence/v1/agents
POST /intelligence/v1/agents/10001/execute
GET /intelligence/v1/knowledge-bases
POST /analytics/v1/reports/generate16. 禁止事项
以下行为不符合本规范：
- URL 使用中文字符作为领域、资源和动作名称。
- URL 使用大写字母、下划线或驼峰命名。
- 将 MES、ERP、SAP、WMS 等底层系统名称作为对外领域。
- 将数据库表名直接作为 API 资源。
- 将 list、create、update、delete 等基础 CRUD 操作全部设计成 URL 动作。
- 同一业务对象在不同接口中使用不同英文名称。
- 未经版本升级直接修改已发布接口的业务含义。
- 将用户密码、API Key、Token 等敏感信息放在 URL 查询参数中。
- 将租户隔离完全交给客户端传入的参数控制。
- 对外接口直接暴露底层系统 IP、端口、数据库或内部网络地址。
- 对 PLC 等工业控制接口缺少独立的安全控制和审计机制。
- 为每个客户或底层系统随意增加独立的 URL 命名体系。
17. 标准执行与治理
17.1 新增 API
新增 API 必须经过以下流程：
- 确认所属业务领域。
- 确认是否存在已有标准资源。
- 确认资源命名和业务动作。
- 定义 HTTP Method 和 URL。
- 定义请求、响应及错误码结构。
- 配置底层连接器和数据映射。
- 配置认证、权限和限流策略。
- 完成接口测试和安全测试。
- 通过评审后发布。
17.2 规范维护
由 iPaaS 平台技术负责人统一维护：
- 业务领域字典。
- 标准资源字典。
- 标准动作字典。
- API 版本目录。
- 接口元数据规范。
- API 生命周期管理规则。
任何团队不得在未经评审的情况下创建重复领域或重复资源。
17.3 规范优先级
当企业内部系统的接口命名与本规范不一致时，以本规范作为 iPaaS 对外 API 的统一标准。
底层系统可以继续保留原有接口，但必须通过 iPaaS 连接器进行适配。
18. 最终标准总结
iPaaS 对外 API 统一采用：
/{domain}/{version}/{resource}需要执行明确业务动作时采用：
/{domain}/{version}/{resource}/{id}/{action}需要访问子资源时采用：
/{domain}/{version}/{resource}/{id}/{sub-resource}统一遵循以下原则：
| 规范项 | 最终标准 |
|---|---|
| URL 结构 | 领域 + 版本 + 资源 + 可选动作 |
| 业务领域 | 统一英文业务领域 |
| 资源名称 | 小写复数、kebab-case |
| 动作名称 | 小写、kebab-case |
| HTTP 方法 | GET、POST、PUT、PATCH、DELETE |
| API 版本 | v1、v2、v3 |
| 数据格式 | JSON |
| 认证机制 | OAuth 2.0 / OIDC / API Key |
| 多租户 | 认证上下文及请求头 |
| 接口文档 | OpenAPI 3.x |
| 底层系统 | 通过内部连接器解耦 |
| API 治理 | 统一注册、授权、发布、监控和审计 |
最终架构定位：
iPaaS 对外提供的不是某个 MES、ERP 或 WMS 系统的原始接口，而是面向整个制造企业的统一业务 API 能力。
所有业务系统通过标准化资源和动作对外提供服务，所有接口通过统一的 API 元数据进行注册、发布和治理，为企业数字化集成、工业互联网、数据中台和 AI Agent 提供统一的业务接口基础设施。
