# TDengine Batch Writer Design

更新时间：2026-07-03

## Problem

`history-writer` 当前按 Kafka 消息逐条处理，并对每个 raw frame/location 调用 TDengine 写入。这个路径简单、可恢复，但在 10,000+ FPS 后会优先暴露三个瓶颈：

- 每帧一次 SQL/网络往返，吞吐上限低。
- Kafka offset 逐条提交，commit 开销随帧率线性增长。
- burst 流量下无法用批量 flush 平滑 TDengine 写入压力。

## Target

按 topic/protocol/目标表分组批量写 TDengine，按数量或时间触发 flush。

初始建议：

| 参数 | 初始值 |
| --- | --- |
| raw frame batch size | 200 |
| location batch size | 500 |
| flush interval | 100ms |
| operation timeout | 5s |
| max SQL payload | 8MB guardrail |
| Kafka commit | TDengine batch 成功后提交本批最大 offset |

## Write Semantics

1. Kafka consumer 拉取消息后解析一次 envelope。
2. envelope 已携带 `parsed_fields` 时，TDengine 写入直接复用，不重新从 raw JSON 解析。
3. raw frame 和 location 可以分批写，但 offset 只能在本消息涉及的所有写入成功后提交。
4. TDengine 写入失败时不提交 offset，让 Kafka 自动重放。
5. 依赖 `event_id` 保持幂等，避免失败重放造成重复业务记录。

## Non-goals

- 第一阶段不改变 raw frame 表结构。
- 第一阶段不合并不同 raw frame。
- 不丢弃 parse error frame。
- 不把 MySQL snapshot 或 Redis 当前态塞进 history-writer。

## Risks

- 批次越大，失败重试的重复写风险越高，必须依赖 `event_id` 或等价键。
- `parsed_json` 较大时容易让单条 SQL 超限，需要按 payload size 提前切批。
- batch flush 需要暴露 pending、flush duration、write error metrics，否则问题只会表现为 Kafka lag。

## Metrics Required

| 指标 | 含义 |
| --- | --- |
| `vehicle_history_batch_flush_total{table,status}` | 批写成功/失败次数 |
| `vehicle_history_batch_rows_total{table,status}` | 批写行数 |
| `vehicle_history_batch_flush_duration_ms{table,status}` | 批写耗时 |
| `vehicle_history_batch_pending_rows{table}` | 当前待 flush 行数 |
| `vehicle_history_kafka_lag` | 下游是否追得上 Kafka |

## Rollout

1. 保留当前逐条写实现作为 fallback。
2. 增加批写器单元测试，覆盖 count flush、interval flush、失败不 commit。
3. 在测试环境打开 batch writer。
4. 生产先用小批次 `100/100ms`，观察 TDengine latency 和 Kafka lag。
5. 逐步提升到 `200-500/100ms`。