EMS 接口与事件契约
本文定义前后端、EMS 与慧知自研能源接入中台之间的稳定契约。接口示例使用 JSON，新增字段必须向后兼容。
统一请求上下文
Authorization: Bearer <access-token>
X-Tenant-Id: 10001
X-Request-Id: 01J...
Idempotency-Key: tenant-10001-device-create-20260821-001
成功响应包含 code、message、data、requestId；业务失败仍返回可定位的错误码，不把异常堆栈暴露给前端。分页接口统一使用 pageNum/pageSize/total/rows。
关键资源接口
| 能力 | 方法 | 语义 |
|---|---|---|
| 接入端点列表 | GET /ems/server-endpoints | 查询已授权的慧知自研能源接入中台入口 |
| 边缘网关镜像 | GET /ems/edge-gateways | 查询边缘网关在线、能力和最后同步时间 |
| 设备预检 | POST /ems/devices/precheck | 只读校验依赖和参数，不下发现场命令 |
| 创建设备任务 | POST /ems/devices/tasks | 创建幂等编排任务，返回 taskId |
| 实时快照 | GET /ems/metrics/realtime | 返回值、单位、采样时间和质量 |
| 历史曲线 | GET /ems/metrics/history | 按资源和时间窗查询降采样数据 |
| 报表重算 | POST /ems/reports/recalculate | 生成新版本，不覆盖已审核结果 |
控制命令生命周期
{
"requestNo": "cmd-20260821-0001",
"resourceId": "ess-1001",
"capability": "setActivePower",
"parameters": { "powerKw": 120 },
"expireAt": "2026-08-21T10:05:00+08:00"
}
状态依次为 ACCEPTED -> PRECHECKED -> SENT -> ACKED -> VERIFIED，超时为 UNKNOWN，拒绝为 REJECTED。ACKED 只表示链路接收，VERIFIED 必须由后续采样满足误差和持续时间条件。
领域事件
事件统一包含 eventId、eventType、tenantId、resourceId、occurredAt、traceId 和 schemaVersion。建议事件：EdgeOnline、EdgeOffline、ResourceChanged、MetricStale、ControlVerified、ReportPublished。消费者必须按 eventId 幂等，不能依赖事件到达顺序；需要顺序时使用资源级 sequence。
错误码分层
AUTH_* 表示认证失败，SCOPE_* 表示租户/数据范围拒绝，RESOURCE_* 表示资源不存在或冲突，CAPABILITY_* 表示设备不支持，CONTROL_* 表示控制预检、链路或验证失败，DATA_* 表示数据缺口或查询超限。前端只依赖错误码，不依赖中文 message。
开放平台能力
接口与事件契约体现的是平台开放能力，而不是简单接口清单。慧知 EMS 通过统一请求上下文、稳定错误码、幂等键、领域事件和版本兼容机制，让前端、大屏、调度任务、第三方系统和数据消费者都可以围绕同一套资源语义协同。
| 开放能力 | 说明 | 价值 |
|---|---|---|
| 统一上下文 | 请求携带租户、身份、请求号和幂等键 | 支撑多租户、审计和链路追踪 |
| 资源 API | 对公司、电站、设备、网关、指标、报表提供统一访问 | 上层应用不需要理解现场协议差异 |
| 控制 API | 能力驱动、参数约束、结果验证和状态回传 | 远程控制可治理、可追踪、可回放 |
| 领域事件 | 资源变化、数据过期、控制完成、报表发布事件化 | 便于扩展通知、大屏、数据同步和外部集成 |
| 兼容演进 | 新字段向后兼容，错误码稳定，事件 schema 版本化 | 降低多端协同升级成本 |
生态扩展价值
基于事件契约，平台可以向 BI、财务结算、工单系统、碳管理平台和集团数据湖输出标准能源事件；基于资源 API，第三方系统可以读取统一电站视图、实时指标和报表结果；基于控制 API，授权系统可以在安全边界内触发策略或设备动作。接口层因此成为慧知 EMS 从单一产品走向能源运营生态的连接面。