feat(M3): 只读 API 端点实现

- store: pgx 只读数据访问层(productByGTIN/ByID/search/nutriments/msrp/brands/categories/source)
- handler: 真实查询替换 501 占位, 统一分页 + 错误信封, MSRP 带免责声明无购买入口
- main: pgxpool 连接池接线
- search: 名称模糊 + 分类子树过滤(ltree <@)
- 测试: healthz/pageParams 单测 + DB-backed handler 集成测试(无库自动跳过)
- CI: Go job 增加 postgres service + migrate up, 实跑 DB 测试
- 依赖: pgx v5.7.2 (固定到兼容 go1.23 的版本)
- 本地实跑: 8 个端点对真实 OFF 数据返回正确(barcode/search/nutriments/msrp/brands/categories/source/404)

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

api/internal/handler/handler.go

@@ -1,5 +1,4 @@
 // Package handler wires up the public, read-only OpenGoods HTTP API.
-//
 // The OpenGoods service is a public-good product information API: it only
 // collects and serves product facts. It exposes no purchase, checkout, or
 // commerce endpoints by design.
@@ -7,48 +6,188 @@ package handler
 
 import (
 	"encoding/json"
+	"errors"
 	"net/http"
+	"strconv"
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
+
+	"github.com/baicai2026-baicai/goods/api/internal/store"
 )
 
 // APIVersion is the current public API version prefix.
 const APIVersion = "v1"
 
+const (
+	defaultPageSize = 20
+	maxPageSize     = 100
+)
+
+// Handler holds dependencies shared by the HTTP routes.
+type Handler struct {
+	store *store.Store
+}
+
+// New constructs a Handler backed by the given store.
+func New(s *store.Store) *Handler {
+	return &Handler{store: s}
+}
+
 // Router builds the top-level HTTP handler with middleware and routes mounted.
-func Router() http.Handler {
+func (h *Handler) Router() http.Handler {
 	r := chi.NewRouter()
 	r.Use(middleware.RequestID)
 	r.Use(middleware.RealIP)
 	r.Use(middleware.Recoverer)
 
-	r.Get("/healthz", Healthz)
+	r.Get("/healthz", h.Healthz)
 
 	r.Route("/api/"+APIVersion, func(r chi.Router) {
 		r.Route("/products", func(r chi.Router) {
-			r.Get("/barcode/{gtin}", notImplemented)
-			r.Get("/search", notImplemented)
-			r.Get("/{id}", notImplemented)
-			r.Get("/{id}/nutriments", notImplemented)
-			r.Get("/{id}/msrp", notImplemented)
+			r.Get("/barcode/{gtin}", h.ProductByBarcode)
+			r.Get("/search", h.SearchProducts)
+			r.Get("/{id}", h.ProductByID)
+			r.Get("/{id}/nutriments", h.ProductNutriments)
+			r.Get("/{id}/msrp", h.ProductMSRP)
 		})
-		r.Get("/brands", notImplemented)
-		r.Get("/categories", notImplemented)
-		r.Get("/sources/{id}", notImplemented)
+		r.Get("/brands", h.ListBrands)
+		r.Get("/categories", h.ListCategories)
+		r.Get("/sources/{id}", h.SourceByID)
 	})
 
 	return r
 }
 
 // Healthz reports liveness of the service.
-func Healthz(w http.ResponseWriter, r *http.Request) {
+func (h *Handler) Healthz(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
 }
 
-// notImplemented is a placeholder for endpoints scoped to later milestones.
-func notImplemented(w http.ResponseWriter, r *http.Request) {
-	writeError(w, r, http.StatusNotImplemented, "not_implemented", "endpoint not implemented yet")
+// ProductByBarcode returns a product by its GTIN.
+func (h *Handler) ProductByBarcode(w http.ResponseWriter, r *http.Request) {
+	p, err := h.store.ProductByGTIN(r.Context(), chi.URLParam(r, "gtin"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, p)
+}
+
+// ProductByID returns a product by its UUID.
+func (h *Handler) ProductByID(w http.ResponseWriter, r *http.Request) {
+	p, err := h.store.ProductByID(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, p)
+}
+
+// SearchProducts runs a fuzzy name search with optional category filter + paging.
+func (h *Handler) SearchProducts(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query().Get("q")
+	category := r.URL.Query().Get("category")
+	page, size := pageParams(r)
+
+	items, total, err := h.store.SearchProducts(r.Context(), q, category, size, (page-1)*size)
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items": items,
+		"page":  page,
+		"size":  size,
+		"total": total,
+	})
+}
+
+// ProductNutriments returns just the nutrition facts of a product.
+func (h *Handler) ProductNutriments(w http.ResponseWriter, r *http.Request) {
+	n, err := h.store.Nutriments(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, n)
+}
+
+// ProductMSRP returns official suggested retail price snapshots (no purchase link).
+func (h *Handler) ProductMSRP(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListMSRP(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items":      items,
+		"disclaimer": "厂商建议零售价历史快照，仅供参考，不构成购买建议，本服务不提供任何购买入口。",
+	})
+}
+
+// ListBrands returns a paginated list of brands.
+func (h *Handler) ListBrands(w http.ResponseWriter, r *http.Request) {
+	page, size := pageParams(r)
+	items, total, err := h.store.ListBrands(r.Context(), size, (page-1)*size)
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items": items, "page": page, "size": size, "total": total,
+	})
+}
+
+// ListCategories returns the full category tree.
+func (h *Handler) ListCategories(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListCategories(r.Context())
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+// SourceByID returns a single data source.
+func (h *Handler) SourceByID(w http.ResponseWriter, r *http.Request) {
+	src, err := h.store.SourceByID(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, src)
+}
+
+// handleErr writes an appropriate error response; returns true if it handled one.
+func (h *Handler) handleErr(w http.ResponseWriter, r *http.Request, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, store.ErrNotFound) {
+		writeError(w, r, http.StatusNotFound, "not_found", "resource not found")
+		return true
+	}
+	writeError(w, r, http.StatusInternalServerError, "internal_error", "internal server error")
+	return true
+}
+
+func pageParams(r *http.Request) (page, size int) {
+	page = atoiDefault(r.URL.Query().Get("page"), 1)
+	if page < 1 {
+		page = 1
+	}
+	size = atoiDefault(r.URL.Query().Get("size"), defaultPageSize)
+	if size < 1 {
+		size = defaultPageSize
+	}
+	if size > maxPageSize {
+		size = maxPageSize
+	}
+	return page, size
+}
+
+func atoiDefault(s string, fallback int) int {
+	if s == "" {
+		return fallback
+	}
+	v, err := strconv.Atoi(s)
+	if err != nil {
+		return fallback
+	}
+	return v
 }
 
 func writeJSON(w http.ResponseWriter, status int, body any) {

api/internal/handler/handler_db_test.go

@@ -0,0 +1,134 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/baicai2026-baicai/goods/api/internal/store"
+)
+
+// newTestHandler connects to the test database, skipping if unavailable or
+// unmigrated. It inserts a known product (cleaned up via t.Cleanup) so the
+// endpoint assertions are deterministic.
+func newTestHandler(t *testing.T) (*Handler, string) {
+	t.Helper()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Skipf("no database: %v", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		t.Skipf("database not reachable: %v", err)
+	}
+
+	var hasProduct bool
+	if err := pool.QueryRow(ctx, "SELECT to_regclass('public.product') IS NOT NULL").Scan(&hasProduct); err != nil || !hasProduct {
+		pool.Close()
+		t.Skip("migrations not applied")
+	}
+
+	gtin := "4006381333931"
+	_, err = pool.Exec(context.Background(), `
+		INSERT INTO product (gtin, name, category_id, net_content_value, net_content_unit)
+		VALUES ($1, 'Test Cola', (SELECT id FROM category WHERE path='food.beverages.carbonated'), 330, 'ml')
+		ON CONFLICT (gtin) WHERE gtin IS NOT NULL DO UPDATE SET name = EXCLUDED.name`, gtin)
+	if err != nil {
+		pool.Close()
+		t.Fatalf("seed insert failed: %v", err)
+	}
+	var pid string
+	_ = pool.QueryRow(context.Background(), "SELECT id FROM product WHERE gtin=$1", gtin).Scan(&pid)
+	_, _ = pool.Exec(context.Background(), `
+		INSERT INTO food_detail (product_id, nutrition_basis, nutriments)
+		VALUES ($1, 'per_100ml', '{"energy_kcal": 42}'::jsonb)
+		ON CONFLICT (product_id) DO UPDATE SET nutriments = EXCLUDED.nutriments`, pid)
+
+	t.Cleanup(func() {
+		_, _ = pool.Exec(context.Background(), "DELETE FROM product WHERE gtin=$1", gtin)
+		pool.Close()
+	})
+	return New(store.New(pool)), gtin
+}
+
+func doGET(t *testing.T, h *Handler, path string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	rec := httptest.NewRecorder()
+	h.Router().ServeHTTP(rec, req)
+	return rec
+}
+
+func TestProductByBarcode(t *testing.T) {
+	h, gtin := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/products/barcode/"+gtin)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rec.Code, rec.Body.String())
+	}
+	var p store.Product
+	if err := json.NewDecoder(rec.Body).Decode(&p); err != nil {
+		t.Fatal(err)
+	}
+	if p.Name != "Test Cola" || p.GTIN == nil || *p.GTIN != gtin {
+		t.Fatalf("unexpected product: %+v", p)
+	}
+	if p.CategoryPath == nil || *p.CategoryPath != "food.beverages.carbonated" {
+		t.Fatalf("category not joined: %+v", p.CategoryPath)
+	}
+}
+
+func TestProductByBarcodeNotFound(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/products/barcode/0000000000000")
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", rec.Code)
+	}
+}
+
+func TestSearchProducts(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/products/search?q=Cola&category=food.beverages")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var body struct {
+		Items []store.ProductSummary `json:"items"`
+		Total int                    `json:"total"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	if body.Total < 1 {
+		t.Fatalf("expected at least 1 result, got %d", body.Total)
+	}
+}
+
+func TestListCategories(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/categories")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var body struct {
+		Items []store.Category `json:"items"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	if len(body.Items) < 20 {
+		t.Fatalf("expected seeded categories, got %d", len(body.Items))
+	}
+}

api/internal/handler/handler_test.go

@@ -11,7 +11,7 @@ func TestHealthz(t *testing.T) {
 	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
 	rec := httptest.NewRecorder()
 
-	Router().ServeHTTP(rec, req)
+	New(nil).Router().ServeHTTP(rec, req)
 
 	if rec.Code != http.StatusOK {
 		t.Fatalf("expected status %d, got %d", http.StatusOK, rec.Code)
@@ -26,13 +26,23 @@ func TestHealthz(t *testing.T) {
 	}
 }
 
-func TestProductEndpointNotImplemented(t *testing.T) {
-	req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/products/barcode/3017624010701", nil)
-	rec := httptest.NewRecorder()
-
-	Router().ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusNotImplemented {
-		t.Fatalf("expected status %d, got %d", http.StatusNotImplemented, rec.Code)
+func TestPageParams(t *testing.T) {
+	cases := []struct {
+		query            string
+		wantPage, wantSz int
+	}{
+		{"", 1, defaultPageSize},
+		{"page=3&size=10", 3, 10},
+		{"page=0&size=-5", 1, defaultPageSize},
+		{"size=1000", 1, maxPageSize},
+		{"page=abc", 1, defaultPageSize},
+	}
+	for _, c := range cases {
+		req := httptest.NewRequest(http.MethodGet, "/?"+c.query, nil)
+		page, size := pageParams(req)
+		if page != c.wantPage || size != c.wantSz {
+			t.Errorf("query %q: got page=%d size=%d, want page=%d size=%d",
+				c.query, page, size, c.wantPage, c.wantSz)
+		}
 	}
 }