# 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` 子类并注册即可，引擎与上行链路零改动。