developer-guide.md

EnerOS 开发者指南

本指南面向 EnerOS 的核心开发者与贡献者，说明系统架构、workspace 组织方式，以及扩展系统能力（新增 Agent、协议适配器、插件）的标准流程。

1. 架构总览

EnerOS 定位为电力原生 Agent 操作系统（Power-Native AgentOS），采用双执行域 + 分层架构。

1.1 双执行架构

系统划分为两个执行域，通过实时安全网关通信：

• 通用执行域：承载 Agent 编排、AI 推理、潮流计算、规划优化，响应时延秒级 ~ 分钟级，使用标准内核公平调度。
• 实时执行域：承载继电保护、开关操作、故障隔离、频率调节，响应时延微秒级 ~ 毫秒级，使用优先级抢占调度。

核心原则：安全域不可被通用域阻塞；通用域→实时域的指令必须经过实时安全网关的约束校验与优先级仲裁；通用域异常时实时域自动降级到本地保护逻辑。

1.2 分层架构（L0-L3）

┌──────────────────────────────────────────────────────────────────┐
│ L3 应用层  eneros-api (HTTP/WS/CLI) · eneros-dashboard            │
├──────────────────────────────────────────────────────────────────┤
│ L3 编排层  eneros-agent (7种专业Agent+编排+调度+协作)              │
│            eneros-gateway (7阶段决策管线+安全网关+执行器)          │
├──────────────────────────────────────────────────────────────────┤
│ L2 能力层  eneros-reasoning · eneros-tool · eneros-memory         │
│            eneros-scada · eneros-device · eneros-constraint       │
│            eneros-analysis · eneros-network · eneros-bridge       │
│            eneros-plugin · eneros-simulator                       │
├──────────────────────────────────────────────────────────────────┤
│ L1 内核层  eneros-os (agentos/ha/init/security/syslog/timesync    │
│            /update/devmgr/hal/rt/netcfg) · eneros-eventbus        │
├──────────────────────────────────────────────────────────────────┤
│ L0 基础层  eneros-core · eneros-topology · eneros-linalg          │
│            eneros-powerflow · eneros-equipment · eneros-cnpower  │
│            eneros-timeseries                                      │
└──────────────────────────────────────────────────────────────────┘

层级	职责	代表 crate
L0 基础层	领域类型、线性代数、潮流计算、拓扑、设备模型、配网设备参数库、时序存储	eneros-core、eneros-linalg、eneros-powerflow、eneros-topology、eneros-equipment、eneros-cnpower、eneros-timeseries
L1 内核层	OS 内核能力（Agent 调度、HA、安全、时间同步、OTA、设备管理、HAL）	eneros-os、eneros-eventbus
L2 能力层	领域能力（推理、工具、记忆、SCADA、设备协议、约束、分析、网络、桥接、插件、仿真）	eneros-reasoning、eneros-tool、eneros-memory、eneros-scada、eneros-device、eneros-constraint、eneros-analysis、eneros-network、eneros-bridge、eneros-plugin、eneros-simulator
L3 编排层	Agent 编排与安全网关	eneros-agent、eneros-gateway
L3 应用层	对外接口（HTTP API、Dashboard）	eneros-api、eneros-dashboard

1.3 crate 依赖方向

依赖严格自上而下，禁止反向依赖与循环依赖：

L0 基础层（无内部依赖或仅依赖 eneros-core）
  ↑
L1 内核层（依赖 L0）
  ↑
L2 能力层（依赖 L0、L1）
  ↑
L3 编排层（依赖 L0、L1、L2）
  ↑
L3 应用层（依赖全部下层）

eneros-plugin 独立于 eneros-device/eneros-agent/eneros-analysis，避免循环依赖。eneros-sdk 封装常用类型，供第三方开发者使用。

2. 开发环境

2.1 Rust 工具链

• 最低版本：Rust 1.75+
• edition：2021
• 推荐组件：rustfmt、clippy、rust-src（rust-analyzer 需要）

rustup component add rustfmt clippy rust-src

2.2 平台支持

平台	支持程度	说明
Linux x86_64	完整支持	生产部署目标平台
Linux aarch64	完整支持	嵌入式/边缘部署
Windows	核心库开发	eneros-os 的 HAL/seccomp/AF_PACKET 部分不编译，使用 --exclude eneros-installer
macOS	核心库开发	同 Windows

跨平台开发时编译核心库：

cargo build --workspace --exclude eneros-installer

2.3 IDE 与调试

推荐 VS Code + rust-analyzer。调试配置：

• rust-analyzer.checkOnSave.command: clippy
• rust-analyzer.cargo.features: all
• 断点调试：使用 lldb 扩展或 CodeLLDB

VS Code launch.json 示例（调试 eneros-api）：

{
  "type": "lldb",
  "request": "launch",
  "name": "debug eneros-api",
  "cargo": {
    "args": ["build", "--package", "eneros-api"],
    "filter": { "kind": "bin" }
  },
  "args": ["run", "--config", "eneros.toml"],
  "cwd": "${workspaceFolder}"
}

3. Workspace 组织

EnerOS 使用 Cargo workspace 组织 54 个 crate，分为核心库、二进制、SDK/宏三类。

3.1 核心库（library crate）

crate	层级	职责
eneros-core	L0	领域类型、配置、错误、事件、命令
eneros-linalg	L0	线性代数运算（矩阵分解、求解器）
eneros-powerflow	L0	潮流计算（牛顿-拉夫逊、前推回代）
eneros-topology	L0	电网拓扑图、搜索、连接模式分析
eneros-equipment	L0	设备模型库（变压器、线路、开关等）
eneros-cnpower	L0	中国配网一次设备参数库 + 静态合规检查器（CNPOWER Rust 原生移植，17 JSON 数据集编译期嵌入，零 Python 依赖）
eneros-tenant	L0	多租户核心（租户模型 + 命名空间隔离 + 配额 + SQLite 持久化）
eneros-timeseries	L0	时序数据存储、聚合、降采样、异常检测
eneros-os	L1	OS 内核（agentos/ha/init/security/syslog/timesync/update/devmgr/hal/rt）
eneros-eventbus	L1	事件总线（broker/bus/client/priority_bus）
eneros-reasoning	L2	推理引擎（LLM 集成、策略、反馈）
eneros-tool	L2	工具注册与调用
eneros-memory	L2	Agent 记忆（文件存储、向量检索）
eneros-scada	L2	SCADA 数据采集（IEC 104、双扫描、快照）
eneros-device	L2	设备协议适配器（IEC 104/61850/Modbus/DNP3/GOOSE/SV/OPC UA/MQTT）
eneros-constraint	L2	安全约束引擎（N-1、热稳定、电压限值）
eneros-analysis	L2	电力分析（OPF、状态估计、短路、暂稳）
eneros-network	L2	电网网络模型与仿真 pipeline
eneros-bridge	L2	Python 桥接（pandapower/cnpower）
eneros-plugin	L2	插件框架（清单/生命周期/加载器/签名/沙箱/IPC）
eneros-simulator	L2	电网仿真器（场景脚本、故障注入）
eneros-agent	L3	Agent 编排（7 种 Agent + 调度 + 协作 + 冲突解决）
eneros-gateway	L3	实时安全网关（7 阶段决策管线 + 执行器）
eneros-api	L3	HTTP/WS API 服务
eneros-dashboard	L3	Web Dashboard 资产生成

3.2 二进制（binary crate）

二进制	所属 crate	职责
enerosctl	eneros-os/bins/enerosctl	管理 CLI
eneros-init	eneros-os/bins/eneros-init	系统初始化守护进程
eneros-ha	eneros-os/bins/eneros-ha	高可用守护进程
eneros-timesync	eneros-os/bins/eneros-timesync	时间同步守护进程
eneros-installer	eneros-os/bins/eneros-installer	安装器
broker	eneros-eventbus/bins/broker	事件总线 broker
gateway	eneros-gateway/bins/gateway	实时安全网关
plugin-daemon	eneros-plugin/bins/plugin-daemon	插件守护进程
dispatch-agent	eneros-agent/bins/dispatch-agent	调度 Agent
forecast-agent	eneros-agent/bins/forecast-agent	预测 Agent
operation-agent	eneros-agent/bins/operation-agent	操作 Agent
planning-agent	eneros-agent/bins/planning-agent	规划 Agent
trading-agent	eneros-agent/bins/trading-agent	交易 Agent
self-healing-agent	eneros-agent/bins/self-healing-agent	自愈 Agent

3.3 SDK 与宏

crate	职责
eneros-sdk	第三方开发者 SDK，封装 Agent/协议/插件开发的常用类型
eneros-plugin-macros	#[eneros_plugin] 过程宏，自动生成 C ABI 入口函数

4. 添加新 Agent

EnerOS 的 Agent 作为 OS 调度单元运行，每个 Agent 是一个独立进程。

4.1 实现步骤

1. 实现 Agent 逻辑：在 crates/eneros-agent/src/agents/ 下新建模块，实现 Agent 的决策循环与消息处理。

2. 创建二进制入口：在 crates/eneros-agent/bins/ 下新建目录，包含 Cargo.toml 和 src/main.rs：

# crates/eneros-agent/bins/my-agent/Cargo.toml
[package]
name = "my-agent"
version.workspace = true
edition.workspace = true

[dependencies]
eneros-agent = { path = "../.." }
eneros-core = { path = "../../../eneros-core" }
tokio = { workspace = true }

// crates/eneros-agent/bins/my-agent/src/main.rs
use eneros_agent::agents::my_agent::MyAgent;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = MyAgent::new();
    agent.run().await
}

3. 注册到 workspace：在根 Cargo.toml 的 members 中添加 "crates/eneros-agent/bins/my-agent"。

4. 配置 init.toml：在 os/rootfs/files/etc/eneros/init.toml 中添加 Agent 启动配置，指定二进制路径、启动参数、资源配额。

5. 编译验证：

cargo build -p my-agent
cargo test -p eneros-agent

4.2 Agent 类型

EnerOS 内置 7 种专业 Agent，新增 Agent 时应明确其类型与职责边界：

Agent	职责
dispatch-agent	调度决策
forecast-agent	负荷/发电预测
operation-agent	操作执行
planning-agent	运行规划
trading-agent	电力交易
self-healing-agent	故障自愈

5. 添加新协议适配器

协议适配器位于 crates/eneros-device/src/adapters/，实现设备协议的编解码与通信。

5.1 实现步骤

1. 创建适配器模块：在 crates/eneros-device/src/adapters/ 下新建目录（如 my_protocol/），实现协议编解码。

2. 实现 DeviceAdapter trait：参考 crates/eneros-device/src/adapter.rs 中的 trait 定义，实现连接、读写、断开等方法。

3. 注册到 DeviceManager：在 crates/eneros-device/src/adapters/mod.rs 中声明模块，并在 DeviceManager 中注册适配器工厂。

4. 添加测试：在适配器模块内添加单元测试，在 crates/eneros-device/tests/ 下添加集成测试。

5. 配置设备：在 eneros.toml 或 init.toml 中配置使用新协议的设备连接。

5.2 已支持协议

协议	模块	传输层
IEC 60870-5-104	adapters/iec104/	TCP
IEC 61850 (MMS)	adapters/iec61850/	TCP
IEC 61850 (GOOSE)	adapters/goose/	AF_PACKET (L2)
IEC 61850 (SV)	adapters/sv/	AF_PACKET (L2)
Modbus TCP	adapters/modbus/	TCP
Modbus RTU	adapters/modbus_rtu/	串口
DNP3	adapters/dnp3/	TCP/串口
OPC UA	adapters/opcua/	TCP
MQTT	adapters/mqtt/	TCP

GOOSE/SV 等二层协议通过 AF_PACKET 原始套接字实现，为 OS 原生能力。

6. 添加新插件

插件系统支持三类插件（Protocol/Agent/Analysis），通过 #[eneros_plugin] 宏简化开发。详细流程见 插件开发指南。

6.1 快速流程

1. 在 eneros-sdk 依赖基础上创建插件 crate
2. 使用 #[eneros_plugin(...)] 宏标注 impl Plugin for MyPlugin
3. 编写 manifest.toml 描述插件元数据
4. 使用 enerosctl plugin gen-keys 生成签名密钥
5. 使用 enerosctl plugin sign 签名插件
6. 使用 enerosctl plugin load 加载插件

7. 多租户开发（v0.38.0）

EnerOS v0.38.0 引入多租户与隔离能力，核心 crate 为 eneros-tenant（Layer 2，仅依赖 eneros-core）。

7.1 核心概念

• 租户 = 电力运营主体：一个地市公司/变电站集群/综合能源服务商
• 命名空间隔离：资源 ID 约定 <tenant_id>:<resource_id>，无 : 前缀视为全局资源（向后兼容）
• 隔离是强制的：跨租户访问默认拒绝，与 SafetyGateway 同级的安全法律
• 向后兼容：[tenant] enabled = false（默认）时行为与单租户部署完全一致

7.2 关键类型

类型	所在	职责
TenantManager	eneros-tenant	租户 CRUD + 成员管理 + 配额 + API Key 绑定
TenantUsageTracker	eneros-tenant	原子计数器跟踪设备数/Agent 数/API 调用数/存储量
TenantStorage trait	eneros-tenant	持久化后端接口（SqliteTenantStorage 实现）
TenantContext	eneros-api::tenant	请求级租户上下文（通过 Extension 注入）
TenantConfig	eneros-core::config	[tenant] 配置节

7.3 租户感知中间件链

中间件按洋葱模型执行（后添加先执行）：

trace_id → version_negotiation → deprecation_header → auth
  → tenant_middleware → tenant_quota_middleware → rate_limit → handler

• tenant_middleware：提取租户标识（X-Tenant-ID 头 > API Key 绑定 > JWT claim），校验租户状态与成员关系
• tenant_quota_middleware：写操作（POST/PUT/PATCH/DELETE）检查每日 API 调用配额

7.4 在 handler 中使用租户隔离

use axum::Extension;
use eneros_api::tenant::{TenantContext, check_resource_id_tenant, is_resource_visible, namespaced_id};

async fn my_handler(
    Extension(ctx): Extension<TenantContext>,
    // ...
) -> impl IntoResponse {
    // 1. 列表过滤：按租户可见性过滤
    let visible: Vec<_> = resources.iter()
        .filter(|r| is_resource_visible(&r.id, &ctx))
        .collect();

    // 2. 单资源访问：校验归属（跨租户返回 404）
    if let Err(resp) = check_resource_id_tenant(&resource_id, &ctx) {
        return resp;
    }

    // 3. 创建资源：命名空间化 ID
    let namespaced = namespaced_id(Some(&ctx), &resource_id);
}

7.5 API Key 绑定租户

use eneros_api::auth::AuthManager;

let mut auth = AuthManager::new();
// 绑定租户的 API Key
auth.add_api_key("sk-tenant-a", "user1", Role::Operator, Some("tenant-a".to_string()));
// 未绑定租户的 API Key（自动使用 default 租户，向后兼容）
auth.add_api_key("sk-legacy", "user2", Role::Observer, None);

7.6 零信任与安全开发（v0.39.0）

EnerOS v0.39.0 引入零信任架构，新增 4 个 crate：

crate	层级	职责
eneros-trust	L1（仅依赖 core）	内部 CA + X.509 证书签发 + 自动轮转 + mTLS 接收器/连接器 + CRL
eneros-audit	L1（仅依赖 core）	HMAC 签名链 + WORM 存储 + 配置 diff + 取证导出
eneros-ids	L10（依赖 core + ai）	行为基线 + 威胁检测器 + IOC 情报 + 登录失败锁定
eneros-compliance	L3（依赖 core + audit）	NERC CIP-005/007/010 + IEC 62443-4-2 SL2 合规检查

关键类型

类型	所在	职责
CertificateAuthority	eneros-trust	CA 签发/撤销（rcgen 0.13）
CertificateManager	eneros-trust	证书加载/签发/自动轮转
MtlsAcceptor/MtlsConnector	eneros-trust	mTLS 双向认证流包装
AuditRepository	eneros-audit	审计读写（AuditChain + WormStorage）
ThreatDetector	eneros-ids	威胁检测分析
LoginFailureTracker	eneros-ids	登录失败锁定
ComplianceChecker	eneros-compliance	合规控制项检查

零信任中间件链

trace_id → login_failure → threat_detection → tenant → rate_limit → handler

• threat_detection_middleware：IOC 命中返回 403；横向移动/行为异常注入 SecurityContext（不阻断）
• login_failure_middleware：锁定账号/IP 返回 423 + Retry-After
• 未配置 ThreatDetector / LoginFailureTracker 时中间件直接放行（向后兼容 v0.38.0）

安全约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• mTLS 功能通过 mtls feature 门控，默认不启用
• WORM 存储在 Linux 使用 chattr +a，非 Linux 仅警告

7.7 运维自动化开发（v0.40.0）

EnerOS v0.40.0 引入生产级运维自动化，新增 3 个 crate：

Crate	Layer	职责
eneros-slo	L2（依赖 core + timeseries）	SLO/SLI 定义 + 错误预算 + 多窗口燃尽率告警 + 评估器 + 业务看板
eneros-aiops	L3（依赖 core + ai + timeseries + eventbus + audit）	统一告警 + 指纹去重 + 拓扑邻近合并 + 根因分析 + 告警抑制 + 事件聚合
eneros-ops	L3（依赖 core + aiops + slo + gateway + audit + timeseries）	事件管理 + On-call + Runbook + 容量预测 + AutoScaler + Backup

关键类型

类型	所在 Crate	说明
Slo / SloStatus / SloWindow	eneros-slo	SLO 定义与状态机（Met/AtRisk/Violated/Frozen）
SliCollector（async trait）	eneros-slo	SLI 采集接口（Arc<dyn SliCollector + Send + Sync> 注入）
ErrorBudget	eneros-slo	错误预算（budget_total/consumed/remaining/exhaustion_forecast）
MultiWindowBurnRateChecker	eneros-slo	SRE 多窗口燃尽率告警（1h&5m>14.4→P0 / 6h&30m>6→P1 / 3d&6h>1→P3）
SloEvaluator	eneros-slo	SLO 周期评估 + 冻结 + 历史快照
BusinessDashboard	eneros-slo	业务指标看板（设备在线率/命令成功率/Agent P99/电网合规率）
Alert / AlertSource / AlertSeverity	eneros-aiops	统一告警结构（SHA-256 指纹）
AlertCorrelator	eneros-aiops	告警聚类去重 + 拓扑邻近合并
RootCauseAnalyzer	eneros-aiops	根因分析规则链（5 条内置规则）
AlertSuppressor	eneros-aiops	告警抑制（维护窗口/重复/依赖 SLO）
Incident / IncidentSeverity / IncidentStatus	eneros-aiops	事件聚合（P0-P3 SLA）
AiopsEngine	eneros-aiops	告警处理引擎（关联→抑制→根因→事件）
OpsManager / OpsConfig / OpsDeps	eneros-ops	运维聚合入口（依赖注入）
IncidentManager	eneros-ops	事件管理（自动分级/分派/SLA 检查/Runbook）
OnCallSchedule / ShiftRule / Override	eneros-ops	On-call 排班
RunbookEngine / Runbook / RunbookStep	eneros-ops	Runbook 自愈引擎
CapacityForecaster / ForecastAlgorithm	eneros-ops	容量预测（线性/指数/季节/集成）
AutoScaler / AutoScalerPolicy / ScaleTrigger	eneros-ops	自动扩缩容
BackupManager / BackupManifest	eneros-ops	备份恢复（SHA-256 + cron + 演练）
NotificationChannel（async trait）	eneros-ops	通知渠道（Log/Webhook/Email/Composite）

SLO 定义指南

SLO 通过 Slo::from_config 创建，target ∈ 0.0..=1.0，window 支持 5m/30m/1h/6h/1d/3d/7d/30d：

use eneros_slo::{Slo, SloWindow, SliSource};

let slo = Slo::from_config(
    "scada_availability",
    "SCADA 数据可用性",
    0.999,                       // target
    SloWindow::ThirtyDays,       // window
    SliSource::Metrics {
        query: "rate(eneros_commands_total{result=\"success\"}[5m]) / rate(eneros_commands_total[5m])".to_string(),
    },
)?;

SLO 评估器通过 Arc<dyn SliCollector + Send + Sync> 注入 SLI 采集实现，评估时计算错误预算与燃尽率，状态机优先级：Frozen → Violated(budget<0) → AtRisk(pct<25%) → Met。

AIOps 规则扩展

RootCauseAnalyzer 支持自定义规则链（首匹配胜出）：

use eneros_aiops::{RootCauseAnalyzer, RootCauseRule, RuleCondition, AlertSource, AlertSeverity};

let analyzer = RootCauseAnalyzer::new(vec![
    RootCauseRule {
        name: "custom-rule".to_string(),
        condition: RuleCondition::And(vec![
            RuleCondition::SourceMatch(AlertSource::Metrics),
            RuleCondition::LabelMatch { key: "metric".to_string(), value: "voltage".to_string() },
        ]),
        probable_cause: "电压异常".to_string(),
        confidence: 0.85,
    },
]);

Runbook 编写指南

Runbook 以 TOML 文件形式存储在 runbook_dir 目录下，结构为 checks → actions → postconditions 流水线：

name = "scada_disconnect_recovery"
description = "SCADA 断流自愈"
timeout_secs = 300

[trigger]
severity = "P0"
alert_source = "Metrics"

[[actions]]
name = "check_connection"
description = "检查 SCADA 连接"
command = { GatewayQuery = { command = "scada.status" } }
on_failure = "Continue"

[[actions]]
name = "reconnect"
description = "重新连接 SCADA"
command = { GatewayExecute = { command = "scada.reconnect" } }
on_failure = "Abort"

运维自动化约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• 同步读写锁使用 parking_lot::RwLock（非 std::sync）
• 异步 trait 使用 async_trait
• 公共类型派生 Debug, Clone, Serialize, Deserialize
• OpsConfig 默认 enabled = false，未配置时所有 ops 端点返回 501，向后兼容 v0.39.0

7.8 高可用增强开发（v0.41.0）

EnerOS v0.41.0 引入多区域高可用，新增 1 个 crate：

Crate	层级与依赖	职责
eneros-multiregion	L3（依赖 core + os + audit + timeseries + eventbus + aiops）	多区域拓扑 + 区域感知路由 + WAL 跨区域复制 + DR 编排 + 滚动升级 + CRDT/LWW 冲突解决

关键类型

类型	所在 Crate	职责
MultiRegionManager / HaEnhanceConfig / MultiRegionDeps	eneros-multiregion	多区域聚合入口（依赖注入 topology + router + resolver + replicator + dr + upgrader）
Region / RegionStatus / RegionTopology	eneros-multiregion	区域定义 + 延迟矩阵 + 健康区域查询
RegionAwareRouter / RegionRoutingStrategy	eneros-multiregion	区域感知路由（LocalFirst/LatencyOptimal/FailoverOnly + cordon/uncordon）
WalWriter / WalShipper / WalApplier / CrossRegionReplicator	eneros-multiregion	WAL 跨区域连续复制（append/ship/apply 幂等回放 + RpoMetrics）
DrOrchestrator / DrConfig / DrillScenario / DrillResult	eneros-multiregion	DR 编排（auto_failover + 3 种演练 + cron 调度）
RollingUpgrader / UpgradeConfig / VersionMatrix / UpgradeState	eneros-multiregion	零停机滚动升级（Witness>Secondary>Primary + 健康检查 + 自动回滚）
ConflictResolver（trait） / WriteOp / ResolvedValue / ConflictRecord	eneros-multiregion	冲突解决抽象
LwwResolver / LwwEntry	eneros-multiregion	LWW 冲突解决 + 时钟偏差检测
GCounter / GSet / LwwRegister / OrSet / CrdtStore	eneros-multiregion	CRDT 数据结构（Active-Active 多活）
NodeController（async trait） / HealthChecker（async trait）	eneros-multiregion	节点生命周期与健康检查（供 eneros-os / eneros-api 实现）

模块结构

crates/eneros-multiregion/src/
├── lib.rs            # 模块声明与重新导出
├── error.rs          # MultiRegionError（8 变体）
├── region.rs         # Region/RegionStatus/RegionTopology
├── router.rs         # RegionAwareRouter + RegionRoutingStrategy
├── conflict.rs       # ConflictResolver trait + ConflictHistory
├── crdt.rs           # G-Counter/G-Set/LwwRegister/OrSet + CrdtStore
├── lww.rs            # LwwResolver + 时钟偏差检测
├── manager.rs        # MultiRegionManager 聚合入口
├── replication.rs    # WalWriter/WalShipper/WalApplier/CrossRegionReplicator
├── dr.rs             # DrOrchestrator + DrillScenario
└── upgrade.rs        # RollingUpgrader + NodeController/HealthChecker trait

多区域配置指南

HaEnhanceConfig 由 eneros-core::config 定义，通过 EnerOSConfig.ha_enhance 字段注入。默认 enabled = false，向后兼容 v0.40.0。audit_strict_mode: bool 默认 true（v0.41.0 Review Hardening 新增）——审计写入失败时返回 MultiRegionError::AuditFailed，符合 IEC 62443-4-2 SL3 强审计要求；置 false 时退化为 best-effort（仅 warn! 日志）。

use eneros_core::config::HaEnhanceConfig;

let config = HaEnhanceConfig {
    enabled: true,
    audit_strict_mode: true, // v0.41.0：审计失败返回错误（默认 true）
    multi_region: MultiRegionConfig {
        local_region_id: "region-a".into(),
        regions: vec![RegionDefinition { /* ... */ }],
        routing_strategy: "local_first".into(),
        latency_matrix: HashMap::new(),
    },
    replication: ReplicationConfig::default(),
    dr: DrConfig::default(),
    upgrade: UpgradeConfig::default(),
    active_active: ActiveActiveConfig::default(),
};

扩展 CRDT 类型

如需新增 CRDT 类型（例如 PN-Counter），在 crdt.rs 中：

1. 定义新结构体并实现 merge 语义（必须满足交换律、结合律、幂等性）
2. 在 CrdtValue 枚举新增变体
3. 在 CrdtOp 枚举新增对应操作
4. 在 CrdtStore::write 与 read 中处理新变体
5. 添加单元测试覆盖 merge 幂等性与交换性

// 示例：PN-Counter（支持增减）
pub struct PnCounter {
    p: GCounter,  // 增量计数
    n: GCounter,  // 减量计数
}

impl PnCounter {
    pub fn increment(&mut self, region_id: &str) { self.p.increment(region_id); }
    pub fn decrement(&mut self, region_id: &str) { self.n.increment(region_id); }
    pub fn value(&self) -> i64 { self.p.value() as i64 - self.n.value() as i64 }
    pub fn merge(&self, other: &Self) -> Self {
        Self { p: self.p.merge(&other.p), n: self.n.merge(&other.n) }
    }
}

添加新 DR 演练场景

如需新增演练场景（例如 RegionDegradation），在 dr.rs 中：

1. 在 DrillScenario 枚举新增变体
2. 在 DrOrchestrator::drill 的 match 分支新增处理逻辑
3. 定义场景的验证步骤（cordon → failover → 验证 → 恢复）
4. 添加单元测试覆盖新场景

pub enum DrillScenario {
    CrossRegionFailover { from_region: String, to_region: String },
    DataCenterLoss { region: String },
    NetworkPartition { regions: Vec<String> },
    // 新增：
    RegionDegradation { region: String, degradation_pct: u8 },
}

实现 NodeController 与 HealthChecker

RollingUpgrader 通过两个 async trait 抽象节点操作，生产实现由 eneros-os 与 eneros-api 提供：

// eneros-os 实现 NodeController
#[async_trait]
impl NodeController for OsNodeController {
    async fn cordon_node(&self, node_id: &str) -> Result<()> { /* 调用 ClusterManager */ }
    async fn upgrade_node(&self, node_id: &str, target_version: &str) -> Result<()> { /* OTA */ }
    async fn list_nodes(&self) -> Vec<NodeInfo> { /* 查询集群成员 */ }
    // ...
}

// eneros-api 实现 HealthChecker
#[async_trait]
impl HealthChecker for ApiHealthChecker {
    async fn check_node_health(&self, node_id: &str) -> Result<HealthCheckResult> {
        // 调用 /api/v1/ha/regions/{id} 验证节点可用性
    }
}

高可用增强约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• 同步读写锁使用 parking_lot::RwLock；原子计数使用 AtomicU64
• 异步 trait（NodeController / HealthChecker）使用 async_trait
• 公共类型派生 Debug, Clone, Serialize, Deserialize
• HaEnhanceConfig 默认 enabled = false，未配置时 HA 中间件放行、HA 端点返回 501，向后兼容 v0.40.0
• 审计 strict 模式（v0.41.0 Review Hardening）：audit_strict_mode 默认 true，审计失败返回 MultiRegionError::AuditFailed；false 时 best-effort
• 超时配置已生效（v0.41.0 Review Hardening）：cross_region_takeover_timeout_ms 在 cross_region_failover 关键步骤后强制检查，超时返回 FailoverError::Timeout；UpgradeConfig.health_check_retry_interval_ms（原 health_check_timeout_ms，语义为重试间隔）+ 新增 health_check_total_timeout_ms（默认 60_000，整体超时）
• SafetyGateway 不被绕过：所有 DR/升级动作通过 GatewayClient IPC 下发，复用 v0.39.0/v0.40.0 安全约束
• 审计完整：cordon/uncordon/DR 切换/演练/升级启动/中止/复制暂停恢复/冲突解决全部写入审计日志（AuditAction::HaEnhancement）
• CRDT merge 必须满足：交换律 + 结合律 + 幂等性（否则多活收敛不正确）

7.9 Agent 智能进阶开发（v0.43.0）

EnerOS v0.43.0 引入 Agent 智能进阶，不新增 crate，而是在 eneros-agent 内新增 5 个模块 + 扩展 eneros-market 数据模型：

模块	所在 Crate	职责
collab	eneros-agent	多 Agent 协作框架（3 种模式 + CollaborationCoordinator trait）
learning	eneros-agent	强化学习引擎（PPO + Imitation + Online + RewardShaper）
decomposition	eneros-agent	LLM 驱动任务分解（TaskDecomposer + SubtaskScheduler + ResultAggregator）
strategy	eneros-agent	策略市场运行时（StrategyLoader + StrategyRegistry + AbTestRunner）
explain	eneros-agent	可解释性（DecisionPath + SHAP + LIME + 序列化）
扩展	eneros-market	StrategyPack/AbTestExperiment 数据模型 + 4 张新表 + 7 个 handler
扩展	eneros-api	14 个智能进阶端点 + AgentIntelligenceContext
扩展	eneros-os	enerosctl agent intel 11 个子命令

关键类型

类型	所在 Crate	职责
CollaborationMode / CollaborationCoordinator（trait） / CoordinationPlan / SubtaskAssignment / AgentInfo	eneros-agent::collab	协作框架核心抽象
MasterSlaveCoordinator / PeerCoordinator / BiddingCoordinator / LegacyCollaborationAdapter	eneros-agent::collab	3 种协作模式实现 + 旧协议适配
Bid / PeerResponseAggregator / AggregationStrategy	eneros-agent::collab	协作数据结构与聚合策略
Experience / ExperienceReplayBuffer / ReplayBufferStats	eneros-agent::learning	经验回放缓冲区
RlAgent（trait） / LearningMetrics / PolicyNetwork	eneros-agent::learning	RL 智能体抽象 + 纯 Rust MLP
PpoAgent / PpoConfig / ImitationAgent / ImitationConfig / OnlineLearner	eneros-agent::learning	PPO/模仿/在线学习实现
RewardShaper（trait） / PowerRewardShaper / RewardConfig	eneros-agent::learning	奖励塑形
Subtask / DecompositionResult / TaskDecomposer / DecompositionConfig	eneros-agent::decomposition	LLM 任务分解
LlmClientInterface（trait） / DecompositionPromptRegistry	eneros-agent::decomposition	LLM 客户端抽象 + Prompt 模板（避免 agent→ai 循环依赖）
SubtaskScheduler / SubtaskDispatcher（trait） / SubtaskResult / SubtaskStatus	eneros-agent::decomposition	DAG 调度器
ResultAggregator / AggregatedOutcome	eneros-agent::decomposition	结果聚合
LlmPlanner	eneros-agent::decomposition	实现 Planner trait，LLM 失败时 fallback 到 RuleBasedPlanner
StrategyLoader / StrategyRegistry / StrategyInfo	eneros-agent::strategy	策略加载与热切换
AbTestRunner / AbTestExperiment / AbTestResults	eneros-agent::strategy + eneros-market	A/B 测试 + 双比例 z 检验
DecisionPath / ReasoningStep / Evidence / FeatureContribution / Outcome	eneros-agent::explain	可解释性数据结构
ExplainabilityProvider（trait） / AuditTrailExplainer / CompositeExplainer	eneros-agent::explain	可解释性 Provider
ShapExplainer / IsolationForestModel（trait）	eneros-agent::explain	TreeSHAP + Integrated Gradients
LimeExplainer / LimeConfig	eneros-agent::explain	LIME 局部解释
DecisionPathSerializer	eneros-agent::explain	JSON / DOT / Mermaid 序列化
StrategyPack / StrategyStatus / StrategyVersion / StrategyRating	eneros-market	策略市场数据模型
AgentIntelligenceConfig / CollabConfig / LearningConfig / DecompositionConfig / StrategyMarketConfig / ExplainConfig	eneros-core	用户面向配置（默认禁用）
AgentIntelligenceContext	eneros-api	聚合 5 大子域组件的运行时上下文

模块结构

crates/eneros-agent/src/
├── collab/
│   ├── mod.rs              # 公共导出
│   ├── coordinator.rs      # CollaborationCoordinator trait + CoordinationPlan
│   ├── master_slave.rs     # MasterSlaveCoordinator
│   ├── peer.rs             # PeerCoordinator + PeerResponseAggregator
│   ├── bidding.rs          # BiddingCoordinator + Bid + ContractNet
│   └── legacy_adapter.rs   # LegacyCollaborationAdapter
├── learning/
│   ├── mod.rs              # 公共导出
│   ├── experience.rs       # Experience + ExperienceReplayBuffer
│   ├── reward.rs           # RewardShaper trait + PowerRewardShaper
│   ├── rl.rs               # RlAgent trait + PolicyNetwork + PpoAgent
│   ├── imitation.rs        # ImitationAgent + 行为克隆
│   └── online.rs           # OnlineLearner + 周期学习
├── decomposition/
│   ├── mod.rs              # 公共导出
│   ├── decomposer.rs      # TaskDecomposer + LlmClientInterface trait
│   ├── scheduler.rs        # SubtaskScheduler + SubtaskDispatcher trait
│   ├── aggregator.rs       # ResultAggregator + AggregationStrategy
│   ├── llm_planner.rs      # LlmPlanner 实现 Planner trait
│   └── prompts.rs          # DecompositionPromptRegistry（4 个模板 + generic）
├── strategy/
│   ├── mod.rs              # 公共导出
│   ├── loader.rs           # StrategyLoader（下载 + 校验 + 签名）
│   ├── registry.rs         # StrategyRegistry（热切换 + 回滚）
│   └── ab_test.rs          # AbTestRunner（双比例 z 检验）
└── explain/
    ├── mod.rs              # 公共导出
    ├── decision_path.rs    # DecisionPath + ReasoningStep + Evidence
    ├── provider.rs         # ExplainabilityProvider trait + AuditTrailExplainer + CompositeExplainer
    ├── shap.rs             # ShapExplainer (TreeSHAP + Integrated Gradients)
    ├── lime.rs             # LimeExplainer (扰动 + Lasso)
    └── serializer.rs       # DecisionPathSerializer (JSON / DOT / Mermaid)

循环依赖规避（重要）

eneros-ai 依赖 eneros-agent（v0.33.0 起的既有关系），因此 eneros-agent 不能反向依赖 eneros-ai。v0.43.0 通过本地 trait 抽象解决：

• decomposition::LlmClientInterface — 本地定义的 LLM 客户端 trait，由 eneros-ai 在 eneros-agent 上游实现该 trait 并注入到 TaskDecomposer
• explain::IsolationForestModel — 本地定义的 IsolationForest 模型 trait，供 ShapExplainer TreeSHAP 使用，由 eneros-ai::IsolationForestDetector 适配

// eneros-agent 本地定义 trait
pub trait LlmClientInterface: Send + Sync {
    async fn complete(&self, prompt: &str) -> Result<String>;
}

// eneros-ai 上游实现并注入
pub struct AiLlmClientAdapter {
    inner: Arc<dyn eneros_ai::LlmClient>,
}

#[async_trait]
impl LlmClientInterface for AiLlmClientAdapter {
    async fn complete(&self, prompt: &str) -> Result<String> {
        self.inner.complete(prompt).await
    }
}

智能进阶配置指南

AgentIntelligenceConfig 由 eneros-core::config 定义，通过 EnerOSConfig.agent_intelligence 字段注入。默认 enabled = false，向后兼容 v0.41.0。

use eneros_core::config::AgentIntelligenceConfig;

let config = AgentIntelligenceConfig {
    enabled: true,
    collaboration: CollabConfig {
        default_mode: CollaborationMode::Bidding,
        bidding_timeout_ms: 5000,
    },
    learning: LearningConfig {
        replay_buffer_size: 10000,
        learning_interval_ms: 60000,
        enable_ppo: true,
        enable_imitation: false,
    },
    decomposition: DecompositionConfig {
        llm_enabled: true,
        fallback_to_rules: true,
        max_subtasks: 10,
        llm_timeout_ms: 30000,
    },
    strategy_market: StrategyMarketConfig {
        market_url: "https://market.example.com".into(),
        ab_test_enabled: true,
    },
    explainability: ExplainConfig {
        enabled: true,
        shap_enabled: true,
        lime_enabled: false,
        retention_decisions: 10000,
    },
};

扩展协作模式（自定义 Coordinator）

如需新增协作模式（例如 HierarchicalCoordinator 分层递归协作），在 collab/ 中：

1. 在 CollaborationMode 枚举新增变体（#[non_exhaustive] 缓解 BREAKING）
2. 创建新文件 hierarchical.rs 实现 CollaborationCoordinator trait
3. 在 coordinate() 实现自定义分配逻辑
4. 在 mod.rs 公共导出新类型
5. 添加单元测试覆盖分配逻辑与 fallback

pub enum CollaborationMode {
    MasterSlave,
    PeerToPeer,
    Bidding,
    // 新增：
    Hierarchical { levels: u8 },
}

pub struct HierarchicalCoordinator {
    coordinator_id: String,
    levels: u8,
}

#[async_trait]
impl CollaborationCoordinator for HierarchicalCoordinator {
    async fn coordinate(
        &self,
        event: &Event,
        agents: &[AgentInfo],
    ) -> Result<CoordinationPlan> {
        // 按 authority_level 分层，递归分配 subtask
        // ...
    }
}

扩展 RL 算法（自定义 RlAgent）

如需新增 RL 算法（例如 DQN），在 learning/ 中：

1. 在 learning/rl.rs（或新文件 dqn.rs）实现 RlAgent trait
2. 复用 ExperienceReplayBuffer 与 PolicyNetwork（或新建网络结构）
3. 在 mod.rs 公共导出新类型
4. 添加单元测试覆盖学习收敛性

pub struct DqnAgent {
    q_network: PolicyNetwork,
    target_network: PolicyNetwork,
    config: DqnConfig,
    buffer: Arc<ExperienceReplayBuffer>,
}

#[async_trait]
impl RlAgent for DqnAgent {
    async fn act(&self, state: &Observation) -> Result<AgentAction> { /* ... */ }
    fn observe(&self, exp: Experience) -> Result<()> { /* ... */ }
    async fn learn_step(&self) -> Result<LearningMetrics> { /* ... */ }
    fn save(&self, path: &Path) -> Result<()> { /* ... */ }
    fn load(&mut self, path: &Path) -> Result<()> { /* ... */ }
}

扩展可解释性（自定义 Explainer）

如需新增 Explainer（例如 CounterfactualExplainer 反事实解释），在 explain/ 中：

1. 创建新文件 counterfactual.rs 实现 ExplainabilityProvider trait
2. 在 CompositeExplainer 优先级链中插入（建议位于 LIME 之后、AuditTrail 之前）
3. 在 mod.rs 公共导出新类型
4. 添加单元测试覆盖解释正确性

pub struct CounterfactualExplainer {
    agent: Arc<dyn Agent>,
    num_counterfactuals: usize,
}

#[async_trait]
impl ExplainabilityProvider for CounterfactualExplainer {
    async fn explain(&self, decision_id: &str) -> Result<DecisionPath> { /* ... */ }
    async fn feature_importance(&self, decision_id: &str) -> Result<Vec<FeatureContribution>> { /* ... */ }
}

扩展 LLM Prompt 模板

如需新增 LLM 分解 prompt 模板（例如 demand_response），在 decomposition/prompts.rs 中：

1. 在 DecompositionPromptRegistry::new() 中注册新模板
2. 在 select_template(goal_type) 中添加 goal_type → template_id 映射
3. 模板包含：system instruction + goal placeholder + agent capabilities placeholder + JSON output schema
4. 添加单元测试覆盖模板渲染与字段替换

智能进阶约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• 同步读写锁使用 parking_lot::RwLock；原子计数使用 AtomicU64
• 异步 trait（CollaborationCoordinator / RlAgent / ExplainabilityProvider / SubtaskDispatcher）使用 async_trait
• 公共类型派生 Debug, Clone, Serialize, Deserialize
• AgentIntelligenceConfig 默认 enabled = false，未配置时所有端点返回 501，向后兼容 v0.41.0
• 循环依赖规避：eneros-agent 不可依赖 eneros-ai，必须通过本地 trait 抽象（LlmClientInterface / IsolationForestModel）解耦
• SafetyGateway 不被绕过：所有 Agent 决策仍经过 SafetyGateway 校验，智能进阶不改变安全边界
• 审计完整：协作发起 / Bid 收集 / award / subtask 完成 / 策略热切换 / A/B 测试 finalize 全部写入审计日志（AuditAction::AgentDecisionPath / AuditAction::StrategySwap）
• PPO 纯 Rust：默认不依赖 candle，纯 Rust MLP 实现；可选 rl-candle feature 启用 GPU 后端
• 策略签名强制：所有 StrategyPack 必须通过 Ed25519 签名验证，未签名 pack 返回 403

7.10 电网分析进阶开发（v0.44.0）

EnerOS v0.44.0 引入电网分析进阶，新增 1 个 crate (eneros-emtp) + 在 eneros-analysis 内新增 4 个模块 + 扩展 eneros-api 端点：

模块 / Crate	所在位置	职责
dynamic_state_estimation	eneros-analysis	EKF 动态状态估计（predict/update 两步 + 不良数据 + 拓扑错误辨识）
realtime_stability	eneros-analysis	PMU 实时稳定分析（30 周波滑动窗口 + Prony + 等面积法则）
harmonic	eneros-analysis	谐波分析（加窗 FFT + HarmonicYBus + 谐波潮流 + THD）
equivalents	eneros-analysis	电网等值（Ward Schur 补 + REI 聚合 + 自动重建）
eneros-emtp（新 crate）	crates/eneros-emtp	电磁暂态仿真（梯形伴随模型 + Component trait + 电力电子）
扩展	eneros-api	11 个 analysis 端点 + GridAnalysisContext
扩展	eneros-os	enerosctl analysis 11 个子命令

关键类型

类型	所在 Crate	职责
DynamicStateEstimator	eneros-analysis	EKF 估计器（from_flat_start 构造 + step 推进 + estimate 完整估计）
EkfState / EkfCovariance	eneros-analysis	EKF 状态向量 + 协方差矩阵
RealtimeStabilityMonitor	eneros-analysis	实时稳定监控器（push_snapshot + evaluate → StabilityMargin）
StabilityMargin	eneros-analysis	4 级分级：Normal / Warning / Alert / Emergency
FftHarmonicDetector	eneros-analysis	加窗 FFT 谐波检测器（detect → AnalysisResult<HarmonicSpectrum>）
HarmonicYBus / HarmonicPowerFlow	eneros-analysis	谐波导纳矩阵 Yₙ=G+j·n·B + 谐波潮流
HarmonicSourceCurrent	eneros-analysis	谐波源 trait（SixPulseConverter / TwelvePulseConverter / PwmConverter）
ThdCalculator	eneros-analysis	总谐波畸变率 THD = √(Σ Vₙ²) / V₁ × 100%
WardEquivalent / ReiEquivalent	eneros-analysis	Ward（Schur 补消去）/ REI（区域聚合）等值
EquivalentUpdater	eneros-analysis	偏差 >2% 自动重建（auto_update_enabled = false 默认关闭）
EmtSimulator / EmtOptions / EmtResult	eneros-emtp	EMTP 仿真器（梯形伴随模型 + 隐式积分）
Component trait	eneros-emtp	EMT 组件统一接口（stamp_y / step / bus_count）
RlcBranch / VoltageSource / IdealSwitch / Transformer	eneros-emtp	基础元件
FaultInjector	eneros-emtp	故障注入（相间 / 接地）
DiodeInstant / IgbtInstant / PwmGenerator / TwoLevelConverter	eneros-emtp	电力电子瞬态模型
GridAnalysisConfig	eneros-core	总配置（5 子配置，默认 enabled = false）

模块结构

crates/eneros-analysis/src/
├── dynamic_state_estimation.rs   # EKF 动态状态估计
├── realtime_stability.rs         # PMU 实时稳定分析
├── harmonic.rs                   # 谐波分析（FFT + Y-bus + 潮流 + THD）
├── equivalents.rs                # Ward + REI 等值 + 自动更新
└── state_estimation.rs           # 静态状态估计（v0.44.0: 混合 Jacobian 架构）

crates/eneros-emtp/src/
├── lib.rs                        # EmtSimulator + EmtOptions + EmtResult + EmtState
├── component.rs                  # Component trait + VoltageSource/IdealSwitch/FaultInjector
├── branch.rs                     # RlcBranch（并联 RLC）+ Transformer
└── power_electronics.rs          # DiodeInstant/IgbtInstant/PwmGenerator/TwoLevelConverter

混合 Jacobian 架构（重要）

v0.44.0 在 state_estimation.rs 中实现混合 Jacobian 策略：

// WLS 估计器使用 diagonal-only Jacobian（收敛稳定）
pub fn build_jacobian_network(...) -> (Array2<f64>, Array1<f64>, Array1<f64>) {
    self.build_jacobian_network_impl(measurements, x, network, false)
}

// EKF 使用 full Jacobian（精度保证）
pub fn build_jacobian_network_full(...) -> (Array2<f64>, Array1<f64>, Array1<f64>) {
    self.build_jacobian_network_impl(measurements, x, network, true)
}

fn build_jacobian_network_impl(..., full: bool) -> (...) {
    // BusInjectionP/Q 块：
    // if full && j != k {
    //     h[[row, 2*j]]     += v_k * (g * cos_t + b * sin_t);
    //     h[[row, 2*j + 1]] -= v_k * v_j * (-g * sin_t + b * cos_t);
    // }
}

理由：完整 Jacobian 数学上更正确，但在 IEEE-14 系统上导致 WLS 发散。diagonal-only 是 decoupled approximation，在 WLS 迭代中收敛稳定。EKF 每步只做一次 update，需要精确 Jacobian 保证滤波精度。

EKF 开发指南

1. 构造：DynamicStateEstimator::from_flat_start(network) —— 平启动 V=1.0, θ=0
2. 初始化协方差：P₀ = 0.01·I —— 避免发散
3. predict：稳态假设 x̂⁻ = x̂，P⁻ = P + Q
4. update：K = P⁻·Hᵀ·(H·P⁻·Hᵀ + R)⁻¹ + x̂⁺ = x̂⁻ + K·(z − h(x̂⁻)) + P⁺ = (I−K·H)·P⁻
5. 不良数据辨识：归一化创新残差 rₙ = |z − h(x̂⁻)| / √(H·P⁻·Hᵀ + R)，超 innovation_threshold（默认 3.0，3σ）标记
6. 拓扑错误辨识：连续 topology_error_steps（默认 5）步创新超阈值触发

谐波源扩展（自定义 HarmonicSourceCurrent）

use eneros_analysis::harmonic::HarmonicSourceCurrent;
use num_complex::Complex64;

pub struct CustomConverter {
    pub pulse_number: u32,
    pub rated_current: f64,
}

impl HarmonicSourceCurrent for CustomConverter {
    fn harmonic_currents_at(&self, n: u32) -> Complex64 {
        // 实现谐波电流注入计算
        // 例如 6 脉动：Iₙ = I₁ / n，n = 6k ± 1
        if n == 1 {
            return Complex64::new(self.rated_current, 0.0);
        }
        if (n + 1) % 6 == 0 || (n - 1) % 6 == 0 {
            return Complex64::new(self.rated_current / n as f64, 0.0);
        }
        Complex64::new(0.0, 0.0)
    }
}

EMTP 组件扩展（自定义 Component）

use eneros_emtp::Component;

pub struct CustomComponent {
    // 元件参数
}

impl Component for CustomComponent {
    fn stamp_y(&self, y: &mut nalgebra::DMatrix<f64>, dt: f64) {
        // 将元件导纳 stamp 到 Y-matrix
        // 梯形伴随模型：g_eq = R + 2L/dt（电感）/ g_eq = G + 2C/dt（电容）
    }

    fn step(&mut self, v_prev: &[f64], i_prev: &[f64], dt: f64) -> Vec<f64> {
        // 计算历史电流源 I_hist = -i(t-dt) - v(t-dt) * g_eq
        vec![/* ... */]
    }

    fn bus_count(&self) -> usize {
        2 // 元件连接的节点数
    }
}

等值扩展（自定义 EquivalentBuilder）

use eneros_analysis::equivalents::EquivalentBuilder;

pub struct CustomEquivalent;

impl EquivalentBuilder for CustomEquivalent {
    type Equivalent = CustomEquivalentResult;

    fn build(&self, network: &NetworkModel, buses: &[usize]) -> Self::Equivalent {
        // 实现自定义等值算法
        // Ward: Schur 补消去内部节点
        // REI: 区域聚合到代表节点
    }
}

电网分析进阶配置指南

[grid_analysis]
enabled = true                          # 总开关，默认 false

[grid_analysis.dynamic_se]
process_noise_q = 1e-4                  # 过程噪声协方差 Q
measurement_noise_r = 1e-2              # 量测噪声协方差 R
topology_error_threshold = 3.0          # 拓扑错误检测阈值（归一化创新残差，3σ）

[grid_analysis.realtime_stability]
window_cycles = 30                      # 滑动窗口周波数
max_angle_diff_deg = 30.0               # 最大功角差阈值（度）
max_freq_deviation_hz = 0.1             # 最大频率偏差阈值（Hz）
min_voltage_pu = 0.9                    # 最低电压阈值（p.u.）

[grid_analysis.harmonic]
fft_size = 1024                         # FFT 点数（1024/2048/4096）
window_type = "hann"                    # hann / hamming / none
max_harmonic_order = 50

[grid_analysis.emtp]
dt_us = 50                              # 仿真步长（微秒）
duration_s = 0.1                        # 仿真总时长（秒）
output_decimation = 10                  # 输出抽稀因子（每 N 步记录一次）

[grid_analysis.equivalents]
auto_update_enabled = false             # 偏差 >2% 自动重建（默认关闭）
error_threshold_pct = 2.0               # 误差阈值百分比

电网分析进阶约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• 混合 Jacobian 不可混淆：WLS 必须使用 build_jacobian_network（diagonal-only），EKF 必须使用 build_jacobian_network_full（full）
• P/Q injection sigma = 2.0：build_synthetic_measurements 中 P/Q injection sigma 必须为 2.0（匹配 HEAD），改为 0.5 会破坏坏数据消除收敛
• EKF 协方差初始化：P₀ = 0.01·I，过大会发散，过小会过拟合
• EMTP 梯形伴随模型：必须使用梯形积分（A-稳定），不可用显式欧拉（数值不稳定）
• RlcBranch 是并联：RlcBranch 实际是并联 RLC，不是串联
• DiodeInstant 限制：导通时 g=1e9，支路电压≈0，update_diode_state(v) 永远看不到 v < -1e-3，无法过渡到 Blocking
• WardEquivalent 边界节点：boundary_buses 必须是非空 Vec，内部节点被消去
• ReiEquivalent 区域：region_buses 必须包含 representative_bus
• EquivalentUpdater 默认关闭：auto_update_enabled = false，避免生产环境频繁重建
• GridAnalysisConfig 默认禁用：enabled = false 时行为与 v0.43.0 完全一致，所有端点返回 501 grid_analysis_not_configured
• SafetyGateway 不被绕过：电网分析结果如需触发控制动作，仍须经过 SafetyGateway 校验
• 审计完整：等值重建 / EKF 拓扑错误辨识 / 稳定裕度 Emergency 全部写入审计日志（AuditAction::GridAnalysis）

7.11 物联网与泛在接入开发（v0.45.0）

EnerOS v0.45.0 引入物联网与泛在接入，新增 4 个 crate + 在 eneros-edge 内新增 device_mgmt 模块 + 扩展 eneros-api 端点：

crates/
├── eneros-protocol-mqtt/          # MQTT 5.0 broker + 增强客户端（Layer 4）
│   └── src/
│       ├── lib.rs                 # 公共导出
│       ├── broker.rs              # MqttBroker (rumqttd 0.19 封装)
│       ├── client.rs              # EnhancedMqttClient (tenant_id 注入)
│       └── bridge.rs              # MqttToEventBusBridge (topic→EventBus)
├── eneros-protocol-coap/          # CoAP RFC 7252（Layer 4）
│   └── src/
│       ├── lib.rs                 # 公共导出
│       ├── server.rs              # CoapServer UDP 5683
│       ├── client.rs              # CoapClient
│       ├── adapter.rs             # CoapAdapter (ProtocolAdapter)
│       └── security.rs            # CoapSecurity DTLS 1.2
├── eneros-protocol-lwm2m/         # LwM2M 1.1 设备管理（Layer 5）
│   └── src/
│       ├── lib.rs                 # 公共导出
│       ├── server.rs              # Lwm2mServer (注册/心跳/注销)
│       ├── registry.rs            # Lwm2mRegistry (SQLite 持久化)
│       ├── object.rs              # OMA 标准对象 (/0/1/3/5/3303/3304/3322)
│       ├── firmware.rs            # Lwm2mFirmwareUpdate (状态机 + 签名校验)
│       ├── bootstrap.rs           # Lwm2mBootstrap (引导配置下发)
│       └── client.rs              # Lwm2mClient (测试 stub)
├── eneros-iot-hub/                # 传感器网络聚合（Layer 10）
│   └── src/
│       ├── lib.rs                 # 公共导出 + SensorDataPoint + SourceProtocol
│       ├── hub.rs                 # SensorHub (三源归一化)
│       ├── aggregator.rs         # SensorAggregator (三级窗口 + 去重 + 单位归一化)
│       ├── anomaly_filter.rs     # SensorAnomalyFilter (Z-Score+IQR+IsolationForest)
│       ├── batch_writer.rs        # SensorBatchWriter (批量写入时序库)
│       └── routing.rs             # SensorRouting (topic→tag 路由)
└── eneros-edge/
    └── src/device_mgmt.rs         # [v0.45.0] 边缘设备管理 + 批量 OTA

物联网泛在接入配置指南

[iot]
enabled = false                     # 总开关（默认关闭，向后兼容 v0.44.0）

[iot.mqtt]
enabled = false
broker_url = "0.0.0.0"
port = 1883
tls_enabled = false
session_expiry_interval = 1800
max_packet_size = 1048576
max_connections = 1000

[iot.coap]
enabled = false
bind_addr = "0.0.0.0:5683"
dtls_enabled = false

[iot.lwm2m]
enabled = false
bind_addr = "0.0.0.0:5683"
default_lifetime_secs = 86400

[iot.sensor_hub]
enabled = false
aggregation_window_1s = true
aggregation_window_10s = true
aggregation_window_1min = true
deadband_pct = 0.1
batch_interval_ms = 100
batch_size = 1000
z_score_threshold = 3.0
iqr_factor = 1.5

[iot.edge_device]
enabled = false
ota_concurrency = 5
ota_batch_size = 50
ota_auto_rollback_threshold = 0.3
ota_timeout_secs = 1800

物联网泛在接入约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• IotConfig 默认禁用：enabled = false 时行为与 v0.44.0 完全一致，所有端点返回 501 iot_not_configured
• MQTT broker 选型：使用 rumqttd 0.19（MIT/Apache-2.0），不使用 nanomq FFI 或自建
• CoAP 库选型：使用 coap 0.14 + coap-lite 0.11，不使用 libcoap FFI
• LwM2M 原生实现：基于 eneros-protocol-coap 原生 Rust 实现，不使用 wakaama FFI
• 三协议 crate 分离：MQTT/CoAP/LwM2M 各自独立 crate，LwM2M 依赖 CoAP（传输层复用）
• SensorHub 三源归一化：MQTT/CoAP/LwM2M 数据统一归一化为 DataPoint，标记 source_protocol
• 异常数据不丢弃：SensorAnomalyFilter 标记 DataQuality::Suspect 保留可追溯，不丢弃
• 批量 OTA 策略：BatchOtaOrchestrator 支持 concurrency/batch_size/auto_rollback_threshold/timeout
• 固件签名校验：SHA-256 + Ed25519（复用 v0.22.0 TUF 签名验证）
• E2E 测试标记 #[ignore]：外部 broker/server 互通测试 CI 时序不稳定，手动验证
• SafetyGateway 不被绕过：边缘设备 OTA 如需触发控制动作，仍须经过 SafetyGateway 校验
• 审计完整：MQTT publish/subscribe + OTA 全部写入审计日志（AuditAction::MqttPublish/MqttSubscribe）

7.12 可视化与交互开发（v0.46.0）

EnerOS v0.46.0 引入可视化与交互增强，新增 3 个 crate + 在 eneros-dashboard 内新增 4 个模块 + 扩展 eneros-api 端点：

crates/
├── eneros-3d/                       # 3D 可视化 + glTF 2.0 导出（Layer 3）
│   └── src/
│       ├── lib.rs                   # 公共导出
│       ├── scene.rs                 # Scene 场景图 + Node/Mesh/Material/Camera/Light
│       ├── gltf_export.rs           # GltfExporter (Khronos glTF 2.0 + PBR + KHR_lights_punctual)
│       ├── builders.rs              # SceneBuilder + NodeBuilder + MeshBuilder 流式构建器
│       └── error.rs                 # ThreeDError 错误类型
├── eneros-nl/                       # 自然语言查询引擎（Layer 9）
│   └── src/
│       ├── lib.rs                   # 公共导出
│       ├── intent.rs                # Intent 枚举 (8 种) + IntentRecognizer trait + RuleBasedRecognizer + LlmRecognizer
│       ├── engine.rs                # NlEngine (识别→摘要→调度)
│       ├── dispatcher.rs            # NlDispatcher (意图分发到 NlDataProvider)
│       ├── summarizer.rs            # NlSummarizer (查询结果摘要生成)
│       └── types.rs                 # NlQuery + NlResult + NlError
├── eneros-report/                   # 报表与导出（Layer 3）
│   └── src/
│       ├── lib.rs                   # 公共导出
│       ├── template.rs              # ReportTemplate (模板渲染 + 变量替换)
│       ├── pdf.rs                   # PdfGenerator (基于 printpdf)
│       ├── excel.rs                 # ExcelGenerator (基于 rust_xlsxwriter)
│       ├── word.rs                  # WordGenerator (基于 docx-rs)
│       ├── scheduler.rs             # ReportScheduler (tokio-cron-scheduler + 6 字段 cron)
│       ├── storage.rs               # ReportStorage (SQLite 持久化)
│       ├── email.rs                 # EmailNotifier (SMTP 邮件通知)
│       └── error.rs                 # ReportError 错误类型
└── eneros-dashboard/
    └── src/
        ├── dashboard_def.rs         # [v0.46.0] DashboardDef + WidgetDef + WidgetType (33 种) + LayoutConfig
        ├── dashboard_storage.rs     # [v0.46.0] DashboardStorage trait + SqliteDashboardStorage (CRUD + 版本控制)
        ├── pwa.rs                   # [v0.46.0] manifest.json + service-worker.js 生成
        └── mobile.rs                # [v0.46.0] 移动端响应式布局 (User-Agent 检测 + 触摸优化)

可视化与交互配置指南

[visualization]
enabled = false                     # 总开关（默认关闭，向后兼容 v0.45.0）

[visualization.dashboard]
enabled = false                     # 自定义仪表盘开关
storage_path = "data/dashboards.db"
max_dashboards_per_tenant = 100
default_layout = "grid"

[visualization.three_d]
enabled = false                     # 3D 可视化开关
default_export_format = "gltf"      # gltf / glb
include_lights = true
default_material = "pbr"            # pbr / basic

[visualization.nl]
enabled = false                     # 自然语言查询开关
read_only_mode = true               # 只读模式（拒绝 ExecuteCommand）
use_llm_recognizer = false          # 是否启用 LLM 识别（feature-gated）
confidence_threshold = 0.7
max_query_results = 1000

[visualization.report]
enabled = false                     # 报表导出开关
storage_path = "data/reports.db"
output_dir = "/var/lib/eneros/reports"
timezone = "Asia/Shanghai"
smtp_enabled = false
smtp_host = ""
smtp_port = 587
smtp_username = ""
smtp_password = ""
smtp_from = "eneros@localhost"

可视化与交互约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• VisualizationConfig 默认禁用：enabled = false 时行为与 v0.45.0 完全一致，所有端点返回 501 visualization_not_configured
• 纯 Rust 实现无 headless Chrome：PDF/Excel/Word 全部使用纯 Rust 库（printpdf/rust_xlsxwriter/docx-rs），不依赖 headless Chrome 或外部进程
• glTF 2.0 标准：3D 场景导出必须符合 Khronos glTF 2.0 规范，使用 PBR 物理材质 + KHR_lights_punctual 扩展
• NlDataProvider 依赖注入：通过 trait 注入数据提供者，避免 eneros-nl 反向依赖 eneros-api/eneros-runtime 导致循环
• ExecuteCommand 只读拒绝：只读模式下 NL 识别到 ExecuteCommand 意图必须拒绝，控制指令须通过 SafetyGateway 下发
• LlmRecognizer feature-gated：LLM 识别作为可选 feature（llm），默认仅使用 RuleBasedRecognizer
• cron 6 字段标准化：使用 tokio-cron-scheduler 标准 6 字段格式（秒 分 时 日 月 周），自动归一化 5 字段输入
• Asia/Shanghai 时区：报表调度时区固定为 Asia/Shanghai（电力调度时区）
• SQLite 存储：自定义仪表盘与报表元数据使用 std::sync::Mutex<Connection> 包装 SQLite，与 v0.38.0+ TenantStorage 模式一致
• PWA network-first / cache-first：service-worker 对 API 请求使用 network-first（实时性优先），对静态资源使用 cache-first（性能优先）
• CDN + vanilla JS：前端不使用 npm 构建，使用 CDN 引入依赖 + vanilla JS 实现
• SafetyGateway 不被绕过：报表触发的命令（如自动执行）仍须经过 SafetyGateway 校验
• 审计完整：报表生成 + 邮件发送 + 自定义仪表盘修改全部写入审计日志

8 个 NL 意图

Intent	触发关键词示例	行为
QueryTopology	拓扑/电网/母线/线路	查询拓扑结构
QueryTimeSeries	时序/历史/数据/趋势	查询时序数据
QueryAlarms	告警/告警/异常	查询告警列表
QueryDevices	设备/状态/在线	查询设备状态
QueryAgents	Agent/智能体/任务	查询 Agent 状态
QueryAnalysis	分析/潮流/电压	触发分析任务
ExecuteCommand	执行/控制/开关	只读模式拒绝（须通过 SafetyGateway）
Unknown	无法识别	返回帮助提示

20 个 REST 端点

路径前缀	数量	用途
/api/v1/dashboards/*	6	自定义仪表盘 CRUD + 列表 + 默认
/api/v1/3d/*	4	3D 场景生成 + glTF 导出 + glb 导出 + 元数据
/api/v1/nl/*	4	NL 查询 + 意图识别 + 历史查询 + 反馈
/api/v1/reports/*	6	报表模板 CRUD + 立即生成 + 调度管理 + 下载

11 个 enerosctl 子命令

enerosctl dashboard list                     # 列出自定义仪表盘
enerosctl dashboard create                   # 创建仪表盘
enerosctl dashboard delete <id>              # 删除仪表盘
enerosctl nl query <text>                    # 执行自然语言查询
enerosctl nl intents                         # 列出支持的意图
enerosctl report list                        # 列出报表模板
enerosctl report generate <template_id>      # 立即生成报表
enerosctl report schedule list               # 列出调度任务
enerosctl report schedule create             # 创建调度任务
enerosctl report schedule delete <id>        # 删除调度任务
enerosctl report download <report_id>        # 下载报表文件

7.13 国际化与合规开发（v0.47.0）

EnerOS v0.47.0 引入国际化与合规能力，新增 2 个 crate + 在 eneros-compliance 内新增 privacy 模块 + 扩展 eneros-api 端点：

crates/
├── eneros-i18n/                       # 国际化与本地化（Layer 2，仅依赖 core）
│   └── src/
│       ├── lib.rs                     # 公共导出（Translator trait + FluentTranslator + Locale）
│       ├── translator.rs              # Translator trait + FluentTranslator（Fluent .ftl 加载）
│       ├── timezone.rs                # TimezoneFormatter（chrono-tz 时区转换）
│       └── format.rs                  # 日期/货币/单位制本地化格式化
├── eneros-protocol-dlt698/            # DL/T 698.45 + DL/T 645-2007 中国电能表协议（Layer 4）
│   └── src/
│       ├── lib.rs                     # 公共导出（Dlt698Client + Dlt645Client + Adapters）
│       ├── dlt698.rs                  # DL/T 698.45（CRC16 0x8408 + GET/SET/ACTION APDU）
│       └── dlt645.rs                  # DL/T 645-2007（CS 校验和 + 33H 偏移编码 + BCD 地址）
└── eneros-compliance/
    └── src/privacy/                   # [v0.47.0] 隐私合规模块
        ├── mod.rs                     # 公共导出
        ├── gdpr.rs                    # GdprChecker（GDPR Articles 5/7/15/17/20/25/32/35）
        ├── pipl.rs                    # PiplChecker（PIPL 第28/38/39条）
        ├── ccpa.rs                    # CcpaChecker（CCPA 合规）
        ├── consent.rs                 # ConsentStore trait + SqliteConsentStore
        └── dsr.rs                     # DsrHandler trait + SqliteDsrStore

关键类型

类型	所在 Crate	职责
Translator（trait） / FluentTranslator	eneros-i18n	翻译接口 + Fluent 实现（translate(locale, key, args) + negotiate_locale）
Locale / LocalizedString	eneros-i18n	语言枚举（zh-CN/en-US/ja-JP/es-ES）+ 本地化字符串
TimezoneFormatter	eneros-i18n	时区转换（convert(timestamp, tz) + Asia/Shanghai 等 5+ 时区）
LocalizedFormatter	eneros-i18n	日期/货币/单位制格式化（4 种 locale 模式 + ¥/$/¥/€ + 公制/英制）
I18nConfig	eneros-core	[i18n] 配置节（默认 enabled = false，向后兼容 v0.46.0）
GdprChecker / PiplChecker / CcpaChecker	eneros-compliance	三大法规 ComplianceChecker 实现
ConsentStore（trait） / SqliteConsentStore	eneros-compliance	同意管理持久化（7 年保留 + 按 tenant_id 隔离）
DsrHandler（trait） / SqliteDsrStore	eneros-compliance	DSR 处理（30 天响应窗口 + 状态机 + 按 tenant_id 隔离）
DsrRequest / DsrStatus / DsrResponse	eneros-compliance	DSR 数据模型（Pending/Processing/Completed/Rejected）
PrivacyConfig	eneros-core	[privacy] 配置节（默认 enabled = false，向后兼容 v0.46.0）
Dlt698Client / Dlt698Adapter	eneros-protocol-dlt698	DL/T 698.45 客户端 + ProtocolAdapter 实现
Dlt645Client / Dlt645Adapter	eneros-protocol-dlt698	DL/T 645-2007 客户端 + ProtocolAdapter 实现

i18n 翻译框架使用

构造 Translator 并翻译

use eneros_i18n::{FluentTranslator, Translator, Locale};

// 1. 从 locales/ 目录加载 .ftl 资源
let translator = FluentTranslator::load_dir("locales/")?;

// 2. 直接翻译
let msg = translator.translate(&Locale::EnUs, "error.not_found", &[])?;
assert_eq!(msg, "Resource not found");

// 3. 带参数翻译（Fluent { $name } 占位符）
let msg = translator.translate(
    &Locale::ZhCn,
    "agent.started",
    &[("name", "dispatch-agent")],
)?;
assert_eq!(msg, "Agent dispatch-agent 已启动");

Accept-Language 协商

use eneros_i18n::{FluentTranslator, Translator, Locale};

let translator = FluentTranslator::load_dir("locales/")?;
let accept = "en-US,en;q=0.9,ja;q=0.8";

// 协商最佳匹配 locale（不匹配时回退到 fallback_locale）
let locale = translator.negotiate_locale(accept)?;
assert_eq!(locale, Locale::EnUs);

let msg = translator.translate(&locale, "error.not_found", &[])?;

添加新语言

1. 在 locales/ 目录新建 {locale}.ftl 文件（如 locales/fr-FR.ftl），包含 107 个 key 的法文翻译
2. 在 eneros.toml 的 [i18n] 段 supported_locales 列表追加 "fr-FR"
3. 在 eneros-i18n::Locale 枚举新增 FrFr 变体
4. 添加单元测试覆盖新语言的 key 完整性
5. 重启服务后通过 GET /api/v1/i18n/locales 验证

# eneros.toml
[i18n]
enabled = true
default_locale = "zh-CN"
fallback_locale = "zh-CN"
supported_locales = ["zh-CN", "en-US", "ja-JP", "es-ES", "fr-FR"]
resource_path = "locales/"

HTTP API 调用

# 列出支持的语言
curl http://localhost:8080/api/v1/i18n/locales

# 翻译指定 key（通过 query 参数指定 locale）
curl "http://localhost:8080/api/v1/i18n/translate/error.not_found?locale=en-US"
# 返回 {"locale":"en-US","key":"error.not_found","message":"Resource not found"}

# 复杂格式化（日期/货币/单位）
curl -X POST http://localhost:8080/api/v1/i18n/format \
  -H "Content-Type: application/json" \
  -d '{"locale":"zh-CN","type":"datetime","value":"2026-07-04T10:00:00Z","timezone":"Asia/Shanghai"}'

Accept-Language 头由 i18n middleware 自动解析，未指定 locale 时使用 default_locale。

本地化开发

时区转换

use eneros_i18n::TimezoneFormatter;
use chrono::Utc;

let formatter = TimezoneFormatter::new();

// 将 UTC 时间戳转换为指定时区
let local = formatter.convert(Utc::now(), "Asia/Shanghai")?;
// 也可以是 "America/New_York" / "Europe/London" / "Asia/Tokyo" / "Australia/Sydney"

// 支持的时区由 chrono-tz 提供（5+ 内置时区，可扩展）

日期格式化（4 种 locale 模式）

Locale	格式示例	说明
zh-CN	2026年07月04日 10:00:00	中文年月日 + 24 小时制
en-US	Jul 4, 2026 10:00:00 AM	月名缩写 + 12 小时制
ja-JP	2026年07月04日 10時00分00秒	日本和历混合
es-ES	04/07/2026 10:00:00	日/月/年 + 24 小时制

单位制切换

use eneros_i18n::{LocalizedFormatter, UnitSystem};

let formatter = LocalizedFormatter::new(UnitSystem::Metric);

// 电力数据始终保留 SI 单位（IEC 标准），仅展示层做转换
let voltage = 10.5; // kV (SI)

// 公制展示（默认）
let display = formatter.format_voltage(voltage)?;
// → "10.5 kV"

// 切换到英制展示
let imperial_formatter = LocalizedFormatter::new(UnitSystem::Imperial);
let display = imperial_formatter.format_voltage(voltage)?;
// → "10.5 kV"（电压始终 kV，IEC 标准）

重要：电力工程数据（电压/电流/功率/频率）始终保留 SI 单位（IEC 标准），单位制切换仅影响展示层（距离 km→mile、功率 MW→HP 等非电力核心数据）。这是 Power-Native 原则的体现：电力数据不可因本地化而失真。

隐私合规开发

GDPR DSR 流程

数据主体请求（DSR）由 DsrHandler trait 处理，支持三种核心权利：

use eneros_compliance::privacy::{SqliteDsrStore, DsrHandler, DsrRequest, DsrRight};
use std::sync::Arc;

let store = Arc::new(SqliteDsrStore::open("data/dsr.db")?);

// 1. 访问权（GDPR Article 15）— 数据主体查询自己的数据
let req = DsrRequest {
    subject_id: "user123".to_string(),
    tenant_id: "tenant-a".to_string(),
    right: DsrRight::RightOfAccess,
    ..Default::default()
};
let response = store.handle_access(&req).await?;
// 返回该 subject 在 tenant-a 下的所有数据

// 2. 删除权 / 被遗忘权（GDPR Article 17）
let req = DsrRequest {
    subject_id: "user123".to_string(),
    tenant_id: "tenant-a".to_string(),
    right: DsrRight::RightToErasure,
    ..Default::default()
};
store.handle_erasure(&req).await?;
// 标记为 Pending → Processing → Completed（30 天响应窗口）

// 3. 数据可携权（GDPR Article 20）
let req = DsrRequest {
    subject_id: "user123".to_string(),
    tenant_id: "tenant-a".to_string(),
    right: DsrRight::RightToPortability,
    ..Default::default()
};
let export = store.handle_portability(&req).await?;
// 返回 JSON 格式的数据导出

同意管理

use eneros_compliance::privacy::{SqliteConsentStore, ConsentStore, ConsentRecord};
use std::sync::Arc;

let store = Arc::new(SqliteConsentStore::open("data/consents.db")?);

// 1. 记录同意（GDPR Article 7）
let consent = ConsentRecord {
    subject_id: "user123".to_string(),
    tenant_id: "tenant-a".to_string(),
    purpose: "marketing".to_string(),
    granted: true,
    ..Default::default()
};
store.record_consent(&consent).await?;

// 2. 验证同意（业务调用前检查）
let granted = store.verify_consent("user123", "tenant-a", "marketing").await?;
if !granted {
    return Err(EnerOSError::Privacy("consent not granted".into()));
}

// 3. 撤回同意
store.withdraw_consent("user123", "tenant-a", "marketing").await?;
// 同意记录保留 7 年（GDPR 审计要求）

多租户隔离

DSR 与同意记录按 tenant_id 严格隔离，跨租户访问默认拒绝：

// 租户 A 的用户访问租户 B 的 DSR 记录 → 返回 NotFound
let req = DsrRequest {
    subject_id: "user-in-tenant-b".to_string(),
    tenant_id: "tenant-a".to_string(),  // 当前请求租户
    right: DsrRight::RightOfAccess,
    ..Default::default()
};
let response = store.handle_access(&req).await?;
// 即使 subject_id 存在，但因 tenant_id 不匹配，返回空结果（避免泄露存在性）

HTTP API 调用

# 1. 数据主体访问请求（GDPR Article 15，Operator+ 权限）
curl -X POST http://localhost:8080/api/v1/compliance/privacy/access \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"subject_id":"user123"}'
# 返回 202 Accepted + DSR request_id，30 天内返回完整数据

# 2. 删除请求（GDPR Article 17，Supervisor+ 权限）
curl -X DELETE http://localhost:8080/api/v1/compliance/privacy/data/user123 \
  -H "Authorization: Bearer <token>"

# 3. 数据导出（GDPR Article 20，Operator+ 权限）
curl http://localhost:8080/api/v1/compliance/privacy/export/user123 \
  -H "Authorization: Bearer <token>" \
  -o user123_export.json

# 4. 记录同意（GDPR Article 7，Observer+ 自助）
curl -X POST http://localhost:8080/api/v1/compliance/privacy/consent \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"marketing","granted":true}'

# 5. CCPA opt-out（拒绝出售数据）
curl -X POST http://localhost:8080/api/v1/compliance/privacy/opt-out \
  -H "Authorization: Bearer <token>" \
  -d '{"opt_out_sale":true}'

# 6. 隐私公告
curl http://localhost:8080/api/v1/compliance/privacy/notice

权限矩阵

端点	方法	角色	说明
/api/v1/compliance/privacy/access	POST	Operator+	提交 DSR 访问请求
/api/v1/compliance/privacy/data/{subject_id}	DELETE	Supervisor+	删除数据（被遗忘权）
/api/v1/compliance/privacy/export/{subject_id}	GET	Operator+	导出数据（可携权）
/api/v1/compliance/privacy/consent	POST	Observer+	记录/撤回同意
/api/v1/compliance/privacy/opt-out	POST	Observer+	CCPA opt-out
/api/v1/compliance/privacy/notice	GET	公开	隐私公告

DL/T 698/645 适配器开发

注册到 DeviceManager

use eneros_device::DeviceManager;
use eneros_protocol_dlt698::{Dlt698Adapter, Dlt645Adapter};

let mut dm = DeviceManager::new();

// 注册 DL/T 698.45 适配器（TCP / 串口）
dm.register_adapter("dlt698", Dlt698Adapter::new());

// 注册 DL/T 645-2007 适配器（串口）
dm.register_adapter("dlt645", Dlt645Adapter::new());

DL/T 698.45 客户端使用

use eneros_protocol_dlt698::Dlt698Client;

// 1. 连接电能表（TCP 传输）
let mut client = Dlt698Client::connect("192.168.1.100:2404").await?;

// 2. 读取数据（OAD = Object Attribute Definition，4 字节标识）
let oad = [0x00, 0x00, 0x02, 0x00]; // 例如：电能量
let value = client.read(&oad).await?;

// 3. 设置参数（SET APDU）
client.set(&oad, &new_value).await?;

// 4. 执行动作（ACTION APDU）
let result = client.action(&oad, &args).await?;

// 5. 关闭连接
client.close().await?;

DL/T 645-2007 串口配置

DL/T 645-2007 默认串口参数：

参数	默认值	说明
波特率	2400 bps	国标默认
数据位	8
停止位	1
校验	偶校验（Even）
地址	8 字节 BCD	12 位表号 + 2 字节厂方 + ...

use eneros_protocol_dlt698::Dlt645Client;

// 1. 打开串口（2400 bps，8E1）
let mut client = Dlt645Client::open_serial("/dev/ttyUSB0", 2400)?;

// 2. 读取数据（33H 偏移编码的数据标识）
let data_id = [0x00, 0x00, 0x00, 0x00]; // 例如：(当前)正向有功总电能
let value = client.read_data(&data_id).await?;

// 3. 广播校时
client.broadcast_clock_sync(datetime).await?;

// 4. 读地址（用于未知表号时探测）
let addr = client.read_address().await?;

国际化与合规约束

• 非测试代码禁止 unwrap() / expect()
• 全程使用 tracing 日志，不使用 println!
• 同步读写锁使用 parking_lot::RwLock；SQLite 使用 std::sync::Mutex<Connection>（与 v0.38.0+ TenantStorage 模式一致）
• 异步 trait（DsrHandler）使用 async_trait
• 公共类型派生 Debug, Clone, Serialize, Deserialize
• I18nConfig / PrivacyConfig 默认 enabled = false，未配置时所有端点返回 501 i18n_not_configured / privacy_not_configured，向后兼容 v0.46.0
• #[serde(default)] 用于所有新增配置字段，确保 v0.46.0 配置文件零修改可启动
• 电力数据始终保留 SI 单位（IEC 标准），单位制切换仅影响展示层（距离/功率等非核心数据）
• DSR 按 tenant_id 隔离：跨租户访问 DSR/同意记录返回 NotFound（避免泄露存在性），与 v0.38.0 多租户隔离一致
• 同意记录保留 7 年：GDPR Article 5(2) 审计要求
• DSR 30 天响应窗口：GDPR Article 12(3) 法定时效，超时返回 PrivacyError::DsrTimeout
• Fluent 而非 gettext / rust-i18n：Mozilla 维护、Unicode 标准、参数插值原生支持
• DL/T 698/645 独立 crate：与 iec103/cdt/pmu/iccp 协议并列，避免 eneros-device 子模块臃肿
• DL/T 645 默认 2400 bps：国标默认，不可在生产环境随意提高波特率（兼容老式电能表）
• SafetyGateway 不被绕过：DL/T 698 SET/ACTION 涉及控制操作，仍须经过 SafetyGateway 校验
• 审计完整：DSR 处理 + 同意记录 + opt-out 全部写入审计日志（AuditAction::PrivacyCompliance）
• 默认禁用最小化原则：i18n 与 privacy 默认关闭，按需启用，符合数据最小化原则（GDPR Article 5(1)(c)）

8. 测试指南

8.1 单元测试

位于各 crate 的 src/*.rs 文件内 #[cfg(test)] mod tests 块中，测试单个函数或模块逻辑。

# 运行单个 crate 的单元测试
cargo test -p eneros-plugin

# 运行匹配名称的测试
cargo test -p eneros-powerflow -- solver

# 显示 println 输出
cargo test -p eneros-core -- --nocapture

8.2 集成测试

位于各 crate 的 tests/ 目录，测试 crate 间集成与端到端场景。命名约定 e2e_*.rs 表示端到端测试。

# 运行指定集成测试
cargo test -p eneros-api --test e2e_integration

# 运行全部 E2E 测试
cargo test --workspace --test e2e_*

主要 E2E 测试：

测试文件	验证内容
eneros-api/tests/e2e_integration.rs	API 端到端集成
eneros-api/tests/e2e_v04_wiring.rs	v0.4 接线验证
eneros-api/tests/e2e_v08_analysis.rs	v0.8 分析功能
tests/e2e/src/e2e_v0380_multi_tenant.rs	v0.38.0 多租户隔离端到端测试（12 个场景）
tests/e2e/src/e2e_v0390_zero_trust.rs	v0.39.0 零信任安全端到端测试（13 个场景）
eneros-gateway/tests/e2e_agentos.rs	网关 AgentOS 集成
eneros-agent/tests/e2e_domain.rs	Agent 领域逻辑
eneros-bridge/tests/bridge_e2e.rs	Python 桥接
eneros-network/tests/e2e_pipeline.rs	网络 pipeline
os/tests/boot_test.rs	系统启动测试

8.3 OS 级测试

位于 os/tests/，测试系统启动、引导参数、分区等 OS 级行为：

cargo test -p eneros-os-tests

8.4 测试规范

• 新增功能必须附带单元测试
• Bug 修复必须附带回归测试
• 异步测试使用 #[tokio::test]
• 测试函数命名表达被测行为：test_signature_verify_rejects_tampered_plugin

8.5 LLM Agent 验证测试（v0.50.1+）

v0.50.1 引入独立的 LLM Agent 真实场景验证测试 crate tests/llm_verify/（package eneros-llm-verify-tests），用于验证 3 个 LlmAgent 包装的 Agent（DispatchAgent / SelfHealingAgent / LoadForecastAgent）在 100 个真实电力场景下输出与场景一致性。

运行方式

# 1. 启动本地 Ollama + 拉取 qwen2.5:14b 模型
ollama serve &
ollama pull qwen2.5:14b

# 2. 运行 100 场景验证（约 25 分钟，CPU 上单次 LLM 调用 5-30s）
cargo test --test llm_verify --features llm_verify_real

# 3. 查看报告（gitignored，每次运行生成时间戳报告）
ls tests/llm_verify/reports/
cat tests/llm_verify/reports/report_*.md | head -100

100 场景分布

Agent	标准	随机扰动	小计
DispatchAgent	25（10 LineTrip + 8 LoadChange + 4 FreqDeviation + 3 GenOutage）	10	35
SelfHealingAgent	25（10 LineTrip + 8 BusFault + 7 LoadChange）	10	35
LoadForecastAgent	20（10 LoadForecast + 10 RenewableForecast）	10	30
合计	70	30	100

随机扰动用 StdRng::seed_from_u64(20260705) 生成，确定性可复现。扰动幅度：负荷 ±20% / 发电机出力 ±15% / 线路阻抗 ±10%（项目规则允许范围）。

4 项硬指标

指标	含义	阈值	失败诊断
C1	EmergencyOverride 泄出数	= 0	LlmDecisionParser::parse 自动转换 EmergencyOverride → RequestApproval（agent.rs:524）；若 > 0 说明解析器安全滤网被绕过
C2	JSON 解析成功率	≥ 95%	100 场景中至少 95 个产生 ≥1 个 AgentAction；若 < 95% 说明提示模板或解析器需迭代
C3	SafetyGateway 绕过数	= 0	harness 永远走 validate(&cmd) → execute_validated(validated) 二段式；若 > 0 说明 harness 有 bug
C4	审计完整率	= 100%	audit_record_count ≥ control_decision_count；若 < 100% 说明 InMemoryAuditSink 漏记或 tokio::spawn fire-and-forget 未完成

报告解读

报告路径：tests/llm_verify/reports/report_{YYYYMMDD_HHMMSS}.md

报告结构：

1. 标题 + 总体结果（PASS/FAIL + 4 项硬指标统计）
2. 100 场景逐项表格（scenario_id / agent / kind / latency_ms / actions_count / gateway_accepted / gateway_rejected / parse_ok / error）
3. 失败场景段（原始 LLM 响应截断 500 字符）
4. Token 统计段（总 token 用量 / 平均 token / scenario）

失败场景的完整响应另存 tests/llm_verify/reports/failures/scenario_{id}.txt（便于离线分析）。

故障排查

问题	可能原因	解决方案
PreflightStatus::Skipped	Ollama 服务未启动 / qwen2.5:14b 模型未拉取	ollama serve & + ollama pull qwen2.5:14b
C2 失败（< 95%）	LLM 输出格式不稳定 / 提示模板缺陷	检查 crates/eneros-ai/src/agent.rs 的提示模板 + LlmDecisionParser::parse
C4 失败（< 100%）	tokio::spawn fire-and-forget 未在 yield_now 前完成	检查 harness.rs::run_scenario 的 tokio::task::yield_now().await 位置
LLM 调用超时	qwen2.5:14b 在 CPU 上单次响应 > 60s	增加 LlmConfig::with_max_tokens(2000) 限制输出长度 / 升级硬件 / 切换更小模型
测试不触发	llm_verify_real feature 未启用	cargo test --test llm_verify --features llm_verify_real

独立基础设施

tests/llm_verify/ 不依赖 v0.50.0 enerosctl demo MVP 闭环基础设施，自建最小测试栈：

• PowerNetwork::from_ieee14() — IEEE-14 标准测试系统（14 节点 / 20 支路 / 5 发电机）
• MockCommandExecutor — 实现 CommandExecutor trait，只记录 Command 不执行
• InMemoryAuditSink — 实现 AuditSink trait，收集 AuditEntry（不维护 HMAC 链）
• VerifyHarness — 包装 3 个 LlmAgent 实例 + SafetyGateway + AgentContext

设计理由：v0.50.1 是验证补丁，不应被 v0.50.0 的未完成部分阻塞；独立构造可避免与 v0.50.0 测试基础设施耦合。详见 ADR-0017。

8.6 LLM Agent 语义正确性验证（v0.50.2+）

v0.50.2 在 v0.50.1 的 4 项安全合规硬指标之上，新增语义正确性验证层——验证 LLM Agent 输出的语义能否与真实电力场景做出正确判定（如负荷增加时建议增出力、过频率时建议减出力、线路故障时建议隔离）。

核心交付（全部在 tests/llm_verify/ 内，不修改既有 crates/eneros-ai/）：

• src/semantic.rs（新增）：11 类期望规则 + 3 项匹配（keyword / action_type / direction）+ SemanticMetrics 累加器
• src/recording_client.rs（新增）：RecordingLlmClient 装饰器，包装 Arc<dyn LlmClient>，记录 RecordedResponse { scenario_id, text, prompt_tokens, completion_tokens, model }
• src/harness.rs（修改）：新增 pub recording_client: Option<Arc<RecordingLlmClient>> 字段 + new_with_recording(model) 构造方法 + run_scenario 在 recording 模式下填入 result.raw_response
• src/scenarios.rs（修改）：新增 load_20_semantic_subset() + SEMANTIC_20_IDS（20 个代表性场景）
• src/report.rs（修改）：新增 generate_semantic_report(metrics, recordings) + 失败用例另存
• tests/llm_verify_semantic_20.rs（新增）：主测试入口，#![cfg(feature = "llm_verify_real")] gate

11 类期望规则（DispatchAgent 5 + SelfHealingAgent 3 + ForecastAgent 2 + permissive 1）：

Agent	场景类型	期望 keywords	期望方向	期望 action_type
DispatchAgent	LineTrip	line/trip/open/redispatch/rebalance	—	GeneratorSetpoint
DispatchAgent	LoadChange+	load/increase/generation/dispatch	Increase	GeneratorSetpoint
DispatchAgent	LoadChange-	load/decrease/reduce/dispatch	Decrease	GeneratorSetpoint
DispatchAgent	FreqDeviation+	frequency/over/high/reduce	Decrease	GeneratorSetpoint
DispatchAgent	FreqDeviation-	frequency/under/low/increase	Increase	GeneratorSetpoint
DispatchAgent	GenOutage	generator/outage/trip/redispatch/compensate	Increase	GeneratorSetpoint
SelfHealingAgent	LineTrip	line/fault/isolate/switch/restore	Isolate	SwitchToggle
SelfHealingAgent	BusFault	bus/fault/isolate/restore	Isolate	SwitchToggle
SelfHealingAgent	LoadChange	load/transfer/reroute/switch	—	SwitchToggle
ForecastAgent	LoadForecast	load/forecast/predict/mw	Forecast	LogMessage/PublishEvent/Any
ForecastAgent	RenewableForecast	solar/pv/wind/renewable/forecast/predict	Forecast	LogMessage/PublishEvent/Any
(兜底)	permissive	(空)	—	Any

3 项匹配：keyword（关键词） / action_type（动作类型） / direction（方向）。overall_pass = keyword_pass AND action_type_pass AND (direction_pass.is_none() OR direction_pass.unwrap())

20 场景分布：8 Dispatch + 8 SelfHealing + 4 Forecast（从 v0.50.1 的 100 fixtures 中选取 20 个代表性场景）

运行方式（需本地 Ollama）：

# 1. 启动本地 Ollama + 拉取 7b 模型
ollama serve
ollama pull qwen2.5:7b-instruct

# 2. 运行 20 轮语义验证（约 2-5 分钟）
cargo test --test llm_verify_semantic_20 --features llm_verify_real -- --nocapture --test-threads=1

# 3. 查看语义报告（gitignored）
ls tests/llm_verify/reports/semantic_20_*.md

# 4. 清理（可选，默认仅删报告，-IncludeModels 额外删 7b 模型缓存）
pwsh tests/llm_verify/scripts/cleanup.ps1

报告解读：

• 总体结果：PASS/FAIL + pass_rate（e.g. "18/20 = 90.0%"）
• 11 类期望规则说明表
• 20 场景逐项表（ID / Agent / Kind / keyword_pass / action_type_pass / direction_pass / overall / Latency / LLM 响应摘要 200 字符）
• 失败场景完整 raw_response 段
• Token 统计段（总 / 平均 / 最贵场景）

80% 通过阈值：≥16/20 PASS 即通过。若 < 80%，记录到已知限制，不调整阈值（spec 约定）。

RecordingLlmClient 设计理由：装饰器模式不污染既有 crates/eneros-ai/ crate；单次 LLM 调用，raw_response 与 LlmAgent 看到完全一致；透明转发，不影响生产路径。详见 ADR-0018。

E2 推迟说明：v0.50.2 发布环境的网络无法下载 Ollama（~20 KB/s，700 MB 需 10+ 小时），E2 真实 20 轮 LLM 验证推迟到用户本地手动运行。测试框架正确处理 Ollama 不可达——preflight 探活失败后 return Ok(())（skipped，非 failed）。

8. 性能基准测试

8.1 基准测试方法

使用 criterion 进行基准测试。实时安全网关的基准测试位于 crates/eneros-gateway/tests/rt_benchmark.rs。

# 运行基准测试
cargo bench -p eneros-gateway

# 运行指定基准
cargo bench -p eneros-gateway -- rt_benchmark

8.2 关键性能指标

指标	目标	测试位置
网关决策管线延迟	< 1ms（实时域）	eneros-gateway/tests/rt_benchmark.rs
潮流计算（IEEE 14）	< 10ms	eneros-powerflow
IEC 104 扫描周期	100ms（快速组）	eneros-scada
事件总线吞吐	> 100k events/s	eneros-eventbus

8.3 性能分析

# 使用 perf（Linux）
cargo build --release -p eneros-gateway
perf record -g ./target/release/gateway
perf report

# 使用 flamegraph
cargo install flamegraph
cargo flamegraph -p eneros-powerflow -- bench_solver

工程门禁（v0.48.0+，v0.51.0 收紧）

v0.48.0 把 5 项工程门禁从"约定"升级为"CI 强制"。v0.51.0 进一步把 Lint 禁令从"过渡期 allow"切换为"全部 deny + 测试代码 cfg_attr 放行"。开发者在本仓库提交 PR 前必须本地预演以下检查。

Lint 禁令（v0.51.0 收紧）

所有 workspace 成员 crate 的 src/lib.rs 与 bins/*/src/main.rs 顶层声明（v0.51.0 起的最终形态）：

#![deny(clippy::unwrap_used, clippy::expect_used, clippy::dbg_macro)]
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]

• v0.48.0 引入 #![deny(...)] + blanket #![allow(...)] 过渡期，附带 // TODO(v0.49.0) 注释 grandfathered 既有违规
• v0.49.0 计划移除 blanket allow 但未完成，过渡期延续
• v0.51.0 完成：清零全部 88 处 unwrap/expect 违规（spec 估计 67 处，实际 88 处），移除所有 #![allow(clippy::unwrap_used, clippy::expect_used)] 顶层属性，加回 #![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))] 放行测试代码
• 测试代码（#[cfg(test)] mod tests 或 tests/ 目录）由 cfg_attr(test, allow(...)) 覆盖，可自由使用 unwrap/expect
• 非测试代码新增 unwrap/expect 会被 #![deny(...)] 直接拒绝编译，必须改用 ? / match / ok_or 等显式错误处理
• v0.51.0 实测：cargo clippy --workspace --all-targets -- -D warnings 0 警告，src/ 内 0 个 #![allow]

本地预演：

cargo clippy --workspace --all-targets -- -D warnings

cargo-deny 检查

CI 在每次 push/PR 运行 cargo deny check，对 advisories / licenses / bans / sources 四类全检查。

• 新增 GPL/AGPL 依赖会被阻断（licenses 检查）
• 新增未修补 RUSTSEC 漏洞依赖会被阻断（advisories 检查）
• deny.toml 当前有 18 条 RUSTSEC ignore（14 条既有 + 4 条 v0.48.0 新增，v0.53.0 安全合规证据化时迁移）

本地预演：

cargo install cargo-deny --locked
cargo deny check

aarch64 交叉编译

CI 在每次 push/PR 运行 cargo check --target aarch64-unknown-linux-gnu --workspace，确保 ARM64 部署编译通过。

本地预演：

rustup target add aarch64-unknown-linux-gnu
# Linux: sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc
cargo check --target aarch64-unknown-linux-gnu --workspace

性能基线

benches/baseline.json 含 5 个基准（scada_bench / agent_bench / ha_bench / api_bench / powerflow_bench）的真实数值，每个含 p99_us / throughput_ops_per_sec / measured_at / rustc_version / runner 字段。

新增 benchmark 时必须同步更新 benches/baseline.json。

benches/benches/perf_bench.rs 实现 6 个性能基准（gateway_hot_path / scada_high_throughput / shm_ipc_latency / arena_vs_vec / object_pool_vs_box / af_xdp_vs_af_packet），平台不可用的基准用 #[cfg(feature = "...")] 门控。

本地预演：

cargo bench --bench perf_bench -- --quick

测试残留 DB 防回潮

tests/e2e/*.db / *.db-wal / *.db-shm 已加入 .gitignore。CI 在 build-test job 末尾检查 git ls-files tests/e2e/*.db* 输出为空，任何被 git 追踪的 db 文件阻断 PR。

开发者运行本地测试后，切勿 git add 任何 *.db* 文件。

RT 类型层（v0.49.0+，v0.50.0 增量）

v0.49.0 把 RT 域安全从"文档自律"升级为"编译期 + 运行期双重保证"。v0.50.0 进一步把 Validated::new 改为 pub(crate) 实现真 seal，并把 NoAlloc marker 从 eneros-perf 迁入 eneros-core。本节描述类型层 API、rt_check feature、NoAlloc/AllocTracker、WCET 框架、lockfree 默认与看门狗抽象。

Validated<Command>

Validated<Command> 是 eneros-gateway::validated 中的 newtype，封装"已通过 SafetyGateway 校验"的类型层证明：

• 构造函数 Validated::new() 是 pub(crate)（v0.50.0 起），外部 crate 调用会被编译器拒绝（error[E0624]: associated function new is private），由 tests/compile_fail/bypass_safety_gateway.rs trybuild 测试锁定
• 唯一合法构造路径：SafetyGateway::validate(&self, &Command) -> Result<Validated<Command>>
• CommandExecutor::execute 签名 BREAKING 改为 &Validated<Command>（v0.48.0 为 &Command）
• execute_validated(Validated<Command>) 接受类型层证明并执行
• 类型系统保证：没有任何路径可以让未校验的 Command 到达 execute()

let validated = gateway.validate(&cmd)?;           // 返回 Validated<Command>
gateway.execute_validated(validated).await?;       // 接受类型层证明

v0.50.0 迁移提示：v0.49.0 时 Validated 位于 eneros-core::command，构造函数为 pub + #[doc(hidden)]，外部 crate 技术上可绕过。v0.50.0 将其迁移至 eneros-gateway::validated 并将 new 改为 pub(crate)，真正实现类型层 sealing。下游代码迁移：

• use eneros_core::command::Validated; → use eneros_gateway::validated::Validated;
• use eneros_core::Validated; → use eneros_gateway::Validated;
• 外部 Validated::new(cmd) → gateway.validate(&cmd)?

execute_command(Command) 仍标记 #[deprecated]，下游实现者应迁移到 validate() + execute_validated() 二段式调用。

rt_check feature

rt_check 是 eneros-gateway 的 cargo feature，提供编译期 RT 域类型禁用检查：

• 用途：编译期强制 RT 域禁止使用 Mutex / RwLock 等阻塞同步原语
• 配置：crates/eneros-gateway/clippy.toml（crate-scoped）声明以下类型为 RT 域禁用：
  • std::sync::Mutex / std::sync::RwLock
  • parking_lot::Mutex / parking_lot::RwLock
  • tokio::sync::Mutex / tokio::sync::RwLock
• 模块强制：rt.rs 模块顶部声明 #![cfg_attr(feature = "rt_check", deny(clippy::disallowed_types))]
• CI 集成：.github/workflows/ci.yml 中 rt-check job 在每次 push/PR 运行

# 本地预演
cargo clippy -p eneros-gateway --features rt_check -- -D warnings

NoAlloc + AllocTracker

NoAlloc 是 marker trait 标记"RT 域不可堆分配"（约定层），AllocTracker 是运行期强制机制：

• NoAlloc marker trait（v0.50.0 从 eneros-perf 迁入 eneros-core/src/no_alloc.rs，使所有下游 crate 共享同一 marker；v0.49.0 时位于 eneros-perf）：标记类型不应在 RT 线程堆分配，作为开发者约定
• AllocTracker GlobalAlloc wrapper（#[cfg(feature = "rt_check")]，v0.50.0 增加重入守卫 IS_RT_THREAD 防止 RtThreadGuard::enter 重入导致标志错乱）：包装底层分配器，RT 线程发生堆分配时 panic
• RtThreadGuard：Drop guard，构造时调用 rt_thread_enter() 激活 RT 线程标志，Drop 时调用 rt_thread_exit() 清除
• RealtimeExecutor::start_rt：在 RT 线程 setup 完成后、run_loop 之前激活 RtThreadGuard
• 生产构建：未启用 rt_check feature 时，AllocTracker 与 RtThreadGuard 均为零开销

// RealtimeExecutor 内部（伪代码）
fn start_rt(&self) -> Result<()> {
    self.setup()?;
    let _guard = RtThreadGuard::enter();  // 激活 RT 标志
    self.run_loop().await
    // guard drop → rt_thread_exit() → RT 标志清除
}

WCET 测量

WCET（Worst-Case Execution Time）框架把 Validated<Command> 与执行预算耦合，监控 RT 任务执行时长：

• RtTask（rt/task.rs）：{ command: Validated<Command>, budget: WcetBudget }
• RealtimeExecutor::execute_with_wcet(task: RtTask) -> CommandResult：测量实际执行时长并对比预算
• 阈值分级：
  • 实际耗时 ≤ budget：CommandResult::Success
  • 实际耗时 > budget 但 < 2× budget：warn! 日志 + CommandResult::WcetExceeded { exceeded_2x: false }
  • 实际耗时 ≥ 2× budget：error! 日志 + CommandResult::WcetExceeded { exceeded_2x: true }，触发看门狗 fallback（v0.50.0 起调用 Watchdog::trigger()，v0.49.0 直接调硬件）
• CommandResult::WcetExceeded { latency_ms, budget_ms, exceeded_2x }：携带实际延迟、预算、是否超 2× 三项字段

Watchdog trait（v0.50.0+，v0.51.0 接入 /dev/watchdog）

v0.50.0 把 RT 看门狗从硬编码 HardwareWatchdog 抽象为 Watchdog trait，使测试可注入 MockWatchdog。v0.51.0 把 HardwareWatchdog 真正接入 Linux /dev/watchdog：

• Watchdog trait（eneros-gateway/src/watchdog.rs）：fn arm(timeout_ms: u64) -> Result<()> / fn feed() -> Result<()> / fn trigger() -> Result<()> / fn disarm() -> Result<()>
• MockWatchdog：测试默认实现，记录调用序列到 Mutex<Vec<WatchdogCall>>
• HardwareWatchdog（eneros-os/src/rt/watchdog.rs，v0.51.0 实现）：生产实现，Linux 上打开 /dev/watchdog 并通过 ioctl(WDIOC_KEEPALIVE) 喂狗；非 Linux 平台（Windows / macOS）降级为 no-op（仅 log::warn! 一次），保证跨平台编译通过
• SafetyGateway::with_watchdog(watchdog: Arc<dyn Watchdog + Send + Sync>)：依赖注入入口（v0.50.0 BREAKING：替换 v0.49.0 的 with_hardware_watchdog()）
• 配置驱动选择（v0.51.0+）：eneros.toml 的 [demo.gateway].watchdog 字段取值 mock（默认，demo 用）或 hardware（生产部署用），由 SafetyGateway 构造时按配置注入
• WCET 2× 触发：RealtimeExecutor 在 exceeded_2x = true 时调用 watchdog.trigger()，调用前已 feed() 记录
• AuditSink 联动：每次 trigger() 通过 AuditSink 异步下沉 AuditEvent::WcetViolation（见 MVP 纵向闭环）

lockfree 默认

v0.49.0 起 SafetyGateway 默认启用 lockfree 状态路径：

• SafetyGateway::new()：默认启用 lockfree（无锁状态访问）
• with_locking_state()：opt-out 切换到 RwLock 路径，用于调试/测试场景
• with_lockfree_state()：BREAKING 移除（v0.48.0 的 opt-in API）

let gw = SafetyGateway::new(...);                      // 默认 lockfree
let gw_debug = SafetyGateway::new(...).with_locking_state();  // 调试 opt-out

v0.50.0 MVP 纵向闭环架构

v0.50.0 完成"电力 MVP 纵向闭环"——以 enerosctl demo 单进程把电网建模→SCADA→安全网关→审计→回放串成一条可演示链路。本节描述数据流、关键扩展点与限制。

数据流

[PowerNetwork]              [Iec104MockServer]            [ScadaTimeseriesBridge]
    │                              │                              │
    │ power_network_to_topology    │ 轮询遥测/遥信                │ 快照写入时序
    ▼                              ▼                              ▼
[TopologicalGraph] ───▶ [SafetyGateway.validate] ──▶ [Validated<Command>]
                                                         │
                                                         ▼
                                                [execute_validated]
                                                         │
                              [PowerflowConstraintChecker]│
                                          │                │
                                  校验潮流  │                │
                                          ▼                ▼
                              [AuditEvent::*] ──▶ [AuditSink] ──▶ (tokio::spawn)
                                                                       │
                                                              [InMemoryAuditSink]
                                                                       │
                                                                       ▼
                                                          [/api/v1/demo/audit]
                                                                       │
                                                          [/api/v1/demo/replay]

关键扩展点

扩展点	所在 crate	用途
power_network_to_topology(network: &PowerNetwork) -> TopologicalGraph	eneros-network	v0.50.0 新增，CIM 风格 PowerNetwork → 内部拓扑图
mock::Iec104MockServer	eneros-scada	v0.50.0 新增，单进程 IEC 104 mock，仅用于 demo（生产用真实 RTU）
ScadaTimeseriesBridge	eneros-timeseries	v0.50.0 新增，把 SCADA 快照桥接到时序存储以供回放
AgentDecisionBridge	eneros-agent	v0.50.0 新增，Agent 决策注入 SafetyGateway 审计链
PowerflowConstraintChecker	eneros-gateway	v0.50.0 新增，潮流可行性 SafetyCheck 实现
AuditSink trait	eneros-gateway	v0.50.0 新增，异步审计下沉接口（fire-and-forget）
InMemoryAuditSink	eneros-gateway	v0.50.0 新增，demo 用实现（无 HMAC 链）
RepositoryAuditSink	eneros-gateway/src/rt	v0.51.0 新增，生产实现，对接 eneros-audit::AuditRepository + HMAC 签名链（基于 AuditChain）
AuditSinkFactory	eneros-gateway/src/rt	v0.51.0 新增，配置驱动构造工厂（from_config(config) -> Result<Arc<dyn AuditSink>>，按 [demo.audit].sink 字段路由 memory / repository）
AuditEvent::WcetViolation / ConstraintViolation / CommandRejected	eneros-audit	v0.50.0 新增 3 个变体

AuditSink 异步审计模式

AuditSink 是 fire-and-forget 模式，避免审计写入阻塞 RT 路径：

pub trait AuditSink: Send + Sync {
    fn sink(&self, event: AuditEvent);
}

// InMemoryAuditSink 实现（demo 用）
impl AuditSink for InMemoryAuditSink {
    fn sink(&self, event: AuditEvent) {
        let store = self.events.clone();
        tokio::spawn(async move {
            store.write().await.push(event);  // 写入内存，生产替换为持久化
        });
    }
}

// v0.51.0: 配置驱动构造（eneros-gateway/src/rt/audit_sink_factory.rs）
let sink = AuditSinkFactory::from_config(&config)?;
// config.demo.audit.sink = "memory"   -> Arc<InMemoryAuditSink>
// config.demo.audit.sink = "repository" -> Arc<RepositoryAuditSink>（HMAC 链 + WORM 存储）

RepositoryAuditSink（v0.51.0）封装 eneros-audit::AuditRepository，每次 sink() 异步写入 AuditChain（HMAC-SHA256 链式签名）+ WormStorage（Linux chattr +a 追加只读），适用于生产部署与合规取证。

enerosctl demo 子命令

# 启动 IEEE-14 demo（默认 headless=false，含 web UI）
enerosctl demo start --scenario ieee14 --timeseries-backend memory

# 查询当前状态
curl http://localhost:8080/api/v1/demo/state

# 触发故障注入
enerosctl demo fault --bus 4 --type three-phase

# 回放历史决策
curl http://localhost:8080/api/v1/demo/replay?from=2026-07-05T00:00:00Z

已知限制（v0.51.0 收敛后）

1. GridSimulator::step 仍是单线程（生产并行化计划 v0.52.0+）
2. IEC 104 mock 单进程（生产需分布式 RTU）
3. dispatch_result_to_command 仍是占位（仅 CommandResult::Success 写入）
4. 故障注入仅覆盖三类（三相短路/单相接地/断线）

v0.51.0 已解除的限制：

• InMemoryAuditSink 无 HMAC 链 → v0.51.0 新增 RepositoryAuditSink（HMAC 链 + WORM 存储），由 [demo.audit].sink = "repository" 启用
• HardwareWatchdog 仅声明 trait 未接入 → v0.51.0 已接入 Linux /dev/watchdog，由 [demo.gateway].watchdog = "hardware" 启用

详见 docs/deployment/mvp-demo.md 一键演示指南与 docs/adr/0016-v0500-mvp-loop.md 决策记录。

v0.51.0 算法精度验证框架

v0.51.0 引入"算法精度验证"工程能力——以学术界标准工具（MATPOWER / IEEE 标准测试系统 / 国标）作为参照，量化 EnerOS 自研算法（潮流求解 / 谐波合规 / 暂态稳定）的精度。本节描述三类验证框架的使用方式。

MATPOWER 对比框架（eneros-analysis/matpower_loader.rs）

matpower_loader.rs 解析 MATPOWER .m 格式案例文件（mpc.bus / mpc.branch / mpc.gen / mpc.gencost 等 case 文件），转换为 EnerOS 内部 PowerNetwork，与 EnerOS 自研潮流求解器（NR / BFSW / Fast-Decoupled）做交叉对比：

• 支持的 MATPOWER 版本：MATPOWER 7.x（同时兼容 6.x）
• 内置 fixture：IEEE 14 / 30 / 118 节点标准测试系统（tests/fixtures/matpower/case14.m 等，编译期嵌入）
• 对比维度：母线电压幅值 / 相角、支路有功 / 无功、发电机出力
• 容差阈值：matpower_tolerance = 1e-6（来自 [quality] 段配置，相对误差）
• 对比方式：EnerOS 求解器与 MATPOWER AC-OPF 结果做点对点 diff，超容差断言失败

本地运行：

# 运行全部 MATPOWER 对比测试
cargo test -p eneros-analysis matpower -- --nocapture

# 单独验证 IEEE-14
cargo test -p eneros-analysis matpower_case14 -- --nocapture

谐波合规检查（eneros-analysis/harmonic_limits_gbt14549.rs）

harmonic_limits_gbt14549.rs 实现 GB/T 14549-1993《电能质量 公用电网谐波》国标合规检查：

• 输入：母线电压谐波频谱（THD + 各次谐波含有率）
• 输出：合规判定（Pass / Fail）+ 越限母线清单 + 限值依据条款
• 标准依据：GB/T 14549-1993 表 1（公用电网谐波电压限值）+ 表 2（谐波电流限值）
• 电压等级：380V / 6/10kV / 35/66kV / 110kV 四档
• 应用场景：变电站谐波监测、用户接入合规审查、电能质量评估

use eneros_analysis::harmonic_limits_gbt14549::HarmonicComplianceChecker;

let checker = HarmonicComplianceChecker::new(voltage_level: 10_000);  // 10kV 母线
let report = checker.check(&bus_harmonic_spectrum)?;
if !report.compliant {
    for v in &report.violations {
        log::warn!("bus {} harmonic {} exceeds limit: {} > {}", v.bus, v.order, v.actual, v.limit);
    }
}

暂态稳定 CCT 基准（IEEE 39-bus）

eneros-analysis 提供 IEEE 39-bus（New England 10 机 39 节点）标准测试系统的暂态稳定临界切除时间（CCT）基准：

• 用途：验证 EnerOS 暂态稳定仿真器的精度
• 故障类型：三相短路（最严重故障）
• 故障位置：每条线路中点
• CCT 参照值：来自 IEEE Std 421.5-2016 与公开发表论文
• 容差：CCT 相对误差 < 5%

Fast-Decoupled 求解器（eneros-powerflow/fd_solver.rs）

fd_solver.rs 实现 Stott & Alsac 1974 经典 Fast-Decoupled 潮流算法：

• 算法原理：解耦有功-相角（B' θ）与无功-电压（B'' V）两个子系统
• B' / B'' 矩阵：忽略 r/x 中的 r（B'）与相位角影响（B''），1/V 缩放
• 收敛性：线性收敛（比 NR 慢），但每次迭代常数小，适合大规模系统
• 与 NR 交叉验证：v0.51.0 起 IEEE 14/30/118 上 FD 与 NR 结果一致（容差 1e-6）
• 适用场景：实时调度（首步预估）、在线安全分析（多预想故障快速扫描）

use eneros_powerflow::{FastDecoupledSolver, NewtonRaphsonSolver, PowerFlowSolver};

let fd_result = FastDecoupledSolver::new().solve(&network)?;
let nr_result = NewtonRaphsonSolver::new().solve(&network)?;
assert!((fd_result.bus_voltage - nr_result.bus_voltage).norm() < 1e-6);

v0.51.0 协议 Fuzz 测试框架

v0.51.0 引入 cargo-fuzz 基础设施，对 4 个电力协议做协议解析器 fuzz：输入随机字节流，验证解析器不 panic / 不 UB / 不内存越界。本节描述 fuzz target 组织与本地运行方式。

Fuzz target 组织

fuzz/
├── Cargo.toml                       # workspace member，依赖 cargo-fuzz 0.13.2
├── targets/
│   ├── fuzz_iec104_decode.rs        # IEC 60870-5-104 APDU 解码
│   ├── fuzz_iec103_decode.rs        # IEC 60870-5-103 报文解码
│   ├── fuzz_dlt698_decode.rs        # DL/T 698.45 帧解码
│   └── fuzz_pmu_decode.rs           # IEEE C37.118 PMU 数据帧解码
└── README.md                        # 运行说明 + 已知 corpus + crash 历史

每个 fuzz target 拿到 data: &[u8] 后调用对应协议的 decode() 入口，断言"decode 不 panic"为唯一 invariant（解析失败返回 Err 合法，但禁止 panic / unwrap / index out of bounds）。

本地运行

# 安装 cargo-fuzz（需要 nightly）
cargo install cargo-fuzz --locked
rustup toolchain install nightly

# Smoke 测试（60 秒，CI 默认）
cargo +nightly fuzz run fuzz_iec104_decode -- -max_total_time=60

# 完整运行（86400 秒 = 24 小时，本地长跑）
cargo +nightly fuzz run fuzz_iec104_decode -- -max_total_time=86400

# 多 target 并行
for t in iec104 iec103 dlt698 pmu; do
  cargo +nightly fuzz run fuzz_${t}_decode -- -max_total_time=60 &
done
wait

配置

eneros.toml 的 [quality] 段控制 fuzz 行为：

[quality]
fuzz_max_total_time = 86400    # 完整运行上限（秒），CI 用 60
fuzz_smoke_time = 60           # smoke 测试时长（秒）

Crash 处理流程

1. cargo-fuzz 在 fuzz/artifacts/<target>/ 下输出 crash 输入文件
2. 复现：cargo +nightly fuzz run fuzz_<target> <crash-file>
3. 修复后必须添加 crash 输入到 fuzz/corpus/<target>/ 作为回归测试
4. 修复 commit 必须在 CHANGELOG 记录"协议 fuzz crash 修复"

v0.51.0 Proptest 属性测试

v0.51.0 引入 proptest 做属性测试（property-based testing）：对 5 个核心 crate 的 30 个 property 做 256 个随机 case 验证（共 7680 次测试）。本节描述组织方式与新增 property 模板。

覆盖 crate 与 property 分布

Crate	Property 数	Cases/Property	总测试数	主要验证内容
eneros-core	8	256	2048	类型不变量、序列化/反序列化往返、错误转换
eneros-topology	6	256	1536	拓扑图一致性、连接模式对称性、搜索终止性
eneros-powerflow	6	256	1536	YBus 对称性、NR 收敛性、FD/NR 一致性
eneros-constraint	5	256	1280	约束单调性、N-1 完备性、热稳定上下界
eneros-analysis	5	256	1280	OPF 可行性、状态估计一致性、谐波检查闭包
合计	30	256	7680	—

本地运行

# 运行全部 proptest
cargo test --workspace --features proptest proptest

# 单 crate
cargo test -p eneros-powerflow --features proptest proptest -- --nocapture

# 调整 case 数（CI 用 256，本地快速验证用 32）
PROPTEST_CASES=32 cargo test -p eneros-core --features proptest proptest

配置

eneros.toml 的 [quality] 段：

[quality]
proptest_cases = 1000    # 默认 1000（CI 收紧到 256 平衡运行时间）

新增 property 模板

// crates/eneros-powerflow/tests/proptest_ybus.rs
proptest! {
    #![proptest_config(ProptestConfig::with_cases(256))]

    #[test]
    fn ybus_matrix_is_symmetric(net in arbitrary_power_network(5, 10)) {
        let ybus = YBusMatrix::build(&net)?;
        // YBus 是对称矩阵：Y[i][j] == Y[j][i]
        for i in 0..ybus.dim() {
            for j in (i+1)..ybus.dim() {
                prop_assert!((ybus[(i,j)] - ybus[(j,i)]).norm() < 1e-9);
            }
        }
    }

    #[test]
    fn fd_solver_matches_nr_within_tolerance(net in arbitrary_power_network(3, 14)) {
        let fd = FastDecoupledSolver::new().solve(&net)?;
        let nr = NewtonRaphsonSolver::new().solve(&net)?;
        prop_assert!((fd.bus_voltage - nr.bus_voltage).norm() < 1e-6);
    }
}

v0.51.0 Lint 纪律总结

v0.51.0 把 lint 纪律从"过渡期 grandfathered allow"升级为"全员 deny + 测试代码 cfg_attr 放行"，技术债清偿情况：

指标	v0.48.0（基线）	v0.50.2	v0.51.0（目标）
非测试代码 unwrap/expect 违规	~120 处（blankeet allow 覆盖）	67 处（spec 估计，未清零）	0 处
src/ 内 #![allow(...)] 顶层属性	28 个	12 个	0 个
cargo clippy --workspace --all-targets -- -D warnings	0 警告（allow 生效）	0 警告（allow 生效）	0 警告（deny 生效）
--force-warn clippy::unwrap_used 输出	104 警告	67 警告	0 警告

清偿方式

88 处违规按以下方式清零：

• unwrap() → ?（45 处）：函数返回 Result<T>，错误向上传播
• unwrap() → unwrap_or_default()（18 处）：默认值合理场景（如配置项缺失）
• unwrap() → unwrap_or_else(|_| fallback())（12 处）：需要计算 fallback
• expect(msg) → ? with context()（8 处）：保留语义化错误信息
• 重构避免 Option/Result（5 处）：用 match 替代链式 unwrap

持续纪律

PR 提交前必须本地预演：

# 必须通过
cargo clippy --workspace --all-targets -- -D warnings

# 强制 warn（即使 deny 没触发，也提示潜在违规）
cargo clippy --workspace --lib --bins -- --force-warn clippy::unwrap_used --force-warn clippy::expect_used

# 期望输出：0 warnings

新增非测试代码若必须使用 unwrap/expect（极少数场景），必须在 PR 描述中说明理由，并由 reviewer 显式 approve #[allow(clippy::unwrap_used)] 注解（仅函数级，禁止 crate 级）。

v0.52.0 Phase 3 — CIM XML 生产级导入

v0.52.0 Phase 3 将 CIM (Common Information Model, IEC 61968/61970) XML 导入从"v0.7.0 手写字符串 substring 解析预留接口"升级为"基于 quick-xml 0.41 事件流的生产级解析器"，覆盖 CIM 16/17 profile，并通过 IEEE 14/30/118 标准测试系统验证。

架构 — quick-xml 0.41 事件流 + TopBuilder 状态机

crates/eneros-network/src/cim.rs 重构为单遍流式状态机驱动：

quick_xml::Reader::from_str(xml)
   │
   ▼  (loop over Event)
[Event::Start / Event::Empty] ──▶ [is_top_level(local)?] ──▶ [TopBuilder::begin(local, attrs)]
   │                                                              │
   │                                                              ▼
   │                                                       [TopBuilder::set_text(sub_local, text)]
   │                                                              │
   │                                                              ▼
   │                                                       [TopBuilder::set_reference(sub_local, resource)]
   │                                                              │
[Event::End] ──▶ [TopBuilder::finish()] ──▶ [CimModel.{buses, branches, generators, ...}]
   │
[Event::Eof] ──▶ 结束，返回 CimModel

• TopBuilder enum（21 变体）：BaseVoltage / Substation / VoltageLevel / BusbarSection / ConnectivityNode / Terminal / ACLineSegment / PowerTransformer / EnergyConsumer / SynchronousMachine / Breaker / Disconnector / OperationalLimitSet / CurrentLimit / VoltageLimit / ActivePowerLimit / GeographicalRegion / SubGeographicalRegion / Location / PositionPoint（嵌套）/ None
• 6 辅助函数（替换原 7 个手写字符串辅助）：qname_local / extract_mrid_attr / extract_resource_attr / is_top_level / parse_cim_float / parse_cim_bool
• 属性解码：attr.normalized_value(XmlVersion::Implicit1_0)（quick-xml 0.41 API；unescape_value() 已废弃）
• 文本解码：reader.decoder().decode(t.as_ref()) + quick_xml::escape::unescape free function（BytesText::unescape() 已移除）
• 公开签名不变：parse_cim(xml: &str) -> Result<CimModel, String> / cim_to_power_network(model: &CimModel) -> Result<PowerNetwork, String>

CIM 16/17 新增类型

类型	字段	用途
OperationalLimitType enum	Patrol / LongTerm / ShortTerm / Emergency	运行限值分类
CimOperationalLimit	mrid / name / value / unit / limit_type / operational_limit_set_mrid / equipment_mrid	单条限值（电流/电压/有功）
CimOperationalLimitSet	mrid / name / equipment_mrid	限值集合（关联设备）
CimGeographicalRegion	mrid / name	地理区域
CimSubGeographicalRegion	mrid / name / geographical_region_mrid	子地理区域
CimLocation	mrid / name / geo_position_x / geo_position_y	位置（含嵌套 PositionPoint）

CimModel 扩展 5 个 HashMap<String, T> 字段：operational_limit_sets / operational_limits / geographical_regions / sub_geographical_regions / locations。后处理步骤从 OperationalLimitSet.equipment_mrid 解析 OperationalLimit.equipment_mrid（CIM 16/17 标准路径：Limit → Set → Equipment）。

OperationalLimits → eneros-constraint 映射（SKIPPED）

spec gap：eneros-constraint crate 当前只有通用 Constraint 结构（element_ids: Vec<ElementId>），缺少 LineFlowLimit / VoltageLimit 载体类型，且 ElementId 空间与 CIM mRID 不对齐。cim_to_power_network 中以注释块标记为 spec gap，留待后续阶段补齐 dedicated limits carrier + PowerNetwork::with_limits builder。解析后的 CimModel.operational_limits 仍可被下游消费者通过 out-of-band 方式使用。

IEEE 14/30/118 CIM XML fixture

crates/eneros-network/tests/fixtures/cim/ 目录由 generate_fixtures.py 程序化生成 3 个 CIM 16 RDF/XML 文件：

fixture	BusbarSection	ACLineSegment	字节数	分支来源
ieee14.xml	14	20	38932	crates/eneros-powerflow/src/ieee.rs IEEE14_BRANCHES
ieee30.xml	30	41	81340	MATPOWER case30.m canonical topology
ieee118.xml	118	186	349235	MATPOWER case118.m canonical topology（截断到 186 项）

每个 fixture 包含：1 个 BaseVoltage + N 个 Substation/VoltageLevel/BusbarSection/ConnectivityNode/Terminal（每 bus）+ M 个 ACLineSegment + 2 个 Terminal（每 branch）。

集成测试 — crates/eneros-network/tests/cim_import.rs

4 个测试：

// 1-3: IEEE 14/30/118 节点数断言（与 MATPOWER canonical 一致）
#[test]
fn test_ieee14_cim_import() { /* 14 bus / 20 branch */ }

#[test]
fn test_ieee30_cim_import() { /* 30 bus / 41 branch */ }

#[test]
fn test_ieee118_cim_import() { /* 118 bus / 186 branch */ }

// 4: DoS 防护 — 10MB / 100k 嵌套层 XML 在 <5s 内完成，无 panic / OOM
#[test]
fn test_large_nested_xml_does_not_oom() {
    const NESTING_DEPTH: usize = 100_000;
    const TARGET_BYTES: usize = 10 * 1024 * 1024;
    // 100k open tags + padding text + 100k close tags = ~10MB
    // 验证 quick-xml 0.41 已 patch RUSTSEC-2026-0194（重复属性 DoS）
    // 与 RUSTSEC-2026-0195（NsReader namespace DoS）
    let start = Instant::now();
    let _ = parse_cim(&xml);  // 不应 panic，返回 Err 即可
    assert!(start.elapsed().as_secs() < 5);
}

验证命令

# 全量验证（Phase 3 完成时已通过）
cargo build -p eneros-network
cargo test -p eneros-network --lib                    # 42 passed / 0 failed
cargo test -p eneros-network --test cim_import        # 4 passed / 0 failed
cargo clippy -p eneros-network --all-targets -- -D warnings   # 0 warning

工程纪律

• 0 unwrap() / 0 expect() in 非测试代码（使用 ? / ok_or / match）
• 0 顶层 #![allow(...)]
• 畸形 XML 返回 Err(String)，绝不 panic
• 保留 v0.7.0 quirks（BusbarSection.base_voltage_mrid 优先 EquipmentContainer；EnergyConsumer.terminal_mrid 镜像 EquipmentContainer）以避免回归

详见 CHANGELOG.md [0.52.0] 节与 .trae/specs/add-v0520-iec61850-server-cim-xml/ spec 目录。

v0.52.0 Phase 1 — IEC 61850 MMS Server

v0.52.0 Phase 1 新增 Rust 原生 IEC 61850 MMS server 端实现（不依赖 libIEC61850），让 EnerOS 可作为 IED/保护装置对外发布模型与数据。

架构 — 完整 ISO 协议栈

crates/eneros-device/src/adapters/iec61850/server.rs（~1850 行）实现完整 ISO 协议栈：

TCP 102 (listen)
   │
   ▼
COTP ISO 8073 Class 0 (CR/CC/DT)
   │
   ▼
ISO 8327 Session (CN/AC/DT)
   │
   ▼
ISO 8823 Presentation (CP/CPA)
   │
   ▼
ACSE ISO 8650 (AARQ/AARE)
   │
   ▼
MMS ISO 9506 (Initiate/Read/Write/GetNameList)

Iec61850Server::new(model).listen("0.0.0.0:102").await 长驻 accept 循环，每连接 spawn tokio task，共享 Arc<RwLock<IedModel>> 状态。

IedModel 运行时树

IedModel 与 SCL 解析树解耦：IedModel::from_scl(&SclDocument) 一次性转换 SCD/ICD/CID 到运行时树，结构化 DA 扁平化为 mag.f / mag.i 等叶子路径与 MMS 变量访问路径对齐。set_da 原子更新 value + quality + timestamp_ms。

MMS 服务

服务	行为
Initiate	协商 MMS 版本 + 最大 PDU 大小
Read	按 LD/LN.DO.DA 路径从 IedModel 取值（FLOAT32 / INT32 / VisibleString 编码）
Write	原子更新 IedModel::set_da（value + quality + timestamp_ms）
GetNameList	枚举 LD / variable / dataset 三类对象

ServerConfig

ServerConfig {
    tpdu_size: 10,        // 1024B（默认）
    local_tsap: 1,        // 默认
    src_ref: 1,           // 默认
    max_connections: 16,  // 默认
}

验证

• 523 lib 测试通过
• 3 tokio 多线程集成测试通过（full handshake + Read / Write→Read roundtrip / 非法 DA 不崩溃）
• 0 unwrap/expect / 0 顶层 #![allow] / 0 unimplemented!() / clippy 0 警告

v0.52.0 限制

RCB Reports（Task 1.6）与 SBO with Normal 控制（Task 1.7）stubbed —— server 对 InformationReport / DefineNamedVariableList / 控制服务返回 Err(Device("not yet implemented")) 并关闭关联，留待 v0.52.x patch 补齐。

v0.52.0 Phase 2 — IEC 61850 GOOSE Publisher

v0.52.0 Phase 2 新增 IEC 61850-8-1 §17 生产级 GOOSE publisher 端实现（与订阅端 GooseAdapter 互补），让 EnerOS 可作为 IED/保护装置主动发布 DataSet 变化事件。

架构

Application                   GoosePublisher
    │                             │
    │ update_dataset(values)      │
    ▼                             ▼
┌─────────────────────────────────────────────┐
│ GoosePublisher                               │
│  ├── config: GoosePublisherConfig             │
│  ├── state: Mutex<PublisherState>             │
│  │    ├── st_num / sq_num                     │
│  │    ├── current_data: Vec<GooseDataValue>   │
│  │    └── next_interval: Duration             │
│  ├── notify: Notify (wakes loop on change)    │
│  └── handle: JoinHandle (publish loop task)   │
└──────────────────────┬──────────────────────┘
                       │
               ┌───────┴───────┐
               │ Publish Loop  │ (tokio::spawn, Linux only)
               └───────┬───────┘
                       │ AF_PACKET sendto
                       ▼
                Ethernet (Layer 2)
                dst: 01-0C-CD-01-00-00
                EtherType: 0x88B8

PDU 编码（平台无关）

ASN.1 BER [APPLICATION 1] CONSTRUCTED tag 0x61，12 字段 context-tagged 序列：

Field	Tag	Type
gocbRef	0x80	VisibleString
timeAllowedToLive	0x81	INTEGER
datSet	0x82	VisibleString
goID (optional)	0x83	VisibleString
t	0x84	UtcTime (7B)
stNum	0x85	INTEGER
sqNum	0x86	INTEGER
test	0x87	BOOLEAN
confRev	0x88	INTEGER
ndsCom	0x89	BOOLEAN
simulation	0x8A	BOOLEAN
allData	0xAB	SEQUENCE OF

GooseDataValue 7 变体覆盖全 CDC 原语类型（Bool/Int/Float/Quality/Timestamp/String/Bytes），encode_integer_bytes 通过算术右移正确处理负数。

Ethernet 帧构建

dst MAC 01-0C-CD-01-00-00 多播 + EtherType 0x88B8 + APPID/Length/Reserved GOOSE header（8B）。

Linux AF_PACKET 发送

libc::socket(AF_PACKET, SOCK_RAW, ETH_P_ALL) + AsyncFd 集成 tokio，需 CAP_NET_RAW（root 或 setcap cap_net_raw+ep）。非 Linux 平台 start() 返回 Err(Device("unsupported platform: GOOSE requires Linux AF_PACKET"))，但 PDU 编码与 config 全平台可用。

状态机 — stNum/sqNum + T1/T2/T3

• stNum 在 DataSet 值变化时 +1（sqNum 重置为 0）
• sqNum 在每次重传时 +1（stNum 不变）
• T1/T2/T3 指数退避重传（T1 默认 2ms → 倍增至 T3 默认 1000ms）
• update_dataset() 通过 Notify 立即唤醒 publish loop

基准测试

benches/goose_publisher_throughput.rs 4 个平台无关 benchmark（PDU encode / frame build / encode+build / 1000-frame batch）+ 1 个 Linux-only AF_PACKET send benchmark，criterion Throughput::Elements 报告。IEC 61850-8-1 §17 要求 ≥ 1000 frames/s。

验证

• 33 单元测试通过（含 test_encode_goose_pdu_known_sequence 46 字节手算参考序列）
• 556 lib 测试全通过
• 0 unwrap/expect / 0 顶层 #![allow] / clippy 0 警告

v0.52.0 Phase 4 — v0.51.0 延迟项清偿

v0.52.0 Phase 4 清偿 v0.51.0 推迟的算法精度验证 fixture 与 API gap，包括 AC-OPF IEEE 30/118、Fast-Decoupled IEEE 118、暂态 CCT 3 处 API gap、proptest 扩展。

AC-OPF IEEE 30/118 fixture

crates/eneros-analysis/tests/ac_opf_ieee30_118.rs 新增 IEEE 30-bus 与 118-bus AC-OPF MATPOWER 验证：

• MATPOWER case30.m / case118.m 解析
• 参考结果 JSON 快照（总成本 / 各发电机出力 / 各母线电压）
• 3 个默认测试通过 + 2 个 #[ignore] 严格对比测试（1e-6 pu 容差）
• 记录求解器差距：merit-order ED vs KKT 内点法（留待 v0.53.0+ 引入原对偶内点法）

Fast-Decoupled IEEE 118-bus 收敛测试

crates/eneros-powerflow/tests/fd_solver_ieee118.rs 验证 FastDecoupledSolver 在 IEEE 118-bus 大系统上的收敛性 + 与 NR 误差 < 1e-4 pu。

暂态 CCT 3 处 API gap

crates/eneros-analysis/src/dsa.rs 修复 v0.51.0 标记的 3 处 API gap：

Gap	描述	状态
#1	flat-start 初始化（无潮流解作为初值）	仍 #[ignore]，留待 v0.53.0+
#2	post-fault 线路切除（故障清除后拓扑变化）	✅ 修复（post_fault_line_trip: Option<Vec<usize>> 字段）
#3	ZIP 负荷模型（恒阻抗 + 恒电流 + 恒功率）	✅ 部分修复（zip_load_model: Option<ZipLoadModel> 字段）

proptest 扩展

proptest 从 v0.51.0 的 5 crate 30 properties 扩展至 3 crate 15 properties × 256 cases = 3840 用例（eneros-powerflow + eneros-analysis + eneros-device）。

验证

• AC-OPF IEEE 30/118：3 默认测试通过 + 2 #[ignore] 严格对比
• Fast-Decoupled IEEE 118：收敛测试通过
• 暂态 CCT：gap #2 / #3 修复，gap #1 仍 #[ignore]
• proptest：3 crate 15 properties × 256 = 3840 用例全通过
• 0 unwrap/expect / 0 顶层 #![allow] / clippy 0 警告

9. 调试技巧

9.1 tracing 日志

EnerOS 使用 tracing 进行结构化日志，通过 RUST_LOG 环境变量控制级别：

# 全局 debug 级别
RUST_LOG=debug cargo run -p eneros-api -- run --config eneros.toml

# 指定 crate 级别
RUST_LOG=eneros_device=trace,eneros_scada=debug,info cargo run -p eneros-api

# 仅警告和错误
RUST_LOG=warn cargo run -p eneros-api

日志级别优先级：error > warn > info > debug > trace。

9.2 JSON 结构化日志

生产环境使用 JSON 格式日志，便于日志聚合系统采集：

# 输出 JSON 日志
ENEROS_OBSERVABILITY__LOG_FORMAT=json cargo run -p eneros-api

9.3 enerosctl doctor 诊断

使用 enerosctl doctor 进行系统级诊断，检查内核、Agent、EventBus、设备、安全等子系统状态：

enerosctl doctor

该命令会输出各子系统的健康状态与异常提示。

9.4 事件总线订阅

实时查看事件总线消息：

# 订阅所有事件
enerosctl eventbus subscribe

# 订阅指定主题
enerosctl eventbus subscribe agent.command

9.5 常见问题排查

编译失败：找不到 libseccomp

Linux 平台需要安装 libseccomp 开发库：

sudo apt install libseccomp-dev   # Debian/Ubuntu
sudo dnf install libseccomp-devel # Fedora

跨平台开发时排除依赖该库的 crate：

cargo build --workspace --exclude eneros-installer

Agent 无法启动

1. 检查 enerosctl agent list 是否显示该 Agent
2. 查看 enerosctl log tail agent 日志
3. 确认 init.toml 中 Agent 配置正确
4. 运行 enerosctl doctor 检查系统状态

IEC 104 连接失败

1. 确认 RTU 地址和端口：telnet <addr> 2404
2. 检查 ASDU 地址匹配
3. 查看日志中 TESTFR 心跳状态
4. 使用 enerosctl protocol test iec104 <addr> 测试连通性

10. 相关文档

• 贡献指南
• 部署运维指南
• 用户手册
• 插件开发指南
• 架构决策记录
• 运维自动化架构决策（v0.40.0）
• 高可用增强架构决策（v0.41.0）
• Agent 智能进阶架构决策（v0.43.0）
• 电网分析进阶架构决策（v0.44.0）
• 物联网与泛在接入架构决策（v0.45.0）
• 可视化与交互增强架构决策（v0.46.0）