From 0aa71402d11e6888ac74d4768730ff45b65a0d66 Mon Sep 17 00:00:00 2001
From: lingniu <lingniu@lingnius-Mac-mini.local>
Date: Fri, 3 Jul 2026 07:53:30 +0800
Subject: [PATCH] docs(go): document realtime total semantics

---
 go/vehicle-gateway/internal/realtime/openapi.go      | 7 ++++---
 go/vehicle-gateway/internal/realtime/openapi_test.go | 5 +++++
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/go/vehicle-gateway/internal/realtime/openapi.go b/go/vehicle-gateway/internal/realtime/openapi.go
index 6eebceec..f10c6b54 100644
--- a/go/vehicle-gateway/internal/realtime/openapi.go
+++ b/go/vehicle-gateway/internal/realtime/openapi.go
@@ -44,7 +44,7 @@ func realtimeOpenAPISpec() map[string]any {
 			"/api/realtime/snapshots": map[string]any{
 				"get": map[string]any{
 					"summary":     "查询车辆实时快照",
-					"description": "从 vehicle_realtime_snapshot 查询各协议最新在线快照，支持协议、VIN、车牌过滤和分页。",
+					"description": "从 vehicle_realtime_snapshot 查询各协议最新在线快照，支持协议、VIN、车牌过滤和分页。默认不执行 COUNT(*)，total 默认表示本页返回条数；需要精确总数时传 includeTotal=true。",
 					"tags":        []string{"Realtime Snapshot API"},
 					"x-table":     "vehicle_realtime_snapshot",
 					"parameters":  commonRealtimeParameters(),
@@ -63,7 +63,7 @@ func realtimeOpenAPISpec() map[string]any {
 			"/api/realtime/locations": map[string]any{
 				"get": map[string]any{
 					"summary":     "查询车辆实时位置",
-					"description": "从 vehicle_realtime_location 查询各协议最新位置，支持协议、VIN、车牌过滤和分页。",
+					"description": "从 vehicle_realtime_location 查询各协议最新位置，支持协议、VIN、车牌过滤和分页。默认不执行 COUNT(*)，total 默认表示本页返回条数；需要精确总数时传 includeTotal=true。",
 					"tags":        []string{"Realtime Location API"},
 					"x-table":     "vehicle_realtime_location",
 					"parameters":  commonRealtimeParameters(),
@@ -127,6 +127,7 @@ func commonRealtimeParameters() []map[string]any {
 		{"name": "protocol", "in": "query", "schema": map[string]any{"type": "string", "enum": []string{"GB32960", "JT808", "YUTONG_MQTT"}}, "required": false},
 		{"name": "vin", "in": "query", "schema": map[string]any{"type": "string"}, "required": false},
 		{"name": "plate", "in": "query", "schema": map[string]any{"type": "string"}, "required": false},
+		{"name": "includeTotal", "in": "query", "schema": map[string]any{"type": "boolean", "default": false}, "required": false, "description": "默认 false，不执行 COUNT(*)；true 时返回精确总数。"},
 		{"name": "limit", "in": "query", "schema": map[string]any{"type": "integer", "minimum": 1, "maximum": 1000, "default": 50}, "required": false},
 		{"name": "offset", "in": "query", "schema": map[string]any{"type": "integer", "minimum": 0, "maximum": 1000000, "default": 0}, "required": false},
 	}
@@ -137,7 +138,7 @@ func pageSchema(itemRef string) map[string]any {
 		"type": "object",
 		"properties": map[string]any{
 			"items":  map[string]any{"type": "array", "items": map[string]any{"$ref": itemRef}},
-			"total":  integerSchema(1),
+			"total":  map[string]any{"type": "integer", "example": 1, "description": "默认表示本页返回条数；includeTotal=true 时表示精确总数。"},
 			"limit":  integerSchema(50),
 			"offset": integerSchema(0),
 		},
diff --git a/go/vehicle-gateway/internal/realtime/openapi_test.go b/go/vehicle-gateway/internal/realtime/openapi_test.go
index ca7b62aa..a9960e86 100644
--- a/go/vehicle-gateway/internal/realtime/openapi_test.go
+++ b/go/vehicle-gateway/internal/realtime/openapi_test.go
@@ -22,4 +22,9 @@ func TestOpenAPIHandlerDocumentsRealtimeSnapshotAndLocation(t *testing.T) {
 			t.Fatalf("openapi missing %s: %s", want, body)
 		}
 	}
+	for _, want := range []string{`"includeTotal"`, `默认不执行 COUNT(*)`, `total 默认表示本页返回条数`} {
+		if !strings.Contains(body, want) {
+			t.Fatalf("openapi should document lightweight total semantics, missing %s: %s", want, body)
+		}
+	}
 }