CMMS 工单适配器
FactVerse CMMS 运营可以通过受治理的工单适配器连接下游 CMMS / EAM 系统。当客户希望 FactVerse 创建、交接、同步或监控维护工单，同时保留既有系统时，请使用本指南。
工单适配器与现场协议适配器不同。工单适配器用于和 Maximo、SAP Plant Maintenance、Honeywell Forge、自定义 REST 服务或 Webhook 端点交换维护记录。BACnet、Modbus、SNMP 等现场协议适配器用于把设备点位值带入资产和工单上下文。
前置条件
配置工单适配器前，请先确认：
- 下游 CMMS 或 EAM 负责人，以及预期的记录系统归属；
- 已批准的服务账号访问、凭据保存和轮换规则；
- 已部署 FactVerse 环境到提供商 endpoint 的网络可达性；
- 打开、已分派、已完成、已取消、失败和重开工单样例；
- 用于映射的资产、位置、站点、工厂或功能位置标识；
- 需要进入统一工单生命周期的提供商状态和优先级值；
- 已批准的写入边界：只读、草稿、交接、同步或写回。
适配器选择流程
支持的适配类型
| 适配类型 | 适用场景 | 典型方向 | 准备重点 |
|---|---|---|---|
| Webhook | 下游系统或中间件可以接收事件 payload，并通过入站 webhook 回传状态 | FactVerse 推送，提供商回调 | 目标 URL、共享密钥、payload 契约、重试策略 |
| Generic REST | 提供商或客户开放项目专用 REST API | 可配置推送和拉取 | Base URL、认证方式、推送路径、拉取路径、字段映射、响应结构 |
| IBM Maximo | 客户使用 Maximo 工单、资产、站点和状态值 | 推送新建工单并拉取状态变更 | Maximo 根 URL、API key、站点或组织默认值、资产映射、状态映射 |
| SAP Plant Maintenance | 客户使用 SAP 维护订单、设备、功能位置和工厂范围 | 推送维护订单并拉取状态变更 | SAP OData 根路径、Basic 或 API key 认证、工厂、订单类型、CSRF 写入流程 |
| Honeywell Forge | 客户项目通过已批准 overlay 使用 Honeywell Forge 或 IBMS 集成类型 | 按 overlay 定义推送、拉取、资产或告警路径 | Forge Base URL、API key 或 OAuth2 客户端凭据、overlay payload 契约 |
适配器是否可用仍取决于部署范围、客户访问批准、提供商版本和最终集成契约。每个集成类型都是实施起点，不能替代提供商发现和客户确认。
核心适配模型
每个工单适配器都应围绕同一组运营契约规划：
| 能力 | 需要确认 |
|---|---|
| 推送工单 | 哪些 FactVerse 工单需要交接或创建到提供商系统，哪些字段必填 |
| 拉取状态更新 | 哪些提供商状态、负责人和时间戳会更新统一工单视图 |
| 健康检查 | 哪个 endpoint 或探针用于判断提供商连接是否可达 |
| 资产映射 | FactVerse 设备如何映射到提供商资产、位置、站点或功能位置 |
| 同步日志 | 成功、失败、重试和提供商响应如何被审阅 |
| 归属规则 | 提供商是否仍是记录系统，FactVerse 是否作为主工作区，或者该流程是否只读 |
配置输入
启用适配器前，请准备：
| 输入 | 作用 |
|---|---|
| 适配器类型 | 选择 webhook、rest、maximo、sap-pm 或客户 overlay 集成类型 |
| Base URL 或 endpoint | 定义请求发送位置和网络访问边界 |
| 认证方式 | 定义服务账号、令牌、凭据轮换和提供商审计归属 |
| 字段映射 | 将 FactVerse 工单字段映射到提供商字段，并保留来源值 |
| 状态映射 | 将提供商状态映射到 CMMS 共享生命周期，同时保留原始状态 |
| 资产映射 | 将 FactVerse 设备 ID 对齐到提供商资产、位置、站点或功能位置 ID |
| 拉取频率 | 定义状态变更读取频率，或确认由提供商 webhook 回调 |
| 写入边界 | 明确只读、草稿、交接、写回等模式 |
Generic REST
当客户、提供商、中间件或承包商系统开放稳定的项目专用 REST API 时，使用 Generic REST。它适合不属于标准打包集成类型、但可以提供稳定工单 API 的系统。
需要确认 Base URL、网络白名单、认证方式、推送路径、HTTP 方法、拉取路径、时间戳参数、结果数组结构、状态字段、FactVerse 字段到 JSON key 的映射、成功创建后返回的外部 ID 字段，以及健康检查路径。
Generic REST 是可配置的适配框架。生产上线前仍需审阅客户侧 API 契约。
IBM Maximo
客户使用 IBM Maximo 管理维护时，可使用 Maximo 集成类型与 Maximo 工单 API 交换记录。
| 领域 | 准备内容 |
|---|---|
| 访问 | Maximo 根 URL，以及通过批准 header 传递的 API key |
| 创建工单 | 描述、长描述、优先级、状态、外部引用、站点、组织、资产和位置字段 |
| 优先级映射 | 将 FactVerse 优先级映射到 Maximo 工单优先级，并按部署复核本地词表 |
| 状态映射 | 将已创建、已分派、进行中、已完成、已取消等状态映射到客户 Maximo 状态模型 |
| 拉取变更 | 确认变更时间窗口、选择字段、分页大小和自定义状态处理 |
| 资产身份 | 将 FactVerse 设备映射到 Maximo assetnum、location、站点和组织 |
Maximo 常会定制状态值、对象结构和必填字段。上线前要用真实的打开、完成、取消、阻塞、重开工单验证。
SAP Plant Maintenance
客户使用 SAP S/4HANA Plant Maintenance 管理维护订单时，可使用 SAP PM 集成类型进行工单交接或同步。
| 领域 | 准备内容 |
|---|---|
| 访问 | SAP OData 服务根路径，以及批准的 Basic 或 API key 认证 |
| 写入流程 | 创建或更新请求所需的 CSRF token 与 session cookie 处理 |
| 范围 | 维护工厂、订单类型、设备和功能位置字段 |
| 创建工单 | 描述、订单类型、工厂、优先级和可追溯引用 |
| 状态映射 | 将 SAP 订单状态码映射到 FactVerse 生命周期，同时保留原始 SAP 状态 |
| 拉取变更 | 确认最后变更时间格式、选择字段和提供商侧过滤条件 |
SAP 环境会因 Gateway 配置、SSO 策略、扩展字段和订单类型而不同。最终服务表面应由客户 SAP 负责人确认。
Honeywell Forge 和 Overlay 集成类型
Honeywell Forge 或 IBMS 类型集成应作为客户批准的 overlay 集成类型处理。它可以使用 API key 或 OAuth2 客户端凭据，但 endpoint 形态、payload 字段和运营方向取决于项目。
使用该路径前，应确认客户已批准 Forge 访问和凭据，payload 形态已由客户或集成伙伴确认，资产主数据归属、告警流向和工单归属已达成一致，写回或交接行为也明确在范围内。
不要假设所有 Forge 项目拥有相同 endpoint 或权限。生产同步前要记录客户批准的集成类型。
与现场协议适配器的边界
BACnet、Modbus 和 SNMP 不是下游 CMMS 工单适配器。它们用于把设备点位值、控制器状态、UPS 读数、环境测量值或受管设备状态带入 FactVerse 上下文。
需要把工单记录与下游维护系统交换时，使用工单适配器。需要在分诊、证据复核、设施运营、预测性维护或 Agent 解释中引用设备点位时，使用现场协议适配器。
验收清单
- 已确认适配器类型和提供商归属。
- 凭据、endpoint、防火墙规则和服务账号已批准。
- 资产映射已用真实设备和位置样例测试。
- 状态和优先级映射保留提供商原始值。
- 推送、拉取、健康检查、同步日志、重试和失败路径已测试。
- 写回行为限制在已批准字段和角色内。
- 操作员能看到工单是原生、已交接、已同步、失败，还是等待提供商动作。