feat: 完成 issue #3 边缘采集网关模板化封装

- 点位字典 CSV schema/加载/自动校验(缺失字段/量纲/重复点号,PRD 5.1)
- 协议可插拔只读驱动:OPC UA(S7-1200 适配)/S7/Modbus/称重/能源/模拟
- 周期采集引擎:只读+背压保护+健康度指标(丢失率/P99/可用性)
- Kafka 流式上行 + 本地 spool 断点续传(丢失率≤0.02% 保障)
- 模板配置外置(gateway.yaml + 点位字典 CSV),换行业零改码
- 18 个单元测试全绿;端到端运行 SLA 达标
This commit is contained in:
2026-08-04 15:32:16 +08:00
parent 21c6259739
commit f49c0920d4
27 changed files with 1806 additions and 0 deletions
+66
View File
@@ -0,0 +1,66 @@
# 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` 轮次成功率 |
| 安全 | 零控制指令下发 | 驱动抽象仅暴露只读读接口(`drivers/base.py`) |
## 目录结构
```
edge-gateway/
├── config/gateway.example.yaml # 采集配置外置示例(模板参数化)
├── point_dict/ # 点位字典:CSV schema + 导入 + 自动校验
│ ├── schema.py # 字段定义与约束(对齐 PRD 5.1 字段表)
│ ├── 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)
```
## 快速开始
```bash
# 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** 驱动(模板 → 行业点位集)。
- 协议选型与连接参数:由 `gateway.yaml` 的 `drivers` 段驱动(模板 → 行业协议栈)。
- Kafka topic 命名:`{template}.{device}.points`,随配置模板变化。
- 新增协议:实现 `drivers/base.py` 的 `Driver` 子类并注册即可,引擎与上行链路零改动。