Merge pull request 'feat(public): 首页改为极简谷歌风格' (#38) from devin/1782372352-home-mobile-center into main

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

.github/workflows/ci.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
   pull_request:
 
+env:
+  GO_VERSION: "1.23.12"
+  GOPROXY: "https://goproxy.cn,direct"
+
 jobs:
   go:
     name: Go (api)
@@ -25,11 +29,22 @@ jobs:
     env:
       OPENGOODS_DATABASE_URL: postgres://opengoods:opengoods@postgres:5432/opengoods?sslmode=disable
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
-        with:
-          go-version: "1.23"
-          cache-dependency-path: api/go.sum
+      - name: Checkout
+        working-directory: ${{ github.workspace }}
+        run: |
+          git config --global --add safe.directory '*'
+          git init -q .
+          git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
+          git -c protocol.version=2 fetch -q --no-tags --depth 1 origin "${GITHUB_REF}"
+          git checkout -q --force FETCH_HEAD
+      - name: Setup Go
+        working-directory: ${{ github.workspace }}
+        run: |
+          curl -fsSL -o /tmp/go.tgz "https://mirrors.aliyun.com/golang/go${GO_VERSION}.linux-amd64.tar.gz"
+          rm -rf /usr/local/go
+          tar -C /usr/local -xzf /tmp/go.tgz
+          echo "/usr/local/go/bin" >> "$GITHUB_PATH"
+          echo "$HOME/go/bin" >> "$GITHUB_PATH"
       - name: Apply migrations
         working-directory: .
         run: |
@@ -44,14 +59,20 @@ jobs:
   python:
     name: Python (ingestion)
     runs-on: ubuntu-latest
+    container:
+      image: nikolaik/python-nodejs:python3.12-nodejs20
     defaults:
       run:
         working-directory: ingestion
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
+      - name: Checkout
+        working-directory: ${{ github.workspace }}
+        run: |
+          git config --global --add safe.directory '*'
+          git init -q .
+          git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
+          git -c protocol.version=2 fetch -q --no-tags --depth 1 origin "${GITHUB_REF}"
+          git checkout -q --force FETCH_HEAD
       - name: Install
         run: pip install -e ".[dev]"
       - name: Ruff lint
@@ -77,10 +98,21 @@ jobs:
     env:
       DBURL: postgres://opengoods:opengoods@postgres:5432/opengoods?sslmode=disable
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
-        with:
-          go-version: "1.23"
+      - name: Checkout
+        working-directory: ${{ github.workspace }}
+        run: |
+          git config --global --add safe.directory '*'
+          git init -q .
+          git remote add origin "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
+          git -c protocol.version=2 fetch -q --no-tags --depth 1 origin "${GITHUB_REF}"
+          git checkout -q --force FETCH_HEAD
+      - name: Setup Go
+        run: |
+          curl -fsSL -o /tmp/go.tgz "https://mirrors.aliyun.com/golang/go${GO_VERSION}.linux-amd64.tar.gz"
+          rm -rf /usr/local/go
+          tar -C /usr/local -xzf /tmp/go.tgz
+          echo "/usr/local/go/bin" >> "$GITHUB_PATH"
+          echo "$HOME/go/bin" >> "$GITHUB_PATH"
       - name: Install golang-migrate
         run: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
       - name: Migrate up

api/cmd/server/main.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/jackc/pgx/v5/pgxpool"
 
+	"github.com/baicai2026-baicai/goods/api/internal/cache"
 	"github.com/baicai2026-baicai/goods/api/internal/config"
 	"github.com/baicai2026-baicai/goods/api/internal/handler"
 	"github.com/baicai2026-baicai/goods/api/internal/publicweb"
@@ -36,7 +37,12 @@ func main() {
 	if !limiter.Enabled() {
 		log.Print("warning: Redis not configured; public API rate limiting disabled")
 	}
-	h := handler.New(store.New(pool), publicweb.Dist()).
+
+	readCache := cache.New(cfg.RedisURL)
+	if !readCache.Enabled() {
+		log.Print("warning: Redis not configured; public API read cache disabled")
+	}
+	h := handler.New(store.New(pool).WithCache(readCache), publicweb.Dist()).
 		WithRateLimit(limiter, cfg.AnonRateLimitPerMin).
 		WithQuotas(cfg.AnonTotalQuota, cfg.RegisteredRateLimitPerMin, cfg.RegisteredQuotaTotal)
 

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"
@@ -110,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
 }
 
@@ -634,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/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/submission.go

@@ -31,6 +31,7 @@ type SubmissionInput struct {
 	CountryOfOrigin  *string           `json:"country_of_origin"`
 	IngredientsText  *string           `json:"ingredients_text"`
 	Nutriments       map[string]any    `json:"nutriments"`
+	Attributes       map[string]any    `json:"attributes"`
 	NutritionBasis   *string           `json:"nutrition_basis"`
 	ServingSize      *string           `json:"serving_size"`
 	NutriScore       *string           `json:"nutri_score"`
@@ -39,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.
@@ -48,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"`
@@ -128,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))
@@ -145,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)
@@ -278,14 +284,19 @@ func (s *Store) ApproveSubmission(ctx context.Context, id, actor string) (*Produ
 
 	fields := submissionFields(in)
 
+	var attrJSON []byte
+	if len(in.Attributes) > 0 {
+		attrJSON, _ = json.Marshal(in.Attributes)
+	}
+
 	if productID == "" {
 		// Create a new product from the contribution.
 		err = tx.QueryRow(ctx, `
 INSERT INTO product (gtin, name, brand_id, category_id, gpc_brick_code,
-   net_content_value, net_content_unit, net_content_canonical, country_of_origin, status)
-VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,'active') RETURNING id`,
+   net_content_value, net_content_unit, net_content_canonical, country_of_origin, attributes, status)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,COALESCE($10::jsonb,'{}'::jsonb),'active') RETURNING id`,
 			in.GTIN, in.Name, brandID, in.CategoryID, gpc,
-			in.NetContentValue, in.NetContentUnit, canonical, in.CountryOfOrigin).Scan(&productID)
+			in.NetContentValue, in.NetContentUnit, canonical, in.CountryOfOrigin, attrJSON).Scan(&productID)
 		if err != nil {
 			return nil, err
 		}
@@ -302,20 +313,28 @@ UPDATE product SET
    net_content_unit=COALESCE($7, net_content_unit),
    net_content_canonical=COALESCE($8, net_content_canonical),
    country_of_origin=COALESCE($9, country_of_origin),
-   gtin=COALESCE($10, gtin)
+   gtin=COALESCE($10, gtin),
+   attributes=product.attributes || COALESCE($11::jsonb,'{}'::jsonb)
 WHERE id=$1`,
 			productID, in.Name, brandID, in.CategoryID, gpc,
-			in.NetContentValue, in.NetContentUnit, canonical, in.CountryOfOrigin, in.GTIN)
+			in.NetContentValue, in.NetContentUnit, canonical, in.CountryOfOrigin, in.GTIN, attrJSON)
 		if err != nil {
 			return nil, err
 		}
 	}
 
-	// food_detail: upsert, preserving existing values where not provided.
+	// food_detail: upsert only when the contribution carries food data, so a
+	// non-food submission (drug/3C/generic) doesn't create an empty row.
 	var nutriJSON []byte
 	if len(in.Nutriments) > 0 {
 		nutriJSON, _ = json.Marshal(in.Nutriments)
 	}
+	foodPresent := len(in.Nutriments) > 0 ||
+		(in.IngredientsText != nil && *in.IngredientsText != "") ||
+		(in.NutritionBasis != nil && *in.NutritionBasis != "") ||
+		(in.ServingSize != nil && *in.ServingSize != "") ||
+		(in.NutriScore != nil && *in.NutriScore != "")
+	if foodPresent {
 		_, err = tx.Exec(ctx, `
 INSERT INTO food_detail (product_id, ingredients_text, nutriments, nutrition_basis, serving_size, nutri_score)
 VALUES ($1,$2,$3,$4,$5,$6)
@@ -329,6 +348,7 @@ ON CONFLICT (product_id) DO UPDATE SET
 		if err != nil {
 			return nil, err
 		}
+	}
 
 	for _, im := range in.Images {
 		url := strings.TrimSpace(im.URL)
@@ -417,5 +437,14 @@ func submissionFields(in SubmissionInput) []string {
 	add("ingredients", in.IngredientsText != nil && *in.IngredientsText != "")
 	add("nutriments", len(in.Nutriments) > 0)
 	add("image", len(in.Images) > 0)
+	for k, v := range in.Attributes {
+		if v == nil {
+			continue
+		}
+		if s, ok := v.(string); ok && s == "" {
+			continue
+		}
+		fields = append(fields, k)
+	}
 	return fields
 }

api/internal/cache/cache.go

@@ -0,0 +1,126 @@
+// Package cache is a Redis-backed, fail-open read cache for the public API.
+//
+// It caches hot product details and search results so repeated reads avoid
+// PostgreSQL. Like the ratelimit package, every operation fails open: if Redis
+// is unavailable or misconfigured the caller simply falls back to the database,
+// so the cache can never take the API down or serve stale data after Redis loss.
+//
+// Invalidation is global and O(1): keys are namespaced by an epoch counter
+// stored in Redis (og:cache:epoch). The Python ingestion bumps that counter
+// after a write run, which logically invalidates every cached entry at once
+// while old keys age out via their TTL. The epoch is read at most once per
+// refresh interval per process, so it adds no per-request round trip.
+package cache
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// epochKey is the Redis key holding the global cache generation counter.
+const epochKey = "og:cache:epoch"
+
+// epochRefresh bounds how often a process re-reads the epoch from Redis.
+const epochRefresh = 10 * time.Second
+
+// opTimeout caps any single Redis operation so a slow backend never blocks a
+// request beyond this; on timeout the cache fails open.
+const opTimeout = 150 * time.Millisecond
+
+// Cache wraps a Redis client. A nil-backed Cache (Redis unconfigured) disables
+// caching: every Get misses and every Set is a no-op.
+type Cache struct {
+	rdb *redis.Client
+
+	mu         sync.RWMutex
+	epoch      int64
+	epochSetAt time.Time
+	epochOK    bool
+}
+
+// New builds a Cache from a redis:// URL. On a parse error it logs and returns a
+// disabled (fail-open) cache so the server still boots.
+func New(redisURL string) *Cache {
+	opt, err := redis.ParseURL(redisURL)
+	if err != nil {
+		log.Printf("cache: invalid redis url %q: %v (caching disabled)", redisURL, err)
+		return &Cache{}
+	}
+	return &Cache{rdb: redis.NewClient(opt)}
+}
+
+// Enabled reports whether a Redis backend is configured.
+func (c *Cache) Enabled() bool { return c != nil && c.rdb != nil }
+
+// epochNow returns the current cache generation, reading it from Redis at most
+// once per epochRefresh. On any Redis error it keeps the last known value and
+// throttles re-reads so a down backend cannot slow the hot path.
+func (c *Cache) epochNow(ctx context.Context) int64 {
+	c.mu.RLock()
+	if c.epochOK && time.Since(c.epochSetAt) < epochRefresh {
+		e := c.epoch
+		c.mu.RUnlock()
+		return e
+	}
+	c.mu.RUnlock()
+
+	cctx, cancel := context.WithTimeout(ctx, opTimeout)
+	defer cancel()
+	n, err := c.rdb.Get(cctx, epochKey).Int64()
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	switch {
+	case err == nil:
+		c.epoch = n
+	case errors.Is(err, redis.Nil):
+		c.epoch = 0
+	}
+	c.epochSetAt = time.Now()
+	c.epochOK = true
+	return c.epoch
+}
+
+// key namespaces a logical suffix under the current epoch.
+func (c *Cache) key(ctx context.Context, suffix string) string {
+	return "og:v" + strconv.FormatInt(c.epochNow(ctx), 10) + ":" + suffix
+}
+
+// GetJSON unmarshals the cached value for suffix into dest and reports a hit.
+// Any miss, decode error, or Redis error returns false (fail-open).
+func (c *Cache) GetJSON(ctx context.Context, suffix string, dest any) bool {
+	if !c.Enabled() {
+		return false
+	}
+	k := c.key(ctx, suffix)
+	cctx, cancel := context.WithTimeout(ctx, opTimeout)
+	defer cancel()
+	b, err := c.rdb.Get(cctx, k).Bytes()
+	if err != nil {
+		return false
+	}
+	return json.Unmarshal(b, dest) == nil
+}
+
+// SetJSON stores val (JSON-encoded) for suffix with the given TTL. Best effort:
+// marshal or Redis errors are ignored.
+func (c *Cache) SetJSON(ctx context.Context, suffix string, val any, ttl time.Duration) {
+	if !c.Enabled() {
+		return
+	}
+	b, err := json.Marshal(val)
+	if err != nil {
+		return
+	}
+	k := c.key(ctx, suffix)
+	cctx, cancel := context.WithTimeout(ctx, opTimeout)
+	defer cancel()
+	_ = c.rdb.Set(cctx, k, b, ttl).Err()
+}

api/internal/cache/cache_test.go

@@ -0,0 +1,84 @@
+package cache
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+)
+
+// TestDisabledFailsOpen verifies a Cache without a Redis backend never panics,
+// always misses, and silently drops writes.
+func TestDisabledFailsOpen(t *testing.T) {
+	c := New("not-a-valid-url") // parse error => disabled
+	if c.Enabled() {
+		t.Fatal("expected cache to be disabled for invalid url")
+	}
+	c.SetJSON(context.Background(), "k", map[string]int{"a": 1}, time.Minute)
+	var dst map[string]int
+	if c.GetJSON(context.Background(), "k", &dst) {
+		t.Fatalf("disabled cache must always miss, got %+v", dst)
+	}
+}
+
+func testCache(t *testing.T) *Cache {
+	t.Helper()
+	url := os.Getenv("OPENGOODS_REDIS_URL")
+	if url == "" {
+		url = "redis://localhost:6379/0"
+	}
+	c := New(url)
+	if !c.Enabled() {
+		t.Skip("redis not configured")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if err := c.rdb.Ping(ctx).Err(); err != nil {
+		t.Skipf("redis not reachable: %v", err)
+	}
+	return c
+}
+
+// TestRoundTrip stores then reads a value back.
+func TestRoundTrip(t *testing.T) {
+	c := testCache(t)
+	ctx := context.Background()
+	suffix := fmt.Sprintf("test:rt:%d", time.Now().UnixNano())
+
+	c.SetJSON(ctx, suffix, map[string]any{"name": "foo", "n": float64(3)}, time.Minute)
+	got := map[string]any{}
+	if !c.GetJSON(ctx, suffix, &got) {
+		t.Fatal("expected cache hit after set")
+	}
+	if got["name"] != "foo" || got["n"] != float64(3) {
+		t.Fatalf("unexpected payload: %+v", got)
+	}
+}
+
+// TestEpochInvalidation verifies that bumping the epoch counter logically drops
+// every previously cached entry.
+func TestEpochInvalidation(t *testing.T) {
+	c := testCache(t)
+	ctx := context.Background()
+	suffix := fmt.Sprintf("test:epoch:%d", time.Now().UnixNano())
+
+	c.SetJSON(ctx, suffix, map[string]int{"v": 1}, time.Minute)
+	var dst map[string]int
+	if !c.GetJSON(ctx, suffix, &dst) {
+		t.Fatal("expected hit before epoch bump")
+	}
+
+	// Simulate an ingestion write bumping the global epoch.
+	if err := c.rdb.Incr(ctx, epochKey).Err(); err != nil {
+		t.Fatalf("incr epoch: %v", err)
+	}
+	// Force the process to re-read the epoch rather than use its cached value.
+	c.mu.Lock()
+	c.epochOK = false
+	c.mu.Unlock()
+
+	if c.GetJSON(ctx, suffix, &dst) {
+		t.Fatal("entry should be invisible after epoch bump")
+	}
+}

api/internal/handler/handler.go

@@ -127,6 +127,7 @@ func (h *Handler) Router() http.Handler {
 			})
 			r.Get("/brands", h.ListBrands)
 			r.Get("/categories", h.ListCategories)
+			r.Get("/kind-fields", h.ListKindFields)
 			r.Get("/sources/{id}", h.SourceByID)
 			r.Get("/stats", h.Stats)
 		})
@@ -275,6 +276,21 @@ func (h *Handler) ListCategories(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// ListKindFields returns the read-only spec field template for an archive kind,
+// used by the contribution form to render kind-specific inputs.
+func (h *Handler) ListKindFields(w http.ResponseWriter, r *http.Request) {
+	kind := strings.TrimSpace(r.URL.Query().Get("kind"))
+	if kind == "" {
+		writeError(w, r, http.StatusBadRequest, "bad_request", "missing kind")
+		return
+	}
+	items, err := h.store.ListKindFields(r.Context(), kind)
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items, "kind": kind})
+}
+
 // 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"))

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

@@ -4,21 +4,35 @@ package store
 
 import (
 	"context"
+	"crypto/sha1"
+	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/baicai2026-baicai/goods/api/internal/cache"
+)
+
+// Cache TTLs for the public read cache. Product details are far less volatile
+// than search result sets, so they live longer; both are also invalidated
+// wholesale whenever ingestion bumps the cache epoch.
+const (
+	productCacheTTL = 24 * time.Hour
+	searchCacheTTL  = time.Hour
 )
 
 // ErrNotFound is returned when a requested row does not exist.
 var ErrNotFound = errors.New("not found")
 
-// Store wraps a PostgreSQL connection pool.
+// Store wraps a PostgreSQL connection pool and an optional read cache.
 type Store struct {
 	pool  *pgxpool.Pool
+	cache *cache.Cache
 }
 
 // New constructs a Store from an existing pgx pool.
@@ -26,6 +40,30 @@ func New(pool *pgxpool.Pool) *Store {
 	return &Store{pool: pool}
 }
 
+// WithCache attaches a Redis-backed read cache. A nil or disabled cache leaves
+// the Store reading straight from PostgreSQL.
+func (s *Store) WithCache(c *cache.Cache) *Store {
+	s.cache = c
+	return s
+}
+
+// cacheGet reads a cached JSON value into dest, reporting a hit. It is a no-op
+// miss when no cache is attached.
+func (s *Store) cacheGet(ctx context.Context, suffix string, dest any) bool {
+	if s.cache == nil {
+		return false
+	}
+	return s.cache.GetJSON(ctx, suffix, dest)
+}
+
+// cacheSet stores a JSON value when a cache is attached.
+func (s *Store) cacheSet(ctx context.Context, suffix string, val any, ttl time.Duration) {
+	if s.cache == nil {
+		return
+	}
+	s.cache.SetJSON(ctx, suffix, val, ttl)
+}
+
 // Ping verifies database connectivity.
 func (s *Store) Ping(ctx context.Context) error {
 	return s.pool.Ping(ctx)
@@ -88,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.
@@ -222,6 +261,10 @@ func stringifyAttr(v any) string {
 
 // ProductByGTIN looks up an active product by any of its barcodes.
 func (s *Store) ProductByGTIN(ctx context.Context, gtin string) (*Product, error) {
+	const suffix = "prod:gtin:"
+	if cached := new(Product); s.cacheGet(ctx, suffix+gtin, cached) {
+		return cached, nil
+	}
 	row := s.pool.QueryRow(ctx, productSelect+`
  WHERE p.status = 'active'
    AND (p.gtin = $1 OR EXISTS (
@@ -238,11 +281,19 @@ 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
 }
 
 // ProductByID looks up a product by its UUID.
 func (s *Store) ProductByID(ctx context.Context, id string) (*Product, error) {
+	const suffix = "prod:id:"
+	if cached := new(Product); s.cacheGet(ctx, suffix+id, cached) {
+		return cached, nil
+	}
 	row := s.pool.QueryRow(ctx, productSelect+" WHERE p.id = $1", id)
 	p, attrs, err := scanProduct(row)
 	if err != nil {
@@ -254,6 +305,10 @@ 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
 }
 
@@ -268,6 +323,11 @@ const fuzzyThreshold = "0.42"
 // similarity blended with quality_score so the best, most-complete records
 // surface first. Without a query, results are ordered by quality_score.
 func (s *Store) SearchProducts(ctx context.Context, f SearchFilters, limit, offset int) ([]ProductSummary, int, error) {
+	suffix := searchCacheSuffix(f, limit, offset)
+	if entry := new(searchCacheEntry); s.cacheGet(ctx, suffix, entry) {
+		return entry.Items, entry.Total, nil
+	}
+
 	args := []any{}
 	where := "WHERE p.status = 'active'"
 
@@ -334,7 +394,28 @@ LEFT JOIN category c ON c.id = p.category_id `
 		}
 		out = append(out, ps)
 	}
-	return out, total, rows.Err()
+	if err := rows.Err(); err != nil {
+		return nil, 0, err
+	}
+	s.cacheSet(ctx, suffix, searchCacheEntry{Items: out, Total: total}, searchCacheTTL)
+	return out, total, nil
+}
+
+// searchCacheEntry is the cached payload for a SearchProducts call.
+type searchCacheEntry struct {
+	Items []ProductSummary `json:"items"`
+	Total int              `json:"total"`
+}
+
+// searchCacheSuffix derives a stable cache key from the full filter set and
+// paging window so distinct queries never collide.
+func searchCacheSuffix(f SearchFilters, limit, offset int) string {
+	raw := strings.Join([]string{
+		f.Query, f.Category, f.Brand, f.Country,
+		strconv.Itoa(limit), strconv.Itoa(offset),
+	}, "\x1f")
+	sum := sha1.Sum([]byte(raw))
+	return "search:" + hex.EncodeToString(sum[:])
 }
 
 // Nutriments returns just the nutrition payload for a product.
@@ -371,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
 	}
@@ -427,12 +509,13 @@ type Category struct {
 	Path         string  `json:"path"`
 	GPCBrickCode *string `json:"gpc_brick_code"`
 	Level        int     `json:"level"`
+	ArchiveKind  string  `json:"archive_kind"`
 }
 
 // ListCategories returns the full category tree ordered by path.
 func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
 	rows, err := s.pool.Query(ctx,
-		"SELECT id, name_zh, name_en, path::text, gpc_brick_code, level FROM category ORDER BY path")
+		"SELECT id, name_zh, name_en, path::text, gpc_brick_code, level, COALESCE(archive_kind, 'generic') FROM category ORDER BY path")
 	if err != nil {
 		return nil, err
 	}
@@ -440,7 +523,7 @@ func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
 	out := []Category{}
 	for rows.Next() {
 		var c Category
-		if err := rows.Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.GPCBrickCode, &c.Level); err != nil {
+		if err := rows.Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.GPCBrickCode, &c.Level, &c.ArchiveKind); err != nil {
 			return nil, err
 		}
 		out = append(out, c)
@@ -448,6 +531,45 @@ func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
 	return out, rows.Err()
 }
 
+// KindField describes one editable spec field for an archive kind. It drives
+// the dynamic contribution form (public, read-only view of the template).
+type KindField struct {
+	Kind        string   `json:"kind"`
+	FieldKey    string   `json:"field_key"`
+	GroupLabel  string   `json:"group_label"`
+	LabelZH     string   `json:"label_zh"`
+	FieldType   string   `json:"field_type"`
+	Unit        *string  `json:"unit"`
+	Options     []string `json:"options"`
+	Placeholder *string  `json:"placeholder"`
+	SortOrder   int      `json:"sort_order"`
+	Qualified   bool     `json:"qualified"`
+}
+
+// ListKindFields returns the ordered field template for one archive kind so the
+// public contribution form can render kind-specific inputs.
+func (s *Store) ListKindFields(ctx context.Context, kind string) ([]KindField, error) {
+	rows, err := s.pool.Query(ctx, `
+SELECT kind, field_key, group_label, label_zh, field_type, unit, options,
+       placeholder, sort_order, qualified
+FROM kind_field WHERE kind = $1 ORDER BY sort_order, field_key`, kind)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []KindField{}
+	for rows.Next() {
+		var f KindField
+		if err := rows.Scan(&f.Kind, &f.FieldKey, &f.GroupLabel, &f.LabelZH,
+			&f.FieldType, &f.Unit, &f.Options, &f.Placeholder, &f.SortOrder,
+			&f.Qualified); err != nil {
+			return nil, err
+		}
+		out = append(out, f)
+	}
+	return out, rows.Err()
+}
+
 // APIKey is the minimal metadata the public API needs to authorize a caller.
 type APIKey struct {
 	ID              string

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），引用时请注明天工商品档案公共仓及原始来源。

docs/scalability.md

@@ -0,0 +1,112 @@
+# 可扩展性设计与路线图 (Scalability Roadmap)
+
+本文档回答一个长期问题:随着商品越来越多、品类越来越杂(食品 / 电子 3C / 药品 /
+……),**检索与新增会不会压垮数据库?要不要按品类「分表」?**
+
+> 结论先行:**现阶段不要按品类手动分表。** 现有「单表 + JSONB + archive_kind 框架」
+> 的设计方向是对的。扩展应当靠 **分区(非分表) + 读副本 + 缓存 + 专用搜索引擎**,
+> 按数据量分阶段推进,避免提前过度设计。
+
+---
+
+## 1. 现状盘点
+
+### 1.1 数据模型
+- 所有商品落在**一张 `product` 表**;非食品的领域字段存 `product.attributes`(JSONB)。
+- 食品有独立明细表 `food_detail`(配料 / 营养 / 过敏原等结构化字段)。
+- `0010_archive_kinds` 引入 **archive_kind 框架**:每个品类带一个 `archive_kind`
+  (`food` / `electronics` / `generic`),`kind_field` 表按 kind 定义字段模板,
+  驱动后台动态表单与合格度评分。
+- **加新品类(如药品)不需要新建表**:只要新增一组 `kind_field` 行 + 一棵品类子树;
+  仅当某品类有大量需被独立筛选/排序的结构化字段时,才考虑像 `food_detail` 那样补一张
+  明细表。
+
+### 1.2 已有索引(检索性能的基础)
+| 对象 | 索引 | 用途 |
+|------|------|------|
+| `product.gtin` | 唯一索引 | 条码精确查 |
+| `product.name` | trigram GIN (`pg_trgm`) | 名称模糊/相似匹配 |
+| `product.search_tsv` | 全文 GIN (`tsvector`) | 全文检索 |
+| `product.attributes` | JSONB GIN | 属性过滤 |
+| `brand.name` | trigram GIN | 品牌模糊匹配 |
+| `product.country_of_origin` | btree | 产地精确/前缀过滤 |
+| category / brand / updated_at | btree | 关联与增量 |
+
+### 1.3 检索方式
+- 有关键词时:`name ILIKE` ∪ `word_similarity ≥ 阈值(~0.42)` ∪ 条码匹配,
+  排序按 `相似度 × (0.5 + quality_score)`。
+- 无关键词时:按 `quality_score` 排序。
+- 翻页:`LIMIT / OFFSET`。
+
+### 1.4 写入特征
+- 写库**只有** Python ingestion 一条路径(批量 ETL),不是高并发 OLTP。
+- 插入瓶颈极低;`search_tsv` 由触发器逐行重算,正常增量下开销可忽略。
+
+---
+
+## 2. 为什么不建议按品类「分表」
+
+1. **核心场景是全局检索**:用户通常不知道商品属于哪个品类,搜索要跨所有品类。
+   按品类拆成多表后,一次搜索得 `UNION ALL` 所有表,**更慢、代码更复杂、排序更难统一**。
+2. **单表足够能打**:Postgres 单表配好索引,**几千万行**量级的检索完全可承载。
+   "表大"很少是真正瓶颈,"搜索方式"和"读并发"才是。
+3. **分表会侵蚀框架优势**:archive_kind 框架的价值就是"加品类零建表";手动分表等于
+   把这套通用能力又拆碎。
+
+> 区分两个概念:**分表(sharding,应用层拆多张表)** ≠ **分区(Postgres 原生
+> declarative partitioning,对上层透明的一张逻辑表)**。后者在超大规模时才有意义,
+> 见第 3 阶段。
+
+---
+
+## 3. 分阶段路线图(按数据量触发,不提前做)
+
+### 阶段 0 — 现在 ~ 数百万条:维持现状 + 低成本优化
+触发:当前规模。改动小、收益稳,建议尽早做:
+- **深翻页改 keyset 分页**:`OFFSET` 越翻越慢(需扫描并丢弃前 N 行);改用
+  `WHERE (score, id) < (:last_score, :last_id)` 形式的游标分页。
+- **部分索引**:绝大多数查询限定 `status='active'`,可建
+  `CREATE INDEX ... WHERE status='active'` 缩小索引、提速。
+- **常用筛选复合索引**:如 `(category_id, quality_score DESC)`、
+  `(archive_kind, quality_score DESC)` 配合域内列表。
+- **Redis 缓存**(已在技术栈内):缓存热门搜索结果与商品详情,挡住重复读。
+
+### 阶段 1 — 千万级以上:读扩展 + 调优
+触发:单库读 QPS 升高、P99 变慢。
+- **只读副本(read replica)**:本服务是**只读公益 API**,天然适合一主多从,
+  把检索/详情读流量分到副本,主库只承接 ingestion 写入。
+- **索引与查询调优**:按慢查询日志补/删索引,`EXPLAIN ANALYZE` 校核计划。
+- **(可选)Postgres 原生分区**:若多数检索"限定单一域"(只搜药品 / 只搜食品),
+  可按 `archive_kind` 做 **LIST 分区**(对上层透明,仍是一张逻辑表)。主要利好
+  **维护**(分区级 vacuum / 归档)与**域内查询裁剪**;对真正的全局搜索帮助有限。
+
+### 阶段 2 — 搜索相关性/规模成为痛点:引入专用搜索引擎
+触发:`pg_trgm`/`tsvector` 在相关性排序、跨字段检索、规模上吃力。
+- 把**检索**迁到专用倒排引擎:**OpenSearch / Meilisearch / Typesense**,
+  或 Postgres 内的 **ParadeDB(`pg_search`,BM25)**。
+- **Postgres 仍是唯一事实来源**;搜索引擎只做索引,由 ingestion 在写库后同步。
+- 这才是"搜索量大"的正解,**比分表有效得多**。
+
+---
+
+## 4. 大批量导入的建议
+- 海量初始化/回填用 `COPY` 而非逐行 `INSERT`。
+- 超大批量时可"先停建二级索引 → COPY → 重建索引",比边插边维护索引快得多。
+- ETL 控制并发与批大小,避免与在线读争抢。
+
+---
+
+## 5. 药品档案怎么落地(回到最初的问题)
+在上述设计下,加"药品"属于**阶段 0 的常规扩展**,不触动架构:
+1. 新增 `drug` 的 `kind_field` 模板(批准文号 / 通用名 / 商品名 / 剂型 / 规格 /
+   生产企业 / OTC 分类 / 适应症 / 用法用量 / 不良反应 / 禁忌 / 注意事项 / 贮藏 /
+   有效期 等),`qualified` 标记关键字段参与合格度评分。
+2. 加一棵药品品类子树,并把这些品类的 `archive_kind` 置为 `drug`。
+3. 仅当药品需要**被独立筛选/排序的强结构化字段**(如按批准文号精确查、按 OTC 分类
+   过滤)时,才考虑补一张 `drug_detail` 明细表;否则继续走 `attributes` JSONB。
+
+---
+
+## 6. 版本
+- 本路线图随规模演进更新;任何落地改动需同步:迁移(SQL) + 本文档 +(涉及对外字段时)
+  `docs/data-contract.md` / `docs/openapi.yaml`。

ingestion/opengoods/cache.py

@@ -0,0 +1,52 @@
+"""Read-cache invalidation signal for the public API.
+
+The Go API caches hot product details and search results in Redis, namespacing
+every key by a global generation counter (``og:cache:epoch``). Bumping that
+counter logically invalidates the entire cache in one O(1) operation while the
+old keys age out via their TTL.
+
+Ingestion is the only writer to the database, so after a run that changed data
+it calls :func:`bump_cache_epoch` to make those changes visible immediately
+instead of waiting for per-key TTLs to expire.
+
+Like the API's cache, this is strictly best effort and fails open: if Redis is
+unconfigured or unreachable the ingestion run still succeeds, and stale entries
+simply expire on their own.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+EPOCH_KEY = "og:cache:epoch"
+
+
+def default_redis_url() -> str | None:
+    """Return the configured Redis URL, or ``None`` when caching is disabled."""
+    return os.environ.get("OPENGOODS_REDIS_URL") or None
+
+
+def bump_cache_epoch(url: str | None = None) -> bool:
+    """Increment the API cache generation counter.
+
+    Returns ``True`` if the counter was bumped, ``False`` if caching is disabled
+    or Redis was unreachable. Never raises: invalidation failures must not fail
+    an ingestion run.
+    """
+    url = url or default_redis_url()
+    if not url:
+        return False
+    try:
+        import redis  # imported lazily so the dependency is optional at runtime
+
+        client = redis.Redis.from_url(url, socket_timeout=2, socket_connect_timeout=2)
+        new_epoch = client.incr(EPOCH_KEY)
+        client.close()
+        logger.info("bumped API cache epoch to %s", new_epoch)
+        return True
+    except Exception as exc:  # noqa: BLE001 - invalidation is best effort
+        logger.warning("cache epoch bump skipped: %s", exc)
+        return False

ingestion/opengoods/jobs/dedup.py

@@ -12,6 +12,7 @@ import sys
 
 import psycopg
 
+from opengoods.cache import bump_cache_epoch
 from opengoods.etl.dedup import dedup_all
 from opengoods.etl.load import default_dsn
 
@@ -23,6 +24,8 @@ def run(args: argparse.Namespace) -> int:
             conn.rollback()
         else:
             conn.commit()
+    if not args.dry_run and summary["merged"]:
+        bump_cache_epoch()
     mode = "dry-run" if args.dry_run else "applied"
     print(f"{mode} groups={summary['groups']} merged={summary['merged']}")
     return 0

ingestion/opengoods/jobs/import_bypos.py

@@ -25,6 +25,7 @@ from collections.abc import Iterator
 import psycopg
 
 from opengoods.adapters.bypos import transform_bypos
+from opengoods.cache import bump_cache_epoch
 from opengoods.etl.load import default_dsn, ensure_bypos_source, load_bypos_record_safe
 
 
@@ -59,6 +60,8 @@ def run(args: argparse.Namespace) -> int:
             else:
                 errored += 1
         conn.commit()
+    if loaded:
+        bump_cache_epoch()
     print(f"loaded={loaded} skipped={skipped} errored={errored}")
     return 0
 

ingestion/opengoods/jobs/seed_off.py

@@ -28,6 +28,7 @@ from opengoods.adapters.openfoodfacts import (
     is_cn_gs1,
     read_dump,
 )
+from opengoods.cache import bump_cache_epoch
 from opengoods.etl.load import default_dsn, ensure_source, load_record_safe
 from opengoods.etl.transform import transform
 
@@ -67,6 +68,8 @@ def run(args: argparse.Namespace) -> int:
             else:
                 errored += 1
         conn.commit()
+    if loaded:
+        bump_cache_epoch()
     print(f"loaded={loaded} skipped={skipped} errored={errored}")
     return 0
 

ingestion/opengoods/jobs/update_off.py

@@ -17,6 +17,7 @@ import sys
 import psycopg
 
 from opengoods.adapters.openfoodfacts import SOURCE_NAME, OpenFoodFactsAdapter
+from opengoods.cache import bump_cache_epoch
 from opengoods.etl.load import default_dsn, ensure_source, load_record_safe
 from opengoods.etl.state import get_watermark, set_watermark
 from opengoods.etl.transform import transform
@@ -49,6 +50,8 @@ def run(args: argparse.Namespace) -> int:
             stats={"loaded": loaded, "skipped": skipped, "errored": errored, "since": since},
         )
         conn.commit()
+    if loaded:
+        bump_cache_epoch()
     print(
         f"since={since} loaded={loaded} skipped={skipped} "
         f"errored={errored} watermark={high_watermark}"

ingestion/pyproject.toml

@@ -6,6 +6,7 @@ requires-python = ">=3.11"
 dependencies = [
     "httpx>=0.27",
     "psycopg[binary]>=3.2",
+    "redis>=5.0,<6",
 ]
 
 [project.optional-dependencies]

ingestion/tests/test_cache.py

@@ -0,0 +1,44 @@
+"""Tests for the best-effort API cache invalidation signal."""
+
+from __future__ import annotations
+
+import sys
+
+import opengoods.cache as cache
+
+
+def test_disabled_when_no_url(monkeypatch):
+    monkeypatch.delenv("OPENGOODS_REDIS_URL", raising=False)
+    assert cache.default_redis_url() is None
+    assert cache.bump_cache_epoch() is False
+
+
+def test_bump_fails_open_when_unreachable(monkeypatch):
+    # An unroutable URL must not raise; the run still succeeds.
+    monkeypatch.setenv("OPENGOODS_REDIS_URL", "redis://127.0.0.1:1/0")
+    assert cache.bump_cache_epoch() is False
+
+
+def test_bump_increments_epoch(monkeypatch):
+    calls = {}
+
+    class FakeClient:
+        def incr(self, key):
+            calls["key"] = key
+            return 7
+
+        def close(self):
+            calls["closed"] = True
+
+    class FakeRedis:
+        @staticmethod
+        def from_url(url, **kwargs):
+            calls["url"] = url
+            return FakeClient()
+
+    monkeypatch.setitem(sys.modules, "redis", type("M", (), {"Redis": FakeRedis}))
+
+    assert cache.bump_cache_epoch("redis://example:6379/0") is True
+    assert calls["key"] == "og:cache:epoch"
+    assert calls["url"] == "redis://example:6379/0"
+    assert calls["closed"] is True

migrations/0012_search_indexes.down.sql

@@ -0,0 +1,2 @@
+DROP INDEX IF EXISTS idx_product_active_category;
+DROP INDEX IF EXISTS idx_product_active_quality;

migrations/0012_search_indexes.up.sql

@@ -0,0 +1,15 @@
+-- 检索优化(可扩展性路线图 阶段0):为最常见的"浏览"路径补部分/复合索引。
+-- 搜索查询恒带 WHERE status = 'active';无关键词时按 quality_score DESC, name 排序。
+-- 现有索引无法同时满足"过滤 active + 按 quality_score/name 排序",深翻页时需要对全部
+-- active 行排序。下面的部分复合索引让规划器直接走索引顺序扫描,省掉排序、加速深翻页与
+-- count(*)。索引只覆盖 active 行,体积更小。
+
+-- 默认浏览(无关键词、无品类):ORDER BY quality_score DESC, name
+CREATE INDEX IF NOT EXISTS idx_product_active_quality
+    ON product (quality_score DESC, name)
+    WHERE status = 'active';
+
+-- 品类内浏览:先按 category_id 收敛,再按 quality_score 排序
+CREATE INDEX IF NOT EXISTS idx_product_active_category
+    ON product (category_id, quality_score DESC)
+    WHERE status = 'active';

migrations/0013_drug_archive_kind.down.sql

@@ -0,0 +1,8 @@
+-- Reverse 0013: detach products from the seeded drug categories, drop the drug
+-- category subtree, and remove the drug field template.
+UPDATE product SET category_id = NULL
+WHERE category_id IN (SELECT id FROM category WHERE path <@ 'drug');
+
+DELETE FROM category WHERE path <@ 'drug';
+
+DELETE FROM kind_field WHERE kind = 'drug';

migrations/0013_drug_archive_kind.up.sql

@@ -0,0 +1,43 @@
+-- Drug (药品) archive kind: a new domain on the generic archive_kind framework
+-- (see 0010). No new table — drug spec values live in product.attributes JSONB,
+-- driven by the kind_field template below, plus a 'drug' category subtree.
+
+-- Field template for the drug domain. field_type is constrained to
+-- text/number/textarea/select/list by kind_field_type_chk. The `qualified`
+-- fields are the identifying / regulatory essentials that count toward the
+-- kind-aware completeness score.
+INSERT INTO kind_field (kind, field_key, group_label, label_zh, field_type, unit, options, sort_order, qualified) VALUES
+('drug','approval_number',    '基础信息','批准文号',        'text',     NULL, '{}',                                  10, true),
+('drug','generic_name',       '基础信息','通用名',          'text',     NULL, '{}',                                  20, true),
+('drug','trade_name',         '基础信息','商品名',          'text',     NULL, '{}',                                  30, false),
+('drug','dosage_form',        '基础信息','剂型',            'select',   NULL, '{片剂,胶囊剂,颗粒剂,散剂,丸剂,注射剂,口服液,糖浆剂,软膏剂,乳膏剂,凝胶剂,滴剂,喷雾剂,气雾剂,栓剂,贴剂,其他}', 40, true),
+('drug','specification',      '基础信息','规格',            'text',     NULL, '{}',                                  50, true),
+('drug','pack_spec',          '基础信息','包装规格',        'text',     NULL, '{}',                                  60, false),
+('drug','rx_class',           '分类与企业','处方分类',      'select',   NULL, '{处方药,甲类OTC,乙类OTC}',            70, true),
+('drug','manufacturer',       '分类与企业','生产企业',      'text',     NULL, '{}',                                  80, true),
+('drug','mah',                '分类与企业','上市许可持有人','text',     NULL, '{}',                                  90, false),
+('drug','indications',        '说明书','适应症/功能主治',   'textarea', NULL, '{}',                                 100, true),
+('drug','dosage_usage',       '说明书','用法用量',          'textarea', NULL, '{}',                                 110, false),
+('drug','adverse_reactions',  '说明书','不良反应',          'textarea', NULL, '{}',                                 120, false),
+('drug','contraindications',  '说明书','禁忌',              'textarea', NULL, '{}',                                 130, false),
+('drug','precautions',        '说明书','注意事项',          'textarea', NULL, '{}',                                 140, false),
+('drug','interactions',       '说明书','药物相互作用',      'textarea', NULL, '{}',                                 150, false),
+('drug','storage',            '贮藏与有效期','贮藏',        'text',     NULL, '{}',                                 160, false),
+('drug','shelf_life',         '贮藏与有效期','有效期',      'text',     NULL, '{}',                                 170, false),
+('drug','spec_source',        '贮藏与有效期','说明书来源',  'text',     NULL, '{}',                                 180, false);
+
+-- Drug category tree. ltree labels are English slugs (no spaces/Chinese);
+-- Chinese names live in category.name_zh.
+INSERT INTO category (name_zh, name_en, parent_id, path, level, archive_kind)
+VALUES ('药品', 'Drug', NULL, 'drug', 0, 'drug');
+
+INSERT INTO category (name_zh, name_en, parent_id, path, level, archive_kind)
+SELECT v.name_zh, v.name_en, c.id, v.path::ltree, 1, 'drug'
+FROM (VALUES
+    ('化学药品',   'Chemical drug',            'drug.chemical'),
+    ('中成药',     'Chinese patent medicine',  'drug.tcm_patent'),
+    ('中药饮片',   'Chinese herbal pieces',    'drug.tcm_herb'),
+    ('生物制品',   'Biological product',       'drug.biological'),
+    ('疫苗',       'Vaccine',                  'drug.vaccine')
+) AS v(name_zh, name_en, path)
+JOIN category c ON c.path = 'drug';

public-frontend/index.html

@@ -3,7 +3,18 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>天工商品档案公共仓</title>
+    <meta name="theme-color" content="#059669" />
+    <meta
+      name="description"
+      content="天工商品档案公共仓——公益、开放、可溯源的商品事实查询与开放 API。"
+    />
+    <title>天工 · 商品档案公共仓</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap"
+      rel="stylesheet"
+    />
   </head>
   <body>
     <div id="root"></div>

public-frontend/public/e8b7a2a873a89b19a584a4f12a5bdd6b.txt

@@ -0,0 +1 @@
+9ef4c7d0ea804c11bc637f4e82198e98af908894

public-frontend/src/App.tsx

@@ -1,10 +1,11 @@
 import { useEffect, useState } from "react";
-import { Boxes, Search, PlusCircle, Code2, KeyRound } from "lucide-react";
+import { Boxes, Search, PlusCircle, Code2, KeyRound, Headset } from "lucide-react";
 import Home from "./components/Home";
 import ProductView from "./components/ProductView";
 import Contribute from "./components/Contribute";
 import ApiDocs from "./components/ApiDocs";
 import Account from "./components/Account";
+import Contact from "./components/Contact";
 import { api } from "./api";
 
 type View =
@@ -12,7 +13,16 @@ type View =
   | { name: "product"; id: string }
   | { name: "contribute" }
   | { name: "api" }
-  | { name: "account" };
+  | { name: "account" }
+  | { name: "contact" };
+
+const NAV: { key: View["name"]; label: string; icon: typeof Search }[] = [
+  { key: "home", label: "检索", icon: Search },
+  { key: "contribute", label: "贡献档案", icon: PlusCircle },
+  { key: "api", label: "API", icon: Code2 },
+  { key: "account", label: "API 密钥", icon: KeyRound },
+  { key: "contact", label: "联系我们", icon: Headset },
+];
 
 export default function App() {
   const [view, setView] = useState<View>({ name: "home" });
@@ -27,58 +37,50 @@ export default function App() {
 
   return (
     <div className="min-h-full flex flex-col">
-      <header className="bg-white border-b">
-        <div className="max-w-5xl mx-auto px-4 h-14 flex items-center justify-between">
+      <header className="sticky top-0 z-30 border-b border-gray-200/70 bg-white/80 backdrop-blur-md">
+        <div className="max-w-5xl mx-auto px-4 h-16 flex items-center justify-between gap-4">
           <button
-            className="flex items-center gap-2 font-semibold text-gray-800"
+            className="flex items-center gap-2.5 font-semibold text-gray-800 group"
             onClick={() => setView({ name: "home" })}
           >
-            <Boxes className="w-6 h-6 text-emerald-600" />
-            天工<span className="text-gray-400 font-normal text-sm">商品档案公共仓</span>
+            <span className="grid h-9 w-9 place-items-center rounded-xl bg-gradient-to-br from-brand-500 to-brand-700 text-white shadow-glow transition group-hover:scale-105">
+              <Boxes className="w-5 h-5" />
+            </span>
+            <span className="flex items-baseline gap-1.5">
+              <span className="text-lg tracking-tight">天工</span>
+              <span className="hidden sm:inline text-gray-400 font-normal text-xs">
+                商品档案公共仓
+              </span>
+            </span>
           </button>
-          <nav className="flex items-center gap-1 text-sm">
+          <nav className="flex items-center gap-0.5 text-sm">
+            {NAV.map(({ key, label, icon: Icon }) => {
+              const active =
+                view.name === key || (key === "home" && view.name === "product");
+              return (
                 <button
-              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
-                view.name === "home" ? "bg-emerald-50 text-emerald-700" : "text-gray-600 hover:bg-gray-100"
+                  key={key}
+                  className={`px-3 py-1.5 rounded-lg flex items-center gap-1.5 font-medium transition ${
+                    active
+                      ? "bg-brand-50 text-brand-700"
+                      : "text-gray-600 hover:bg-gray-100"
                   }`}
-              onClick={() => setView({ name: "home" })}
+                  onClick={() => setView({ name: key } as View)}
                 >
-              <Search className="w-4 h-4" /> 检索
-            </button>
-            <button
-              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
-                view.name === "contribute" ? "bg-emerald-50 text-emerald-700" : "text-gray-600 hover:bg-gray-100"
-              }`}
-              onClick={() => setView({ name: "contribute" })}
-            >
-              <PlusCircle className="w-4 h-4" /> 贡献档案
-            </button>
-            <button
-              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
-                view.name === "api" ? "bg-emerald-50 text-emerald-700" : "text-gray-600 hover:bg-gray-100"
-              }`}
-              onClick={() => setView({ name: "api" })}
-            >
-              <Code2 className="w-4 h-4" /> API
-            </button>
-            <button
-              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
-                view.name === "account" ? "bg-emerald-50 text-emerald-700" : "text-gray-600 hover:bg-gray-100"
-              }`}
-              onClick={() => setView({ name: "account" })}
-            >
-              <KeyRound className="w-4 h-4" /> API 密钥
+                  <Icon className="w-4 h-4" />
+                  <span className="hidden sm:inline">{label}</span>
                 </button>
+              );
+            })}
           </nav>
         </div>
       </header>
 
-      <main className="flex-1 max-w-5xl w-full mx-auto px-4 py-6">
+      <main className="flex-1 max-w-5xl w-full mx-auto px-4 py-8">
         {view.name === "home" && (
           <Home
             onOpen={(id) => setView({ name: "product", id })}
             onContribute={() => setView({ name: "contribute" })}
-            onApi={() => setView({ name: "api" })}
           />
         )}
         {view.name === "product" && (
@@ -89,24 +91,36 @@ export default function App() {
         )}
         {view.name === "api" && <ApiDocs onRegister={() => setView({ name: "account" })} />}
         {view.name === "account" && <Account />}
+        {view.name === "contact" && <Contact />}
       </main>
 
-      <footer className="border-t bg-white">
-        <div className="max-w-5xl mx-auto px-4 py-4 text-xs text-gray-400 leading-relaxed text-center">
+      <footer className="border-t border-gray-200/70 bg-white/60">
+        <div className="max-w-5xl mx-auto px-4 py-6 text-xs text-gray-400 leading-relaxed text-center">
           {qualified != null && (
-            <div className="mb-2 text-gray-500">
-              目前已收录
-              <span className="mx-1 font-semibold text-emerald-600">
+            <div className="mb-3 inline-flex items-center gap-1.5 rounded-full border border-brand-100 bg-brand-50 px-3 py-1 text-gray-500">
+              已收录
+              <span className="font-semibold text-brand-600">
                 {qualified.toLocaleString()}
               </span>
               条合格商品档案
             </div>
           )}
-          天工是一个公益性商品档案库。主要收录商品名称，条码，品类，配料等官方快照。不涉及任何交易行为。
-          <button onClick={() => setView({ name: "api" })} className="ml-1 text-emerald-600 hover:underline">
+          <p className="max-w-2xl mx-auto">
+            天工是一个公益性商品档案库，主要收录商品名称、条码、品类、配料等官方快照，不涉及任何交易行为。
+            <button
+              onClick={() => setView({ name: "api" })}
+              className="ml-1 text-brand-600 font-medium hover:underline"
+            >
               API 调用说明
             </button>
-          <div className="mt-2">
+            <button
+              onClick={() => setView({ name: "contact" })}
+              className="ml-1 text-brand-600 font-medium hover:underline"
+            >
+              联系我们
+            </button>
+          </p>
+          <div className="mt-3">
             <a
               href="https://beian.miit.gov.cn/"
               target="_blank"

public-frontend/src/api.ts

@@ -1,4 +1,4 @@
-import type { Category, Product, ProductSummary, SubmissionInput } from "./types";
+import type { Category, KindField, Product, ProductSummary, SubmissionInput } from "./types";
 
 async function req<T>(path: string, init?: RequestInit): Promise<T> {
   const res = await fetch(path, {
@@ -67,6 +67,10 @@ export const api = {
   },
   product: (id: string) => req<Product>(`/api/v1/products/${id}`),
   categories: () => req<{ items: Category[] }>(`/api/v1/categories`),
+  kindFields: (kind: string) =>
+    req<{ items: KindField[]; kind: string }>(
+      `/api/v1/kind-fields?kind=${encodeURIComponent(kind)}`,
+    ),
   submit: (input: SubmissionInput) =>
     req<{ id: string; status: string }>(`/api/public/submissions`, {
       method: "POST",

public-frontend/src/components/Account.tsx

@@ -5,7 +5,7 @@ import { api, type AccountInfo, type KeyResponse } from "../api";
 function KeyReveal({ data }: { data: KeyResponse }) {
   const [copied, setCopied] = useState(false);
   return (
-    <div className="mt-4 rounded-lg border border-emerald-200 bg-emerald-50 p-4">
+    <div className="mt-4 rounded-lg border border-brand-100 bg-brand-50 p-4">
       <div className="flex items-start gap-2 text-amber-700 text-sm">
         <AlertTriangle className="w-4 h-4 mt-0.5 shrink-0" />
         <span>请立即复制保存此密钥，它只显示这一次，无法再次查看。</span>
@@ -27,7 +27,7 @@ function KeyReveal({ data }: { data: KeyResponse }) {
           className="text-gray-400 hover:text-gray-600 shrink-0"
           title="复制"
         >
-          {copied ? <Check className="w-5 h-5 text-emerald-600" /> : <Copy className="w-5 h-5" />}
+          {copied ? <Check className="w-5 h-5 text-brand-600" /> : <Copy className="w-5 h-5" />}
         </button>
       </div>
       <div className="mt-3 text-sm text-gray-600">
@@ -92,9 +92,9 @@ export default function Account() {
 
   return (
     <div className="max-w-xl mx-auto space-y-5">
-      <div className="bg-white border rounded-lg p-5">
+      <div className="card p-5">
         <h1 className="flex items-center gap-2 text-2xl font-bold text-gray-800">
-          <KeyRound className="w-6 h-6 text-emerald-600" /> API 密钥
+          <KeyRound className="w-6 h-6 text-brand-600" /> API 密钥
         </h1>
         <p className="mt-2 text-sm text-gray-600 leading-relaxed">
           匿名调用免费，但每个来源 IP 累计共 <strong>1000</strong> 次。注册一个账号即可自助领取专属 API
@@ -104,7 +104,7 @@ export default function Account() {
         <div className="mt-4 inline-flex rounded-md border bg-gray-50 p-0.5 text-sm">
           <button
             className={`px-4 py-1.5 rounded ${
-              mode === "register" ? "bg-white shadow-sm text-emerald-700" : "text-gray-500"
+              mode === "register" ? "bg-white shadow-sm text-brand-700" : "text-gray-500"
             }`}
             onClick={() => {
               setMode("register");
@@ -115,7 +115,7 @@ export default function Account() {
           </button>
           <button
             className={`px-4 py-1.5 rounded ${
-              mode === "manage" ? "bg-white shadow-sm text-emerald-700" : "text-gray-500"
+              mode === "manage" ? "bg-white shadow-sm text-brand-700" : "text-gray-500"
             }`}
             onClick={() => {
               setMode("manage");
@@ -135,7 +135,7 @@ export default function Account() {
               value={email}
               onChange={(e) => setEmail(e.target.value)}
               placeholder="you@example.com"
-              className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-500"
+              className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500"
             />
           </div>
           <div>
@@ -146,14 +146,14 @@ export default function Account() {
               value={password}
               onChange={(e) => setPassword(e.target.value)}
               placeholder="••••••••"
-              className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-500"
+              className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-brand-500"
             />
           </div>
           {error && <div className="text-sm text-red-600">{error}</div>}
           <button
             type="submit"
             disabled={loading}
-            className="w-full bg-emerald-600 text-white rounded-md py-2 text-sm font-medium hover:bg-emerald-700 disabled:opacity-50"
+            className="w-full bg-brand-600 text-white rounded-md py-2 text-sm font-medium hover:bg-brand-700 disabled:opacity-50"
           >
             {loading ? "处理中…" : mode === "register" ? "注册并领取密钥" : "查询账号"}
           </button>
@@ -175,12 +175,12 @@ export default function Account() {
             <div>
               累计配额：已用 <strong>{info.quota_used.toLocaleString()}</strong> /{" "}
               {info.quota_total.toLocaleString()} 次（剩余{" "}
-              <strong className="text-emerald-600">{info.quota_remaining.toLocaleString()}</strong>）
+              <strong className="text-brand-600">{info.quota_remaining.toLocaleString()}</strong>）
             </div>
             <button
               onClick={regenerate}
               disabled={loading}
-              className="mt-2 text-emerald-600 hover:underline disabled:opacity-50"
+              className="mt-2 text-brand-600 hover:underline disabled:opacity-50"
             >
               忘记密钥？重置并生成新密钥
             </button>

public-frontend/src/components/ApiDocs.tsx

@@ -20,7 +20,7 @@ function CopyBtn({ text }: { text: string }) {
       className="text-gray-400 hover:text-gray-600"
       title="复制"
     >
-      {done ? <Check className="w-4 h-4 text-emerald-600" /> : <Copy className="w-4 h-4" />}
+      {done ? <Check className="w-4 h-4 text-brand-600" /> : <Copy className="w-4 h-4" />}
     </button>
   );
 }
@@ -39,7 +39,7 @@ function Code({ children }: { children: string }) {
 }
 
 function Method({ m }: { m: string }) {
-  const color = m === "GET" ? "bg-sky-100 text-sky-700" : "bg-emerald-100 text-emerald-700";
+  const color = m === "GET" ? "bg-sky-100 text-sky-700" : "bg-brand-100 text-brand-700";
   return <span className={`text-xs font-mono font-semibold rounded px-1.5 py-0.5 ${color}`}>{m}</span>;
 }
 
@@ -63,7 +63,7 @@ function Endpoint({
   response: string;
 }) {
   return (
-    <div className="bg-white border rounded-lg p-5">
+    <div className="card p-5">
       <div className="flex items-center gap-2 flex-wrap">
         <Method m={method} />
         <code className="text-sm text-gray-800 font-mono break-all">{path}</code>
@@ -105,7 +105,7 @@ function Endpoint({
 export default function ApiDocs({ onRegister }: { onRegister?: () => void }) {
   return (
     <div className="space-y-5">
-      <div className="bg-white border rounded-lg p-5">
+      <div className="card p-5">
         <h1 className="text-2xl font-bold text-gray-800">API 调用说明</h1>
         <p className="mt-2 text-gray-600 text-sm leading-relaxed">
           天工商品档案公共仓提供<strong>公开、只读、免鉴权</strong>的商品事实 REST API，任何人都可直接调用，
@@ -119,7 +119,7 @@ export default function ApiDocs({ onRegister }: { onRegister?: () => void }) {
           <ul className="mt-2 list-disc pl-5 text-gray-600 space-y-1">
             <li>
               无需 API Key / Token 即可直接 GET；匿名调用按来源 IP 累计共 <strong>1000</strong> 次，
-              用满后需<button onClick={onRegister} className="text-emerald-600 hover:underline">注册账号</button>
+              用满后需<button onClick={onRegister} className="text-brand-600 hover:underline">注册账号</button>
               领取更高配额密钥（见下文「鉴权与配额」）。
             </li>
             <li>
@@ -135,13 +135,13 @@ export default function ApiDocs({ onRegister }: { onRegister?: () => void }) {
         </div>
       </div>
 
-      <div className="bg-white border rounded-lg p-5">
+      <div className="card p-5">
         <h2 className="text-lg font-semibold text-gray-800">鉴权与配额</h2>
         <p className="mt-2 text-gray-600 text-sm leading-relaxed">
           API 默认<strong>匿名可用</strong>：无需任何凭证即可调用，但按来源 IP 计一个
           <strong>累计总配额（共 1000 次）</strong>，用满后返回
           <code className="font-mono">403</code>（错误码 <code className="font-mono">quota_exhausted</code>），
-          需<button onClick={onRegister} className="text-emerald-600 hover:underline">注册账号</button>
+          需<button onClick={onRegister} className="text-brand-600 hover:underline">注册账号</button>
           自助领取更高配额的 API Key。注册得到的密钥拥有更高的每分钟频率与累计调用配额，请求时通过请求头携带：
         </p>
         <div className="mt-3">
@@ -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/Contact.tsx

@@ -0,0 +1,113 @@
+import { useState } from "react";
+import { Phone, Mail, Globe, MessageSquare, Copy, Check, Headset } from "lucide-react";
+
+type Channel = {
+  key: string;
+  icon: typeof Phone;
+  label: string;
+  value: string;
+  href?: string;
+  copy: string;
+};
+
+const CHANNELS: Channel[] = [
+  {
+    key: "phone",
+    icon: Phone,
+    label: "电话",
+    value: "188 6595 7520",
+    href: "tel:18865957520",
+    copy: "18865957520",
+  },
+  {
+    key: "email",
+    icon: Mail,
+    label: "邮箱",
+    value: "1115084741@qq.com",
+    href: "mailto:1115084741@qq.com",
+    copy: "1115084741@qq.com",
+  },
+  {
+    key: "site",
+    icon: Globe,
+    label: "官网",
+    value: "www.wenyaoyu.com",
+    href: "https://www.wenyaoyu.com",
+    copy: "https://www.wenyaoyu.com",
+  },
+  {
+    key: "wechat",
+    icon: MessageSquare,
+    label: "微信",
+    value: "s-b-m-y",
+    copy: "s-b-m-y",
+  },
+];
+
+export default function Contact() {
+  const [copied, setCopied] = useState<string | null>(null);
+
+  async function copy(channel: Channel) {
+    try {
+      await navigator.clipboard.writeText(channel.copy);
+      setCopied(channel.key);
+      setTimeout(() => setCopied((k) => (k === channel.key ? null : k)), 1500);
+    } catch {
+      /* clipboard unavailable */
+    }
+  }
+
+  return (
+    <div className="max-w-3xl mx-auto animate-fade-up">
+      <div className="text-center">
+        <span className="mx-auto grid h-14 w-14 place-items-center rounded-2xl bg-gradient-to-br from-brand-500 to-brand-700 text-white shadow-glow">
+          <Headset className="w-7 h-7" />
+        </span>
+        <h1 className="mt-4 text-2xl font-semibold tracking-tight text-gray-900">联系我们</h1>
+        <p className="mx-auto mt-2 max-w-xl text-sm text-gray-500">
+          欢迎交流与对接合作。无论是数据接入、商务合作还是问题反馈，都可以通过以下任一方式联系我们。
+        </p>
+      </div>
+
+      <div className="mt-8 grid grid-cols-1 sm:grid-cols-2 gap-4">
+        {CHANNELS.map((c) => {
+          const Icon = c.icon;
+          return (
+            <div key={c.key} className="card p-5 flex items-center gap-4">
+              <span className="grid h-11 w-11 shrink-0 place-items-center rounded-xl bg-brand-50 text-brand-600">
+                <Icon className="w-5 h-5" />
+              </span>
+              <div className="min-w-0 flex-1">
+                <div className="text-xs font-medium text-gray-400">{c.label}</div>
+                {c.href ? (
+                  <a
+                    href={c.href}
+                    target={c.key === "site" ? "_blank" : undefined}
+                    rel={c.key === "site" ? "noreferrer" : undefined}
+                    className="block truncate font-medium text-gray-800 hover:text-brand-600 hover:underline"
+                  >
+                    {c.value}
+                  </a>
+                ) : (
+                  <div className="truncate font-medium text-gray-800">{c.value}</div>
+                )}
+              </div>
+              <button
+                type="button"
+                onClick={() => copy(c)}
+                title="复制"
+                className="shrink-0 grid h-9 w-9 place-items-center rounded-lg border border-gray-200 text-gray-400 transition hover:bg-gray-50 hover:text-brand-600"
+              >
+                {copied === c.key ? (
+                  <Check className="w-4 h-4 text-brand-600" />
+                ) : (
+                  <Copy className="w-4 h-4" />
+                )}
+              </button>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

public-frontend/src/components/Contribute.tsx

@@ -1,7 +1,7 @@
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { CheckCircle2, PlusCircle, Trash2 } from "lucide-react";
 import { api } from "../api";
-import type { Category, SubmissionImage, SubmissionInput } from "../types";
+import type { Category, KindField, SubmissionImage, SubmissionInput } from "../types";
 
 const NUTRI_FIELDS: { key: string; label: string }[] = [
   { key: "energy_kcal", label: "能量 (kcal)" },
@@ -35,6 +35,8 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
   const [ingredients, setIngredients] = useState("");
   const [basis, setBasis] = useState("");
   const [nutri, setNutri] = useState<Record<string, string>>({});
+  const [kindFields, setKindFields] = useState<KindField[]>([]);
+  const [attrs, setAttrs] = useState<Record<string, string>>({});
   const [images, setImages] = useState<SubmissionImage[]>([]);
   const [imageURL, setImageURL] = useState("");
   const [submitter, setSubmitter] = useState("");
@@ -45,6 +47,33 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
     api.categories().then((r) => setCategories(r.items)).catch(() => undefined);
   }, []);
 
+  // Derive the archive kind from the selected category. No category => generic.
+  const kind = useMemo(() => {
+    const c = categories.find((x) => x.id === categoryID);
+    return c?.archive_kind || "generic";
+  }, [categories, categoryID]);
+
+  // Fetch the kind-specific field template for non-food kinds.
+  useEffect(() => {
+    setAttrs({});
+    if (kind === "food" || kind === "generic") {
+      setKindFields([]);
+      return;
+    }
+    let alive = true;
+    api
+      .kindFields(kind)
+      .then((r) => {
+        if (alive) setKindFields(r.items);
+      })
+      .catch(() => {
+        if (alive) setKindFields([]);
+      });
+    return () => {
+      alive = false;
+    };
+  }, [kind]);
+
   async function submit(e: React.FormEvent) {
     e.preventDefault();
     if (name.trim() === "") {
@@ -55,10 +84,32 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
     setError("");
 
     const nutriments: Record<string, number> = {};
+    if (kind === "food") {
       for (const [k, v] of Object.entries(nutri)) {
         const n = parseFloat(v);
         if (!Number.isNaN(n)) nutriments[k] = n;
       }
+    }
+
+    const attributes: Record<string, unknown> = {};
+    if (kind !== "food" && kind !== "generic") {
+      for (const f of kindFields) {
+        const raw = (attrs[f.field_key] || "").trim();
+        if (raw === "") continue;
+        if (f.field_type === "number") {
+          const n = parseFloat(raw);
+          if (!Number.isNaN(n)) attributes[f.field_key] = n;
+        } else if (f.field_type === "list") {
+          const parts = raw
+            .split(/[\n,，、]/)
+            .map((s) => s.trim())
+            .filter((s) => s !== "");
+          if (parts.length) attributes[f.field_key] = parts;
+        } else {
+          attributes[f.field_key] = raw;
+        }
+      }
+    }
 
     const input: SubmissionInput = {
       name: name.trim(),
@@ -68,9 +119,10 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
       net_content_value: field(netValue) ? parseFloat(netValue) : null,
       net_content_unit: field(netUnit),
       country_of_origin: field(country),
-      ingredients_text: field(ingredients),
+      ingredients_text: kind === "food" ? field(ingredients) : null,
       nutriments: Object.keys(nutriments).length ? nutriments : null,
-      nutrition_basis: basis || null,
+      attributes: Object.keys(attributes).length ? attributes : null,
+      nutrition_basis: kind === "food" && basis ? basis : null,
       images: images.length ? images : undefined,
       submitter_name: field(submitter),
       submitter_contact: field(contact),
@@ -89,38 +141,91 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
 
   if (done) {
     return (
-      <div className="max-w-xl mx-auto text-center py-16">
-        <CheckCircle2 className="w-14 h-14 text-emerald-500 mx-auto" />
+      <div className="max-w-xl mx-auto text-center py-16 animate-fade-up">
+        <span className="mx-auto grid h-16 w-16 place-items-center rounded-2xl bg-brand-50">
+          <CheckCircle2 className="w-9 h-9 text-brand-600" />
+        </span>
         <h1 className="mt-4 text-xl font-semibold text-gray-800">已提交，等待审核</h1>
         <p className="mt-2 text-gray-500">
           感谢你的贡献！资料将由管理员人工审核，通过后会收录进公共商品库。
         </p>
-        <button
-          onClick={onDone}
-          className="mt-6 px-5 py-2 rounded-lg bg-emerald-600 text-white hover:bg-emerald-700"
-        >
+        <button onClick={onDone} className="btn-primary mt-6">
           返回首页
         </button>
       </div>
     );
   }
 
-  const input =
-    "w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-400";
-  const label = "block text-xs text-gray-500 mb-1";
+  const input = "input";
+  const label = "block text-xs font-medium text-gray-500 mb-1";
+
+  // Group the kind fields by their group label, preserving template order.
+  const groups: { label: string; fields: KindField[] }[] = [];
+  for (const f of kindFields) {
+    let g = groups.find((x) => x.label === f.group_label);
+    if (!g) {
+      g = { label: f.group_label, fields: [] };
+      groups.push(g);
+    }
+    g.fields.push(f);
+  }
+
+  const KIND_LABEL: Record<string, string> = {
+    drug: "药品",
+    electronics: "数码 3C",
+    food: "食品",
+    generic: "通用",
+  };
+
+  function renderField(f: KindField) {
+    const val = attrs[f.field_key] || "";
+    const set = (v: string) => setAttrs((p) => ({ ...p, [f.field_key]: v }));
+    const lbl = f.unit ? `${f.label_zh} (${f.unit})` : f.label_zh;
+    return (
+      <div key={f.field_key} className={f.field_type === "textarea" || f.field_type === "list" ? "sm:col-span-2" : ""}>
+        <label className={label}>
+          {lbl}
+          {f.qualified && <span className="text-brand-500"> *</span>}
+        </label>
+        {f.field_type === "select" ? (
+          <select className={input} value={val} onChange={(e) => set(e.target.value)}>
+            <option value="">（未选择）</option>
+            {(f.options || []).map((o) => (
+              <option key={o} value={o}>
+                {o}
+              </option>
+            ))}
+          </select>
+        ) : f.field_type === "textarea" ? (
+          <textarea className={input} rows={3} value={val} placeholder={f.placeholder || ""} onChange={(e) => set(e.target.value)} />
+        ) : f.field_type === "list" ? (
+          <textarea className={input} rows={2} value={val} placeholder={f.placeholder || "每行一项，或用、逗号分隔"} onChange={(e) => set(e.target.value)} />
+        ) : (
+          <input
+            type={f.field_type === "number" ? "number" : "text"}
+            step={f.field_type === "number" ? "any" : undefined}
+            className={input}
+            value={val}
+            placeholder={f.placeholder || ""}
+            onChange={(e) => set(e.target.value)}
+          />
+        )}
+      </div>
+    );
+  }
 
   return (
-    <form onSubmit={submit} className="max-w-3xl mx-auto">
-      <h1 className="text-xl font-semibold text-gray-800">贡献商品档案</h1>
+    <form onSubmit={submit} className="max-w-3xl mx-auto animate-fade-up">
+      <h1 className="text-2xl font-semibold tracking-tight text-gray-900">贡献商品档案</h1>
       <p className="mt-1 text-sm text-gray-500">
-        任何人都可以提交新商品资料。提交后会进入审核队列，<b>通过人工审核后才会收纳</b>。带 * 为必填。
+        任何人都可以提交新商品资料。提交后会进入审核队列，<b>通过人工审核后才会收纳</b>。除商品名称外均为选填，按品类填写对应资料即可。
       </p>
 
       {error && (
-        <div className="mt-4 bg-red-50 text-red-700 text-sm rounded-md px-4 py-2">{error}</div>
+        <div className="mt-4 rounded-xl bg-red-50 px-4 py-2.5 text-sm text-red-700">{error}</div>
       )}
 
-      <div className="bg-white border rounded-lg p-5 mt-4">
+      <div className="card p-5 mt-4">
         <h2 className="font-medium text-gray-700 mb-3">基础信息</h2>
         <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
           <div className="sm:col-span-2">
@@ -145,6 +250,11 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
                 </option>
               ))}
             </select>
+            {categoryID && (
+              <p className="mt-1 text-xs text-gray-400">
+                档案类型：{KIND_LABEL[kind] || kind}
+              </p>
+            )}
           </div>
           <div>
             <label className={label}>产地</label>
@@ -167,7 +277,8 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
         </div>
       </div>
 
-      <div className="bg-white border rounded-lg p-5 mt-4">
+      {kind === "food" && (
+        <div className="card p-5 mt-4">
           <h2 className="font-medium text-gray-700 mb-3">配料与营养</h2>
           <label className={label}>配料表</label>
           <textarea
@@ -200,8 +311,24 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
             ))}
           </div>
         </div>
+      )}
 
-      <div className="bg-white border rounded-lg p-5 mt-4">
+      {kind !== "food" && kind !== "generic" && kindFields.length > 0 && (
+        <div className="card p-5 mt-4">
+          <h2 className="font-medium text-gray-700 mb-1">{KIND_LABEL[kind] || kind}资料</h2>
+          <p className="text-xs text-gray-400 mb-3">带 * 为该品类的关键字段，建议尽量填写。</p>
+          {groups.map((g) => (
+            <div key={g.label} className="mt-3 first:mt-0">
+              {g.label && <h3 className="text-xs font-semibold text-gray-400 mb-2">{g.label}</h3>}
+              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+                {g.fields.map(renderField)}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      <div className="card p-5 mt-4">
         <h2 className="font-medium text-gray-700 mb-3">图片（仅填 URL）</h2>
         {images.length > 0 && (
           <ul className="mb-3 space-y-1">
@@ -234,14 +361,14 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
                 setImageURL("");
               }
             }}
-            className="shrink-0 px-3 rounded-md border text-sm flex items-center gap-1 hover:bg-gray-50"
+            className="shrink-0 px-3 rounded-xl border border-gray-200 text-sm flex items-center gap-1 hover:bg-gray-50"
           >
             <PlusCircle className="w-4 h-4" /> 添加
           </button>
         </div>
       </div>
 
-      <div className="bg-white border rounded-lg p-5 mt-4">
+      <div className="card p-5 mt-4">
         <h2 className="font-medium text-gray-700 mb-3">联系方式（选填）</h2>
         <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
           <div>
@@ -260,11 +387,7 @@ export default function Contribute({ onDone }: { onDone: () => void }) {
       </div>
 
       <div className="mt-5 flex items-center gap-3">
-        <button
-          type="submit"
-          disabled={submitting}
-          className="px-6 py-2.5 rounded-lg bg-emerald-600 text-white font-medium hover:bg-emerald-700 disabled:opacity-60"
-        >
+        <button type="submit" disabled={submitting} className="btn-primary px-6">
           {submitting ? "提交中…" : "提交审核"}
         </button>
         <button type="button" onClick={onDone} className="text-sm text-gray-500 hover:underline">

public-frontend/src/components/Home.tsx

@@ -1,16 +1,14 @@
 import { useState } from "react";
-import { Search, PlusCircle, Code2 } from "lucide-react";
+import { Search, PlusCircle, ArrowRight } from "lucide-react";
 import { api } from "../api";
 import type { ProductSummary } from "../types";
 
 export default function Home({
   onOpen,
   onContribute,
-  onApi,
 }: {
   onOpen: (id: string) => void;
   onContribute: () => void;
-  onApi: () => void;
 }) {
   const [q, setQ] = useState("");
   const [items, setItems] = useState<ProductSummary[]>([]);
@@ -19,12 +17,14 @@ export default function Home({
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
 
-  async function run(e?: React.FormEvent) {
+  async function run(term?: string, e?: React.FormEvent) {
     e?.preventDefault();
+    const keyword = (term ?? q).trim();
+    if (term !== undefined) setQ(term);
     setLoading(true);
     setError("");
     try {
-      const res = await api.search(q.trim(), 1, 30);
+      const res = await api.search(keyword, 1, 30);
       setItems(res.items);
       setTotal(res.total);
       setSearched(true);
@@ -36,81 +36,98 @@ export default function Home({
   }
 
   return (
-    <div>
-      <div className="text-center py-10">
-        <h1 className="text-3xl font-bold text-gray-800">天工</h1>
-        <p className="mt-2 text-gray-500">
-          输入商品名称或条码，检索客观、可溯源的商品资料。人人可查，人人可贡献。
-        </p>
-        <form onSubmit={run} className="mt-6 max-w-2xl mx-auto flex gap-2">
-          <div className="flex-1 flex items-center gap-2 bg-white border rounded-lg px-3 shadow-sm focus-within:ring-2 focus-within:ring-emerald-400">
-            <Search className="w-5 h-5 text-gray-400" />
+    <div className="animate-fade-up">
+      <section
+        className={`flex flex-col items-center px-4 text-center ${
+          searched
+            ? "pt-2 pb-6"
+            : "min-h-[calc(100vh-12rem)] justify-center"
+        }`}
+      >
+        <h1
+          className={`font-medium tracking-tight text-gray-800 ${
+            searched ? "text-3xl" : "text-6xl sm:text-7xl"
+          }`}
+        >
+          天<span className="text-brand-600">工</span>
+        </h1>
+
+        <form
+          onSubmit={(e) => run(undefined, e)}
+          className="mx-auto mt-8 w-full max-w-xl"
+        >
+          <div className="flex items-center gap-3 rounded-full border border-gray-200 bg-white px-5 py-3 shadow-sm transition hover:shadow-md focus-within:shadow-md">
+            <Search className="h-5 w-5 shrink-0 text-gray-400" />
             <input
               autoFocus
               value={q}
               onChange={(e) => setQ(e.target.value)}
-              placeholder="例如：可乐、Nutella、5449000000996"
-              className="flex-1 py-3 outline-none bg-transparent"
+              placeholder="搜索商品名称或条码"
+              className="flex-1 bg-transparent outline-none"
             />
           </div>
+          {!searched && (
+            <div className="mt-8">
               <button
                 type="submit"
                 disabled={loading}
-            className="px-6 rounded-lg bg-emerald-600 text-white font-medium hover:bg-emerald-700 disabled:opacity-60"
+                className="rounded-md border border-gray-200 bg-gray-50 px-6 py-2.5 text-sm text-gray-700 transition hover:border-gray-300 hover:shadow-sm"
               >
                 {loading ? "检索中…" : "检索"}
               </button>
-        </form>
-        <button
-          onClick={onApi}
-          className="mt-4 inline-flex items-center gap-1.5 text-sm text-emerald-700 hover:underline"
-        >
-          <Code2 className="w-4 h-4" /> 开发者？查看 API 调用说明，免鉴权接入商品档案
-        </button>
             </div>
+          )}
+        </form>
+      </section>
 
       {error && (
-        <div className="max-w-2xl mx-auto bg-red-50 text-red-700 text-sm rounded-md px-4 py-2">
+        <div className="mx-auto mt-6 max-w-2xl rounded-xl bg-red-50 px-4 py-2.5 text-sm text-red-700">
           {error}
         </div>
       )}
 
       {searched && (
-        <div className="mt-2">
-          <div className="text-sm text-gray-500 mb-2">
-            共 {total} 条结果{q ? `（关键词：${q}）` : ""}
+        <div className="mt-8">
+          <div className="mb-3 text-sm text-gray-500">
+            共 <span className="font-semibold text-gray-700">{total}</span> 条结果
+            {q ? `（关键词：${q}）` : ""}
           </div>
           {items.length === 0 ? (
-            <div className="bg-white border rounded-lg p-8 text-center text-gray-500">
+            <div className="card p-10 text-center text-gray-500">
               <p>没有找到相关商品。</p>
               <button
                 onClick={onContribute}
-                className="mt-3 inline-flex items-center gap-1.5 text-emerald-700 hover:underline"
+                className="mt-3 inline-flex items-center gap-1.5 font-medium text-brand-700 hover:underline"
               >
                 <PlusCircle className="w-4 h-4" /> 你知道这个商品？去贡献档案
               </button>
             </div>
           ) : (
-            <ul className="bg-white border rounded-lg divide-y">
+            <ul className="card divide-y divide-gray-100 overflow-hidden">
               {items.map((p) => (
                 <li key={p.id}>
                   <button
                     onClick={() => onOpen(p.id)}
-                    className="w-full text-left px-4 py-3 hover:bg-gray-50 flex items-center justify-between gap-4"
+                    className="group flex w-full items-center justify-between gap-4 px-4 py-3.5 text-left transition hover:bg-brand-50/50"
                   >
-                    <div>
-                      <div className="font-medium text-gray-800">{p.name}</div>
-                      <div className="text-xs text-gray-500 mt-0.5">
+                    <div className="min-w-0">
+                      <div className="truncate font-medium text-gray-800 group-hover:text-brand-700">
+                        {p.name}
+                      </div>
+                      <div className="mt-0.5 text-xs text-gray-500">
                         {p.brand || "未知品牌"}
                         {p.gtin ? ` · ${p.gtin}` : ""}
                       </div>
                     </div>
-                    <span className="text-xs text-gray-400 text-right">
+                    <div className="flex shrink-0 items-center gap-3">
+                      <span className="text-right text-xs text-gray-400">
                         <span className="block">{p.category_path || ""}</span>
                         {p.country_of_origin ? (
-                        <span className="block text-gray-400">产地：{p.country_of_origin}</span>
+                          <span className="block">产地：{p.country_of_origin}</span>
                         ) : null}
                       </span>
+                      <ArrowRight className="h-4 w-4 text-gray-300 transition group-hover:translate-x-0.5 group-hover:text-brand-500" />
+                    </div>
                   </button>
                 </li>
               ))}

public-frontend/src/components/ProductView.tsx

@@ -28,11 +28,11 @@ export default function ProductView({ id, onBack }: { id: string; onBack: () =>
         <button onClick={onBack} className="text-sm text-gray-500 flex items-center gap-1 mb-4">
           <ArrowLeft className="w-4 h-4" /> 返回
         </button>
-        <div className="bg-red-50 text-red-700 text-sm rounded-md px-4 py-3">{error}</div>
+        <div className="rounded-xl bg-red-50 px-4 py-3 text-sm text-red-700">{error}</div>
       </div>
     );
   }
-  if (!p) return <div className="text-gray-400">加载中…</div>;
+  if (!p) return <div className="text-gray-400 animate-pulse">加载中…</div>;
 
   const basisLabel: Record<string, string> = {
     per_100g: "每 100g",
@@ -42,17 +42,23 @@ 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>
-      <button onClick={onBack} className="text-sm text-gray-500 flex items-center gap-1 mb-4">
+      <button onClick={onBack} className="mb-4 inline-flex items-center gap-1 text-sm text-gray-500 hover:text-gray-700">
         <ArrowLeft className="w-4 h-4" /> 返回检索
       </button>
 
-      <div className="bg-white border rounded-lg p-5">
+      <div className="card p-6 animate-fade-up">
         <div className="flex items-start justify-between gap-4">
-          <h1 className="text-xl font-semibold text-gray-800">{p.name}</h1>
-          <span className="shrink-0 text-xs bg-emerald-50 text-emerald-700 rounded px-2 py-1">
+          <h1 className="text-2xl font-semibold tracking-tight text-gray-900">{p.name}</h1>
+          <span className="shrink-0 rounded-full border border-brand-100 bg-brand-50 px-2.5 py-1 text-xs font-medium text-brand-700">
             质量分 {Math.round(p.quality_score * 100)}
           </span>
         </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
@@ -107,7 +124,7 @@ export default function ProductView({ id, onBack }: { id: string; onBack: () =>
       </div>
 
       {p.specs && p.specs.length > 0 && (
-        <div className="bg-white border rounded-lg p-5 mt-4">
+        <div className="card p-6 mt-4">
           <h2 className="font-medium text-gray-700 mb-2">规格参数</h2>
           <div className="grid grid-cols-1 sm:grid-cols-2 gap-2 text-sm">
             {p.specs.map((s) => (
@@ -124,7 +141,7 @@ export default function ProductView({ id, onBack }: { id: string; onBack: () =>
       )}
 
       {nutriEntries.length > 0 && (
-        <div className="bg-white border rounded-lg p-5 mt-4">
+        <div className="card p-6 mt-4">
           <h2 className="font-medium text-gray-700 mb-2">
             营养成分
             {p.nutrition_basis ? `（${basisLabel[p.nutrition_basis] || p.nutrition_basis}）` : ""}

public-frontend/src/index.css

@@ -10,7 +10,36 @@ body,
 
 body {
   margin: 0;
-  background: #f3f4f6;
-  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue",
-    Arial, "PingFang SC", "Microsoft YaHei", sans-serif;
+  color: #1f2937;
+  font-family: theme("fontFamily.sans");
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+  background-color: #f6f8f7;
+  background-image:
+    radial-gradient(60rem 60rem at 100% -10%, rgba(16, 185, 129, 0.10), transparent 60%),
+    radial-gradient(50rem 50rem at -10% 0%, rgba(45, 212, 191, 0.10), transparent 55%);
+  background-attachment: fixed;
+}
+
+@layer components {
+  .card {
+    @apply bg-white rounded-2xl border border-gray-100;
+    box-shadow: theme("boxShadow.card");
+  }
+
+  .input {
+    @apply w-full rounded-xl border border-gray-200 bg-white px-3.5 py-2.5 text-sm text-gray-800 placeholder:text-gray-400 transition focus:outline-none focus:border-brand-400 focus:ring-4 focus:ring-brand-500/10;
+  }
+
+  .btn-primary {
+    @apply inline-flex items-center justify-center gap-1.5 rounded-xl bg-brand-600 px-5 py-2.5 text-sm font-semibold text-white shadow-sm transition hover:bg-brand-700 active:bg-brand-800 disabled:opacity-60;
+  }
+
+  .btn-ghost {
+    @apply inline-flex items-center justify-center gap-1.5 rounded-xl px-3.5 py-2 text-sm font-medium text-gray-600 transition hover:bg-gray-100;
+  }
+
+  .chip {
+    @apply inline-flex items-center gap-1 rounded-full border border-gray-200 bg-white/70 px-3 py-1 text-xs font-medium text-gray-600 transition hover:border-brand-300 hover:text-brand-700 hover:bg-brand-50;
+  }
 }

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 {
@@ -51,6 +61,20 @@ export interface Category {
   name_en: string | null;
   path: string;
   level: number;
+  archive_kind: string;
+}
+
+export interface KindField {
+  kind: string;
+  field_key: string;
+  group_label: string;
+  label_zh: string;
+  field_type: "text" | "number" | "textarea" | "select" | "list";
+  unit: string | null;
+  options: string[] | null;
+  placeholder: string | null;
+  sort_order: number;
+  qualified: boolean;
 }
 
 export interface SubmissionImage {
@@ -68,6 +92,7 @@ export interface SubmissionInput {
   country_of_origin?: string | null;
   ingredients_text?: string | null;
   nutriments?: Record<string, number> | null;
+  attributes?: Record<string, unknown> | null;
   nutrition_basis?: string | null;
   serving_size?: string | null;
   nutri_score?: string | null;

public-frontend/tailwind.config.js

@@ -1,6 +1,55 @@
 /** @type {import('tailwindcss').Config} */
 export default {
   content: ["./index.html", "./src/**/*.{ts,tsx}"],
-  theme: { extend: {} },
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          50: "#ecfdf5",
+          100: "#d1fae5",
+          200: "#a7f3d0",
+          300: "#6ee7b7",
+          400: "#34d399",
+          500: "#10b981",
+          600: "#059669",
+          700: "#047857",
+          800: "#065f46",
+          900: "#064e3b",
+        },
+      },
+      fontFamily: {
+        sans: [
+          "Inter",
+          "system-ui",
+          "-apple-system",
+          "Segoe UI",
+          "Roboto",
+          "Helvetica Neue",
+          "Arial",
+          "PingFang SC",
+          "Microsoft YaHei",
+          "sans-serif",
+        ],
+      },
+      boxShadow: {
+        card: "0 1px 2px rgba(16,24,40,0.04), 0 4px 16px -8px rgba(16,24,40,0.10)",
+        "card-hover": "0 10px 30px -10px rgba(16,24,40,0.18)",
+        glow: "0 12px 40px -12px rgba(5,150,105,0.45)",
+      },
+      borderRadius: {
+        "2xl": "1rem",
+        "3xl": "1.5rem",
+      },
+      keyframes: {
+        "fade-up": {
+          "0%": { opacity: "0", transform: "translateY(8px)" },
+          "100%": { opacity: "1", transform: "translateY(0)" },
+        },
+      },
+      animation: {
+        "fade-up": "fade-up 0.4s ease-out both",
+      },
+    },
+  },
   plugins: [],
 };

tools/bypos-collector/README.md

@@ -58,10 +58,9 @@ GET http://zc.bypos.net/byGoodsService/byMessage.asmx/GetGoodsinfo
 
 ## 配置
 
-- `sdogid`：中心库账号 id（本项目所属云店账号的授权 id）。
-  优先从环境变量 `BYPOS_SDOGID` 读取，其次是命令行 `-sdogid` 参数，
-  也可以在 Web 控制台的输入框中填写。**三者都未设时启动会警告、开始采集时会报错。**
-- 网络错误自动重试（最多 3 次，指数退避 500ms/1s/2s）。
+- `sdogid`:中心库账号 id(本项目所属云店账号的授权 id)。默认值见
+  `collect.go` 的 `defaultSdogID`,也可用 `-sdogid` 参数或控制台覆盖。
+  **这是账号级凭证**——若本仓库对外公开,建议改为从环境变量/外部配置读取。
 
 ## 导入 goods/天工库
 

tools/bypos-collector/collect.go

@@ -1,7 +1,6 @@
 package main
 
 import (
-	"bufio"
 	"context"
 	"crypto/md5"
 	"encoding/hex"
@@ -21,21 +20,12 @@ import (
 )
 
 // ---- upstream config ----
+// sdogid is the 云店 account license id observed in the live request. It is
+// configurable so the tool is not tied to a single account.
+const defaultSdogID = "137966"
 
 const endpoint = "http://zc.bypos.net/byGoodsService/byMessage.asmx/GetGoodsinfo"
 
-// maxRetries is the number of retry attempts for transient network errors.
-const maxRetries = 3
-
-// resolveSdogID reads the account id from $BYPOS_SDOGID, falling back to the
-// explicit argument (CLI flag or Web UI input). Returns empty if neither set.
-func resolveSdogID(explicit string) string {
-	if v := os.Getenv("BYPOS_SDOGID"); v != "" {
-		return v
-	}
-	return explicit
-}
-
 var stringTagRe = regexp.MustCompile(`(?s)<string[^>]*>(.*)</string>`)
 
 // Product is the normalized record we persist (one JSON object per line).
@@ -97,8 +87,8 @@ func ean13Check(body string) (string, bool) {
 	return body + strconv.Itoa(chk), true
 }
 
-// lookupOnce performs a single HTTP request to the upstream central library.
-func (c *Collector) lookupOnce(ctx context.Context, barcode string) (*Product, error) {
+// lookup queries the upstream central library for one barcode.
+func (c *Collector) lookup(ctx context.Context, barcode string) (*Product, error) {
 	tsMs := strconv.FormatInt(time.Now().Unix()*1000, 10) // always ends in 000
 	sparm1 := md5hex(c.sdogID)
 	sparm2 := md5hex(barcode + tsMs)
@@ -157,34 +147,8 @@ func (c *Collector) lookupOnce(ctx context.Context, barcode string) (*Product, e
 	return p, nil
 }
 
-// lookup queries the upstream with up to maxRetries retries on transient errors.
-func (c *Collector) lookup(ctx context.Context, barcode string) (*Product, error) {
-	var lastErr error
-	for attempt := 0; attempt <= maxRetries; attempt++ {
-		if ctx.Err() != nil {
-			return nil, ctx.Err()
-		}
-		p, err := c.lookupOnce(ctx, barcode)
-		if err == nil {
-			return p, nil
-		}
-		lastErr = err
-		if attempt < maxRetries {
-			backoff := time.Duration(1<<uint(attempt)) * 500 * time.Millisecond
-			select {
-			case <-time.After(backoff):
-			case <-ctx.Done():
-				return nil, ctx.Err()
-			}
-		}
-	}
-	return nil, lastErr
-}
-
 // ---- job / collector state ----
 
-const collectedFile = "collected.txt"
-
 type Stats struct {
 	Running   bool   `json:"running"`
 	Total     int64  `json:"total"`
@@ -198,7 +162,6 @@ type Stats struct {
 	OutFile   string `json:"out_file"`
 	StartedAt string `json:"started_at"`
 	Message   string `json:"message"`
-	HistoryCount int    `json:"history_count"`
 }
 
 type Collector struct {
@@ -219,20 +182,20 @@ type Collector struct {
 	startedAt string
 	message   string
 
-	seen        map[string]struct{} // barcodes already collected (dedupe)
-	collectedFp *os.File            // persistent history file handle
+	seen   map[string]struct{} // barcodes already in output (dedupe / resume)
 	recent []Product           // ring of last results for UI
 }
 
 func NewCollector(sdogID string) *Collector {
-	sdogID = resolveSdogID(sdogID)
+	if sdogID == "" {
+		sdogID = defaultSdogID
+	}
 	c := &Collector{
 		client: &http.Client{Timeout: 25 * time.Second},
 		sdogID: sdogID,
 		seen:   map[string]struct{}{},
 	}
 	c.current.Store("")
-	c.loadCollected()
 	return c
 }
 
@@ -244,7 +207,6 @@ func (c *Collector) snapshot() Stats {
 	msg := c.message
 	out := c.outPath
 	started := c.startedAt
-	hist := len(c.seen)
 	c.mu.Unlock()
 	return Stats{
 		Running:   c.isRunning(),
@@ -259,7 +221,6 @@ func (c *Collector) snapshot() Stats {
 		OutFile:   out,
 		StartedAt: started,
 		Message:   msg,
-		HistoryCount: hist,
 	}
 }
 
@@ -280,24 +241,9 @@ func (c *Collector) pushRecent(p Product) {
 	c.mu.Unlock()
 }
 
-// loadCollected reads the persistent history file (one barcode per line).
-func (c *Collector) loadCollected() {
-	f, err := os.Open(collectedFile)
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		bc := strings.TrimSpace(sc.Text())
-		if bc != "" {
-			c.seen[bc] = struct{}{}
-		}
-	}
-}
-
-// loadSeen reads an existing output file and adds to the dedupe set (for resume).
+// loadSeen reads an existing output file to build the dedupe set (for resume).
 func (c *Collector) loadSeen(path string) error {
+	c.seen = map[string]struct{}{}
 	f, err := os.Open(path)
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -362,9 +308,6 @@ func (c *Collector) Start(req JobReq) error {
 	if req.SdogID != "" {
 		c.sdogID = req.SdogID
 	}
-	if c.sdogID == "" {
-		return fmt.Errorf("未指定 sdogid，请通过控制台输入框、环境变量 $BYPOS_SDOGID 或 -sdogid 参数配置")
-	}
 
 	// Build the list of barcodes to query.
 	var barcodes []string
@@ -410,7 +353,6 @@ func (c *Collector) Start(req JobReq) error {
 	}
 	c.outFile = f
 	c.outPath = abs
-	c.collectedFp, _ = os.OpenFile(collectedFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
 
 	// reset counters
 	atomic.StoreInt64(&c.total, int64(len(barcodes)))
@@ -448,11 +390,6 @@ func (c *Collector) run(ctx context.Context, barcodes []string, req JobReq) {
 			c.outFile.Close()
 			c.outFile = nil
 		}
-		if c.collectedFp != nil {
-			c.collectedFp.Sync()
-			c.collectedFp.Close()
-			c.collectedFp = nil
-		}
 		c.current.Store("")
 	}()
 
@@ -501,19 +438,16 @@ func (c *Collector) run(ctx context.Context, barcodes []string, req JobReq) {
 			}
 			atomic.AddInt64(&c.done, 1)
 			c.pushRecent(*p)
-			writeMu.Lock()
 			if p.Status == "hit" || req.LogMiss {
 				line, _ := json.Marshal(p)
+				writeMu.Lock()
 				c.outFile.Write(line)
 				c.outFile.Write([]byte("\n"))
-			}
 				c.seen[bc] = struct{}{}
-			if c.collectedFp != nil {
-				c.collectedFp.WriteString(bc + "\n")
-			}
 				writeMu.Unlock()
 			}
 		}
+	}
 
 	for i := 0; i < req.Concurrency; i++ {
 		c.wg.Add(1)

tools/bypos-collector/collect_test.go

@@ -1,113 +0,0 @@
-package main
-
-import (
-	"os"
-	"testing"
-)
-
-func TestEan13Check_valid(t *testing.T) {
-	tests := []struct {
-		body string
-		want string
-	}{
-		{"692045990501", "6920459905012"},
-		{"690100000000", "6901000000004"},
-		{"690100000099", "6901000000998"},
-	}
-	for _, tt := range tests {
-		got, ok := ean13Check(tt.body)
-		if !ok {
-			t.Errorf("ean13Check(%q) returned not ok", tt.body)
-			continue
-		}
-		if got != tt.want {
-			t.Errorf("ean13Check(%q) = %q, want %q", tt.body, got, tt.want)
-		}
-	}
-}
-
-func TestEan13Check_invalid(t *testing.T) {
-	cases := []string{"", "12345", "12345678901", "1234567890123", "69010000a000"}
-	for _, body := range cases {
-		_, ok := ean13Check(body)
-		if ok {
-			t.Errorf("ean13Check(%q) should return not ok", body)
-		}
-	}
-}
-
-func TestMd5hex(t *testing.T) {
-	got := md5hex("137966")
-	if len(got) != 32 {
-		t.Errorf("md5hex should return 32-char hex, got len=%d", len(got))
-	}
-	if got != md5hex("137966") {
-		t.Error("md5hex should be deterministic")
-	}
-	if got == md5hex("other") {
-		t.Error("md5hex should differ for different inputs")
-	}
-}
-
-func TestSanitizeBarcodes(t *testing.T) {
-	got := sanitizeBarcodes("6920459905012\n6901028941068  123")
-	want := []string{"6920459905012", "6901028941068", "123"}
-	if len(got) != len(want) {
-		t.Fatalf("len = %d, want %d", len(got), len(want))
-	}
-	for i := range want {
-		if got[i] != want[i] {
-			t.Errorf("got[%d] = %q, want %q", i, got[i], want[i])
-		}
-	}
-}
-
-func TestSanitizeBarcodes_empty(t *testing.T) {
-	got := sanitizeBarcodes("  \n\t ")
-	if len(got) != 0 {
-		t.Errorf("expected empty, got %v", got)
-	}
-}
-
-func TestResolveSdogID_envOverride(t *testing.T) {
-	os.Setenv("BYPOS_SDOGID", "999999")
-	defer os.Unsetenv("BYPOS_SDOGID")
-	got := resolveSdogID("111111")
-	if got != "999999" {
-		t.Errorf("expected env var override, got %q", got)
-	}
-}
-
-func TestResolveSdogID_fallback(t *testing.T) {
-	os.Unsetenv("BYPOS_SDOGID")
-	got := resolveSdogID("111111")
-	if got != "111111" {
-		t.Errorf("expected fallback to explicit, got %q", got)
-	}
-}
-
-func TestResolveSdogID_empty(t *testing.T) {
-	os.Unsetenv("BYPOS_SDOGID")
-	got := resolveSdogID("")
-	if got != "" {
-		t.Errorf("expected empty, got %q", got)
-	}
-}
-
-func TestNewCollector_sdogFromEnv(t *testing.T) {
-	os.Setenv("BYPOS_SDOGID", "888888")
-	defer os.Unsetenv("BYPOS_SDOGID")
-	c := NewCollector("")
-	if c.sdogID != "888888" {
-		t.Errorf("expected sdogID from env, got %q", c.sdogID)
-	}
-}
-
-func TestStartRejectsEmptySdogID(t *testing.T) {
-	os.Unsetenv("BYPOS_SDOGID")
-	c := NewCollector("")
-	err := c.Start(JobReq{Mode: "list", List: "6920459905012"})
-	if err == nil {
-		t.Fatal("expected error for empty sdogid")
-	}
-}

tools/bypos-collector/main.go

@@ -1,8 +1,6 @@
 package main
 
 import (
-	"bufio"
-	"bytes"
 	"embed"
 	"encoding/csv"
 	"encoding/json"
@@ -16,55 +14,24 @@ import (
 	"os"
 	"os/exec"
 	"runtime"
-	"strings"
 	"time"
 )
 
 //go:embed web/*
 var webFS embed.FS
 
-var collector *Collector
-
-// waitExit keeps the console window open on Windows so the user can read errors.
-func waitExit() {
-	if runtime.GOOS == "windows" {
-		fmt.Println("\n按回车键退出...")
-		bufio.NewReader(os.Stdin).ReadBytes('\n')
-	}
-}
+var collector = NewCollector("")
 
 func main() {
-	// Log to file so crashes are diagnosable even if console closes.
-	lf, lfErr := os.OpenFile("bypos-collector.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
-	if lfErr == nil {
-		log.SetOutput(io.MultiWriter(os.Stderr, lf))
-		defer lf.Close()
-	}
-
-	defer func() {
-		if r := recover(); r != nil {
-			log.Printf("程序崩溃: %v", r)
-			waitExit()
-		}
-	}()
-
-	log.Println("bypos-collector 启动中...")
-
 	addr := flag.String("addr", "127.0.0.1:8765", "本地监听地址")
 	noOpen := flag.Bool("no-open", false, "不自动打开浏览器")
-	sdog := flag.String("sdogid", "", "中心库账号 id（优先读 $BYPOS_SDOGID 环境变量）")
+	sdog := flag.String("sdogid", "", "中心库账号 id(默认使用内置值)")
 	flag.Parse()
-	collector = NewCollector(*sdog)
-	if collector.sdogID == "" {
-		log.Println("警告: 未配置 sdogid，请通过 $BYPOS_SDOGID 环境变量、-sdogid 参数或控制台输入框指定")
+	if *sdog != "" {
+		collector.sdogID = *sdog
 	}
 
-	sub, err := fs.Sub(webFS, "web")
-	if err != nil {
-		log.Printf("错误: 无法加载内嵌 web 资源: %v", err)
-		waitExit()
-		return
-	}
+	sub, _ := fs.Sub(webFS, "web")
 	mux := http.NewServeMux()
 	mux.Handle("/", http.FileServer(http.FS(sub)))
 	mux.HandleFunc("/api/start", handleStart)
@@ -72,17 +39,10 @@ func main() {
 	mux.HandleFunc("/api/stats", handleStats)
 	mux.HandleFunc("/api/download", handleDownload)
 	mux.HandleFunc("/api/export.csv", handleExportCSV)
-	mux.HandleFunc("/api/import", handleImport)
 
 	ln, err := net.Listen("tcp", *addr)
 	if err != nil {
-		log.Printf("端口 %s 被占用，自动选择可用端口...", *addr)
-		ln, err = net.Listen("tcp", "127.0.0.1:0")
-		if err != nil {
-			log.Printf("错误: 无法监听: %v", err)
-			waitExit()
-			return
-		}
+		log.Fatalf("无法监听 %s: %v", *addr, err)
 	}
 	realAddr := ln.Addr().String()
 	urlStr := "http://" + realAddr + "/"
@@ -91,14 +51,10 @@ func main() {
 	fmt.Println(" 控制台: " + urlStr)
 	fmt.Println(" 关闭本窗口即停止程序")
 	fmt.Println("==============================================")
-	log.Printf("监听地址: %s", realAddr)
 	if !*noOpen {
 		go openBrowser(urlStr)
 	}
-	if err := http.Serve(ln, mux); err != nil {
-		log.Printf("HTTP 服务异常退出: %v", err)
-		waitExit()
-	}
+	log.Fatal(http.Serve(ln, mux))
 }
 
 func openBrowser(url string) {
@@ -171,79 +127,6 @@ func handleDownload(w http.ResponseWriter, r *http.Request) {
 	io.Copy(w, f)
 }
 
-func handleImport(w http.ResponseWriter, r *http.Request) {
-	if r.Method != "POST" {
-		http.Error(w, "method", 405)
-		return
-	}
-	var req struct {
-		APIURL   string `json:"api_url"`
-		Username string `json:"username"`
-		Password string `json:"password"`
-	}
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		writeJSON(w, 400, map[string]string{"error": "请求格式错误"})
-		return
-	}
-	req.APIURL = strings.TrimRight(req.APIURL, "/")
-	if req.APIURL == "" || req.Username == "" || req.Password == "" {
-		writeJSON(w, 400, map[string]string{"error": "请填写完整的 API 地址、用户名和密码"})
-		return
-	}
-
-	s := collector.snapshot()
-	if s.OutFile == "" {
-		writeJSON(w, 400, map[string]string{"error": "没有采集数据可导入"})
-		return
-	}
-
-	client := &http.Client{Timeout: 60 * time.Second}
-
-	loginBody, _ := json.Marshal(map[string]string{"username": req.Username, "password": req.Password})
-	loginResp, err := client.Post(req.APIURL+"/api/login", "application/json", bytes.NewReader(loginBody))
-	if err != nil {
-		writeJSON(w, 502, map[string]string{"error": "无法连接 Goods 系统: " + err.Error()})
-		return
-	}
-	defer loginResp.Body.Close()
-	var loginResult struct {
-		Token string `json:"token"`
-		Error *struct {
-			Message string `json:"message"`
-		} `json:"error"`
-	}
-	json.NewDecoder(loginResp.Body).Decode(&loginResult)
-	if loginResp.StatusCode != 200 || loginResult.Token == "" {
-		msg := "登录失败"
-		if loginResult.Error != nil {
-			msg = loginResult.Error.Message
-		}
-		writeJSON(w, 401, map[string]string{"error": msg})
-		return
-	}
-
-	jsonlData, err := os.ReadFile(s.OutFile)
-	if err != nil {
-		writeJSON(w, 500, map[string]string{"error": "读取采集文件失败: " + err.Error()})
-		return
-	}
-
-	importReq, _ := http.NewRequest("POST", req.APIURL+"/api/import/bypos", bytes.NewReader(jsonlData))
-	importReq.Header.Set("Content-Type", "application/x-ndjson")
-	importReq.Header.Set("Authorization", "Bearer "+loginResult.Token)
-	importResp, err := client.Do(importReq)
-	if err != nil {
-		writeJSON(w, 502, map[string]string{"error": "导入请求失败: " + err.Error()})
-		return
-	}
-	defer importResp.Body.Close()
-	respBody, _ := io.ReadAll(importResp.Body)
-
-	w.Header().Set("Content-Type", "application/json; charset=utf-8")
-	w.WriteHeader(importResp.StatusCode)
-	w.Write(respBody)
-}
-
 func handleExportCSV(w http.ResponseWriter, r *http.Request) {
 	s := collector.snapshot()
 	if s.OutFile == "" {
@@ -260,14 +143,14 @@ func handleExportCSV(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Disposition", "attachment; filename=products.csv")
 	w.Write([]byte{0xEF, 0xBB, 0xBF}) // UTF-8 BOM so Excel reads Chinese correctly
 	cw := csv.NewWriter(w)
-	cw.Write([]string{"barcode", "name", "spec", "unit", "area", "manufacturer", "license", "in_price", "sell_price", "status", "retmsg", "fetched_at", "source"})
+	cw.Write([]string{"barcode", "name", "spec", "unit", "area", "manufacturer", "license", "in_price", "sell_price", "status", "fetched_at"})
 	dec := json.NewDecoder(f)
 	for {
 		var p Product
 		if err := dec.Decode(&p); err != nil {
 			break
 		}
-		cw.Write([]string{p.Barcode, p.Name, p.Spec, p.Unit, p.Area, p.Manufacturer, p.License, p.InPrice, p.SellPrice, p.Status, p.RetMsg, p.FetchedAt, p.Source})
+		cw.Write([]string{p.Barcode, p.Name, p.Spec, p.Unit, p.Area, p.Manufacturer, p.License, p.InPrice, p.SellPrice, p.Status, p.FetchedAt})
 	}
 	cw.Flush()
 }

tools/bypos-collector/web/index.html

@@ -37,11 +37,6 @@
   .hit { color:#2da44e; } .miss { color:#999; } .invalid { color:#d1242f; } .error { color:#bf8700; }
   .hint { font-size:12px; color:#888; margin-top:6px; line-height:1.5; }
   .est { font-size:13px; color:#1f6feb; margin-top:6px; }
-  .history-badge { display:inline-block; background:#e8f0fe; color:#1f6feb; padding:4px 12px; border-radius:12px; font-size:13px; font-weight:600; margin-bottom:10px; }
-  .import-result { margin-top:10px; padding:10px; border-radius:6px; font-size:13px; }
-  .import-result.ok { background:#dcfce7; color:#166534; }
-  .import-result.fail { background:#fee2e2; color:#991b1b; }
-  input[type=password] { width:100%; padding:8px 10px; border:1px solid #cdd5e0; border-radius:6px; font-size:14px; }
 </style>
 </head>
 <body>
@@ -84,10 +79,6 @@
   <div class="card">
     <h3>② 采集参数</h3>
     <div class="row">
-      <div>
-        <label>中心库账号 sdogid</label>
-        <input type="text" id="sdogid" placeholder="留空则使用环境变量或启动参数"/>
-      </div>
       <div>
         <label>并发数</label>
         <input type="number" id="concurrency" value="3" min="1" max="20"/>
@@ -102,12 +93,11 @@
       </div>
     </div>
     <label style="margin-top:12px"><input type="checkbox" id="logmiss"/> 同时记录未命中/无效条码(默认只存命中)</label>
-    <div class="hint">速度越快越容易触发上游频控。建议并发 3、间隔 300ms 起步,稳定后再调。已采过的条码会自动跳过(跨次去重)。</div>
+    <div class="hint">速度越快越容易触发上游频控。建议并发 3、间隔 300ms 起步,稳定后再调。已采过的条码会自动跳过(断点续采)。</div>
   </div>
 
   <div class="card">
     <h3>③ 运行</h3>
-    <div class="history-badge" id="history-badge">历史已采集: 0 个条码</div>
     <div style="margin-bottom:12px">
       <button class="primary" id="btnStart" onclick="start()">开始采集</button>
       <button class="danger" id="btnStop" onclick="stop()" disabled>停止</button>
@@ -122,36 +112,13 @@
       <div class="stat"><div class="n miss" id="s-miss">0</div><div class="l">未命中</div></div>
       <div class="stat"><div class="n invalid" id="s-invalid">0</div><div class="l">无效</div></div>
       <div class="stat"><div class="n error" id="s-errors">0</div><div class="l">错误</div></div>
-      <div class="stat"><div class="n" id="s-skipped">0</div><div class="l">跳过(已采)</div></div>
+      <div class="stat"><div class="n" id="s-skipped">0</div><div class="l">跳过</div></div>
     </div>
     <div class="hint" id="msg"></div>
   </div>
 
   <div class="card">
-    <h3>④ 导入到 Goods 系统</h3>
-    <div class="hint" style="margin-top:0;margin-bottom:10px">采集完成后,将数据一键导入到 OpenGoods 商品档案系统。</div>
-    <div class="row">
-      <div>
-        <label>Goods 管理后台地址</label>
-        <input type="text" id="import-url" placeholder="如 http://192.168.1.100:8080/ping"/>
-      </div>
-      <div>
-        <label>管理员用户名</label>
-        <input type="text" id="import-user" placeholder="admin"/>
-      </div>
-      <div>
-        <label>管理员密码</label>
-        <input type="password" id="import-pass"/>
-      </div>
-    </div>
-    <div style="margin-top:12px">
-      <button class="primary" id="btnImport" onclick="doImport()">导入到 Goods</button>
-    </div>
-    <div id="import-result"></div>
-  </div>
-
-  <div class="card">
-    <h3>⑤ 实时结果(最近 60 条)</h3>
+    <h3>④ 实时结果(最近 60 条)</h3>
     <div style="max-height:340px; overflow:auto">
       <table>
         <thead><tr><th>条码</th><th>品名</th><th>规格</th><th>单位</th><th>产地</th><th>进价</th><th>零售价</th><th>状态</th></tr></thead>
@@ -198,7 +165,6 @@ async function start(){
     start_body: document.getElementById('start').value.trim(),
     end_body: document.getElementById('end').value.trim(),
     list: document.getElementById('list').value,
-    sdog_id: document.getElementById('sdogid').value.trim(),
     concurrency: parseInt(document.getElementById('concurrency').value)||3,
     delay_ms: parseInt(document.getElementById('delay').value)||0,
     log_miss: document.getElementById('logmiss').checked,
@@ -225,7 +191,6 @@ async function poll(){
     document.getElementById('s-skipped').textContent = s.skipped;
     let pct = s.total>0 ? Math.floor(s.done*100/s.total) : 0;
     document.getElementById('prog').style.width = pct + '%';
-    document.getElementById('history-badge').textContent = '历史已采集: ' + (s.history_count||0) + ' 个条码';
     document.getElementById('msg').textContent = (s.running? ('采集中… 当前 '+s.current) : (s.message||'空闲'));
     document.getElementById('btnStart').disabled = s.running;
     document.getElementById('btnStop').disabled = !s.running;
@@ -236,35 +201,6 @@ async function poll(){
   }catch(e){}
 }
 setInterval(poll, 1000); poll();
-
-async function doImport(){
-  let url = document.getElementById('import-url').value.trim();
-  let user = document.getElementById('import-user').value.trim();
-  let pass = document.getElementById('import-pass').value;
-  if(!url || !user || !pass){ alert('请填写完整的 Goods 系统地址、用户名和密码'); return; }
-  let btn = document.getElementById('btnImport');
-  let res = document.getElementById('import-result');
-  btn.disabled = true;
-  btn.textContent = '导入中...';
-  res.innerHTML = '';
-  try {
-    let r = await fetch('/api/import', {
-      method:'POST',
-      headers:{'Content-Type':'application/json'},
-      body:JSON.stringify({api_url:url, username:user, password:pass})
-    });
-    let j = await r.json();
-    if(j.error){
-      res.innerHTML = '<div class="import-result fail">导入失败: '+esc(j.error.message||j.error)+'</div>';
-    } else {
-      res.innerHTML = '<div class="import-result ok">导入完成: 成功 '+j.loaded+' 条, 跳过 '+j.skipped+' 条, 失败 '+j.errored+' 条</div>';
-    }
-  } catch(e){
-    res.innerHTML = '<div class="import-result fail">导入失败: '+esc(e.message)+'</div>';
-  }
-  btn.disabled = false;
-  btn.textContent = '导入到 Goods';
-}
 </script>
 </body>
 </html>