feat: retry gateway kafka publishes

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

@@ -182,6 +182,13 @@ go/vehicle-gateway/
 
 接入层必须先写 RAW topic，再写 unified event。后续消费者只依赖 Kafka，不直接依赖接入进程内存。
 
+发布可靠性：
+
+- Kafka 生产端必须开启同步写入，RAW 写成功后才允许写 unified event。
+- Kafka 写入必须支持可配置重试、单次写超时和短退避，默认值为 `KAFKA_PUBLISH_ATTEMPTS=3`、`KAFKA_PUBLISH_TIMEOUT_MS=3000`、`KAFKA_PUBLISH_BACKOFF_MS=100`。
+- 当前阶段的重试只解决短暂网络抖动；后续阶段需要增加本地磁盘 spool/WAL，使 Kafka 长时间不可用时 RAW 不丢失，并支持恢复后补发。
+- Kafka topic 不允许自动创建，topic 和分区数由部署脚本或运维初始化，避免生产拼写错误造成隐性分流。
+
 ## TDengine 数据库设计
 
 如果现有 TDengine 库不符合目标，可以新建库并迁移。建议库名：
@@ -399,7 +406,7 @@ flowchart LR
 
 - 协议坏帧仍写 RAW topic，`parse_status=BAD_FRAME`。
 - 可部分解析的帧写 `parse_status=PARTIAL`，保留 parse error。
-- Kafka 写失败时接入层不确认业务成功；协议是否应答按协议要求处理，但必须打错误日志和 metrics。
+- Kafka 写失败时接入层先按配置重试；重试耗尽后不写 unified event，必须打错误日志和 metrics。
 - TDengine 写失败不提交 Kafka offset。
 - MySQL 统计写失败不提交 Kafka offset。
 - Redis 写失败不影响历史和统计，但要通过 metrics 暴露。
@@ -465,6 +472,7 @@ TDengine 连接：
 
 - Go gateway 能在 ECS 上接收真实 32960、808、宇通 MQTT 数据。
 - 三种协议 RAW 都进入 Kafka。
+- Kafka 短暂写失败时，gateway 按配置重试；单元测试覆盖首次失败后成功和重试耗尽返回错误。
 - 三种协议 RAW 和 parsed JSON 都进入 TDengine。
 - 32960 和 808 的位置进入 `vehicle_locations`。
 - 32960 和 808 的总里程采样进入 `vehicle_mileage_points`。