fix(admin): 回流接口校验/规范化 GTIN，非法条码标记 invalid 而非中断批次

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

api/internal/adminhandler/handler.go

@@ -14,6 +14,7 @@ import (
 	"github.com/go-chi/chi/v5/middleware"
 
 	"github.com/baicai2026-baicai/goods/api/internal/adminstore"
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
 	"github.com/baicai2026-baicai/goods/api/internal/auth"
 	"github.com/baicai2026-baicai/goods/api/internal/gtin"
 	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
@@ -90,6 +91,8 @@ func (h *Handler) Router() http.Handler {
 			r.Put("/api/categories/{id}", h.UpdateCategory)
 			r.Delete("/api/categories/{id}", h.DeleteCategory)
 
+			r.Post("/api/import/bypos", h.ImportBypos)
+
 			r.Get("/api/submissions", h.ListSubmissions)
 			r.Get("/api/submissions/{id}", h.GetSubmission)
 			r.Post("/api/submissions/{id}/approve", h.ApproveSubmission)
@@ -108,6 +111,11 @@ func (h *Handler) Router() http.Handler {
 	// admin approves them.
 	r.Post("/api/public/submissions", h.CreateSubmission)
 
+	// Archive backflow: inventory-management software pushes products missing
+	// from the archive. Authenticated with a public API key; records enter the
+	// same moderation queue and are archived only after admin approval.
+	r.Post("/api/public/backflow", h.Backflow)
+
 	return r
 }
 
@@ -632,6 +640,62 @@ func (h *Handler) CreateSubmission(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusCreated, map[string]string{"id": id, "status": "pending"})
 }
 
+// Backflow accepts a batch of products pushed by inventory-management software.
+// It authenticates with a public API key (X-API-Key or Bearer), enqueues each
+// item for admin review (deduplicating by GTIN), and returns a per-item summary.
+func (h *Handler) Backflow(w http.ResponseWriter, r *http.Request) {
+	raw := presentedAPIKey(r)
+	if raw == "" {
+		writeError(w, http.StatusUnauthorized, "missing_api_key", "缺少 API key（请在 X-API-Key 或 Authorization: Bearer 中提供）")
+		return
+	}
+	if !apikey.IsWellFormed(raw) {
+		writeError(w, http.StatusUnauthorized, "invalid_api_key", "API key 格式无效")
+		return
+	}
+	if _, err := h.store.APIKeyByHash(r.Context(), apikey.Hash(raw)); err != nil {
+		if errors.Is(err, adminstore.ErrNotFound) {
+			writeError(w, http.StatusUnauthorized, "invalid_api_key", "API key 无效或已吊销")
+			return
+		}
+		writeError(w, http.StatusInternalServerError, "internal_error", err.Error())
+		return
+	}
+
+	var items []adminstore.SubmissionInput
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 16<<20)).Decode(&items); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "请求体应为商品数组 (JSON array)")
+		return
+	}
+
+	if len(items) == 0 {
+		writeError(w, http.StatusBadRequest, "bad_request", "回流列表为空")
+		return
+	}
+	if len(items) > 1000 {
+		writeError(w, http.StatusBadRequest, "too_many", "单次回流最多 1000 条")
+		return
+	}
+
+	sum, err := h.store.CreateBackflowSubmissions(r.Context(), items, realIP(r))
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "internal_error", err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, sum)
+}
+
+// presentedAPIKey extracts a public API key from X-API-Key or a Bearer token.
+func presentedAPIKey(r *http.Request) string {
+	if v := strings.TrimSpace(r.Header.Get("X-API-Key")); v != "" {
+		return v
+	}
+	if v := r.Header.Get("Authorization"); strings.HasPrefix(v, "Bearer ") {
+		return strings.TrimSpace(strings.TrimPrefix(v, "Bearer "))
+	}
+	return ""
+}
+
 // ListSubmissions returns the moderation queue (admin).
 func (h *Handler) ListSubmissions(w http.ResponseWriter, r *http.Request) {
 	status := r.URL.Query().Get("status")

api/internal/adminhandler/import_bypos.go

@@ -0,0 +1,30 @@
+package adminhandler
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/baicai2026-baicai/goods/api/internal/adminstore"
+)
+
+func (h *Handler) ImportBypos(w http.ResponseWriter, r *http.Request) {
+	var records []adminstore.ByposRecord
+	dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 50<<20))
+	for dec.More() {
+		var rec adminstore.ByposRecord
+		if err := dec.Decode(&rec); err != nil {
+			continue
+		}
+		records = append(records, rec)
+	}
+	if len(records) == 0 {
+		writeError(w, http.StatusBadRequest, "empty", "\u6ca1\u6709\u53ef\u5bfc\u5165\u7684\u8bb0\u5f55")
+		return
+	}
+	result, err := h.store.ImportByposRecords(r.Context(), records)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "import_error", err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, result)
+}

api/internal/adminstore/backflow.go

@@ -0,0 +1,158 @@
+package adminstore
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+
+	"github.com/baicai2026-baicai/goods/api/internal/gtin"
+	"github.com/jackc/pgx/v5"
+)
+
+// backflowSource is the value stored in submission.payload->>'source' for
+// records pushed by inventory-management software via the backflow API.
+const backflowSource = "backflow"
+
+// APIKeyAuth is the minimal key metadata needed to authenticate a backflow
+// caller. Only active (non-revoked) keys resolve.
+type APIKeyAuth struct {
+	ID   string
+	Name string
+}
+
+// APIKeyByHash returns the active key matching a SHA-256 hash, or ErrNotFound
+// when no such active key exists. Used to authenticate machine callers (e.g.
+// the backflow endpoint) with the same public API keys issued to API users.
+func (s *Store) APIKeyByHash(ctx context.Context, hash string) (*APIKeyAuth, error) {
+	var k APIKeyAuth
+	err := s.pool.QueryRow(ctx,
+		"SELECT id, name FROM api_key WHERE key_hash = $1 AND revoked_at IS NULL", hash,
+	).Scan(&k.ID, &k.Name)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &k, nil
+}
+
+// BackflowResult reports the outcome of one item in a backflow batch.
+type BackflowResult struct {
+	GTIN   *string `json:"gtin"`
+	Name   string  `json:"name"`
+	Status string  `json:"status"`       // queued | exists | duplicate | invalid
+	ID     string  `json:"id,omitempty"` // submission id when queued
+	Reason string  `json:"reason,omitempty"`
+}
+
+// BackflowSummary aggregates a backflow batch outcome.
+type BackflowSummary struct {
+	Total     int              `json:"total"`
+	Queued    int              `json:"queued"`
+	Exists    int              `json:"exists"`
+	Duplicate int              `json:"duplicate"`
+	Invalid   int              `json:"invalid"`
+	Results   []BackflowResult `json:"results"`
+}
+
+// CreateBackflowSubmissions enqueues products pushed by inventory software for
+// admin review. Each item is deduplicated by GTIN: items whose barcode already
+// matches an archived product are skipped ("exists"), and items that duplicate
+// a pending submission are skipped ("duplicate"). Accepted items are tagged
+// with source="backflow" and enter the same moderation queue as public
+// contributions; approval creates the product exactly as ApproveSubmission does.
+//
+// Items are processed independently: a bad item never rolls back accepted ones.
+func (s *Store) CreateBackflowSubmissions(ctx context.Context, items []SubmissionInput, remoteIP string) (BackflowSummary, error) {
+	sum := BackflowSummary{Total: len(items), Results: make([]BackflowResult, 0, len(items))}
+
+	for _, in := range items {
+		in.Name = strings.TrimSpace(in.Name)
+		res := BackflowResult{Name: in.Name}
+
+		if in.GTIN != nil {
+			g := strings.TrimSpace(*in.GTIN)
+			if g == "" {
+				in.GTIN = nil
+			} else {
+				// Validate/normalize so a malformed barcode is reported as an
+				// invalid item instead of aborting the batch (the gtin column
+				// is varchar(14) and only GS1 codes are archived).
+				norm, err := gtin.Normalize(g)
+				if err != nil {
+					res.GTIN = &g
+					res.Status = "invalid"
+					res.Reason = err.Error()
+					sum.Invalid++
+					sum.Results = append(sum.Results, res)
+					continue
+				}
+				in.GTIN = &norm
+				res.GTIN = &norm
+			}
+		}
+
+		if in.Name == "" {
+			res.Status = "invalid"
+			res.Reason = "商品名称不能为空"
+			sum.Invalid++
+			sum.Results = append(sum.Results, res)
+			continue
+		}
+
+		if in.GTIN != nil {
+			// Already archived: backflow only carries products we don't have yet.
+			var pid string
+			err := s.pool.QueryRow(ctx, "SELECT id FROM product WHERE gtin = $1", *in.GTIN).Scan(&pid)
+			if err == nil {
+				res.Status = "exists"
+				res.Reason = "该条码商品已收录"
+				sum.Exists++
+				sum.Results = append(sum.Results, res)
+				continue
+			} else if !errors.Is(err, pgx.ErrNoRows) {
+				return sum, err
+			}
+
+			// Collapse repeated auto-pushes of the same barcode in the queue.
+			var sid string
+			err = s.pool.QueryRow(ctx,
+				"SELECT id FROM submission WHERE gtin = $1 AND status = 'pending' LIMIT 1", *in.GTIN).Scan(&sid)
+			if err == nil {
+				res.Status = "duplicate"
+				res.Reason = "已有待审核的同条码回流记录"
+				res.ID = sid
+				sum.Duplicate++
+				sum.Results = append(sum.Results, res)
+				continue
+			} else if !errors.Is(err, pgx.ErrNoRows) {
+				return sum, err
+			}
+		}
+
+		src := backflowSource
+		in.Source = &src
+
+		payload, err := json.Marshal(in)
+		if err != nil {
+			return sum, err
+		}
+
+		var id string
+		err = s.pool.QueryRow(ctx, `
+INSERT INTO submission (gtin, name, payload, submitter_name, submitter_contact, note, remote_ip)
+VALUES ($1,$2,$3,$4,$5,$6,$7) RETURNING id`,
+			in.GTIN, in.Name, payload, in.SubmitterName, in.SubmitterContact, in.Note, remoteIP).Scan(&id)
+		if err != nil {
+			return sum, err
+		}
+		res.Status = "queued"
+		res.ID = id
+		sum.Queued++
+		sum.Results = append(sum.Results, res)
+	}
+
+	return sum, nil
+}

api/internal/adminstore/import_bypos.go

@@ -0,0 +1,217 @@
+package adminstore
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+)
+
+type ByposRecord struct {
+	Barcode      string `json:"barcode"`
+	Name         string `json:"name"`
+	Spec         string `json:"spec"`
+	Unit         string `json:"unit"`
+	Area         string `json:"area"`
+	Manufacturer string `json:"manufacturer"`
+	License      string `json:"license"`
+	InPrice      string `json:"in_price"`
+	SellPrice    string `json:"sell_price"`
+	Status       string `json:"status"`
+	RetMsg       string `json:"retmsg"`
+	FetchedAt    string `json:"fetched_at"`
+	Source       string `json:"source"`
+}
+
+type ImportByposResult struct {
+	Loaded  int `json:"loaded"`
+	Skipped int `json:"skipped"`
+	Errored int `json:"errored"`
+}
+
+const byposSourceName = "bypos\u4e2d\u5fc3\u5e93"
+const byposSourceURL = "https://zc.bypos.net"
+
+func (s *Store) ensureByposSource(ctx context.Context, tx pgx.Tx) (string, error) {
+	var id string
+	err := tx.QueryRow(ctx, `
+INSERT INTO source (name, homepage, license, trust_weight)
+VALUES ($1, $2, 'proprietary', 0.6)
+ON CONFLICT (name) DO UPDATE SET homepage = EXCLUDED.homepage
+RETURNING id`, byposSourceName, byposSourceURL).Scan(&id)
+	return id, err
+}
+
+func (s *Store) ensureManufacturer(ctx context.Context, tx pgx.Tx, name string, country *string) (string, error) {
+	norm := strings.Join(strings.Fields(strings.ToLower(name)), " ")
+	var id string
+	err := tx.QueryRow(ctx, `
+INSERT INTO manufacturer (name, normalized_name, country)
+VALUES ($1, $2, $3)
+ON CONFLICT (normalized_name) DO UPDATE SET name = manufacturer.name
+RETURNING id`, name, norm, country).Scan(&id)
+	return id, err
+}
+
+func (s *Store) importByposRecord(ctx context.Context, tx pgx.Tx, rec ByposRecord, sourceID string) error {
+	if rec.Status != "hit" || strings.TrimSpace(rec.Name) == "" {
+		return nil
+	}
+
+	barcode := strings.TrimSpace(rec.Barcode)
+	name := strings.TrimSpace(rec.Name)
+
+	var country *string
+	if strings.HasPrefix(barcode, "69") {
+		c := "\u4e2d\u56fd"
+		country = &c
+	}
+
+	var manufacturerID *string
+	if mfr := strings.TrimSpace(rec.Manufacturer); mfr != "" {
+		mid, err := s.ensureManufacturer(ctx, tx, mfr, country)
+		if err != nil {
+			return err
+		}
+		manufacturerID = &mid
+	}
+
+	attrs := map[string]interface{}{}
+	if v := strings.TrimSpace(rec.Spec); v != "" {
+		attrs["spec"] = v
+	}
+	if v := strings.TrimSpace(rec.Unit); v != "" {
+		attrs["pack_unit"] = v
+	}
+	if v := strings.TrimSpace(rec.Area); v != "" {
+		attrs["origin_area"] = v
+	}
+	if v := strings.TrimSpace(rec.License); v != "" {
+		attrs["production_license"] = v
+	}
+	attrsJSON, _ := json.Marshal(attrs)
+
+	var productID string
+	if barcode != "" {
+		err := tx.QueryRow(ctx, `
+INSERT INTO product (gtin, name, manufacturer_id, country_of_origin, attributes, status)
+VALUES ($1, $2, $3, $4, $5, 'active')
+ON CONFLICT (gtin) WHERE gtin IS NOT NULL DO UPDATE SET
+    name = EXCLUDED.name,
+    manufacturer_id = COALESCE(EXCLUDED.manufacturer_id, product.manufacturer_id),
+    country_of_origin = COALESCE(EXCLUDED.country_of_origin, product.country_of_origin),
+    attributes = product.attributes || EXCLUDED.attributes
+RETURNING id`, barcode, name, manufacturerID, country, attrsJSON).Scan(&productID)
+		if err != nil {
+			return err
+		}
+	} else {
+		err := tx.QueryRow(ctx, `
+INSERT INTO product (name, manufacturer_id, country_of_origin, attributes, status)
+VALUES ($1, $2, $3, $4, 'active')
+RETURNING id`, name, manufacturerID, country, attrsJSON).Scan(&productID)
+		if err != nil {
+			return err
+		}
+	}
+
+	_, _ = tx.Exec(ctx, "DELETE FROM product_msrp WHERE product_id = $1 AND source_id = $2", productID, sourceID)
+	if sp := strings.TrimSpace(rec.SellPrice); sp != "" && sp != "0" {
+		_, _ = tx.Exec(ctx, `
+INSERT INTO product_msrp (product_id, amount, currency, region, source_id, source_url)
+VALUES ($1, $2::numeric, 'CNY', 'CN', $3, $4)`, productID, sp, sourceID, byposSourceURL)
+	}
+
+	_, _ = tx.Exec(ctx, "DELETE FROM product_source WHERE product_id = $1 AND source_id = $2", productID, sourceID)
+	fields := []string{"name", "country_of_origin"}
+	if manufacturerID != nil {
+		fields = append(fields, "manufacturer")
+	}
+	if len(attrs) > 0 {
+		fields = append(fields, "attributes")
+	}
+	if barcode != "" {
+		fields = append(fields, "gtin")
+	}
+	rawJSON, _ := json.Marshal(rec)
+	fetchedAt := strings.TrimSpace(rec.FetchedAt)
+	if fetchedAt == "" {
+		fetchedAt = ""
+	}
+
+	if fetchedAt != "" {
+		_, err := tx.Exec(ctx, `
+INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+VALUES ($1, $2, $3, $4, $5::timestamptz, $6)`,
+			productID, sourceID, byposSourceURL, fields, fetchedAt, rawJSON)
+		if err != nil {
+			return err
+		}
+	} else {
+		_, err := tx.Exec(ctx, `
+INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+VALUES ($1, $2, $3, $4, now(), $5)`,
+			productID, sourceID, byposSourceURL, fields, rawJSON)
+		if err != nil {
+			return err
+		}
+	}
+
+	if barcode != "" {
+		gtinType := "EAN13"
+		switch len(barcode) {
+		case 8:
+			gtinType = "EAN8"
+		case 12:
+			gtinType = "UPC"
+		case 14:
+			gtinType = "GTIN14"
+		}
+		_, _ = tx.Exec(ctx, `
+INSERT INTO product_barcode (product_id, gtin, gtin_type, pack_level, is_primary, source_id)
+VALUES ($1, $2, $3, 'each', true, $4)
+ON CONFLICT (gtin) DO NOTHING`, productID, barcode, gtinType, sourceID)
+	}
+
+	_, err := s.recomputeQualityTx(ctx, tx, productID)
+	return err
+}
+
+func (s *Store) ImportByposRecords(ctx context.Context, records []ByposRecord) (*ImportByposResult, error) {
+	result := &ImportByposResult{}
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	sourceID, err := s.ensureByposSource(ctx, tx)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, rec := range records {
+		if rec.Status != "hit" || strings.TrimSpace(rec.Name) == "" {
+			result.Skipped++
+			continue
+		}
+		sp, spErr := tx.Begin(ctx)
+		if spErr != nil {
+			result.Errored++
+			continue
+		}
+		if err := s.importByposRecord(ctx, sp, rec, sourceID); err != nil {
+			sp.Rollback(ctx)
+			result.Errored++
+		} else {
+			sp.Commit(ctx)
+			result.Loaded++
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	return result, nil
+}

api/internal/adminstore/submission.go

@@ -40,6 +40,10 @@ type SubmissionInput struct {
 	SubmitterName    *string           `json:"submitter_name"`
 	SubmitterContact *string           `json:"submitter_contact"`
 	Note             *string           `json:"note"`
+	// Source tags the origin of the submission, stored inside the payload so no
+	// schema change is needed. Empty means the default public contribution
+	// ("community"); "backflow" marks records pushed by inventory software.
+	Source *string `json:"source,omitempty"`
 }
 
 // SubmissionRow is a queue-list row for the admin review table.
@@ -49,6 +53,7 @@ type SubmissionRow struct {
 	Name          string  `json:"name"`
 	Status        string  `json:"status"`
 	SubmitterName *string `json:"submitter_name"`
+	Source        *string `json:"source"`
 	Matched       bool    `json:"matched"`
 	CreatedAt     string  `json:"created_at"`
 	ReviewedAt    *string `json:"reviewed_at"`
@@ -129,8 +134,8 @@ func (s *Store) ListSubmissions(ctx context.Context, status string, limit, offse
 
 	args = append(args, limit, offset)
 	sql := `
-SELECT id, gtin, name, status, submitter_name, (target_product_id IS NOT NULL),
-       created_at, reviewed_at
+SELECT id, gtin, name, status, submitter_name, NULLIF(payload->>'source',''),
+       (target_product_id IS NOT NULL), created_at, reviewed_at
 FROM submission ` + where +
 		" ORDER BY (status='pending') DESC, created_at DESC LIMIT $" +
 		strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
@@ -146,7 +151,7 @@ FROM submission ` + where +
 		var r SubmissionRow
 		var created time.Time
 		var reviewed *time.Time
-		if err := rows.Scan(&r.ID, &r.GTIN, &r.Name, &r.Status, &r.SubmitterName, &r.Matched, &created, &reviewed); err != nil {
+		if err := rows.Scan(&r.ID, &r.GTIN, &r.Name, &r.Status, &r.SubmitterName, &r.Source, &r.Matched, &created, &reviewed); err != nil {
 			return nil, 0, err
 		}
 		r.CreatedAt = created.Format(time.RFC3339)

api/internal/handler/openapi.json

@@ -208,7 +208,22 @@
           "nutriments": { "type": "object", "additionalProperties": true, "nullable": true },
           "nutrition_basis": { "type": "string", "nullable": true },
           "nutri_score": { "type": "string", "nullable": true },
-          "ingredients_text": { "type": "string", "nullable": true }
+          "ingredients_text": { "type": "string", "nullable": true },
+          "msrp": {
+            "type": "array",
+            "description": "Manufacturer suggested retail price snapshots (reference only, newest first; zero-amount entries omitted).",
+            "items": {
+              "type": "object",
+              "properties": {
+                "amount": { "type": "number" },
+                "currency": { "type": "string" },
+                "region": { "type": "string" },
+                "effective_date": { "type": "string", "nullable": true },
+                "source_url": { "type": "string", "nullable": true },
+                "note": { "type": "string", "nullable": true }
+              }
+            }
+          }
         }
       }
     }

api/internal/store/store.go

@@ -126,6 +126,7 @@ type Product struct {
 	Ingredients     *string        `json:"ingredients_text,omitempty"`
 	Allergens       []string       `json:"allergens,omitempty"`
 	Additives       []string       `json:"additives,omitempty"`
+	MSRP            []MSRP         `json:"msrp,omitempty"`
 }
 
 // ProductBarcodes returns every barcode attached to a product, primary first.
@@ -280,6 +281,9 @@ func (s *Store) ProductByGTIN(ctx context.Context, gtin string) (*Product, error
 	if p.Specs, err = s.buildSpecs(ctx, p.ArchiveKind, attrs); err != nil {
 		return nil, err
 	}
+	if p.MSRP, err = s.ListMSRP(ctx, p.ID); err != nil {
+		return nil, err
+	}
 	s.cacheSet(ctx, suffix+gtin, p, productCacheTTL)
 	return p, nil
 }
@@ -301,6 +305,9 @@ func (s *Store) ProductByID(ctx context.Context, id string) (*Product, error) {
 	if p.Specs, err = s.buildSpecs(ctx, p.ArchiveKind, attrs); err != nil {
 		return nil, err
 	}
+	if p.MSRP, err = s.ListMSRP(ctx, p.ID); err != nil {
+		return nil, err
+	}
 	s.cacheSet(ctx, suffix+id, p, productCacheTTL)
 	return p, nil
 }
@@ -445,11 +452,12 @@ type MSRP struct {
 	Note          *string `json:"note"`
 }
 
-// ListMSRP returns all MSRP snapshots for a product.
+// ListMSRP returns a product's suggested-retail-price snapshots, newest first.
+// Zero-amount entries are excluded as they carry no price information.
 func (s *Store) ListMSRP(ctx context.Context, id string) ([]MSRP, error) {
 	rows, err := s.pool.Query(ctx,
 		`SELECT amount, currency, region, effective_date::text, source_url, note
-		 FROM product_msrp WHERE product_id = $1 ORDER BY effective_date DESC NULLS LAST`, id)
+		 FROM product_msrp WHERE product_id = $1 AND amount > 0 ORDER BY effective_date DESC NULLS LAST`, id)
 	if err != nil {
 		return nil, err
 	}

docs/api.md

@@ -112,6 +112,64 @@ curl "https://goods.tangshasha.com/api/v1/products/barcode/5449000000996"
 
 ### `GET /sources/{id}` — 数据来源
 
+## 档案回流（写接口，需 API Key）
+
+> 仅供进销存等机器调用方使用：把档案里**尚未收录**的商品批量回流到站点，进入人工审核队列，审核通过后才会收录。**必须携带 API Key**（与上文同一类 `og_live_` 密钥），不会直接写入商品。
+
+### `POST /api/public/backflow` — 批量回流未收录商品
+
+- 鉴权：请求头携带 `X-API-Key: og_live_xxxxxxxx`（或 `Authorization: Bearer og_live_xxxxxxxx`）。缺失/无效/已吊销返回 `401`。
+- 请求体：商品对象**数组**（与公众投稿同结构），单次最多 `1000` 条。常用字段：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `name` | 是 | 商品名称 |
+| `gtin` | 否 | 条码（GTIN）。强烈建议提供，用于去重 |
+| `brand_name` | 否 | 品牌名 |
+| `category_id` | 否 | 品类编码，如 `food.beverages` |
+| `net_content_value` / `net_content_unit` | 否 | 净含量数值 / 单位 |
+| `country_of_origin` | 否 | 产地 |
+| `ingredients_text` | 否 | 配料表 |
+| `nutriments` | 否 | 营养成分对象 |
+| `msrp` | 否 | 零售价快照数组，元素含 `amount`/`currency`/`region`/`effective_date` |
+| `note` | 否 | 备注 |
+
+> 来源会自动标记为 `source="backflow"`，在后台审核队列中与公众投稿区分，无需调用方提供。
+
+- 去重（按 `gtin` 逐条判断，互不影响）：
+  - 该条码已收录为商品 → `exists`，跳过；
+  - 已存在同条码的待审核回流 → `duplicate`，跳过（避免反复刷队列）；
+  - 否则入队 → `queued`（status=`pending`，等待后台审核）；
+  - 名称为空等 → `invalid`。
+
+```bash
+curl -X POST "https://goods.tangshasha.com/api/public/backflow" \
+  -H "X-API-Key: og_live_xxxxxxxx" \
+  -H "Content-Type: application/json" \
+  -d '[
+    {"name":"某某牛奶 250ml","gtin":"6901234567890","brand_name":"某品牌",
+     "net_content_value":250,"net_content_unit":"ml",
+     "msrp":[{"amount":3.5,"currency":"CNY","region":"CN"}]},
+    {"name":"已收录商品","gtin":"5449000000996"}
+  ]'
+```
+
+```json
+{
+  "total": 2,
+  "queued": 1,
+  "exists": 1,
+  "duplicate": 0,
+  "invalid": 0,
+  "results": [
+    { "gtin": "6901234567890", "name": "某某牛奶 250ml", "status": "queued", "id": "<submission-id>" },
+    { "gtin": "5449000000996", "name": "已收录商品", "status": "exists", "reason": "该条码商品已收录" }
+  ]
+}
+```
+
+审核通过后，系统按提交内容**新建商品**；若审核时该条码已存在商品，则**补全**到已有商品（逻辑与公众投稿一致）。
+
 ## 免责声明
 
 数据可能存在误差或滞后，按「现状」提供，不构成医疗/购买建议。商品资料版权归各原始来源所有，请遵循其许可（如 OpenFoodFacts 的 ODbL），引用时请注明天工商品档案公共仓及原始来源。

public-frontend/src/components/ApiDocs.tsx

@@ -343,6 +343,41 @@ curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛
 }`}
       />
 
+      <Endpoint
+        method="POST"
+        path="/api/public/backflow"
+        title="档案回流（批量回流未收录商品，需 API Key）"
+        desc="供进销存等机器调用方使用：把档案里尚未收录的商品批量推送过来，进入人工审核队列，审核通过后才收录。必须携带 API Key（与上文同一类 og_live_ 密钥），不会直接写入商品。请求体为商品对象数组（与公众投稿同结构），单次最多 1000 条；按条码 GTIN 逐条去重，返回每条结果：queued（入队待审）/ exists（已收录跳过）/ duplicate（已有同条码待审跳过）/ invalid（无效，如名称为空）。"
+        params={[
+          { name: "name", required: true, desc: "商品名称（数组中每个元素）" },
+          { name: "gtin", desc: "条码（GTIN），强烈建议提供，用于去重" },
+          { name: "brand_name", desc: "品牌名" },
+          { name: "category_id", desc: "品类编码，如 food.beverages" },
+          { name: "net_content_value / net_content_unit", desc: "净含量数值 / 单位" },
+          { name: "country_of_origin", desc: "产地" },
+          { name: "msrp", desc: "零售价快照数组，元素含 amount/currency/region/effective_date" },
+          { name: "note", desc: "备注" },
+        ]}
+        example={`curl -X POST ${ORIGIN}/api/public/backflow \\
+  -H "X-API-Key: og_live_xxxxxxxx" \\
+  -H "Content-Type: application/json" \\
+  -d '[
+    {"name":"某某牛奶 250ml","gtin":"6901234567890","brand_name":"某品牌",
+     "net_content_value":250,"net_content_unit":"ml",
+     "msrp":[{"amount":3.5,"currency":"CNY","region":"CN"}]},
+    {"name":"已收录商品","gtin":"5449000000996"}
+  ]'`}
+        response={`{
+  "total": 2, "queued": 1, "exists": 1, "duplicate": 0, "invalid": 0,
+  "results": [
+    { "gtin": "6901234567890", "name": "某某牛奶 250ml",
+      "status": "queued", "id": "<submission-id>" },
+    { "gtin": "5449000000996", "name": "已收录商品",
+      "status": "exists", "reason": "该条码商品已收录" }
+  ]
+}`}
+      />
+
       <Endpoint
         method="POST"
         path="/api/v1/register"

public-frontend/src/components/ProductView.tsx

@@ -42,6 +42,12 @@ export default function ProductView({ id, onBack }: { id: string; onBack: () =>
   const nutriEntries = Object.entries(p.nutriments || {}).filter(
     ([, v]) => v !== null && v !== undefined,
   );
+  const latestMsrp = (p.msrp || [])[0];
+  const msrpText = latestMsrp
+    ? latestMsrp.currency === "CNY"
+      ? `¥${latestMsrp.amount.toFixed(2)}`
+      : `${latestMsrp.amount.toFixed(2)} ${latestMsrp.currency}`
+    : null;
 
   return (
     <div>
@@ -93,6 +99,17 @@ export default function ProductView({ id, onBack }: { id: string; onBack: () =>
             }
           />
           <Row label="产地" value={p.country_of_origin} />
+          <Row
+            label="建议零售价"
+            value={
+              msrpText ? (
+                <span className="inline-flex items-baseline gap-2">
+                  <span className="font-medium text-gray-900">{msrpText}</span>
+                  <span className="text-xs text-gray-400">厂商建议，仅供参考</span>
+                </span>
+              ) : null
+            }
+          />
           <Row label="Nutri-Score" value={p.nutri_score} />
           <Row label="配料" value={p.ingredients_text} />
           <Row

public-frontend/src/types.ts

@@ -24,6 +24,15 @@ export interface ProductSpec {
   unit?: string;
 }
 
+export interface Msrp {
+  amount: number;
+  currency: string;
+  region: string;
+  effective_date?: string | null;
+  source_url?: string | null;
+  note?: string | null;
+}
+
 export interface Product {
   id: string;
   gtin: string | null;
@@ -43,6 +52,7 @@ export interface Product {
   ingredients_text?: string | null;
   allergens?: string[] | null;
   additives?: string[] | null;
+  msrp?: Msrp[] | null;
 }
 
 export interface Category {