feat(go): batch tdengine history writes

docs/ops/100k-capacity-baseline.md

@@ -66,6 +66,9 @@ systemd gateway 已配置 `LimitNOFILE=1048576`，需要持续保持。
 | Gateway async sink | `vehicle_async_sink_publish_total{sink,kind,status}` | `error` 不增长 |
 | Gateway | `vehicle_gateway_publish_total{status="ok"}` | 持续增长 |
 | Gateway | parse/publish duration | p99 小于容量目标 |
+| History writer | `vehicle_history_batch_flush_total{status}` | `error` 不增长 |
+| History writer | `vehicle_history_batch_rows_total{status}` | batch 行数持续增长 |
+| History writer | `vehicle_history_batch_flush_duration_ms{status}` | flush 延迟不持续上升 |
 | NATS bridge | `vehicle_bridge_nats_consumer_ack_pending` | 稳态为 0 |
 | NATS bridge | `vehicle_bridge_nats_consumer_pending` | burst 后下降 |
 | Kafka consumers | `vehicle_*_kafka_lag` | 稳态为 0，burst 后下降 |

docs/ops/go-vehicle-ingest-memory.md

@@ -406,6 +406,25 @@ vehicle_async_sink_queue_depth{sink}
 
 这些指标是进入带帧率压测前的关键保护栏：如果 `queue_depth` 持续增长或 `enqueue_total{status="timeout"}` 增长，说明入口 publish 队列已成为瓶颈。
 
+### History writer TDengine 批写
+
+2026-07-03 已实现 history-writer 第一阶段批写：
+
+- `history.Writer.AppendAllBatch` 按 TDengine child table 聚合 raw/location 多行 `INSERT`。
+- `cmd/history-writer` 默认 `HISTORY_BATCH_SIZE=200`、`HISTORY_BATCH_WAIT_MS=100`。
+- TDengine batch 成功后才批量提交 Kafka messages；失败不提交 offset。
+- 保留单条 `AppendAll` 路径作为回退。
+
+新增指标：
+
+```text
+vehicle_history_batch_flush_total{status}
+vehicle_history_batch_rows_total{status}
+vehicle_history_batch_flush_duration_ms{status}
+```
+
+进入带帧率压测时，必须同时观察 `vehicle_history_kafka_lag` 和 `vehicle_history_batch_*`。
+
 ## 下次恢复上下文时先做
 
 1. 读本文件。

docs/ops/vehicle-ingest-runbook.md

@@ -73,6 +73,7 @@ curl -fsS http://127.0.0.1:20214/metrics \
   | grep -E 'vehicle_bridge_(nats_consumer|kafka_writes_total|nats_acks_total)'
 
 curl -fsS http://127.0.0.1:20212/metrics | grep vehicle_history_kafka_lag
+curl -fsS http://127.0.0.1:20212/metrics | grep vehicle_history_batch
 curl -fsS http://127.0.0.1:20213/metrics | grep vehicle_stat_kafka_lag
 curl -fsS http://127.0.0.1:20200/metrics | grep vehicle_realtime_kafka_lag
 ```
@@ -118,6 +119,8 @@ go run ./cmd/load-sim \
 | `vehicle_async_sink_queue_depth{sink="nats"}` | 持续增长且不回落 | Gateway 到 NATS/Kafka 的异步 publish 队列开始积压。 |
 | `vehicle_async_sink_enqueue_total{status="timeout"}` | 任意增长 | Gateway publish 队列已满或 worker 长时间阻塞，入口可能开始丢实时性。 |
 | `vehicle_async_sink_publish_total{status="error"}` | 连续增长 | NATS/Kafka publish 失败，需要先查中间件连接和日志。 |
+| `vehicle_history_batch_flush_total{status="error"}` | 任意增长 | TDengine 批写失败；Kafka offset 不会提交，应先查 TDengine 和 SQL 错误。 |
+| `vehicle_history_batch_flush_duration_ms{status="ok"}` | 持续上升 | TDengine 写入延迟增加，可能需要降低 batch size 或扩容 TDengine。 |
 | `vehicle_bridge_nats_consumer_ack_pending` | 连续 2 分钟 `> 0` | 消息已投递给 bridge，但 Kafka 写入后未完成 ack。 |
 | `vehicle_bridge_nats_consumer_pending` | 持续增长且 `> 10000` | bridge 消费 NATS 的速度跟不上生产速度。 |
 | Kafka lag | 连续 5 分钟增长或 `> 10000` | 下游 consumer 或存储存在瓶颈。 |