feat(search+docs): trigram fuzzy search, brand/country filters, developer docs

Search:
- migration 0009: trigram GIN index on brand.name + btree on country_of_origin
- SearchProducts: typo-tolerant word_similarity matching (>=0.42) on top of
  ILIKE substring + barcode; new brand/country filters; rank by
  similarity * (0.5 + quality_score). Response gains country_of_origin,
  quality_score and per-result relevance score.
- public search UI: brand/country filter inputs; show country in results

Docs:
- serve embedded OpenAPI 3 spec at GET /api/v1/openapi.json (not rate limited)
- ApiDocs page: auth + rate-limit section, updated search params/response
- docs/api.md developer guide

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

api/internal/handler/handler_db_test.go

@@ -116,6 +116,101 @@ func TestSearchProducts(t *testing.T) {
 	}
 }
 
+func TestSearchFuzzyAndFilters(t *testing.T) {
+	h, _ := newTestHandler(t)
+	ctx := context.Background()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Skipf("no database: %v", err)
+	}
+	defer pool.Close()
+
+	_, err = pool.Exec(ctx,
+		"INSERT INTO brand (name, normalized_name) VALUES ('ZZ Test Brand','zz test brand') ON CONFLICT DO NOTHING")
+	if err != nil {
+		t.Fatalf("seed brand: %v", err)
+	}
+	_, err = pool.Exec(ctx, `
+		INSERT INTO product (name, brand_id, country_of_origin, quality_score, status)
+		VALUES ('ZZ Hazelnut Chocolate', (SELECT id FROM brand WHERE name='ZZ Test Brand'), 'Testland', 0.5, 'active')`)
+	if err != nil {
+		t.Fatalf("seed product: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, "DELETE FROM product WHERE name='ZZ Hazelnut Chocolate'")
+		_, _ = pool.Exec(ctx, "DELETE FROM brand WHERE name='ZZ Test Brand'")
+	})
+
+	decode := func(path string) []store.ProductSummary {
+		rec := doGET(t, h, path)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("%s -> status %d", path, rec.Code)
+		}
+		var body struct {
+			Items []store.ProductSummary `json:"items"`
+		}
+		if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+			t.Fatal(err)
+		}
+		return body.Items
+	}
+	has := func(items []store.ProductSummary, name string) *store.ProductSummary {
+		for i := range items {
+			if items[i].Name == name {
+				return &items[i]
+			}
+		}
+		return nil
+	}
+
+	// Typo "choclate" should fuzzy-match via word_similarity and carry a score.
+	got := has(decode("/api/"+APIVersion+"/products/search?q=choclate"), "ZZ Hazelnut Chocolate")
+	if got == nil {
+		t.Fatal("fuzzy query 'choclate' did not match 'ZZ Hazelnut Chocolate'")
+	}
+	if got.Score == nil || *got.Score <= 0 {
+		t.Fatalf("expected positive fuzzy score, got %v", got.Score)
+	}
+
+	// Brand filter.
+	if has(decode("/api/"+APIVersion+"/products/search?brand=ZZ+Test+Brand"), "ZZ Hazelnut Chocolate") == nil {
+		t.Fatal("brand filter did not return the product")
+	}
+	// Country filter (case-insensitive prefix).
+	if has(decode("/api/"+APIVersion+"/products/search?country=test"), "ZZ Hazelnut Chocolate") == nil {
+		t.Fatal("country filter did not return the product")
+	}
+	// Non-matching country excludes it.
+	if has(decode("/api/"+APIVersion+"/products/search?country=france"), "ZZ Hazelnut Chocolate") != nil {
+		t.Fatal("country filter 'france' should not return the product")
+	}
+}
+
+func TestOpenAPISpec(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/openapi.json")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var spec struct {
+		OpenAPI string         `json:"openapi"`
+		Paths   map[string]any `json:"paths"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&spec); err != nil {
+		t.Fatalf("openapi.json is not valid JSON: %v", err)
+	}
+	if spec.OpenAPI == "" || len(spec.Paths) == 0 {
+		t.Fatalf("unexpected spec: %+v", spec)
+	}
+	if _, ok := spec.Paths["/products/search"]; !ok {
+		t.Fatal("spec missing /products/search path")
+	}
+}
+
 func TestListCategories(t *testing.T) {
 	h, _ := newTestHandler(t)
 	rec := doGET(t, h, "/api/"+APIVersion+"/categories")