iAOP/core/edge-gateway/README.md

iAOP-Core · 边缘采集网关（Edge Gateway）模板化封装

对应 PRD 5.1「① 边缘采集网关」与 NFR 第 9 章。本模块把化工 AI 边缘网关 改造成模板化实现：协议可插拔、采集配置全部外置（点位字典 CSV + YAML）， 严格只读采集（DCS / PLC / 称重 / 能源表），Kafka 流式上行， 断点续传 + 本地 spool 缓存 + 背压保护，并实时统计健康度指标。

验收口径（PRD 5.1 / 9 章）

指标	目标	实现落点
采集 P99 延迟	≤ 1.8s（600 点位 1Hz）	collector/metrics.py 统计，engine.py 调度
丢失率	≤ 0.02%	collector/spool.py 断点续传 + 背压丢弃计数
可用性	≥ 99.8%	collector/metrics.py 轮次成功率
安全-网络	严格只读、零控制指令；传输 mTLS	驱动仅只读接口；upstream/kafka_sink.py 支持 SSL/SASL_SSL 双向 mTLS
可维护	统一日志规范（结构化 JSON）	main.py --log-json 输出结构化 JSON 日志

目录结构

edge-gateway/
├── config/gateway.example.yaml   # 采集配置外置示例（模板参数化）
├── point_dict/                   # 点位字典：CSV schema + 导入 + 自动校验
│   ├── schema.py                 # 字段定义与约束（对齐 PRD 5.1 字段表 + issue #21 协议维度）
│   ├── loader.py                 # CSV → 内存模型
│   └── validator.py              # 校验：缺失字段 / 量纲 / 重复点号 / 采样率 / 协议
├── drivers/                      # 协议可插拔驱动（只读）
│   ├── base.py                   # 驱动抽象基类（唯一入口 read_points）
│   ├── opcua_driver.py           # OPC UA（和利时 DCS 等）
│   ├── s7_driver.py              # 西门子 S7-1200（python-snap7）
│   ├── modbus_driver.py          # Modbus RTU/TCP（PLC / 称重仪表）
│   ├── weighing_driver.py        # 称重终端
│   └── energy_driver.py          # 能源表（电表等）
├── collector/
│   ├── engine.py                 # 周期采集调度引擎（只读 + 背压保护）
│   ├── spool.py                  # 本地缓存 + 断点续传（重启重发）
│   └── metrics.py                # 健康度统计（丢失率 / P99 / 可用性）
├── upstream/kafka_sink.py        # Kafka 流式上行（失败重试 + 确认删除 spool）
├── main.py                       # 入口：加载配置 → 校验点位 → 启动采集
└── tests/                        # 单元测试（python -m unittest）

快速开始

# 1) 准备点位字典 CSV（字段见 point_dict/schema.py 与 PRD 5.1）
cp config/point_dict.example.csv /tmp/points.csv

# 2) 准备采集配置（复制示例并修改）
cp config/gateway.example.yaml /tmp/gateway.yaml

# 3) 运行（--dry-run 只做配置加载与点位校验，不启动采集）
python main.py --config /tmp/gateway.yaml --point-dict /tmp/points.csv --dry-run

# 4) 正式启动（采集 → spool → Kafka 上行）
python main.py --config /tmp/gateway.yaml --point-dict /tmp/points.csv

# 5) 测试
python -m unittest discover -s tests

模板化说明（换行业只改配置，不改代码）

• 点位范围 / 采样率 / 量纲 / 协议：由点位字典 CSV 驱动（模板 → 行业点位集）。
  • 采样率（issue #23）：点位字典 CSV 的 sampleRate 列逐点位控制采集频率， 引擎以 gateway.yaml 的 interval_ms 为基准 tick，sampleRate > interval_ms 的点位按比例降频（如 5000ms / 1000ms tick → 每 5 tick 采一次）； sampleRate ≤ interval_ms 的点位每 tick 采集。点位采样率完全外置、零硬编码。
  • 协议列（可选）提供点位级协议覆盖；留空则按 gateway.yaml drivers 段前缀路由。
• 协议选型与连接参数：由 gateway.yaml 的 drivers 段驱动（模板 → 行业协议栈）。
• Kafka topic 命名：{template}.{device}.points，随配置模板变化。
• 新增协议：实现 drivers/base.py 的 Driver 子类并注册即可，引擎与上行链路零改动。