feat(barcode): 多条码管理（后端+迁移+GTIN校验）WIP

- 迁移 0007: 新增 product_barcode 表（一品多码），回填旧 product.gtin 为主码，
  全局唯一索引保证「一码一品」，每品至多一个主码
- internal/gtin: GS1 GTIN-8/12/13/14 校验（校验位 + 拒收店内码/变量重量码/优惠券码）
- 公开只读 API: 任一条码命中商品、详情返回 barcodes、搜索匹配条码
- adminstore: 商品详情含 barcodes；新增 AddBarcode/DeleteBarcode/SetPrimaryBarcode，
  一码命中其他商品返回 ConflictError 供后台去重

待办（按用户要求暂停）: 后台 handler 路由、投稿/审核多条码、前后端 UI

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

api/internal/adminstore/adminstore.go

@@ -162,6 +162,7 @@ type ProductDetail struct {
 	NutritionBasis  *string        `json:"nutrition_basis"`
 	ServingSize     *string        `json:"serving_size"`
 	NutriScore      *string        `json:"nutri_score"`
+	Barcodes        []Barcode      `json:"barcodes"`
 	Images          []ProductImage `json:"images"`
 	MSRP            []MSRP         `json:"msrp"`
 	Missing         []string       `json:"missing"`
@@ -207,6 +208,12 @@ WHERE p.id = $1`, id).Scan(
 		d.Additives = []string{}
 	}
 
+	bcs, err := s.listBarcodes(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	d.Barcodes = bcs
+
 	imgs, err := s.listImages(ctx, id)
 	if err != nil {
 		return nil, err

api/internal/adminstore/barcode.go

@@ -0,0 +1,270 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+
+	"github.com/baicai2026-baicai/goods/api/internal/gtin"
+)
+
+// Barcode is one GS1 trade item number attached to a product.
+type Barcode struct {
+	ID        string  `json:"id"`
+	GTIN      string  `json:"gtin"`
+	GTINType  string  `json:"gtin_type"`
+	PackLevel string  `json:"pack_level"`
+	Region    *string `json:"region"`
+	IsPrimary bool    `json:"is_primary"`
+}
+
+// BarcodeInput is the payload for attaching a barcode to a product.
+type BarcodeInput struct {
+	GTIN      string  `json:"gtin"`
+	GTINType  string  `json:"gtin_type"`
+	PackLevel string  `json:"pack_level"`
+	Region    *string `json:"region"`
+	IsPrimary bool    `json:"is_primary"`
+}
+
+// ConflictError signals that a barcode is already attached to another product,
+// so the operator must de-duplicate instead of creating a clash.
+type ConflictError struct {
+	GTIN        string
+	ProductID   string
+	ProductName string
+}
+
+func (e *ConflictError) Error() string { return "条码已被其他商品占用：" + e.GTIN }
+
+func validPackLevel(p string) string {
+	switch p {
+	case "each", "case", "pallet":
+		return p
+	default:
+		return "each"
+	}
+}
+
+func validGTINType(t, normalized string) string {
+	switch t {
+	case "EAN8", "UPC", "EAN13", "ITF14", "GTIN14":
+		return t
+	default:
+		return gtin.InferType(normalized)
+	}
+}
+
+func (s *Store) listBarcodes(ctx context.Context, productID string) ([]Barcode, error) {
+	rows, err := s.pool.Query(ctx,
+		`SELECT id, gtin, gtin_type, pack_level, region, is_primary
+		 FROM product_barcode WHERE product_id = $1
+		 ORDER BY is_primary DESC, gtin`, productID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Barcode{}
+	for rows.Next() {
+		var b Barcode
+		if err := rows.Scan(&b.ID, &b.GTIN, &b.GTINType, &b.PackLevel, &b.Region, &b.IsPrimary); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
+// barcodeOwner returns the product currently owning a barcode, if any.
+func barcodeOwner(ctx context.Context, q pgx.Tx, code string) (productID, productName string, found bool, err error) {
+	err = q.QueryRow(ctx,
+		`SELECT pb.product_id, p.name FROM product_barcode pb
+		 JOIN product p ON p.id = pb.product_id WHERE pb.gtin = $1`, code).
+		Scan(&productID, &productName)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", "", false, nil
+	}
+	if err != nil {
+		return "", "", false, err
+	}
+	return productID, productName, true, nil
+}
+
+// AddBarcode validates and attaches a barcode to a product, recording audit.
+// A barcode already owned by another product yields a *ConflictError.
+func (s *Store) AddBarcode(ctx context.Context, productID, actor string, in BarcodeInput) (*Barcode, error) {
+	code, err := gtin.Normalize(in.GTIN)
+	if err != nil {
+		return nil, err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	// Product must exist.
+	var exists bool
+	if err := tx.QueryRow(ctx, "SELECT EXISTS(SELECT 1 FROM product WHERE id=$1)", productID).Scan(&exists); err != nil {
+		return nil, err
+	}
+	if !exists {
+		return nil, ErrNotFound
+	}
+
+	// Globally unique: a barcode owned by any product (this one included)
+	// is a conflict the operator must resolve by de-duplicating.
+	if owner, name, found, err := barcodeOwner(ctx, tx, code); err != nil {
+		return nil, err
+	} else if found {
+		return nil, &ConflictError{GTIN: code, ProductID: owner, ProductName: name}
+	}
+
+	// Make this the primary barcode when requested or when none exists yet.
+	makePrimary := in.IsPrimary
+	if !makePrimary {
+		var hasPrimary bool
+		if err := tx.QueryRow(ctx,
+			"SELECT EXISTS(SELECT 1 FROM product_barcode WHERE product_id=$1 AND is_primary)", productID).
+			Scan(&hasPrimary); err != nil {
+			return nil, err
+		}
+		makePrimary = !hasPrimary
+	}
+	if makePrimary {
+		if _, err := tx.Exec(ctx,
+			"UPDATE product_barcode SET is_primary=false WHERE product_id=$1 AND is_primary", productID); err != nil {
+			return nil, err
+		}
+	}
+
+	srcID, _ := s.manualSourceID(ctx, tx)
+	var srcArg any
+	if srcID != "" {
+		srcArg = srcID
+	}
+
+	var b Barcode
+	err = tx.QueryRow(ctx, `
+INSERT INTO product_barcode (product_id, gtin, gtin_type, pack_level, region, is_primary, source_id)
+VALUES ($1,$2,$3,$4,$5,$6,$7)
+RETURNING id, gtin, gtin_type, pack_level, region, is_primary`,
+		productID, code, validGTINType(in.GTINType, code), validPackLevel(in.PackLevel),
+		in.Region, makePrimary, srcArg).
+		Scan(&b.ID, &b.GTIN, &b.GTINType, &b.PackLevel, &b.Region, &b.IsPrimary)
+	if err != nil {
+		return nil, err
+	}
+
+	if makePrimary {
+		if _, err := tx.Exec(ctx, "UPDATE product SET gtin=$2 WHERE id=$1", productID, code); err != nil {
+			return nil, err
+		}
+	}
+	if _, err := s.recomputeQualityTx(ctx, tx, productID); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+
+	_ = s.writeAudit(ctx, actor, "add_barcode", "product", &productID, []string{"gtin"}, nil, b)
+	return &b, nil
+}
+
+// DeleteBarcode removes a barcode; if it was primary, another is promoted.
+func (s *Store) DeleteBarcode(ctx context.Context, productID, barcodeID, actor string) error {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	var code string
+	var wasPrimary bool
+	err = tx.QueryRow(ctx,
+		"DELETE FROM product_barcode WHERE id=$1 AND product_id=$2 RETURNING gtin, is_primary",
+		barcodeID, productID).Scan(&code, &wasPrimary)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return ErrNotFound
+	}
+	if err != nil {
+		return err
+	}
+
+	if wasPrimary {
+		var newID, newGTIN string
+		e := tx.QueryRow(ctx,
+			"SELECT id, gtin FROM product_barcode WHERE product_id=$1 ORDER BY gtin LIMIT 1", productID).
+			Scan(&newID, &newGTIN)
+		if e == nil {
+			if _, err := tx.Exec(ctx, "UPDATE product_barcode SET is_primary=true WHERE id=$1", newID); err != nil {
+				return err
+			}
+			if _, err := tx.Exec(ctx, "UPDATE product SET gtin=$2 WHERE id=$1", productID, newGTIN); err != nil {
+				return err
+			}
+		} else if errors.Is(e, pgx.ErrNoRows) {
+			if _, err := tx.Exec(ctx, "UPDATE product SET gtin=NULL WHERE id=$1", productID); err != nil {
+				return err
+			}
+		} else {
+			return e
+		}
+	}
+
+	if _, err := s.recomputeQualityTx(ctx, tx, productID); err != nil {
+		return err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return err
+	}
+	_ = s.writeAudit(ctx, actor, "delete_barcode", "product", &productID, []string{"gtin"},
+		map[string]string{"gtin": code}, nil)
+	return nil
+}
+
+// SetPrimaryBarcode marks one barcode primary and mirrors it to product.gtin.
+func (s *Store) SetPrimaryBarcode(ctx context.Context, productID, barcodeID, actor string) (*Barcode, error) {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var code string
+	err = tx.QueryRow(ctx, "SELECT gtin FROM product_barcode WHERE id=$1 AND product_id=$2", barcodeID, productID).Scan(&code)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "UPDATE product_barcode SET is_primary=false WHERE product_id=$1 AND is_primary", productID); err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "UPDATE product_barcode SET is_primary=true WHERE id=$1", barcodeID); err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "UPDATE product SET gtin=$2 WHERE id=$1", productID, code); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "set_primary_barcode", "product", &productID, []string{"gtin"}, nil,
+		map[string]string{"gtin": code})
+
+	bcs, err := s.listBarcodes(ctx, productID)
+	if err != nil {
+		return nil, err
+	}
+	for i := range bcs {
+		if bcs[i].ID == barcodeID {
+			return &bcs[i], nil
+		}
+	}
+	return nil, ErrNotFound
+}

api/internal/gtin/gtin.go

@@ -0,0 +1,110 @@
+// Package gtin validates and normalizes GS1 trade item numbers (GTIN-8/12/13/14).
+// Only globally-unique GS1 codes are accepted: store-internal / variable-weight /
+// coupon codes (which are not globally unique) are rejected on purpose.
+package gtin
+
+import (
+	"errors"
+	"strings"
+)
+
+// Validation errors.
+var (
+	ErrEmpty      = errors.New("条码不能为空")
+	ErrFormat     = errors.New("条码必须为 8/12/13/14 位数字")
+	ErrCheck      = errors.New("条码校验位不正确")
+	ErrRestricted = errors.New("店内码/变量重量码/优惠券码等非全球唯一码，不予收录")
+)
+
+// Normalize trims and validates a GTIN, returning the cleaned digit string.
+// It enforces length, the GS1 mod-10 check digit, and rejects restricted
+// (non-globally-unique) number ranges.
+func Normalize(raw string) (string, error) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return "", ErrEmpty
+	}
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return "", ErrFormat
+		}
+	}
+	switch len(s) {
+	case 8, 12, 13, 14:
+	default:
+		return "", ErrFormat
+	}
+	if !validCheckDigit(s) {
+		return "", ErrCheck
+	}
+	if restricted(s) {
+		return "", ErrRestricted
+	}
+	return s, nil
+}
+
+// InferType returns the conventional GTIN type label for a normalized code.
+func InferType(s string) string {
+	switch len(s) {
+	case 8:
+		return "EAN8"
+	case 12:
+		return "UPC"
+	case 14:
+		return "GTIN14"
+	default:
+		return "EAN13"
+	}
+}
+
+// validCheckDigit verifies the trailing GS1 mod-10 check digit. The digit
+// immediately left of the check digit carries weight 3, then weights alternate.
+func validCheckDigit(s string) bool {
+	n := len(s)
+	sum := 0
+	for i := 0; i < n-1; i++ {
+		d := int(s[i] - '0')
+		if (n-1-i)%2 == 1 {
+			sum += d * 3
+		} else {
+			sum += d
+		}
+	}
+	check := (10 - (sum % 10)) % 10
+	return check == int(s[n-1]-'0')
+}
+
+// restricted reports whether a (length/check-digit valid) code falls in a
+// number range reserved for non-globally-unique use.
+func restricted(s string) bool {
+	switch len(s) {
+	case 13:
+		p2 := s[:2]
+		switch {
+		case s[0] == '2': // 20-29 restricted distribution / in-store
+			return true
+		case p2 == "02": // 020-029 variable-measure within a store
+			return true
+		case p2 == "04": // 040-049 restricted circulation within a company
+			return true
+		case p2 == "05": // 050-059 coupons
+			return true
+		case p2 == "98" || p2 == "99": // 980-989/99 coupons & refund receipts
+			return true
+		}
+	case 12: // UPC-A: leading number-system digit
+		switch s[0] {
+		case '2': // in-store / random weight
+			return true
+		case '4': // unrestricted in-store use
+			return true
+		case '5': // coupons
+			return true
+		}
+	case 8: // EAN-8: 0/2 prefixes reserved for in-store use
+		if s[0] == '0' || s[0] == '2' {
+			return true
+		}
+	}
+	return false
+}

api/internal/gtin/gtin_test.go

@@ -0,0 +1,49 @@
+package gtin
+
+import "testing"
+
+func TestNormalizeValid(t *testing.T) {
+	cases := []struct{ in, want, typ string }{
+		{" 5449000000996 ", "5449000000996", "EAN13"}, // Coca-Cola EAN-13
+		{"3017624010701", "3017624010701", "EAN13"},   // Nutella EAN-13
+		{"036000291452", "036000291452", "UPC"},       // UPC-A
+		{"96385074", "96385074", "EAN8"},              // EAN-8
+		{"00012345600012", "00012345600012", "GTIN14"},
+		{"6901234567892", "6901234567892", "EAN13"}, // China 690 prefix
+	}
+	for _, c := range cases {
+		got, err := Normalize(c.in)
+		if err != nil {
+			t.Errorf("Normalize(%q) unexpected error: %v", c.in, err)
+			continue
+		}
+		if got != c.want {
+			t.Errorf("Normalize(%q) = %q, want %q", c.in, got, c.want)
+		}
+		if InferType(got) != c.typ {
+			t.Errorf("InferType(%q) = %q, want %q", got, InferType(got), c.typ)
+		}
+	}
+}
+
+func TestNormalizeRejects(t *testing.T) {
+	cases := []struct {
+		in   string
+		want error
+	}{
+		{"", ErrEmpty},
+		{"12ab5678", ErrFormat},
+		{"12345", ErrFormat},
+		{"5449000000997", ErrCheck},       // bad check digit
+		{"2012345678903", ErrRestricted}, // 20-29 in-store EAN-13
+		{"0212345678909", ErrRestricted}, // 02x variable measure
+		{"212345678909", ErrRestricted},  // UPC number system 2
+		{"02345673", ErrRestricted},      // EAN-8 in-store
+	}
+	for _, c := range cases {
+		_, err := Normalize(c.in)
+		if err != c.want {
+			t.Errorf("Normalize(%q) error = %v, want %v", c.in, err, c.want)
+		}
+	}
+}

api/internal/store/store.go

@@ -29,6 +29,15 @@ func (s *Store) Ping(ctx context.Context) error {
 	return s.pool.Ping(ctx)
 }
 
+// Barcode is one GS1 trade item number attached to a product.
+type Barcode struct {
+	GTIN      string  `json:"gtin"`
+	GTINType  string  `json:"gtin_type"`
+	PackLevel string  `json:"pack_level"`
+	Region    *string `json:"region"`
+	IsPrimary bool    `json:"is_primary"`
+}
+
 // Product is the full public view of a product.
 type Product struct {
 	ID              string         `json:"id"`
@@ -41,6 +50,7 @@ type Product struct {
 	NetContentUnit  *string        `json:"net_content_unit"`
 	CountryOfOrigin *string        `json:"country_of_origin"`
 	QualityScore    float64        `json:"quality_score"`
+	Barcodes        []Barcode      `json:"barcodes"`
 	Nutriments      map[string]any `json:"nutriments,omitempty"`
 	NutritionBasis  *string        `json:"nutrition_basis,omitempty"`
 	NutriScore      *string        `json:"nutri_score,omitempty"`
@@ -49,6 +59,27 @@ type Product struct {
 	Additives       []string       `json:"additives,omitempty"`
 }
 
+// ProductBarcodes returns every barcode attached to a product, primary first.
+func (s *Store) ProductBarcodes(ctx context.Context, productID string) ([]Barcode, error) {
+	rows, err := s.pool.Query(ctx,
+		`SELECT gtin, gtin_type, pack_level, region, is_primary
+		 FROM product_barcode WHERE product_id = $1
+		 ORDER BY is_primary DESC, gtin`, productID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Barcode{}
+	for rows.Next() {
+		var b Barcode
+		if err := rows.Scan(&b.GTIN, &b.GTINType, &b.PackLevel, &b.Region, &b.IsPrimary); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
 // ProductSummary is a lightweight row used in search/listing responses.
 type ProductSummary struct {
 	ID           string  `json:"id"`
@@ -86,16 +117,35 @@ func scanProduct(row pgx.Row) (*Product, error) {
 	return &p, nil
 }
 
-// ProductByGTIN looks up an active product by its barcode.
+// ProductByGTIN looks up an active product by any of its barcodes.
 func (s *Store) ProductByGTIN(ctx context.Context, gtin string) (*Product, error) {
-	row := s.pool.QueryRow(ctx, productSelect+" WHERE p.gtin = $1 AND p.status = 'active'", gtin)
-	return scanProduct(row)
+	row := s.pool.QueryRow(ctx, productSelect+`
+ WHERE p.status = 'active'
+   AND (p.gtin = $1 OR EXISTS (
+         SELECT 1 FROM product_barcode pb
+         WHERE pb.product_id = p.id AND pb.gtin = $1))
+ LIMIT 1`, gtin)
+	p, err := scanProduct(row)
+	if err != nil {
+		return nil, err
+	}
+	if p.Barcodes, err = s.ProductBarcodes(ctx, p.ID); err != nil {
+		return nil, err
+	}
+	return p, nil
 }
 
 // ProductByID looks up a product by its UUID.
 func (s *Store) ProductByID(ctx context.Context, id string) (*Product, error) {
 	row := s.pool.QueryRow(ctx, productSelect+" WHERE p.id = $1", id)
-	return scanProduct(row)
+	p, err := scanProduct(row)
+	if err != nil {
+		return nil, err
+	}
+	if p.Barcodes, err = s.ProductBarcodes(ctx, p.ID); err != nil {
+		return nil, err
+	}
+	return p, nil
 }
 
 // SearchProducts performs a fuzzy name search with optional category subtree filter.
@@ -104,7 +154,9 @@ func (s *Store) SearchProducts(ctx context.Context, q, category string, limit, o
 	where := "WHERE p.status = 'active'"
 	if q != "" {
 		args = append(args, q)
-		where += " AND p.name ILIKE '%' || $1 || '%'"
+		where += ` AND (p.name ILIKE '%' || $1 || '%'
+			OR EXISTS (SELECT 1 FROM product_barcode pb
+			           WHERE pb.product_id = p.id AND pb.gtin ILIKE '%' || $1 || '%'))`
 	}
 	if category != "" {
 		args = append(args, category)

migrations/0007_product_barcode.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS product_barcode;

migrations/0007_product_barcode.up.sql

@@ -0,0 +1,36 @@
+-- Multi-barcode support: one product can carry many GS1 barcodes
+-- (consumer unit EAN-13/UPC, case ITF-14, regional re-labels, etc.).
+-- product.gtin is kept as the denormalized "primary" barcode for
+-- backward compatibility and is mirrored from the is_primary row here.
+
+CREATE TABLE product_barcode (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    product_id UUID NOT NULL REFERENCES product(id) ON DELETE CASCADE,
+    gtin       VARCHAR(14) NOT NULL,
+    gtin_type  VARCHAR(8) NOT NULL DEFAULT 'EAN13',
+    pack_level VARCHAR(8) NOT NULL DEFAULT 'each',
+    region     VARCHAR(8),
+    is_primary BOOLEAN NOT NULL DEFAULT false,
+    source_id  UUID REFERENCES source(id),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CONSTRAINT product_barcode_type_chk CHECK (gtin_type IN ('EAN8','UPC','EAN13','ITF14','GTIN14')),
+    CONSTRAINT product_barcode_pack_chk CHECK (pack_level IN ('each','case','pallet'))
+);
+
+-- A barcode is globally unique: one code maps to exactly one product.
+CREATE UNIQUE INDEX idx_product_barcode_gtin ON product_barcode (gtin);
+CREATE INDEX idx_product_barcode_product ON product_barcode (product_id);
+-- At most one primary barcode per product.
+CREATE UNIQUE INDEX idx_product_barcode_primary ON product_barcode (product_id) WHERE is_primary;
+
+-- Backfill: lift each product's existing gtin into the new table as primary.
+INSERT INTO product_barcode (product_id, gtin, gtin_type, pack_level, is_primary)
+SELECT id, gtin,
+       CASE WHEN length(gtin) = 8 THEN 'EAN8'
+            WHEN length(gtin) = 12 THEN 'UPC'
+            WHEN length(gtin) = 14 THEN 'GTIN14'
+            ELSE 'EAN13' END,
+       'each', true
+FROM product
+WHERE gtin IS NOT NULL AND gtin <> ''
+ON CONFLICT (gtin) DO NOTHING;