feat: spool gateway publishes to disk

docs/superpowers/specs/2026-07-01-go-ingest-redesign-design.md

@@ -186,7 +186,9 @@ go/vehicle-gateway/
 
 - Kafka 生产端必须开启同步写入，RAW 写成功后才允许写 unified event。
 - Kafka 写入必须支持可配置重试、单次写超时和短退避，默认值为 `KAFKA_PUBLISH_ATTEMPTS=3`、`KAFKA_PUBLISH_TIMEOUT_MS=3000`、`KAFKA_PUBLISH_BACKOFF_MS=100`。
-- 当前阶段的重试只解决短暂网络抖动；后续阶段需要增加本地磁盘 spool/WAL，使 Kafka 长时间不可用时 RAW 不丢失，并支持恢复后补发。
+- gateway 支持本地磁盘 spool/WAL，配置 `KAFKA_SPOOL_DIR` 后启用；Kafka 长时间不可用时，发布失败的 envelope 先原子写入本地 JSON 文件。
+- spool 补发按文件名顺序执行，补发成功后删除文件；默认补发间隔由 `KAFKA_SPOOL_REPLAY_INTERVAL_MS=1000` 控制。
+- 如果 RAW 写 Kafka 失败并已落盘，同一个 event 的 unified event 不允许抢先写 Kafka，也必须进入 spool，确保恢复后按 RAW -> unified 顺序补发。
 - Kafka topic 不允许自动创建，topic 和分区数由部署脚本或运维初始化，避免生产拼写错误造成隐性分流。
 
 ## TDengine 数据库设计
@@ -407,6 +409,7 @@ flowchart LR
 - 协议坏帧仍写 RAW topic，`parse_status=BAD_FRAME`。
 - 可部分解析的帧写 `parse_status=PARTIAL`，保留 parse error。
 - Kafka 写失败时接入层先按配置重试；重试耗尽后不写 unified event，必须打错误日志和 metrics。
+- 启用 `KAFKA_SPOOL_DIR` 后，Kafka 重试耗尽会落本地 spool；如果 spool 写失败，才视为接入层最终失败。
 - TDengine 写失败不提交 Kafka offset。
 - MySQL 统计写失败不提交 Kafka offset。
 - Redis 写失败不影响历史和统计，但要通过 metrics 暴露。
@@ -473,6 +476,7 @@ TDengine 连接：
 - Go gateway 能在 ECS 上接收真实 32960、808、宇通 MQTT 数据。
 - 三种协议 RAW 都进入 Kafka。
 - Kafka 短暂写失败时，gateway 按配置重试；单元测试覆盖首次失败后成功和重试耗尽返回错误。
+- Kafka 长时间不可用时，gateway 可把 RAW/unified 写入本地 spool；单元测试覆盖 RAW 已落盘时 unified 也落盘、恢复后按顺序补发并删除文件。
 - 三种协议 RAW 和 parsed JSON 都进入 TDengine。
 - 32960 和 808 的位置进入 `vehicle_locations`。
 - 32960 和 808 的总里程采样进入 `vehicle_mileage_points`。