CMMS API 参考
本页提供面向客户的 CMMS 集成接口结构。最终 endpoint、payload 和字段映射以客户部署范围和运行时 OpenAPI 为准。
API 表面
当前 API 锚点
适配器类型参考
| 类型 | 用途 |
|---|---|
webhook | 将工单事件推送到下游 endpoint，并通过入站 webhook 接收状态回调。 |
rest | 使用客户批准的路径、认证、字段映射和结果解析配置通用 REST 集成类型。 |
maximo | 通过 Maximo REST 集成类型连接 IBM Maximo 工单。 |
sap-pm | 通过 SAP OData 集成类型连接 SAP Plant Maintenance 维护订单。 |
| Forge 或客户 overlay 集成类型 | 通过批准的 overlay wiring 和 payload 契约连接 Honeywell Forge 或其他客户专项提供商。 |
BACnet、Modbus、SNMP 是设备上下文用的现场协议适配器，不应配置为下游 CMMS 工单适配器。
| 分组 | API |
|---|---|
| CMMS 配置 | GET /api/v1/cmms/adapters, POST /api/v1/cmms/adapters, POST /api/v1/cmms/adapters/{id}/test |
| 资产映射 | GET /api/v1/cmms/asset-mappings, POST /api/v1/cmms/asset-mappings, POST /api/v1/cmms/asset-mappings/batch |
| 同步日志 | GET /api/v1/cmms/sync/logs |
| CMMS 概览 | GET /api/v1/cmms/dashboard-summary |
| 工单 | GET /api/v1/workorders, POST /api/v1/workorders, PUT /api/v1/workorders/{id}/assign-resource, POST /api/v1/workorders/{id}/feedback |
| 工单请求 | POST /api/v1/platform/worker-issues, POST /api/v1/platform/worker-issues/{id}/triage, POST /api/v1/platform/worker-issues/{id}/convert |
| 预测性维护连接 | GET /api/v1/pdm/cmms, POST /api/v1/pdm/cmms, POST /api/v1/pdm/advisory/{id}/work-order, POST /api/v1/pdm/advisory/{id}/outcome |
契约字段
| 字段 | 用途 |
|---|---|
common_work_order_id | FactVerse 工单引用。 |
provider_id | 来源 CMMS、EAM、承包商系统或集成配置。 |
source_work_order_id | 提供商原生工单 ID。 |
asset_ref | MDM 资产、设备、位置或系统引用。 |
source_status / common_status | 原始状态和共享生命周期状态。 |
sync_state | 导入、待同步、已同步、重试、拒绝或陈旧。 |
错误处理
认证、授权、字段校验、资产身份、冲突和提供商不可用都应有明确的返回、同步日志和人工处理路径。
运行接口补充
| 能力 | 典型接口 |
|---|---|
| 技术员和班组 | GET /api/v1/technicians, GET /api/v1/crews, PUT /api/v1/workorders/id/assign-resource |
| 预防性维护 | GET /api/v1/maintenance-schedules, GET /api/v1/maintenance-calendar, POST /api/v1/maintenance-completions |
| 备件和库存 | GET /api/v1/spare-parts, GET /api/v1/inventory, POST /api/v1/inventory/transactions |
CMMS Agent 和 MCP 工具锚点
CMMS Agent 工具表面由租户 Agent 配置限定。tools/list 只应显示当前 Agent 绑定的 CMMS 工具。tools/call 在执行前应应用租户范围、权限检查、风险上限、幂等和审计。
| 工具 | 权限 | 契约 |
|---|---|---|
cmms_query_backlog | cmms.read | 读取工单积压总数、优先级分布和 SLA 违约数量。 |
cmms_query_equipment | cmms.read | 读取设备或资产记录，可按站点过滤。 |
cmms_query_work_orders | cmms.read | 按状态、设备和分页窗口读取工单。 |
cmms_suggest_technician | cmms.read | 返回可用技术员候选，不执行派工。 |
cmms_create_work_request | workorders.create | 创建申请或现场问题报告，并留下审计记录。 |
cmms_create_work_order | workorders.create | 在完成所需审阅或确认后创建工单。 |
cmms_assign_work_order | workorders.assign | 在确认后把工单派给技术员或班组。 |
cmms_close_work_order | workorders.complete | 在确认后完成工单；完成属于终态运营动作。 |
读取工具通过范围和权限检查后执行。工单申请是带审计的低风险写入。创建工单、派工和完成工单在负责人确认前应保持为需要确认的状态。调用方重试同一逻辑动作时应传入稳定的幂等键。
正式项目应以部署环境暴露的 OpenAPI 和客户侧权限矩阵为准。