feat(go): add 100k ingest hardening baseline

docs/architecture/tdengine-batch-writer-design.md

@@ -0,0 +1,65 @@
+# 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`。