feat(go): add realtime kv projection

go/vehicle-gateway/internal/realtime/openapi.go

@@ -38,7 +38,7 @@ func realtimeOpenAPISpec() map[string]any {
 		"info": map[string]any{
 			"title":       "Lingniu Vehicle Realtime API",
 			"version":     "1.0.0",
-			"description": "MySQL realtime query APIs for vehicle_realtime_snapshot and vehicle_realtime_location.",
+			"description": "MySQL realtime query APIs for vehicle_realtime_snapshot, vehicle_realtime_location, and vehicle_realtime_kv.",
 		},
 		"paths": map[string]any{
 			"/api/realtime/snapshots": map[string]any{
@@ -79,11 +79,31 @@ func realtimeOpenAPISpec() map[string]any {
 					},
 				},
 			},
+			"/api/realtime/kv": map[string]any{
+				"get": map[string]any{
+					"summary":     "查询车辆实时 KV 字段",
+					"description": "从 vehicle_realtime_kv 查询实时字段投影，支持协议、VIN、domain、field 过滤和分页。适合 UI 局部刷新、快速字段查询和统计输入。",
+					"tags":        []string{"Realtime KV API"},
+					"x-table":     "vehicle_realtime_kv",
+					"parameters":  kvRealtimeParameters(),
+					"responses": map[string]any{
+						"200": map[string]any{
+							"description": "KV page",
+							"content": map[string]any{
+								"application/json": map[string]any{
+									"schema": map[string]any{"$ref": "#/components/schemas/KVPage"},
+								},
+							},
+						},
+					},
+				},
+			},
 		},
 		"components": map[string]any{
 			"schemas": map[string]any{
 				"SnapshotPage": pageSchema("#/components/schemas/SnapshotRow"),
 				"LocationPage": pageSchema("#/components/schemas/LocationRow"),
+				"KVPage":       pageSchema("#/components/schemas/KVRow"),
 				"SnapshotRow": map[string]any{
 					"type": "object",
 					"properties": map[string]any{
@@ -117,11 +137,35 @@ func realtimeOpenAPISpec() map[string]any {
 						"updated_at":       stringSchema("2026-07-02 16:11:04"),
 					},
 				},
+				"KVRow": map[string]any{
+					"type": "object",
+					"properties": map[string]any{
+						"protocol":    stringSchema("GB32960"),
+						"vin":         stringSchema("LNXNEGRR0SR321372"),
+						"domain":      stringSchema("gd_fc_stack"),
+						"field":       stringSchema("stack_water_outlet_temp_c"),
+						"value":       stringSchema("63"),
+						"value_type":  stringSchema("number"),
+						"event_time":  stringSchema("2026-07-03 11:18:45.000"),
+						"received_at": stringSchema("2026-07-03 11:18:45.123"),
+						"event_id":    stringSchema("event id"),
+						"updated_at":  stringSchema("2026-07-03 11:18:46"),
+					},
+				},
 			},
 		},
 	}
 }
 
+func kvRealtimeParameters() []map[string]any {
+	params := commonRealtimeParameters()
+	params = append(params,
+		map[string]any{"name": "domain", "in": "query", "schema": map[string]any{"type": "string", "example": "gd_fc_stack"}, "required": false},
+		map[string]any{"name": "field", "in": "query", "schema": map[string]any{"type": "string", "example": "stack_water_outlet_temp_c"}, "required": false},
+	)
+	return params
+}
+
 func commonRealtimeParameters() []map[string]any {
 	return []map[string]any{
 		{"name": "protocol", "in": "query", "schema": map[string]any{"type": "string", "enum": []string{"GB32960", "JT808", "YUTONG_MQTT"}}, "required": false},