feat(platform): use vehicle keyword for data queries

vehicle-data-platform/apps/api/internal/platform/handler.go

@@ -86,7 +86,8 @@ func (h *Handler) handleRawFramesGet(w http.ResponseWriter, r *http.Request) {
 	q := r.URL.Query()
 	query := RawFrameQuery{
 		Protocol:      q.Get("protocol"),
-		VIN:           q.Get("vin"),
+		VIN:           firstNonEmpty(q.Get("vin"), q.Get("keyword")),
+		Keyword:       q.Get("keyword"),
 		DateFrom:      q.Get("dateFrom"),
 		DateTo:        q.Get("dateTo"),
 		Fields:        splitCSV(q.Get("fields")),

vehicle-data-platform/apps/api/internal/platform/handler_test.go

@@ -145,6 +145,27 @@ func TestHandlerVehicleRealtime(t *testing.T) {
 	}
 }
 
+func TestHandlerVehicleRealtimeAcceptsKeyword(t *testing.T) {
+	handler := NewHandler(NewService(NewMockStore()))
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/realtime/vehicles?keyword=川AHTWO1&limit=10", nil)
+	handler.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", rec.Code, rec.Body.String())
+	}
+	var body struct {
+		Data struct {
+			Items []VehicleRealtimeRow `json:"items"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("response JSON should decode: %v body=%s", err, rec.Body.String())
+	}
+	if len(body.Data.Items) != 1 || body.Data.Items[0].VIN != "LNXNEGRR7SR318212" {
+		t.Fatalf("realtime vehicles should accept vehicle keyword, got %+v body=%s", body.Data.Items, rec.Body.String())
+	}
+}
+
 func TestHandlerHistoryMileageQualityOps(t *testing.T) {
 	cases := []struct {
 		path string
@@ -179,10 +200,14 @@ func TestHandlerVehicleDataAPIsResolveVehicleKeyword(t *testing.T) {
 	cases := []struct {
 		name    string
 		path    string
+		wantVIN string
 	}{
-		{name: "history locations", path: "/api/history/locations?vin=粤AG18312&limit=10"},
+		{name: "history locations vin alias", path: "/api/history/locations?vin=粤AG18312&limit=10", wantVIN: "LB9A32A24R0LS1426"},
-		{name: "raw frames", path: "/api/history/raw-frames?vin=粤AG18312&limit=1"},
+		{name: "raw frames vin alias", path: "/api/history/raw-frames?vin=粤AG18312&limit=1", wantVIN: "LB9A32A24R0LS1426"},
-		{name: "daily mileage", path: "/api/mileage/daily?vin=粤AG18312&limit=10"},
+		{name: "daily mileage vin alias", path: "/api/mileage/daily?vin=粤AG18312&limit=10", wantVIN: "LB9A32A24R0LS1426"},
+		{name: "history locations keyword", path: "/api/history/locations?keyword=川AHTWO1&limit=10", wantVIN: "LNXNEGRR7SR318212"},
+		{name: "raw frames keyword", path: "/api/history/raw-frames?keyword=川AHTWO1&limit=1", wantVIN: "LNXNEGRR7SR318212"},
+		{name: "daily mileage keyword", path: "/api/mileage/daily?keyword=川AHTWO1&limit=10", wantVIN: "LNXNEGRR7SR318212"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -192,8 +217,21 @@ func TestHandlerVehicleDataAPIsResolveVehicleKeyword(t *testing.T) {
 			if rec.Code != http.StatusOK {
 				t.Fatalf("status = %d body=%s", rec.Code, rec.Body.String())
 			}
-			if !strings.Contains(rec.Body.String(), `"vin":"LB9A32A24R0LS1426"`) {
+			var body struct {
-				t.Fatalf("vehicle data API should resolve plate keyword to VIN: %s", rec.Body.String())
+				Data struct {
+					Items []struct {
+						VIN string `json:"vin"`
+					} `json:"items"`
+				} `json:"data"`
+			}
+			if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+				t.Fatalf("response JSON should decode: %v body=%s", err, rec.Body.String())
+			}
+			if len(body.Data.Items) == 0 {
+				t.Fatalf("vehicle data API should return rows for resolved keyword: %s", rec.Body.String())
+			}
+			if body.Data.Items[0].VIN != tc.wantVIN {
+				t.Fatalf("vehicle data API should resolve keyword to VIN %s, got %s body=%s", tc.wantVIN, body.Data.Items[0].VIN, rec.Body.String())
 			}
 		})
 	}

vehicle-data-platform/apps/api/internal/platform/service.go

@@ -26,6 +26,7 @@ type Store interface {
 type RawFrameQuery struct {
 	Protocol      string   `json:"protocol"`
 	VIN           string   `json:"vin"`
+	Keyword       string   `json:"keyword"`
 	DateFrom      string   `json:"dateFrom"`
 	DateTo        string   `json:"dateTo"`
 	Fields        []string `json:"fields"`
@@ -55,7 +56,11 @@ func (s *Service) VehicleCoverage(ctx context.Context, query url.Values) (Page[V
 }
 
 func (s *Service) VehicleRealtime(ctx context.Context, query url.Values) (Page[VehicleRealtimeRow], error) {
-	return s.store.VehicleRealtime(ctx, query)
+	resolvedQuery, err := s.resolveVehicleQuery(ctx, query)
+	if err != nil {
+		return Page[VehicleRealtimeRow]{}, err
+	}
+	return s.store.VehicleRealtime(ctx, resolvedQuery)
 }
 
 func (s *Service) VehicleDetail(ctx context.Context, vin string, protocol string) (VehicleDetail, error) {
@@ -239,6 +244,9 @@ func (s *Service) RawFrames(ctx context.Context, query RawFrameQuery) (Page[RawF
 	if query.Limit <= 0 || query.Limit > 500 {
 		query.Limit = 100
 	}
+	if strings.TrimSpace(query.VIN) == "" {
+		query.VIN = query.Keyword
+	}
 	resolvedVIN, err := s.resolveVehicleVIN(ctx, query.VIN, query.Protocol)
 	if err != nil {
 		return Page[RawFrameRow]{}, err
@@ -279,7 +287,7 @@ func (s *Service) OpsHealth(ctx context.Context) (OpsHealth, error) {
 
 func (s *Service) resolveVehicleQuery(ctx context.Context, query url.Values) (url.Values, error) {
 	resolved := cloneValues(query)
-	vin := strings.TrimSpace(resolved.Get("vin"))
+	vin := firstNonEmpty(resolved.Get("vin"), resolved.Get("keyword"))
 	if vin == "" {
 		return resolved, nil
 	}

vehicle-data-platform/apps/web/src/pages/History.tsx

@@ -6,7 +6,7 @@ import type { HistoryLocationRow, Page, RawFrameRow } from '../api/types';
 import { PageHeader } from '../components/PageHeader';
 
 type HistoryFilters = {
-  vin?: string;
+  keyword?: string;
   protocol?: string;
   dateFrom?: string;
   dateTo?: string;
@@ -15,7 +15,7 @@ type HistoryFilters = {
 };
 
 const defaultFilters: HistoryFilters = {
-  vin: 'LB9A32A24R0LS1426',
+  keyword: 'LB9A32A24R0LS1426',
   includeFields: false
 };
 
@@ -27,7 +27,7 @@ function canOpenVehicle(vin?: string) {
 }
 
 export function History({ initialVin, onOpenVehicle }: { initialVin: string; onOpenVehicle: (vin: string) => void }) {
-  const [filters, setFilters] = useState<HistoryFilters>({ ...defaultFilters, vin: initialVin || defaultFilters.vin });
+  const [filters, setFilters] = useState<HistoryFilters>({ ...defaultFilters, keyword: initialVin || defaultFilters.keyword });
   const [locations, setLocations] = useState<Page<HistoryLocationRow>>(defaultPage);
   const [rawFrames, setRawFrames] = useState<Page<RawFrameRow>>(defaultPage);
   const [selectedRaw, setSelectedRaw] = useState<RawFrameRow | null>(null);
@@ -38,7 +38,7 @@ export function History({ initialVin, onOpenVehicle }: { initialVin: string; onO
 
   const buildParams = (nextFilters: HistoryFilters, limit: number, offset: number, raw: boolean) => {
     const params = new URLSearchParams({ limit: String(limit), offset: String(offset) });
-    if (nextFilters.vin?.trim()) params.set('vin', nextFilters.vin.trim());
+    if (nextFilters.keyword?.trim()) params.set('keyword', nextFilters.keyword.trim());
     if (nextFilters.protocol?.trim()) params.set('protocol', nextFilters.protocol.trim());
     if (nextFilters.dateFrom?.trim()) params.set('dateFrom', nextFilters.dateFrom.trim());
     if (nextFilters.dateTo?.trim()) params.set('dateTo', nextFilters.dateTo.trim());
@@ -71,7 +71,7 @@ export function History({ initialVin, onOpenVehicle }: { initialVin: string; onO
 
   const submit = (values: Record<string, unknown>) => {
     const nextFilters: HistoryFilters = {
-      vin: String(values.vin ?? ''),
+      keyword: String(values.keyword ?? ''),
       protocol: String(values.protocol ?? ''),
       dateFrom: String(values.dateFrom ?? ''),
       dateTo: String(values.dateTo ?? ''),
@@ -84,14 +84,14 @@ export function History({ initialVin, onOpenVehicle }: { initialVin: string; onO
   };
 
   const reset = () => {
-    const nextFilters = { ...defaultFilters, vin: initialVin || defaultFilters.vin };
+    const nextFilters = { ...defaultFilters, keyword: initialVin || defaultFilters.keyword };
     setFilters(nextFilters);
     loadLocations(nextFilters, 1, locationPagination.pageSize);
     loadRawFrames(nextFilters, 1, rawPagination.pageSize);
   };
 
   useEffect(() => {
-    const nextFilters = { ...defaultFilters, vin: initialVin || defaultFilters.vin };
+    const nextFilters = { ...defaultFilters, keyword: initialVin || defaultFilters.keyword };
     setFilters(nextFilters);
     loadLocations(nextFilters, 1, locationPagination.pageSize);
     loadRawFrames(nextFilters, 1, rawPagination.pageSize);
@@ -103,8 +103,8 @@ export function History({ initialVin, onOpenVehicle }: { initialVin: string; onO
     <div className="vp-page">
       <PageHeader title="历史数据" description="按车辆查询位置历史和 RAW 帧历史，数据来源只作为过滤和诊断维度" />
       <Card bordered>
-        <Form key={`${filters.vin ?? ''}-${filters.protocol ?? ''}-${filters.includeFields ? 'fields' : 'light'}`} initValues={filters} layout="horizontal" onSubmit={(values) => submit(values)}>
+        <Form key={`${filters.keyword ?? ''}-${filters.protocol ?? ''}-${filters.includeFields ? 'fields' : 'light'}`} initValues={filters} layout="horizontal" onSubmit={(values) => submit(values)}>
-          <Form.Input field="vin" label="VIN" placeholder="输入 VIN" style={{ width: 260 }} />
+          <Form.Input field="keyword" label="车辆关键词" placeholder="VIN / 车牌 / 手机号" style={{ width: 260 }} />
           <Form.Select field="protocol" label="数据来源" placeholder="全部来源" style={{ width: 190 }}>
             <Select.Option value="GB32960">GB32960</Select.Option>
             <Select.Option value="JT808">JT808</Select.Option>

vehicle-data-platform/apps/web/src/pages/Mileage.tsx

@@ -16,7 +16,7 @@ function mileageParams(values: Record<string, string>, pageSize?: number, offset
   const params = new URLSearchParams();
   if (pageSize != null) params.set('limit', String(pageSize));
   if (offset != null) params.set('offset', String(offset));
-  if (values?.vin) params.set('vin', values.vin);
+  if (values?.keyword) params.set('keyword', values.keyword);
   if (values?.protocol) params.set('protocol', values.protocol);
   if (values?.dateFrom) params.set('dateFrom', values.dateFrom);
   if (values?.dateTo) params.set('dateTo', values.dateTo);
@@ -37,7 +37,7 @@ export function Mileage({ initialVin, onOpenVehicle }: { initialVin: string; onO
   const [summary, setSummary] = useState<MileageSummary>(emptySummary);
   const [loading, setLoading] = useState(true);
   const [summaryLoading, setSummaryLoading] = useState(true);
-  const [filters, setFilters] = useState<Record<string, string>>({ vin: initialVin });
+  const [filters, setFilters] = useState<Record<string, string>>({ keyword: initialVin });
   const [pagination, setPagination] = useState({ currentPage: 1, pageSize: 20, total: 0 });
 
   const loadSummary = (values: Record<string, string> = filters) => {
@@ -60,7 +60,7 @@ export function Mileage({ initialVin, onOpenVehicle }: { initialVin: string; onO
   };
 
   useEffect(() => {
-    const nextFilters = { vin: initialVin };
+    const nextFilters = { keyword: initialVin };
     setFilters(nextFilters);
     loadSummary(nextFilters);
     load(nextFilters, 1, pagination.pageSize);
@@ -70,13 +70,13 @@ export function Mileage({ initialVin, onOpenVehicle }: { initialVin: string; onO
     <div className="vp-page">
       <PageHeader title="里程统计" description="按车辆汇总每日里程、区间里程和异常差值分析" />
       <Card bordered>
-        <Form key={filters.vin ?? ''} initValues={filters} layout="horizontal" onSubmit={(values) => {
+        <Form key={filters.keyword ?? ''} initValues={filters} layout="horizontal" onSubmit={(values) => {
           const nextFilters = values as Record<string, string>;
           setFilters(nextFilters);
           loadSummary(nextFilters);
           load(nextFilters, 1, pagination.pageSize);
         }}>
-          <Form.Input field="vin" label="关键词" placeholder="VIN / 车牌 / 手机号 / OEM" style={{ width: 260 }} />
+          <Form.Input field="keyword" label="车辆关键词" placeholder="VIN / 车牌 / 手机号 / OEM" style={{ width: 260 }} />
           <Form.Select field="protocol" label="数据来源" placeholder="全部来源" style={{ width: 180 }}>
             <Select.Option value="GB32960">GB32960</Select.Option>
             <Select.Option value="JT808">JT808</Select.Option>
@@ -87,7 +87,7 @@ export function Mileage({ initialVin, onOpenVehicle }: { initialVin: string; onO
           <Space>
             <Button htmlType="submit" theme="solid" type="primary">查询</Button>
             <Button onClick={() => {
-              const nextFilters = { vin: initialVin };
+              const nextFilters = { keyword: initialVin };
               setFilters(nextFilters);
               loadSummary(nextFilters);
               load(nextFilters, 1, pagination.pageSize);

vehicle-data-platform/apps/web/src/pages/Realtime.tsx

@@ -20,7 +20,7 @@ export function Realtime({ onOpenVehicle }: { onOpenVehicle: (vin: string) => vo
   const load = (values: Record<string, string> = filters, page = pagination.currentPage, pageSize = pagination.pageSize) => {
     setLoading(true);
     const params = new URLSearchParams({ limit: String(pageSize), offset: String((page - 1) * pageSize) });
-    if (values?.vin) params.set('vin', values.vin);
+    if (values?.keyword) params.set('keyword', values.keyword);
     if (values?.protocol) params.set('protocol', values.protocol);
     if (values?.online) params.set('online', values.online);
     api.vehicleRealtime(params)
@@ -45,7 +45,7 @@ export function Realtime({ onOpenVehicle }: { onOpenVehicle: (vin: string) => vo
           setFilters(nextFilters);
           load(nextFilters, 1, pagination.pageSize);
         }} style={{ marginBottom: 12 }}>
-          <Form.Input field="vin" label="关键词" placeholder="VIN / 车牌 / 手机号 / OEM" style={{ width: 260 }} />
+          <Form.Input field="keyword" label="车辆关键词" placeholder="VIN / 车牌 / 手机号 / OEM" style={{ width: 260 }} />
           <Form.Select field="protocol" label="数据来源" placeholder="全部来源" style={{ width: 180 }}>
             <Select.Option value="GB32960">GB32960</Select.Option>
             <Select.Option value="JT808">JT808</Select.Option>