docs(platform): define vehicle keyword API contract

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

@@ -236,3 +236,43 @@ func TestHandlerVehicleDataAPIsResolveVehicleKeyword(t *testing.T) {
 		})
 	}
 }
+
+func TestHandlerRawFramesPostAcceptsKeyword(t *testing.T) {
+	handler := NewHandler(NewService(NewMockStore()))
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/history/raw-frames/query", strings.NewReader(`{"keyword":"川AHTWO1","limit":1}`))
+	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 []RawFrameRow `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("raw POST should resolve keyword to VIN, got %+v body=%s", body.Data.Items, rec.Body.String())
+	}
+}
+
+func TestHandlerRawFramesKeepsUnresolvedKeywordEmpty(t *testing.T) {
+	handler := NewHandler(NewService(NewMockStore()))
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/history/raw-frames?keyword=64646848247&limit=1", 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 Page[RawFrameRow] `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 body.Data.Total != 0 || len(body.Data.Items) != 0 {
+		t.Fatalf("unresolved keyword should not fabricate raw rows: %+v body=%s", body.Data, rec.Body.String())
+	}
+}