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

Search: - migration 0009: trigram GIN index on brand.name + btree on country_of_origin - SearchProducts: typo-tolerant word_similarity matching (>=0.42) on top of ILIKE substring + barcode; new brand/country filters; rank by similarity * (0.5 + quality_score). Response gains country_of_origin, quality_score and per-result relevance score. - public search UI: brand/country filter inputs; show country in results Docs: - serve embedded OpenAPI 3 spec at GET /api/v1/openapi.json (not rate limited) - ApiDocs page: auth + rate-limit section, updated search params/response - docs/api.md developer guide Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Merge pull request 'feat(api): API Key + Redis 限流 + 用量统计 (M5a)' (#7 ) from devin/1781943842-m5a-api-key-ratelimit into main
2026-06-20 09:38:27 +00:00 · 2026-06-20 16:27:13 +08:00 · 2026-06-20 08:24:07 +00:00 · 2026-06-20 15:54:07 +08:00 · 2026-06-20 15:53:43 +08:00 · 2026-06-20 07:33:10 +00:00
129 changed files with 16501 additions and 34 deletions
@@ -0,0 +1,14 @@
+.git
+**/node_modules
+admin-frontend/dist
+public-frontend/dist
+api/server
+*.test
+*.out
+__pycache__
+.venv
+.pytest_cache
+.ruff_cache
+.env
+.env.*
+!.env.example
@@ -0,0 +1,12 @@
+# Copy to .env and fill in real values before running docker-compose.prod.yml.
+# Used by docker-compose.prod.yml for production deployment.
+POSTGRES_USER=opengoods
+POSTGRES_PASSWORD=change-me
+POSTGRES_DB=opengoods
+MINIO_ROOT_USER=opengoods
+MINIO_ROOT_PASSWORD=change-me
+
+# Admin console (served at /ping). Set a strong password and a random JWT secret.
+GOODS_ADMIN_USER=admin
+GOODS_ADMIN_PASSWORD=change-me
+GOODS_ADMIN_JWT_SECRET=change-me-to-a-long-random-string
@@ -12,12 +12,29 @@ jobs:
    defaults:
      run:
        working-directory: api
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: opengoods
+          POSTGRES_PASSWORD: opengoods
+          POSTGRES_DB: opengoods
+        options: >-
+          --health-cmd "pg_isready -U opengoods"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+    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: Apply migrations
+        working-directory: .
+        run: |
+          go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
+          migrate -path migrations -database "$OPENGOODS_DATABASE_URL" up
      - name: Verify gofmt
        run: test -z "$(gofmt -l .)"
      - run: go vet ./...
@@ -43,3 +60,30 @@ jobs:
        run: ruff format --check .
      - name: Pytest
        run: pytest -q
+
+  migrations:
+    name: Migrations (postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: opengoods
+          POSTGRES_PASSWORD: opengoods
+          POSTGRES_DB: opengoods
+        options: >-
+          --health-cmd "pg_isready -U opengoods"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+    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: Install golang-migrate
+        run: go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.18.1
+      - name: Migrate up
+        run: migrate -path migrations -database "$DBURL" up
+      - name: Migrate down (reversibility)
+        run: migrate -path migrations -database "$DBURL" down -all
@@ -18,6 +18,15 @@ dist/
 .env.*
 !.env.example

+# Node / admin frontend
+node_modules/
+
+# Keep the embedded SPA placeholders (real builds are injected during Docker build)
+!api/internal/adminweb/dist/
+!api/internal/adminweb/dist/index.html
+!api/internal/publicweb/dist/
+!api/internal/publicweb/dist/index.html
+
 # OS / editors
 .DS_Store
 *.swp
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>天工商品档案公共仓 · 管理后台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
@@ -0,0 +1,26 @@
+{
+  "name": "opengoods-admin-frontend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "lucide-react": "^0.344.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.55",
+    "@types/react-dom": "^18.2.19",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.17",
+    "postcss": "^8.4.35",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.1.0"
+  }
+}
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
@@ -0,0 +1,138 @@
+import { useEffect, useState } from "react";
+import { api, clearToken, getToken } from "./api";
+import Login from "./components/Login";
+import ProductList from "./components/ProductList";
+import ProductDetail from "./components/ProductDetail";
+import SubmissionsPage from "./components/SubmissionsPage";
+import ApiKeysPage from "./components/ApiKeysPage";
+import { Inbox, KeyRound, LogOut, Package } from "lucide-react";
+
+type Tab = "products" | "submissions" | "keys";
+type View = { name: "list" } | { name: "detail"; id: string };
+
+export default function App() {
+  const [authed, setAuthed] = useState(false);
+  const [checking, setChecking] = useState(true);
+  const [username, setUsername] = useState("");
+  const [tab, setTab] = useState<Tab>("products");
+  const [pending, setPending] = useState<number | null>(null);
+  const [view, setView] = useState<View>({ name: "list" });
+
+  useEffect(() => {
+    if (!authed) return;
+    api
+      .listSubmissions("pending", 1, 1)
+      .then((r) => setPending(r.pending))
+      .catch(() => undefined);
+  }, [authed]);
+
+  useEffect(() => {
+    if (!getToken()) {
+      setChecking(false);
+      return;
+    }
+    api
+      .me()
+      .then((r) => {
+        setUsername(r.username);
+        setAuthed(true);
+      })
+      .catch(() => clearToken())
+      .finally(() => setChecking(false));
+  }, []);
+
+  function onLoggedIn(name: string) {
+    setUsername(name);
+    setAuthed(true);
+    setView({ name: "list" });
+  }
+
+  function logout() {
+    clearToken();
+    setAuthed(false);
+    setUsername("");
+  }
+
+  if (checking) {
+    return (
+      <div className="flex h-full items-center justify-center text-gray-500">
+        加载中…
+      </div>
+    );
+  }
+
+  if (!authed) return <Login onLoggedIn={onLoggedIn} />;
+
+  return (
+    <div className="flex h-full flex-col">
+      <header className="flex items-center justify-between bg-white px-6 py-3 shadow-sm">
+        <div className="flex items-center gap-6">
+          <div className="flex items-center gap-2 text-lg font-semibold text-gray-800">
+            <Package className="h-5 w-5 text-emerald-600" />
+            天工商品档案公共仓 · 后台
+          </div>
+          <nav className="flex items-center gap-1 text-sm">
+            <button
+              onClick={() => {
+                setTab("products");
+                setView({ name: "list" });
+              }}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "products"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <Package className="h-4 w-4" /> 商品档案
+            </button>
+            <button
+              onClick={() => setTab("submissions")}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "submissions"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <Inbox className="h-4 w-4" /> 待审核投稿
+              {pending != null && pending > 0 && (
+                <span className="ml-1 text-xs bg-amber-500 text-white rounded-full px-1.5">
+                  {pending}
+                </span>
+              )}
+            </button>
+            <button
+              onClick={() => setTab("keys")}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "keys"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <KeyRound className="h-4 w-4" /> API 密钥
+            </button>
+          </nav>
+        </div>
+        <div className="flex items-center gap-4 text-sm text-gray-600">
+          <span>{username}</span>
+          <button
+            onClick={logout}
+            className="flex items-center gap-1 rounded px-2 py-1 text-gray-500 hover:bg-gray-100 hover:text-gray-800"
+          >
+            <LogOut className="h-4 w-4" /> 退出
+          </button>
+        </div>
+      </header>
+      <main className="flex-1 overflow-auto p-6">
+        {tab === "keys" ? (
+          <ApiKeysPage />
+        ) : tab === "submissions" ? (
+          <SubmissionsPage onPending={setPending} />
+        ) : view.name === "list" ? (
+          <ProductList onOpen={(id) => setView({ name: "detail", id })} />
+        ) : (
+          <ProductDetail id={view.id} onBack={() => setView({ name: "list" })} />
+        )}
+      </main>
+    </div>
+  );
+}
@@ -0,0 +1,140 @@
+// API base derives from Vite's BASE_URL (/ping/) so it matches the nginx prefix.
+const API_BASE = `${import.meta.env.BASE_URL}api`;
+const TOKEN_KEY = "opengoods_admin_token";
+
+export function getToken(): string | null {
+  return localStorage.getItem(TOKEN_KEY);
+}
+
+export function setToken(token: string) {
+  localStorage.setItem(TOKEN_KEY, token);
+}
+
+export function clearToken() {
+  localStorage.removeItem(TOKEN_KEY);
+}
+
+export class ApiError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...(options.headers as Record<string, string>),
+  };
+  const token = getToken();
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const res = await fetch(`${API_BASE}${path}`, { ...options, headers });
+  if (res.status === 401) {
+    clearToken();
+    throw new ApiError(401, "登录已过期，请重新登录");
+  }
+  const text = await res.text();
+  const data = text ? JSON.parse(text) : null;
+  if (!res.ok) {
+    const msg = data?.error?.message || `请求失败 (${res.status})`;
+    throw new ApiError(res.status, msg);
+  }
+  return data as T;
+}
+
+export const api = {
+  login: (username: string, password: string) =>
+    request<{ token: string; username: string }>("/login", {
+      method: "POST",
+      body: JSON.stringify({ username, password }),
+    }),
+  me: () => request<{ username: string }>("/me"),
+  listProducts: (q: string, page: number, size: number) =>
+    request<{
+      items: import("./types").ProductRow[];
+      page: number;
+      size: number;
+      total: number;
+      completeness_fields: string[];
+    }>(`/products?q=${encodeURIComponent(q)}&page=${page}&size=${size}`),
+  getProduct: (id: string) =>
+    request<import("./types").ProductDetail>(`/products/${id}`),
+  updateProduct: (id: string, body: unknown) =>
+    request<import("./types").ProductDetail>(`/products/${id}`, {
+      method: "PUT",
+      body: JSON.stringify(body),
+    }),
+  listAudit: (id: string) =>
+    request<{ items: import("./types").AuditEntry[] }>(`/products/${id}/audit`),
+  addImage: (id: string, url: string, kind: string) =>
+    request<import("./types").ProductImage>(`/products/${id}/images`, {
+      method: "POST",
+      body: JSON.stringify({ url, kind }),
+    }),
+  deleteImage: (id: string, imageId: string) =>
+    request<{ status: string }>(`/products/${id}/images/${imageId}`, {
+      method: "DELETE",
+    }),
+  addMsrp: (id: string, body: unknown) =>
+    request<import("./types").MSRP>(`/products/${id}/msrp`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  deleteMsrp: (id: string, msrpId: string) =>
+    request<{ status: string }>(`/products/${id}/msrp/${msrpId}`, {
+      method: "DELETE",
+    }),
+  addBarcode: (id: string, body: unknown) =>
+    request<import("./types").Barcode>(`/products/${id}/barcodes`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  deleteBarcode: (id: string, barcodeId: string) =>
+    request<{ status: string }>(`/products/${id}/barcodes/${barcodeId}`, {
+      method: "DELETE",
+    }),
+  setPrimaryBarcode: (id: string, barcodeId: string) =>
+    request<import("./types").Barcode>(
+      `/products/${id}/barcodes/${barcodeId}/primary`,
+      { method: "POST" },
+    ),
+  listBrands: () =>
+    request<{ items: import("./types").Brand[] }>("/brands"),
+  listCategories: () =>
+    request<{ items: import("./types").Category[] }>("/categories"),
+  listSubmissions: (status: string, page: number, size: number) =>
+    request<{
+      items: import("./types").SubmissionRow[];
+      page: number;
+      size: number;
+      total: number;
+      pending: number;
+    }>(`/submissions?status=${encodeURIComponent(status)}&page=${page}&size=${size}`),
+  getSubmission: (id: string) =>
+    request<import("./types").SubmissionDetail>(`/submissions/${id}`),
+  approveSubmission: (id: string) =>
+    request<import("./types").ProductDetail>(`/submissions/${id}/approve`, {
+      method: "POST",
+    }),
+  rejectSubmission: (id: string, note: string) =>
+    request<{ status: string }>(`/submissions/${id}/reject`, {
+      method: "POST",
+      body: JSON.stringify({ note }),
+    }),
+  listApiKeys: () =>
+    request<{ items: import("./types").ApiKey[] }>("/keys"),
+  createApiKey: (body: {
+    name: string;
+    owner_email?: string;
+    tier?: string;
+    rate_limit_per_min?: number;
+  }) =>
+    request<{ key: string; item: import("./types").ApiKey; warning: string }>(
+      "/keys",
+      { method: "POST", body: JSON.stringify(body) },
+    ),
+  revokeApiKey: (id: string) =>
+    request<{ status: string }>(`/keys/${id}`, { method: "DELETE" }),
+};
@@ -0,0 +1,278 @@
+import { useEffect, useState } from "react";
+import { api, ApiError } from "../api";
+import type { ApiKey } from "../types";
+import { Copy, KeyRound, Plus, Trash2 } from "lucide-react";
+
+const TIERS = [
+  { key: "free", label: "免费 (free)", rate: 120 },
+  { key: "partner", label: "合作方 (partner)", rate: 600 },
+  { key: "internal", label: "内部 (internal)", rate: 6000 },
+];
+
+function tierLabel(tier: string): string {
+  return TIERS.find((t) => t.key === tier)?.label ?? tier;
+}
+
+export default function ApiKeysPage() {
+  const [rows, setRows] = useState<ApiKey[]>([]);
+  const [error, setError] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [newKey, setNewKey] = useState<string | null>(null);
+
+  async function load() {
+    setError("");
+    try {
+      const res = await api.listApiKeys();
+      setRows(res.items);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "加载失败");
+    }
+  }
+
+  useEffect(() => {
+    load();
+  }, []);
+
+  async function revoke(id: string, name: string) {
+    if (!confirm(`确认吊销密钥「${name}」？使用该密钥的请求将立即被拒绝。`)) return;
+    try {
+      await api.revokeApiKey(id);
+      await load();
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "操作失败");
+    }
+  }
+
+  return (
+    <div className="max-w-4xl">
+      <div className="flex items-center justify-between mb-4">
+        <div>
+          <h2 className="text-lg font-semibold text-gray-800 flex items-center gap-2">
+            <KeyRound className="h-5 w-5 text-emerald-600" /> API 密钥
+          </h2>
+          <p className="text-sm text-gray-500 mt-1">
+            公开 API 免费只读，匿名也可调用（低额度）。签发密钥可获得更高速率上限并归属用量。
+          </p>
+        </div>
+        <button
+          onClick={() => setCreating(true)}
+          className="px-4 py-2 rounded-lg bg-emerald-600 text-white text-sm font-medium hover:bg-emerald-700 flex items-center gap-1.5"
+        >
+          <Plus className="h-4 w-4" /> 签发密钥
+        </button>
+      </div>
+
+      {error && (
+        <div className="mb-3 bg-red-50 text-red-700 text-sm rounded px-4 py-2">{error}</div>
+      )}
+
+      {newKey && (
+        <div className="mb-4 bg-amber-50 border border-amber-200 rounded-lg p-4">
+          <div className="text-sm font-medium text-amber-800 mb-1">
+            密钥已生成，请立即复制保存——它只显示这一次。
+          </div>
+          <div className="flex items-center gap-2">
+            <code className="flex-1 bg-white border rounded px-3 py-2 text-sm break-all">
+              {newKey}
+            </code>
+            <button
+              onClick={() => navigator.clipboard?.writeText(newKey)}
+              className="px-3 py-2 rounded border text-sm text-gray-600 hover:bg-gray-50 flex items-center gap-1"
+            >
+              <Copy className="h-4 w-4" /> 复制
+            </button>
+            <button
+              onClick={() => setNewKey(null)}
+              className="px-3 py-2 rounded text-sm text-gray-500 hover:bg-gray-100"
+            >
+              我已保存
+            </button>
+          </div>
+        </div>
+      )}
+
+      {creating && (
+        <CreateKeyForm
+          onClose={() => setCreating(false)}
+          onCreated={(plaintext) => {
+            setCreating(false);
+            setNewKey(plaintext);
+            load();
+          }}
+        />
+      )}
+
+      <div className="bg-white border rounded-lg overflow-hidden">
+        <table className="w-full text-sm">
+          <thead className="bg-gray-50 text-gray-500 text-left">
+            <tr>
+              <th className="px-4 py-2 font-medium">名称</th>
+              <th className="px-4 py-2 font-medium">前缀</th>
+              <th className="px-4 py-2 font-medium">级别</th>
+              <th className="px-4 py-2 font-medium">速率/分钟</th>
+              <th className="px-4 py-2 font-medium">用量(今日/累计)</th>
+              <th className="px-4 py-2 font-medium">状态</th>
+              <th className="px-4 py-2 font-medium"></th>
+            </tr>
+          </thead>
+          <tbody className="divide-y">
+            {rows.length === 0 ? (
+              <tr>
+                <td colSpan={7} className="px-4 py-8 text-center text-gray-400">
+                  暂无密钥
+                </td>
+              </tr>
+            ) : (
+              rows.map((k) => (
+                <tr key={k.id} className={k.revoked_at ? "opacity-50" : ""}>
+                  <td className="px-4 py-2 text-gray-800">
+                    {k.name}
+                    {k.owner_email && (
+                      <span className="block text-xs text-gray-400">{k.owner_email}</span>
+                    )}
+                  </td>
+                  <td className="px-4 py-2 text-gray-500">
+                    <code>{k.key_prefix}…</code>
+                  </td>
+                  <td className="px-4 py-2 text-gray-600">{tierLabel(k.tier)}</td>
+                  <td className="px-4 py-2 text-gray-600">{k.rate_limit_per_min}</td>
+                  <td className="px-4 py-2 text-gray-600">
+                    {k.usage.today} / {k.usage.total}
+                  </td>
+                  <td className="px-4 py-2">
+                    {k.revoked_at ? (
+                      <span className="text-xs rounded px-2 py-0.5 bg-red-50 text-red-700">
+                        已吊销
+                      </span>
+                    ) : (
+                      <span className="text-xs rounded px-2 py-0.5 bg-emerald-50 text-emerald-700">
+                        启用中
+                      </span>
+                    )}
+                  </td>
+                  <td className="px-4 py-2 text-right">
+                    {!k.revoked_at && (
+                      <button
+                        onClick={() => revoke(k.id, k.name)}
+                        className="text-gray-400 hover:text-red-600"
+                        title="吊销"
+                      >
+                        <Trash2 className="h-4 w-4" />
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}
+
+function CreateKeyForm({
+  onClose,
+  onCreated,
+}: {
+  onClose: () => void;
+  onCreated: (plaintext: string) => void;
+}) {
+  const [name, setName] = useState("");
+  const [ownerEmail, setOwnerEmail] = useState("");
+  const [tier, setTier] = useState("free");
+  const [rate, setRate] = useState(120);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+
+  function pickTier(t: string) {
+    setTier(t);
+    const def = TIERS.find((x) => x.key === t);
+    if (def) setRate(def.rate);
+  }
+
+  async function submit() {
+    if (!name.trim()) {
+      setError("名称不能为空");
+      return;
+    }
+    setBusy(true);
+    setError("");
+    try {
+      const res = await api.createApiKey({
+        name: name.trim(),
+        owner_email: ownerEmail.trim() || undefined,
+        tier,
+        rate_limit_per_min: rate,
+      });
+      onCreated(res.key);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "创建失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="mb-4 bg-white border rounded-lg p-5">
+      <h3 className="font-medium text-gray-700 mb-3">签发新密钥</h3>
+      {error && <div className="mb-3 bg-red-50 text-red-700 text-sm rounded px-3 py-2">{error}</div>}
+      <div className="grid grid-cols-2 gap-4">
+        <label className="block">
+          <span className="text-xs text-gray-500">名称 *</span>
+          <input
+            className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            placeholder="例如：我的 App / 合作方 X"
+          />
+        </label>
+        <label className="block">
+          <span className="text-xs text-gray-500">负责人邮箱（可选）</span>
+          <input
+            className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+            value={ownerEmail}
+            onChange={(e) => setOwnerEmail(e.target.value)}
+            placeholder="owner@example.com"
+          />
+        </label>
+        <label className="block">
+          <span className="text-xs text-gray-500">级别</span>
+          <select
+            className="w-full border rounded-md px-3 py-2 text-sm mt-1 bg-white"
+            value={tier}
+            onChange={(e) => pickTier(e.target.value)}
+          >
+            {TIERS.map((t) => (
+              <option key={t.key} value={t.key}>
+                {t.label}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="block">
+          <span className="text-xs text-gray-500">速率上限（次/分钟）</span>
+          <input
+            type="number"
+            min={1}
+            className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+            value={rate}
+            onChange={(e) => setRate(Math.max(1, parseInt(e.target.value || "1", 10)))}
+          />
+        </label>
+      </div>
+      <div className="mt-4 flex gap-2">
+        <button
+          onClick={submit}
+          disabled={busy}
+          className="px-4 py-2 rounded bg-emerald-600 text-white text-sm hover:bg-emerald-700 disabled:opacity-60"
+        >
+          生成
+        </button>
+        <button onClick={onClose} className="px-4 py-2 rounded border text-sm text-gray-600">
+          取消
+        </button>
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,75 @@
+import { useState } from "react";
+import { api, setToken } from "../api";
+import { Package } from "lucide-react";
+
+export default function Login({
+  onLoggedIn,
+}: {
+  onLoggedIn: (username: string) => void;
+}) {
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState("");
+  const [loading, setLoading] = useState(false);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError("");
+    setLoading(true);
+    try {
+      const r = await api.login(username, password);
+      setToken(r.token);
+      onLoggedIn(r.username);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "登录失败");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div className="flex h-full items-center justify-center">
+      <form
+        onSubmit={submit}
+        className="w-80 rounded-xl bg-white p-8 shadow-md"
+      >
+        <div className="mb-6 flex flex-col items-center gap-2">
+          <Package className="h-8 w-8 text-emerald-600" />
+          <h1 className="text-lg font-semibold text-gray-800">
+            天工商品档案公共仓 · 管理后台
+          </h1>
+        </div>
+        {error && (
+          <div className="mb-4 rounded bg-red-50 px-3 py-2 text-sm text-red-600">
+            {error}
+          </div>
+        )}
+        <label className="mb-3 block">
+          <span className="mb-1 block text-sm text-gray-600">用户名</span>
+          <input
+            value={username}
+            onChange={(e) => setUsername(e.target.value)}
+            className="w-full rounded border border-gray-300 px-3 py-2 text-sm focus:border-emerald-500 focus:outline-none"
+            autoFocus
+          />
+        </label>
+        <label className="mb-5 block">
+          <span className="mb-1 block text-sm text-gray-600">密码</span>
+          <input
+            type="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            className="w-full rounded border border-gray-300 px-3 py-2 text-sm focus:border-emerald-500 focus:outline-none"
+          />
+        </label>
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full rounded bg-emerald-600 py-2 text-sm font-medium text-white hover:bg-emerald-700 disabled:opacity-60"
+        >
+          {loading ? "登录中…" : "登录"}
+        </button>
+      </form>
+    </div>
+  );
+}
@@ -0,0 +1,806 @@
+import { useEffect, useMemo, useState } from "react";
+import { api } from "../api";
+import {
+  AuditEntry,
+  Brand,
+  Category,
+  FIELD_LABELS,
+  ProductDetail as Detail,
+} from "../types";
+import {
+  ArrowLeft,
+  Plus,
+  Save,
+  Trash2,
+  AlertCircle,
+  History,
+  Star,
+} from "lucide-react";
+
+const GTIN_TYPES = ["EAN13", "EAN8", "UPC", "ITF14", "GTIN14"];
+const PACK_LEVELS: { value: string; label: string }[] = [
+  { value: "each", label: "消费单元" },
+  { value: "case", label: "箱" },
+  { value: "pallet", label: "托盘" },
+];
+
+const NUTRIMENT_KEYS: { key: string; label: string }[] = [
+  { key: "energy_kcal", label: "能量 (kcal)" },
+  { key: "energy_kj", label: "能量 (kJ)" },
+  { key: "fat", label: "脂肪 (g)" },
+  { key: "saturated_fat", label: "饱和脂肪 (g)" },
+  { key: "carbohydrates", label: "碳水 (g)" },
+  { key: "sugars", label: "糖 (g)" },
+  { key: "proteins", label: "蛋白质 (g)" },
+  { key: "salt", label: "盐 (g)" },
+];
+
+const STATUS_OPTIONS = [
+  { value: "active", label: "在用" },
+  { value: "merged", label: "已合并" },
+  { value: "deprecated", label: "已停用" },
+];
+
+const ACTION_LABEL: Record<string, string> = {
+  update: "编辑",
+  add_image: "新增图片",
+  delete_image: "删除图片",
+  add_msrp: "新增建议零售价",
+  delete_msrp: "删除建议零售价",
+  add_barcode: "新增条码",
+  delete_barcode: "删除条码",
+  set_primary_barcode: "设为主条码",
+};
+
+function Card({
+  title,
+  children,
+}: {
+  title: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-5">
+      <h3 className="mb-4 text-sm font-semibold text-gray-700">{title}</h3>
+      {children}
+    </div>
+  );
+}
+
+function Field({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <label className="block">
+      <span className="mb-1 block text-xs text-gray-500">{label}</span>
+      {children}
+    </label>
+  );
+}
+
+const inputCls =
+  "w-full rounded border border-gray-300 px-3 py-2 text-sm focus:border-emerald-500 focus:outline-none";
+
+export default function ProductDetail({
+  id,
+  onBack,
+}: {
+  id: string;
+  onBack: () => void;
+}) {
+  const [d, setD] = useState<Detail | null>(null);
+  const [brands, setBrands] = useState<Brand[]>([]);
+  const [categories, setCategories] = useState<Category[]>([]);
+  const [audit, setAudit] = useState<AuditEntry[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [msg, setMsg] = useState("");
+  const [error, setError] = useState("");
+
+  // editable form state
+  const [name, setName] = useState("");
+  const [gtin, setGtin] = useState("");
+  const [brandName, setBrandName] = useState("");
+  const [categoryId, setCategoryId] = useState("");
+  const [netValue, setNetValue] = useState("");
+  const [netUnit, setNetUnit] = useState("");
+  const [country, setCountry] = useState("");
+  const [status, setStatus] = useState("active");
+  const [ingredients, setIngredients] = useState("");
+  const [allergens, setAllergens] = useState("");
+  const [additives, setAdditives] = useState("");
+  const [nutriments, setNutriments] = useState<Record<string, string>>({});
+  const [basis, setBasis] = useState("");
+  const [serving, setServing] = useState("");
+  const [nutriScore, setNutriScore] = useState("");
+
+  function hydrate(detail: Detail) {
+    setD(detail);
+    setName(detail.name);
+    setGtin(detail.gtin || "");
+    setBrandName(detail.brand || "");
+    setCategoryId(detail.category_id || "");
+    setNetValue(detail.net_content_value?.toString() || "");
+    setNetUnit(detail.net_content_unit || "");
+    setCountry(detail.country_of_origin || "");
+    setStatus(detail.status);
+    setIngredients(detail.ingredients_text || "");
+    setAllergens(detail.allergens.join(", "));
+    setAdditives(detail.additives.join(", "));
+    const nm: Record<string, string> = {};
+    if (detail.nutriments) {
+      for (const [k, v] of Object.entries(detail.nutriments)) nm[k] = String(v);
+    }
+    setNutriments(nm);
+    setBasis(detail.nutrition_basis || "");
+    setServing(detail.serving_size || "");
+    setNutriScore(detail.nutri_score || "");
+  }
+
+  function reload() {
+    setLoading(true);
+    Promise.all([api.getProduct(id), api.listAudit(id)])
+      .then(([detail, a]) => {
+        hydrate(detail);
+        setAudit(a.items);
+      })
+      .catch((e) => setError(e.message))
+      .finally(() => setLoading(false));
+  }
+
+  useEffect(() => {
+    reload();
+    api.listBrands().then((r) => setBrands(r.items)).catch(() => {});
+    api.listCategories().then((r) => setCategories(r.items)).catch(() => {});
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [id]);
+
+  const missing = useMemo(() => d?.missing ?? [], [d]);
+
+  function parseList(s: string): string[] {
+    return s
+      .split(",")
+      .map((x) => x.trim())
+      .filter(Boolean);
+  }
+
+  async function save() {
+    setSaving(true);
+    setMsg("");
+    setError("");
+    const nm: Record<string, number> = {};
+    for (const [k, v] of Object.entries(nutriments)) {
+      const n = parseFloat(v);
+      if (!Number.isNaN(n)) nm[k] = n;
+    }
+    const body = {
+      gtin: gtin.trim() || null,
+      name: name.trim(),
+      brand_name: brandName.trim() || null,
+      brand_id: brandName.trim() ? undefined : null,
+      category_id: categoryId || null,
+      net_content_value: netValue.trim() ? parseFloat(netValue) : null,
+      net_content_unit: netUnit.trim() || null,
+      country_of_origin: country.trim() || null,
+      status,
+      ingredients_text: ingredients.trim() || null,
+      allergens: parseList(allergens),
+      additives: parseList(additives),
+      nutriments: nm,
+      nutrition_basis: basis || null,
+      serving_size: serving.trim() || null,
+      nutri_score: nutriScore || null,
+    };
+    try {
+      const updated = await api.updateProduct(id, body);
+      hydrate(updated);
+      const a = await api.listAudit(id);
+      setAudit(a.items);
+      setMsg("已保存");
+      setTimeout(() => setMsg(""), 2500);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "保存失败");
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (loading) {
+    return <div className="text-gray-400">加载中…</div>;
+  }
+  if (!d) {
+    return (
+      <div>
+        <button onClick={onBack} className="text-emerald-600">
+          返回
+        </button>
+        <p className="mt-4 text-red-600">{error || "未找到商品"}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="mx-auto max-w-5xl space-y-5">
+      <div className="flex items-center justify-between">
+        <button
+          onClick={onBack}
+          className="flex items-center gap-1 text-sm text-gray-600 hover:text-gray-900"
+        >
+          <ArrowLeft className="h-4 w-4" /> 返回列表
+        </button>
+        <div className="flex items-center gap-3">
+          {msg && <span className="text-sm text-emerald-600">{msg}</span>}
+          {error && <span className="text-sm text-red-600">{error}</span>}
+          <span className="text-xs text-gray-400">
+            质量分 {Math.round(d.quality_score * 100)}
+          </span>
+          <button
+            onClick={save}
+            disabled={saving}
+            className="flex items-center gap-1 rounded bg-emerald-600 px-4 py-2 text-sm text-white hover:bg-emerald-700 disabled:opacity-60"
+          >
+            <Save className="h-4 w-4" /> {saving ? "保存中…" : "保存"}
+          </button>
+        </div>
+      </div>
+
+      {missing.length > 0 && (
+        <div className="flex items-center gap-2 rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-700">
+          <AlertCircle className="h-4 w-4" />
+          待补全字段：{missing.map((f) => FIELD_LABELS[f] || f).join("、")}
+        </div>
+      )}
+
+      <Card title="基础信息">
+        <div className="grid grid-cols-2 gap-4">
+          <Field label="名称 *">
+            <input
+              className={inputCls}
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+            />
+          </Field>
+          <Field label="条码 (GTIN)">
+            <input
+              className={inputCls}
+              value={gtin}
+              onChange={(e) => setGtin(e.target.value)}
+            />
+          </Field>
+          <Field label="品牌（不存在将自动创建）">
+            <input
+              className={inputCls}
+              list="brand-list"
+              value={brandName}
+              onChange={(e) => setBrandName(e.target.value)}
+            />
+            <datalist id="brand-list">
+              {brands.map((b) => (
+                <option key={b.id} value={b.name} />
+              ))}
+            </datalist>
+          </Field>
+          <Field label="品类">
+            <select
+              className={inputCls}
+              value={categoryId}
+              onChange={(e) => setCategoryId(e.target.value)}
+            >
+              <option value="">（未分类）</option>
+              {categories.map((c) => (
+                <option key={c.id} value={c.id}>
+                  {"\u00A0".repeat(c.level * 2)}
+                  {c.name_zh} ({c.path})
+                </option>
+              ))}
+            </select>
+          </Field>
+          <Field label="净含量">
+            <input
+              className={inputCls}
+              type="number"
+              step="any"
+              value={netValue}
+              onChange={(e) => setNetValue(e.target.value)}
+            />
+          </Field>
+          <Field label="净含量单位 (g/ml/cl…)">
+            <input
+              className={inputCls}
+              value={netUnit}
+              onChange={(e) => setNetUnit(e.target.value)}
+            />
+          </Field>
+          <Field label="产地">
+            <input
+              className={inputCls}
+              value={country}
+              onChange={(e) => setCountry(e.target.value)}
+            />
+          </Field>
+          <Field label="状态">
+            <select
+              className={inputCls}
+              value={status}
+              onChange={(e) => setStatus(e.target.value)}
+            >
+              {STATUS_OPTIONS.map((o) => (
+                <option key={o.value} value={o.value}>
+                  {o.label}
+                </option>
+              ))}
+            </select>
+          </Field>
+        </div>
+      </Card>
+
+      <Card title="配料与营养">
+        <div className="mb-4 grid grid-cols-2 gap-4">
+          <Field label="配料表">
+            <textarea
+              className={inputCls}
+              rows={3}
+              value={ingredients}
+              onChange={(e) => setIngredients(e.target.value)}
+            />
+          </Field>
+          <div className="grid grid-cols-2 gap-4">
+            <Field label="过敏原（逗号分隔）">
+              <input
+                className={inputCls}
+                value={allergens}
+                onChange={(e) => setAllergens(e.target.value)}
+              />
+            </Field>
+            <Field label="添加剂（逗号分隔）">
+              <input
+                className={inputCls}
+                value={additives}
+                onChange={(e) => setAdditives(e.target.value)}
+              />
+            </Field>
+            <Field label="营养基准">
+              <select
+                className={inputCls}
+                value={basis}
+                onChange={(e) => setBasis(e.target.value)}
+              >
+                <option value="">（未设置）</option>
+                <option value="per_100g">每 100g</option>
+                <option value="per_100ml">每 100ml</option>
+                <option value="per_serving">每份</option>
+              </select>
+            </Field>
+            <Field label="份量">
+              <input
+                className={inputCls}
+                value={serving}
+                onChange={(e) => setServing(e.target.value)}
+              />
+            </Field>
+            <Field label="Nutri-Score (A-E)">
+              <input
+                className={inputCls}
+                maxLength={1}
+                value={nutriScore}
+                onChange={(e) =>
+                  setNutriScore(e.target.value.toUpperCase())
+                }
+              />
+            </Field>
+          </div>
+        </div>
+        <div className="grid grid-cols-4 gap-3">
+          {NUTRIMENT_KEYS.map((n) => (
+            <Field key={n.key} label={n.label}>
+              <input
+                className={inputCls}
+                type="number"
+                step="any"
+                value={nutriments[n.key] ?? ""}
+                onChange={(e) =>
+                  setNutriments((prev) => ({ ...prev, [n.key]: e.target.value }))
+                }
+              />
+            </Field>
+          ))}
+        </div>
+      </Card>
+
+      <BarcodesCard product={d} onChange={reload} onError={setError} />
+      <ImagesCard
+        product={d}
+        onChange={reload}
+        onError={setError}
+      />
+      <MsrpCard product={d} onChange={reload} onError={setError} />
+
+      <Card title="操作记录">
+        {audit.length === 0 ? (
+          <p className="text-sm text-gray-400">暂无记录</p>
+        ) : (
+          <ul className="space-y-2 text-sm">
+            {audit.map((a) => (
+              <li
+                key={a.id}
+                className="flex items-center gap-3 text-gray-600"
+              >
+                <History className="h-3.5 w-3.5 text-gray-400" />
+                <span className="text-gray-400">{a.created_at}</span>
+                <span className="font-medium text-gray-700">{a.actor}</span>
+                <span>{ACTION_LABEL[a.action] || a.action}</span>
+                {a.fields.length > 0 && (
+                  <span className="text-gray-400">
+                    [{a.fields.map((f) => FIELD_LABELS[f] || f).join("、")}]
+                  </span>
+                )}
+              </li>
+            ))}
+          </ul>
+        )}
+      </Card>
+    </div>
+  );
+}
+
+function BarcodesCard({
+  product,
+  onChange,
+  onError,
+}: {
+  product: Detail;
+  onChange: () => void;
+  onError: (m: string) => void;
+}) {
+  const [gtin, setGtin] = useState("");
+  const [gtinType, setGtinType] = useState("EAN13");
+  const [packLevel, setPackLevel] = useState("each");
+  const [region, setRegion] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  async function add() {
+    if (!gtin.trim()) return;
+    setBusy(true);
+    try {
+      await api.addBarcode(product.id, {
+        gtin: gtin.trim(),
+        gtin_type: gtinType,
+        pack_level: packLevel,
+        region: region.trim() || null,
+        is_primary: false,
+      });
+      setGtin("");
+      setRegion("");
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "添加失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+  async function remove(barcodeId: string) {
+    try {
+      await api.deleteBarcode(product.id, barcodeId);
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "删除失败");
+    }
+  }
+  async function makePrimary(barcodeId: string) {
+    try {
+      await api.setPrimaryBarcode(product.id, barcodeId);
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "设置失败");
+    }
+  }
+
+  return (
+    <Card title="条码（一品多码，主条码镜像到 GTIN）">
+      <div className="mb-3 space-y-2">
+        {product.barcodes.length === 0 && (
+          <span className="text-sm text-gray-400">暂无条码</span>
+        )}
+        {product.barcodes.map((b) => (
+          <div
+            key={b.id}
+            className="flex items-center gap-3 rounded border border-gray-100 bg-gray-50 px-3 py-2 text-sm"
+          >
+            <button
+              onClick={() => !b.is_primary && makePrimary(b.id)}
+              title={b.is_primary ? "主条码" : "设为主条码"}
+              disabled={b.is_primary}
+              className={
+                b.is_primary
+                  ? "text-amber-500"
+                  : "text-gray-300 hover:text-amber-500"
+              }
+            >
+              <Star
+                className="h-4 w-4"
+                fill={b.is_primary ? "currentColor" : "none"}
+              />
+            </button>
+            <span className="font-mono font-medium text-gray-800">
+              {b.gtin}
+            </span>
+            <span className="rounded bg-gray-200 px-1.5 py-0.5 text-[11px] text-gray-600">
+              {b.gtin_type}
+            </span>
+            <span className="text-gray-500">
+              {PACK_LEVELS.find((p) => p.value === b.pack_level)?.label ||
+                b.pack_level}
+            </span>
+            <span className="flex-1 text-gray-400">{b.region || ""}</span>
+            <button
+              onClick={() => remove(b.id)}
+              className="text-gray-400 hover:text-red-600"
+            >
+              <Trash2 className="h-4 w-4" />
+            </button>
+          </div>
+        ))}
+      </div>
+      <div className="flex flex-wrap items-end gap-2">
+        <Field label="条码 (GTIN)">
+          <input
+            className="w-44 rounded border border-gray-300 px-3 py-2 text-sm"
+            value={gtin}
+            onChange={(e) => setGtin(e.target.value)}
+            placeholder="8/12/13/14 位"
+          />
+        </Field>
+        <Field label="类型">
+          <select
+            className="rounded border border-gray-300 px-2 py-2 text-sm"
+            value={gtinType}
+            onChange={(e) => setGtinType(e.target.value)}
+          >
+            {GTIN_TYPES.map((t) => (
+              <option key={t} value={t}>
+                {t}
+              </option>
+            ))}
+          </select>
+        </Field>
+        <Field label="包装层级">
+          <select
+            className="rounded border border-gray-300 px-2 py-2 text-sm"
+            value={packLevel}
+            onChange={(e) => setPackLevel(e.target.value)}
+          >
+            {PACK_LEVELS.map((p) => (
+              <option key={p.value} value={p.value}>
+                {p.label}
+              </option>
+            ))}
+          </select>
+        </Field>
+        <Field label="地区（可选）">
+          <input
+            className="w-20 rounded border border-gray-300 px-3 py-2 text-sm"
+            value={region}
+            onChange={(e) => setRegion(e.target.value.toUpperCase())}
+          />
+        </Field>
+        <button
+          onClick={add}
+          disabled={busy}
+          className="flex items-center gap-1 rounded bg-gray-700 px-3 py-2 text-sm text-white hover:bg-gray-800 disabled:opacity-60"
+        >
+          <Plus className="h-4 w-4" /> 添加
+        </button>
+      </div>
+    </Card>
+  );
+}
+
+function ImagesCard({
+  product,
+  onChange,
+  onError,
+}: {
+  product: Detail;
+  onChange: () => void;
+  onError: (m: string) => void;
+}) {
+  const [url, setUrl] = useState("");
+  const [kind, setKind] = useState("front");
+
+  async function add() {
+    if (!url.trim()) return;
+    try {
+      await api.addImage(product.id, url.trim(), kind);
+      setUrl("");
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "添加失败");
+    }
+  }
+  async function remove(imageId: string) {
+    try {
+      await api.deleteImage(product.id, imageId);
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "删除失败");
+    }
+  }
+
+  return (
+    <Card title="图片（仅存 URL）">
+      <div className="mb-3 flex flex-wrap gap-3">
+        {product.images.length === 0 && (
+          <span className="text-sm text-gray-400">暂无图片</span>
+        )}
+        {product.images.map((im) => (
+          <div
+            key={im.id}
+            className="relative h-24 w-24 overflow-hidden rounded border border-gray-200"
+          >
+            <img
+              src={im.url}
+              alt={im.kind}
+              className="h-full w-full object-cover"
+            />
+            <button
+              onClick={() => remove(im.id)}
+              className="absolute right-1 top-1 rounded bg-black/50 p-1 text-white hover:bg-black/70"
+            >
+              <Trash2 className="h-3 w-3" />
+            </button>
+            <span className="absolute bottom-0 left-0 bg-black/50 px-1 text-[10px] text-white">
+              {im.kind}
+            </span>
+          </div>
+        ))}
+      </div>
+      <div className="flex items-center gap-2">
+        <input
+          className={inputCls}
+          placeholder="图片 URL"
+          value={url}
+          onChange={(e) => setUrl(e.target.value)}
+        />
+        <select
+          className="rounded border border-gray-300 px-2 py-2 text-sm"
+          value={kind}
+          onChange={(e) => setKind(e.target.value)}
+        >
+          <option value="front">正面</option>
+          <option value="ingredients">配料</option>
+          <option value="nutrition">营养</option>
+          <option value="other">其他</option>
+        </select>
+        <button
+          onClick={add}
+          className="flex items-center gap-1 whitespace-nowrap rounded bg-gray-700 px-3 py-2 text-sm text-white hover:bg-gray-800"
+        >
+          <Plus className="h-4 w-4" /> 添加
+        </button>
+      </div>
+    </Card>
+  );
+}
+
+function MsrpCard({
+  product,
+  onChange,
+  onError,
+}: {
+  product: Detail;
+  onChange: () => void;
+  onError: (m: string) => void;
+}) {
+  const [amount, setAmount] = useState("");
+  const [currency, setCurrency] = useState("CNY");
+  const [region, setRegion] = useState("CN");
+  const [date, setDate] = useState("");
+  const [note, setNote] = useState("");
+
+  async function add() {
+    const a = parseFloat(amount);
+    if (Number.isNaN(a)) return;
+    try {
+      await api.addMsrp(product.id, {
+        amount: a,
+        currency,
+        region,
+        effective_date: date || null,
+        note: note.trim() || null,
+      });
+      setAmount("");
+      setNote("");
+      setDate("");
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "添加失败");
+    }
+  }
+  async function remove(msrpId: string) {
+    try {
+      await api.deleteMsrp(product.id, msrpId);
+      onChange();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : "删除失败");
+    }
+  }
+
+  return (
+    <Card title="官方建议零售价（MSRP 快照，非售卖）">
+      <div className="mb-3 space-y-2">
+        {product.msrp.length === 0 && (
+          <span className="text-sm text-gray-400">暂无记录</span>
+        )}
+        {product.msrp.map((m) => (
+          <div
+            key={m.id}
+            className="flex items-center gap-3 rounded border border-gray-100 bg-gray-50 px-3 py-2 text-sm"
+          >
+            <span className="font-medium text-gray-800">
+              {m.amount} {m.currency}
+            </span>
+            <span className="text-gray-500">{m.region}</span>
+            <span className="text-gray-400">{m.effective_date || ""}</span>
+            <span className="flex-1 text-gray-400">{m.note || ""}</span>
+            <button
+              onClick={() => remove(m.id)}
+              className="text-gray-400 hover:text-red-600"
+            >
+              <Trash2 className="h-4 w-4" />
+            </button>
+          </div>
+        ))}
+      </div>
+      <div className="flex flex-wrap items-end gap-2">
+        <Field label="金额">
+          <input
+            className="w-28 rounded border border-gray-300 px-3 py-2 text-sm"
+            type="number"
+            step="any"
+            value={amount}
+            onChange={(e) => setAmount(e.target.value)}
+          />
+        </Field>
+        <Field label="币种">
+          <input
+            className="w-20 rounded border border-gray-300 px-3 py-2 text-sm"
+            value={currency}
+            onChange={(e) => setCurrency(e.target.value.toUpperCase())}
+          />
+        </Field>
+        <Field label="地区">
+          <input
+            className="w-20 rounded border border-gray-300 px-3 py-2 text-sm"
+            value={region}
+            onChange={(e) => setRegion(e.target.value.toUpperCase())}
+          />
+        </Field>
+        <Field label="生效日期">
+          <input
+            className="rounded border border-gray-300 px-3 py-2 text-sm"
+            type="date"
+            value={date}
+            onChange={(e) => setDate(e.target.value)}
+          />
+        </Field>
+        <Field label="备注">
+          <input
+            className="w-40 rounded border border-gray-300 px-3 py-2 text-sm"
+            value={note}
+            onChange={(e) => setNote(e.target.value)}
+          />
+        </Field>
+        <button
+          onClick={add}
+          className="flex items-center gap-1 rounded bg-gray-700 px-3 py-2 text-sm text-white hover:bg-gray-800"
+        >
+          <Plus className="h-4 w-4" /> 添加
+        </button>
+      </div>
+    </Card>
+  );
+}
@@ -0,0 +1,178 @@
+import { useEffect, useState } from "react";
+import { api } from "../api";
+import { FIELD_LABELS, ProductRow } from "../types";
+import { Search, AlertCircle } from "lucide-react";
+
+const STATUS_LABEL: Record<string, string> = {
+  active: "在用",
+  merged: "已合并",
+  deprecated: "已停用",
+};
+
+function QualityBadge({ score }: { score: number }) {
+  const pct = Math.round(score * 100);
+  const color =
+    score >= 0.8
+      ? "bg-emerald-100 text-emerald-700"
+      : score >= 0.5
+        ? "bg-amber-100 text-amber-700"
+        : "bg-red-100 text-red-700";
+  return (
+    <span className={`rounded px-2 py-0.5 text-xs font-medium ${color}`}>
+      {pct}
+    </span>
+  );
+}
+
+export default function ProductList({
+  onOpen,
+}: {
+  onOpen: (id: string) => void;
+}) {
+  const [q, setQ] = useState("");
+  const [input, setInput] = useState("");
+  const [page, setPage] = useState(1);
+  const [size] = useState(20);
+  const [rows, setRows] = useState<ProductRow[]>([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    setLoading(true);
+    setError("");
+    api
+      .listProducts(q, page, size)
+      .then((r) => {
+        setRows(r.items);
+        setTotal(r.total);
+      })
+      .catch((e) => setError(e.message))
+      .finally(() => setLoading(false));
+  }, [q, page, size]);
+
+  const pages = Math.max(1, Math.ceil(total / size));
+
+  return (
+    <div className="mx-auto max-w-6xl">
+      <div className="mb-4 flex items-center justify-between">
+        <h2 className="text-xl font-semibold text-gray-800">
+          商品档案 <span className="text-sm font-normal text-gray-400">共 {total} 条</span>
+        </h2>
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            setPage(1);
+            setQ(input.trim());
+          }}
+          className="flex items-center gap-2"
+        >
+          <div className="relative">
+            <Search className="absolute left-2 top-2.5 h-4 w-4 text-gray-400" />
+            <input
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              placeholder="按名称 / 条码搜索"
+              className="w-64 rounded border border-gray-300 py-2 pl-8 pr-3 text-sm focus:border-emerald-500 focus:outline-none"
+            />
+          </div>
+          <button className="rounded bg-emerald-600 px-3 py-2 text-sm text-white hover:bg-emerald-700">
+            搜索
+          </button>
+        </form>
+      </div>
+
+      {error && (
+        <div className="mb-3 rounded bg-red-50 px-3 py-2 text-sm text-red-600">
+          {error}
+        </div>
+      )}
+
+      <div className="overflow-hidden rounded-lg border border-gray-200 bg-white">
+        <table className="w-full text-sm">
+          <thead className="bg-gray-50 text-left text-xs uppercase text-gray-500">
+            <tr>
+              <th className="px-4 py-3">名称</th>
+              <th className="px-4 py-3">品牌</th>
+              <th className="px-4 py-3">条码</th>
+              <th className="px-4 py-3">品类</th>
+              <th className="px-4 py-3">状态</th>
+              <th className="px-4 py-3">质量分</th>
+              <th className="px-4 py-3">缺失字段</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-gray-100">
+            {loading ? (
+              <tr>
+                <td colSpan={7} className="px-4 py-8 text-center text-gray-400">
+                  加载中…
+                </td>
+              </tr>
+            ) : rows.length === 0 ? (
+              <tr>
+                <td colSpan={7} className="px-4 py-8 text-center text-gray-400">
+                  暂无数据
+                </td>
+              </tr>
+            ) : (
+              rows.map((r) => (
+                <tr
+                  key={r.id}
+                  onClick={() => onOpen(r.id)}
+                  className="cursor-pointer hover:bg-emerald-50/50"
+                >
+                  <td className="px-4 py-3 font-medium text-gray-800">{r.name}</td>
+                  <td className="px-4 py-3 text-gray-600">{r.brand || "—"}</td>
+                  <td className="px-4 py-3 font-mono text-xs text-gray-500">
+                    {r.gtin || "—"}
+                  </td>
+                  <td className="px-4 py-3 text-xs text-gray-500">
+                    {r.category_path || "—"}
+                  </td>
+                  <td className="px-4 py-3 text-gray-600">
+                    {STATUS_LABEL[r.status] || r.status}
+                  </td>
+                  <td className="px-4 py-3">
+                    <QualityBadge score={r.quality_score} />
+                  </td>
+                  <td className="px-4 py-3">
+                    {r.missing.length === 0 ? (
+                      <span className="text-xs text-emerald-600">完整</span>
+                    ) : (
+                      <span className="flex items-center gap-1 text-xs text-amber-600">
+                        <AlertCircle className="h-3.5 w-3.5" />
+                        {r.missing
+                          .map((f) => FIELD_LABELS[f] || f)
+                          .join("、")}
+                      </span>
+                    )}
+                  </td>
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      <div className="mt-4 flex items-center justify-end gap-2 text-sm text-gray-600">
+        <button
+          disabled={page <= 1}
+          onClick={() => setPage((p) => p - 1)}
+          className="rounded border border-gray-300 px-3 py-1 disabled:opacity-50"
+        >
+          上一页
+        </button>
+        <span>
+          {page} / {pages}
+        </span>
+        <button
+          disabled={page >= pages}
+          onClick={() => setPage((p) => p + 1)}
+          className="rounded border border-gray-300 px-3 py-1 disabled:opacity-50"
+        >
+          下一页
+        </button>
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,314 @@
+import { useEffect, useState } from "react";
+import { api, ApiError } from "../api";
+import type { SubmissionDetail, SubmissionRow } from "../types";
+import { FIELD_LABELS } from "../types";
+import { ArrowLeft, Check, X } from "lucide-react";
+
+const STATUS_TABS = [
+  { key: "pending", label: "待审核" },
+  { key: "approved", label: "已通过" },
+  { key: "rejected", label: "已驳回" },
+];
+
+const STATUS_BADGE: Record<string, string> = {
+  pending: "bg-amber-50 text-amber-700",
+  approved: "bg-emerald-50 text-emerald-700",
+  rejected: "bg-red-50 text-red-700",
+};
+const STATUS_TEXT: Record<string, string> = {
+  pending: "待审核",
+  approved: "已通过",
+  rejected: "已驳回",
+};
+
+export default function SubmissionsPage({ onPending }: { onPending?: (n: number) => void }) {
+  const [tab, setTab] = useState("pending");
+  const [rows, setRows] = useState<SubmissionRow[]>([]);
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [error, setError] = useState("");
+
+  async function load() {
+    setError("");
+    try {
+      const res = await api.listSubmissions(tab, 1, 50);
+      setRows(res.items);
+      onPending?.(res.pending);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "加载失败");
+    }
+  }
+
+  useEffect(() => {
+    load();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tab]);
+
+  if (openId) {
+    return (
+      <SubmissionView
+        id={openId}
+        onBack={() => {
+          setOpenId(null);
+          load();
+        }}
+      />
+    );
+  }
+
+  return (
+    <div>
+      <div className="flex items-center gap-2 mb-4">
+        {STATUS_TABS.map((t) => (
+          <button
+            key={t.key}
+            onClick={() => setTab(t.key)}
+            className={`px-3 py-1.5 rounded-md text-sm ${
+              tab === t.key
+                ? "bg-emerald-600 text-white"
+                : "bg-white border text-gray-600 hover:bg-gray-50"
+            }`}
+          >
+            {t.label}
+          </button>
+        ))}
+      </div>
+
+      {error && (
+        <div className="mb-3 bg-red-50 text-red-700 text-sm rounded px-4 py-2">{error}</div>
+      )}
+
+      <div className="bg-white border rounded-lg overflow-hidden">
+        <table className="w-full text-sm">
+          <thead className="bg-gray-50 text-gray-500 text-left">
+            <tr>
+              <th className="px-4 py-2 font-medium">商品名称</th>
+              <th className="px-4 py-2 font-medium">条码</th>
+              <th className="px-4 py-2 font-medium">投稿人</th>
+              <th className="px-4 py-2 font-medium">类型</th>
+              <th className="px-4 py-2 font-medium">提交时间</th>
+              <th className="px-4 py-2 font-medium">状态</th>
+            </tr>
+          </thead>
+          <tbody className="divide-y">
+            {rows.length === 0 ? (
+              <tr>
+                <td colSpan={6} className="px-4 py-8 text-center text-gray-400">
+                  暂无投稿
+                </td>
+              </tr>
+            ) : (
+              rows.map((r) => (
+                <tr
+                  key={r.id}
+                  onClick={() => setOpenId(r.id)}
+                  className="cursor-pointer hover:bg-gray-50"
+                >
+                  <td className="px-4 py-2 text-gray-800">{r.name}</td>
+                  <td className="px-4 py-2 text-gray-500">{r.gtin || "—"}</td>
+                  <td className="px-4 py-2 text-gray-500">{r.submitter_name || "匿名"}</td>
+                  <td className="px-4 py-2">
+                    <span className="text-xs text-gray-500">
+                      {r.matched ? "补全已有商品" : "新建商品"}
+                    </span>
+                  </td>
+                  <td className="px-4 py-2 text-gray-500">
+                    {new Date(r.created_at).toLocaleString()}
+                  </td>
+                  <td className="px-4 py-2">
+                    <span className={`text-xs rounded px-2 py-0.5 ${STATUS_BADGE[r.status]}`}>
+                      {STATUS_TEXT[r.status]}
+                    </span>
+                  </td>
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}
+
+function Field({ label, value }: { label: string; value: React.ReactNode }) {
+  if (value === null || value === undefined || value === "") return null;
+  return (
+    <div className="flex py-1.5 text-sm">
+      <div className="w-28 shrink-0 text-gray-400">{label}</div>
+      <div className="text-gray-800 break-all">{value}</div>
+    </div>
+  );
+}
+
+function SubmissionView({ id, onBack }: { id: string; onBack: () => void }) {
+  const [d, setD] = useState<SubmissionDetail | null>(null);
+  const [error, setError] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [rejecting, setRejecting] = useState(false);
+  const [reason, setReason] = useState("");
+
+  useEffect(() => {
+    api.getSubmission(id).then(setD).catch((e) => setError(e.message));
+  }, [id]);
+
+  async function approve() {
+    if (!confirm("确认通过该投稿？将写入正式商品库并记录来源 community。")) return;
+    setBusy(true);
+    setError("");
+    try {
+      await api.approveSubmission(id);
+      onBack();
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "操作失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function reject() {
+    setBusy(true);
+    setError("");
+    try {
+      await api.rejectSubmission(id, reason.trim());
+      onBack();
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "操作失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (error && !d) {
+    return (
+      <div>
+        <button onClick={onBack} className="text-sm text-gray-500 flex items-center gap-1 mb-4">
+          <ArrowLeft className="h-4 w-4" /> 返回
+        </button>
+        <div className="bg-red-50 text-red-700 text-sm rounded px-4 py-3">{error}</div>
+      </div>
+    );
+  }
+  if (!d) return <div className="text-gray-400">加载中…</div>;
+
+  const p = d.payload;
+  const nutri = Object.entries(p.nutriments || {});
+
+  return (
+    <div className="max-w-3xl">
+      <button onClick={onBack} className="text-sm text-gray-500 flex items-center gap-1 mb-4">
+        <ArrowLeft className="h-4 w-4" /> 返回投稿队列
+      </button>
+
+      <div className="flex items-center justify-between">
+        <h2 className="text-lg font-semibold text-gray-800">{p.name}</h2>
+        <span className={`text-xs rounded px-2 py-0.5 ${STATUS_BADGE[d.status]}`}>
+          {STATUS_TEXT[d.status]}
+        </span>
+      </div>
+
+      {error && <div className="mt-3 bg-red-50 text-red-700 text-sm rounded px-4 py-2">{error}</div>}
+
+      {d.target_product_id && (
+        <div className="mt-3 text-sm bg-blue-50 text-blue-700 rounded px-4 py-2">
+          该条码已存在商品，通过后将<b>补全已有商品</b>（仅覆盖本次提供的字段）。
+        </div>
+      )}
+
+      <div className="bg-white border rounded-lg p-5 mt-4">
+        <h3 className="font-medium text-gray-700 mb-2">投稿内容</h3>
+        <Field label="商品名称" value={p.name} />
+        <Field label="条码" value={p.gtin} />
+        <Field label="品牌" value={p.brand_name} />
+        <Field
+          label="净含量"
+          value={p.net_content_value != null ? `${p.net_content_value} ${p.net_content_unit || ""}` : null}
+        />
+        <Field label="产地" value={p.country_of_origin} />
+        <Field label="配料" value={p.ingredients_text} />
+        {nutri.length > 0 && (
+          <Field
+            label="营养成分"
+            value={
+              <span>
+                {p.nutrition_basis ? `(${p.nutrition_basis}) ` : ""}
+                {nutri.map(([k, v]) => `${FIELD_LABELS[k] || k}:${v}`).join("，")}
+              </span>
+            }
+          />
+        )}
+        {p.images && p.images.length > 0 && (
+          <Field
+            label="图片"
+            value={
+              <div className="flex flex-wrap gap-2">
+                {p.images.map((im, i) => (
+                  <a key={i} href={im.url} target="_blank" rel="noreferrer">
+                    <img src={im.url} alt="" className="h-20 w-20 object-cover rounded border" />
+                  </a>
+                ))}
+              </div>
+            }
+          />
+        )}
+      </div>
+
+      <div className="bg-white border rounded-lg p-5 mt-4">
+        <h3 className="font-medium text-gray-700 mb-2">投稿人 / 备注</h3>
+        <Field label="称呼" value={p.submitter_name || "匿名"} />
+        <Field label="联系方式" value={p.submitter_contact} />
+        <Field label="备注" value={p.note} />
+        <Field label="提交时间" value={new Date(d.created_at).toLocaleString()} />
+        {d.reviewed_by && <Field label="审核人" value={d.reviewed_by} />}
+        {d.review_note && <Field label="驳回原因" value={d.review_note} />}
+        {d.result_product_id && <Field label="收录商品ID" value={d.result_product_id} />}
+      </div>
+
+      {d.status === "pending" && (
+        <div className="mt-5">
+          {rejecting ? (
+            <div className="bg-white border rounded-lg p-4">
+              <label className="block text-xs text-gray-500 mb-1">驳回原因</label>
+              <input
+                className="w-full border rounded-md px-3 py-2 text-sm"
+                value={reason}
+                onChange={(e) => setReason(e.target.value)}
+                placeholder="例如：资料无法核实 / 重复投稿"
+              />
+              <div className="mt-3 flex gap-2">
+                <button
+                  onClick={reject}
+                  disabled={busy}
+                  className="px-4 py-2 rounded bg-red-600 text-white text-sm hover:bg-red-700 disabled:opacity-60"
+                >
+                  确认驳回
+                </button>
+                <button
+                  onClick={() => setRejecting(false)}
+                  className="px-4 py-2 rounded border text-sm text-gray-600"
+                >
+                  取消
+                </button>
+              </div>
+            </div>
+          ) : (
+            <div className="flex gap-3">
+              <button
+                onClick={approve}
+                disabled={busy}
+                className="px-5 py-2.5 rounded-lg bg-emerald-600 text-white font-medium hover:bg-emerald-700 disabled:opacity-60 flex items-center gap-1.5"
+              >
+                <Check className="h-4 w-4" /> 通过并收录
+              </button>
+              <button
+                onClick={() => setRejecting(true)}
+                disabled={busy}
+                className="px-5 py-2.5 rounded-lg border text-gray-700 font-medium hover:bg-gray-50 flex items-center gap-1.5"
+              >
+                <X className="h-4 w-4" /> 驳回
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
@@ -0,0 +1,16 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+html,
+body,
+#root {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  background: #f3f4f6;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue",
+    Arial, "PingFang SC", "Microsoft YaHei", sans-serif;
+}
@@ -0,0 +1,10 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
@@ -0,0 +1,169 @@
+export interface ProductRow {
+  id: string;
+  gtin: string | null;
+  name: string;
+  brand: string | null;
+  category_path: string | null;
+  status: string;
+  quality_score: number;
+  missing: string[];
+  updated_at: string;
+}
+
+export interface Barcode {
+  id: string;
+  gtin: string;
+  gtin_type: string;
+  pack_level: string;
+  region: string | null;
+  is_primary: boolean;
+}
+
+export interface ProductImage {
+  id: string;
+  url: string;
+  kind: string;
+  license: string | null;
+}
+
+export interface MSRP {
+  id: string;
+  amount: number;
+  currency: string;
+  region: string;
+  effective_date: string | null;
+  source_url: string | null;
+  note: string | null;
+}
+
+export interface ProductDetail {
+  id: string;
+  gtin: string | null;
+  name: string;
+  brand_id: string | null;
+  brand: string | null;
+  category_id: string | null;
+  category_path: string | null;
+  net_content_value: number | null;
+  net_content_unit: string | null;
+  country_of_origin: string | null;
+  status: string;
+  quality_score: number;
+  ingredients_text: string | null;
+  allergens: string[];
+  additives: string[];
+  nutriments: Record<string, number> | null;
+  nutrition_basis: string | null;
+  serving_size: string | null;
+  nutri_score: string | null;
+  barcodes: Barcode[];
+  images: ProductImage[];
+  msrp: MSRP[];
+  missing: string[];
+  updated_at: string;
+}
+
+export interface Brand {
+  id: string;
+  name: string;
+}
+
+export interface Category {
+  id: string;
+  name_zh: string;
+  name_en: string | null;
+  path: string;
+  level: number;
+}
+
+export interface AuditEntry {
+  id: string;
+  actor: string;
+  action: string;
+  fields: string[];
+  created_at: string;
+}
+
+export interface SubmissionRow {
+  id: string;
+  gtin: string | null;
+  name: string;
+  status: string;
+  submitter_name: string | null;
+  matched: boolean;
+  created_at: string;
+  reviewed_at: string | null;
+}
+
+export interface SubmissionImage {
+  url: string;
+  kind: string;
+}
+
+export interface SubmissionPayload {
+  gtin: string | null;
+  name: string;
+  brand_name: string | null;
+  category_id: string | null;
+  net_content_value: number | null;
+  net_content_unit: string | null;
+  country_of_origin: string | null;
+  ingredients_text: string | null;
+  nutriments: Record<string, number> | null;
+  nutrition_basis: string | null;
+  serving_size: string | null;
+  nutri_score: string | null;
+  images: SubmissionImage[] | null;
+  submitter_name: string | null;
+  submitter_contact: string | null;
+  note: string | null;
+}
+
+export interface SubmissionDetail {
+  id: string;
+  status: string;
+  gtin: string | null;
+  name: string;
+  submitter_name: string | null;
+  submitter_contact: string | null;
+  note: string | null;
+  review_note: string | null;
+  reviewed_by: string | null;
+  reviewed_at: string | null;
+  created_at: string;
+  target_product_id: string | null;
+  result_product_id: string | null;
+  payload: SubmissionPayload;
+  existing_product?: ProductDetail;
+}
+
+export interface ApiKeyUsage {
+  total: number;
+  today: number;
+  last_used_at?: number | null;
+}
+
+export interface ApiKey {
+  id: string;
+  name: string;
+  key_prefix: string;
+  owner_email: string | null;
+  tier: string;
+  rate_limit_per_min: number;
+  revoked_at: string | null;
+  created_by: string | null;
+  created_at: string;
+  usage: ApiKeyUsage;
+}
+
+export const FIELD_LABELS: Record<string, string> = {
+  name: "名称",
+  gtin: "条码",
+  brand: "品牌",
+  category: "品类",
+  net_content: "净含量",
+  country_of_origin: "产地",
+  nutriments: "营养成分",
+  ingredients: "配料",
+  image: "图片",
+};
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
@@ -0,0 +1,6 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{ts,tsx}"],
+  theme: { extend: {} },
+  plugins: [],
+};
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}
@@ -0,0 +1,9 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// Served under /ping by the admin Go binary; base must match the nginx prefix.
+export default defineConfig({
+  base: "/ping/",
+  plugins: [react()],
+  build: { outDir: "dist", emptyOutDir: true },
+});
@@ -0,0 +1,29 @@
+# Admin console image: builds the SPA (node), embeds it into the Go admin
+# binary, and ships a static scratch runtime. Build context is the repo root.
+
+# Stage 1: build the admin SPA.
+FROM node:22-alpine AS web
+WORKDIR /web
+ENV npm_config_registry=https://registry.npmmirror.com
+COPY admin-frontend/package.json admin-frontend/package-lock.json* ./
+RUN npm ci || npm install
+COPY admin-frontend/ ./
+RUN npm run build
+
+# Stage 2: build the Go admin binary with the SPA embedded.
+FROM golang:1.23-alpine AS build
+ENV GOPROXY=https://goproxy.cn,direct
+WORKDIR /src
+COPY api/go.mod api/go.sum ./
+RUN go mod download
+COPY api/ ./
+RUN rm -rf internal/adminweb/dist && mkdir -p internal/adminweb/dist
+COPY --from=web /web/dist/ internal/adminweb/dist/
+RUN CGO_ENABLED=0 go build -o /out/admin ./cmd/admin
+
+# Stage 3: minimal runtime.
+FROM scratch
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=build /out/admin /admin
+EXPOSE 8080
+ENTRYPOINT ["/admin"]
@@ -0,0 +1,31 @@
+# Public API image: builds the public SPA (homepage + search + contribute),
+# embeds it into the Go read-only server binary, and ships a static scratch
+# runtime (used where gcr.io/distroless is not reachable). Build context is the
+# repo root.
+
+# Stage 1: build the public SPA.
+FROM node:22-alpine AS web
+WORKDIR /web
+ENV npm_config_registry=https://registry.npmmirror.com
+COPY public-frontend/package.json public-frontend/package-lock.json* ./
+RUN npm ci || npm install
+COPY public-frontend/ ./
+RUN npm run build
+
+# Stage 2: build the Go server binary with the SPA embedded.
+FROM golang:1.23-alpine AS build
+ENV GOPROXY=https://goproxy.cn,direct
+WORKDIR /src
+COPY api/go.mod api/go.sum ./
+RUN go mod download
+COPY api/ ./
+RUN rm -rf internal/publicweb/dist && mkdir -p internal/publicweb/dist
+COPY --from=web /web/dist/ internal/publicweb/dist/
+RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server
+
+# Stage 3: minimal runtime.
+FROM scratch
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+COPY --from=build /out/server /server
+EXPOSE 8080
+ENTRYPOINT ["/server"]
@@ -0,0 +1,86 @@
+// Command admin starts the OpenGoods admin console (authenticated write API +
+// embedded SPA), served under a base path (default /ping).
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"log"
+	"net/http"
+	"os"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/baicai2026-baicai/goods/api/internal/adminhandler"
+	"github.com/baicai2026-baicai/goods/api/internal/adminstore"
+	"github.com/baicai2026-baicai/goods/api/internal/adminweb"
+	"github.com/baicai2026-baicai/goods/api/internal/auth"
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+)
+
+func getenv(key, fallback string) string {
+	if v, ok := os.LookupEnv(key); ok && v != "" {
+		return v
+	}
+	return fallback
+}
+
+func main() {
+	addr := getenv("GOODS_ADMIN_ADDR", ":8080")
+	dbURL := getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable")
+	basePath := getenv("GOODS_ADMIN_BASE_PATH", "/ping")
+	username := getenv("GOODS_ADMIN_USER", "admin")
+
+	// Password: prefer a bcrypt hash; otherwise hash a plaintext password.
+	var passwordHash []byte
+	if h := os.Getenv("GOODS_ADMIN_PASSWORD_HASH"); h != "" {
+		passwordHash = []byte(h)
+	} else if p := os.Getenv("GOODS_ADMIN_PASSWORD"); p != "" {
+		hashed, err := bcrypt.GenerateFromPassword([]byte(p), bcrypt.DefaultCost)
+		if err != nil {
+			log.Fatalf("failed to hash admin password: %v", err)
+		}
+		passwordHash = hashed
+	} else {
+		log.Fatal("set GOODS_ADMIN_PASSWORD or GOODS_ADMIN_PASSWORD_HASH")
+	}
+
+	secret := []byte(os.Getenv("GOODS_ADMIN_JWT_SECRET"))
+	if len(secret) == 0 {
+		secret = make([]byte, 32)
+		if _, err := rand.Read(secret); err != nil {
+			log.Fatalf("failed to generate jwt secret: %v", err)
+		}
+		log.Print("warning: GOODS_ADMIN_JWT_SECRET not set; using a random secret (tokens invalidate on restart)")
+	}
+
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dbURL)
+	if err != nil {
+		log.Fatalf("failed to create db pool: %v", err)
+	}
+	defer pool.Close()
+
+	pingCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	if err := pool.Ping(pingCtx); err != nil {
+		log.Printf("warning: database not reachable at startup: %v", err)
+	}
+
+	authn := auth.New(username, passwordHash, secret, 12*time.Hour)
+	usage := ratelimit.New(getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"))
+	h := adminhandler.New(adminstore.New(pool), authn, basePath, adminweb.Dist()).
+		WithUsage(usage)
+
+	srv := &http.Server{
+		Addr:              addr,
+		Handler:           h.Router(),
+		ReadHeaderTimeout: 10 * time.Second,
+	}
+	log.Printf("OpenGoods admin console listening on %s (base path %s)", addr, basePath)
+	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+		log.Fatalf("server error: %v", err)
+	}
+}
@@ -2,20 +2,46 @@
 package main

 import (
+	"context"
 	"log"
 	"net/http"
 	"time"

+	"github.com/jackc/pgx/v5/pgxpool"
+
 	"github.com/baicai2026-baicai/goods/api/internal/config"
 	"github.com/baicai2026-baicai/goods/api/internal/handler"
+	"github.com/baicai2026-baicai/goods/api/internal/publicweb"
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+	"github.com/baicai2026-baicai/goods/api/internal/store"
 )

 func main() {
 	cfg := config.Load()

+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, cfg.DatabaseURL)
+	if err != nil {
+		log.Fatalf("failed to create db pool: %v", err)
+	}
+	defer pool.Close()
+
+	pingCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	if err := pool.Ping(pingCtx); err != nil {
+		log.Printf("warning: database not reachable at startup: %v", err)
+	}
+
+	limiter := ratelimit.New(cfg.RedisURL)
+	if !limiter.Enabled() {
+		log.Print("warning: Redis not configured; public API rate limiting disabled")
+	}
+	h := handler.New(store.New(pool), publicweb.Dist()).
+		WithRateLimit(limiter, cfg.AnonRateLimitPerMin)
+
 	srv := &http.Server{
 		Addr:              cfg.Addr,
-		Handler:           handler.Router(),
+		Handler:           h.Router(),
 		ReadHeaderTimeout: 10 * time.Second,
 	}

@@ -2,4 +2,20 @@ module github.com/baicai2026-baicai/goods/api

 go 1.23.4

-require github.com/go-chi/chi/v5 v5.1.0
+require (
+	github.com/go-chi/chi/v5 v5.1.0
+	github.com/jackc/pgx/v5 v5.7.2
+	github.com/redis/go-redis/v9 v9.18.0
+	golang.org/x/crypto v0.31.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	golang.org/x/sync v0.10.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
+)
@@ -1,2 +1,46 @@
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/go-chi/chi/v5 v5.1.0 h1:acVI1TYaD+hhedDJ3r54HyA6sExp3HfXq7QWEEY/xMw=
 github.com/go-chi/chi/v5 v5.1.0/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITLSKoi8=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.7.2 h1:mLoDLV6sonKlvjIEsV56SkWNCnuNv531l94GaIzO+XI=
+github.com/jackc/pgx/v5 v5.7.2/go.mod h1:ncY89UGWxg82EykZUwSpUKEfccBGGYq1xjrOpsbsfGQ=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/klauspost/cpuid/v2 v2.0.9 h1:lgaqFMSdTdQYdZ04uHyN2d/eKdOMyi2YLSvlQIBFYa4=
+github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/redis/go-redis/v9 v9.18.0 h1:pMkxYPkEbMPwRdenAzUNyFNrDgHx9U+DrBabWNfSRQs=
+github.com/redis/go-redis/v9 v9.18.0/go.mod h1:k3ufPphLU5YXwNTUcCRXGxUoF1fqxnhFQmscfkCoDA0=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
+github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
+golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
+golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
+golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
+golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -0,0 +1,70 @@
+package adminhandler
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+
+	"github.com/baicai2026-baicai/goods/api/internal/adminstore"
+	"github.com/baicai2026-baicai/goods/api/internal/auth"
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+)
+
+// apiKeyView is an issued key plus its usage counters.
+type apiKeyView struct {
+	adminstore.APIKeyRow
+	Usage ratelimit.UsageStat `json:"usage"`
+}
+
+// ListAPIKeys returns all issued keys with usage stats merged in.
+func (h *Handler) ListAPIKeys(w http.ResponseWriter, r *http.Request) {
+	keys, err := h.store.ListAPIKeys(r.Context())
+	if h.handleErr(w, err) {
+		return
+	}
+	views := make([]apiKeyView, 0, len(keys))
+	for _, k := range keys {
+		v := apiKeyView{APIKeyRow: k}
+		if h.usage != nil {
+			v.Usage = h.usage.Usage(r.Context(), k.ID)
+		}
+		views = append(views, v)
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": views})
+}
+
+// CreateAPIKey issues a new key and returns its plaintext exactly once.
+func (h *Handler) CreateAPIKey(w http.ResponseWriter, r *http.Request) {
+	var in adminstore.APIKeyInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if strings.TrimSpace(in.Name) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "名称不能为空")
+		return
+	}
+	if in.Tier != "" && in.Tier != "free" && in.Tier != "partner" && in.Tier != "internal" {
+		writeError(w, http.StatusBadRequest, "bad_request", "tier 取值无效")
+		return
+	}
+	plaintext, row, err := h.store.CreateAPIKey(r.Context(), in, auth.UserFrom(r.Context()))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, map[string]any{
+		"key":     plaintext,
+		"item":    row,
+		"warning": "请立即复制保存此密钥，它只显示这一次，无法再次查看。",
+	})
+}
+
+// RevokeAPIKey disables a key. Subsequent requests with it are rejected.
+func (h *Handler) RevokeAPIKey(w http.ResponseWriter, r *http.Request) {
+	if err := h.store.RevokeAPIKey(r.Context(), chi.URLParam(r, "id")); h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "revoked"})
+}
@@ -0,0 +1,469 @@
+// Package adminhandler wires up the authenticated admin console: a JSON write
+// API mounted under a base path (default /ping) plus the embedded SPA.
+package adminhandler
+
+import (
+	"encoding/json"
+	"errors"
+	"io/fs"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+
+	"github.com/baicai2026-baicai/goods/api/internal/adminstore"
+	"github.com/baicai2026-baicai/goods/api/internal/auth"
+	"github.com/baicai2026-baicai/goods/api/internal/gtin"
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+)
+
+// Handler holds the admin dependencies.
+type Handler struct {
+	store       *adminstore.Store
+	authn       *auth.Authenticator
+	basePath    string
+	spa         fs.FS
+	submitLimit *rateLimiter
+	usage       *ratelimit.Limiter
+}
+
+// New constructs an admin Handler. basePath is e.g. "/ping" (no trailing slash).
+func New(store *adminstore.Store, authn *auth.Authenticator, basePath string, spa fs.FS) *Handler {
+	basePath = "/" + strings.Trim(basePath, "/")
+	return &Handler{
+		store:       store,
+		authn:       authn,
+		basePath:    basePath,
+		spa:         spa,
+		submitLimit: newRateLimiter(5, 10*time.Minute),
+	}
+}
+
+// WithUsage attaches a Redis-backed limiter used to read per-key usage counters
+// for the API-key management view. Optional; without it usage shows as zero.
+func (h *Handler) WithUsage(l *ratelimit.Limiter) *Handler {
+	h.usage = l
+	return h
+}
+
+// Router builds the HTTP handler.
+func (h *Handler) Router() http.Handler {
+	r := chi.NewRouter()
+	r.Use(middleware.RequestID)
+	r.Use(middleware.RealIP)
+	r.Use(middleware.Recoverer)
+
+	r.Route(h.basePath, func(r chi.Router) {
+		r.Get("/healthz", func(w http.ResponseWriter, _ *http.Request) {
+			writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+		})
+		r.Post("/api/login", h.Login)
+
+		r.Group(func(r chi.Router) {
+			r.Use(h.authn.Middleware)
+			r.Get("/api/me", h.Me)
+			r.Get("/api/products", h.ListProducts)
+			r.Get("/api/products/{id}", h.GetProduct)
+			r.Put("/api/products/{id}", h.UpdateProduct)
+			r.Get("/api/products/{id}/audit", h.ListAudit)
+			r.Post("/api/products/{id}/images", h.AddImage)
+			r.Delete("/api/products/{id}/images/{imageID}", h.DeleteImage)
+			r.Post("/api/products/{id}/msrp", h.AddMSRP)
+			r.Delete("/api/products/{id}/msrp/{msrpID}", h.DeleteMSRP)
+			r.Post("/api/products/{id}/barcodes", h.AddBarcode)
+			r.Delete("/api/products/{id}/barcodes/{barcodeID}", h.DeleteBarcode)
+			r.Post("/api/products/{id}/barcodes/{barcodeID}/primary", h.SetPrimaryBarcode)
+			r.Get("/api/brands", h.ListBrands)
+			r.Get("/api/categories", h.ListCategories)
+
+			r.Get("/api/submissions", h.ListSubmissions)
+			r.Get("/api/submissions/{id}", h.GetSubmission)
+			r.Post("/api/submissions/{id}/approve", h.ApproveSubmission)
+			r.Post("/api/submissions/{id}/reject", h.RejectSubmission)
+
+			r.Get("/api/keys", h.ListAPIKeys)
+			r.Post("/api/keys", h.CreateAPIKey)
+			r.Delete("/api/keys/{id}", h.RevokeAPIKey)
+		})
+
+		r.Handle("/*", http.HandlerFunc(h.serveSPA))
+	})
+
+	// Public, unauthenticated contribution endpoint (proxied at /api/public/*).
+	// Submissions enter a moderation queue and never touch products until an
+	// admin approves them.
+	r.Post("/api/public/submissions", h.CreateSubmission)
+
+	return r
+}
+
+func (h *Handler) serveSPA(w http.ResponseWriter, r *http.Request) {
+	rel := strings.TrimPrefix(r.URL.Path, h.basePath)
+	rel = strings.TrimPrefix(rel, "/")
+	if rel == "" {
+		rel = "index.html"
+	}
+	if f, err := h.spa.Open(rel); err == nil {
+		f.Close()
+		http.StripPrefix(h.basePath+"/", http.FileServer(http.FS(h.spa))).ServeHTTP(w, r)
+		return
+	}
+	// SPA fallback: serve index.html for client-side routes.
+	index, err := h.spa.Open("index.html")
+	if err != nil {
+		http.NotFound(w, r)
+		return
+	}
+	defer index.Close()
+	data, _ := fs.ReadFile(h.spa, "index.html")
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	_, _ = w.Write(data)
+}
+
+// ---------- auth ----------
+
+// Login authenticates and returns a bearer token.
+func (h *Handler) Login(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Username string `json:"username"`
+		Password string `json:"password"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	token, err := h.authn.Login(body.Username, body.Password)
+	if err != nil {
+		writeError(w, http.StatusUnauthorized, "unauthorized", "用户名或密码错误")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"token": token, "username": body.Username})
+}
+
+// Me returns the current authenticated user.
+func (h *Handler) Me(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, map[string]string{"username": auth.UserFrom(r.Context())})
+}
+
+// ---------- products ----------
+
+// ListProducts returns a paginated product list.
+func (h *Handler) ListProducts(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query().Get("q")
+	page, size := pageParams(r)
+	items, total, err := h.store.ListProducts(r.Context(), q, size, (page-1)*size)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items": items, "page": page, "size": size, "total": total,
+		"completeness_fields": adminstore.CompletenessFields,
+	})
+}
+
+// GetProduct returns full editable detail.
+func (h *Handler) GetProduct(w http.ResponseWriter, r *http.Request) {
+	d, err := h.store.GetProduct(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, d)
+}
+
+// UpdateProduct applies an edit.
+func (h *Handler) UpdateProduct(w http.ResponseWriter, r *http.Request) {
+	var in adminstore.ProductInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if strings.TrimSpace(in.Name) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "名称不能为空")
+		return
+	}
+	d, err := h.store.UpdateProduct(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), in)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, d)
+}
+
+// ListAudit returns audit history for a product.
+func (h *Handler) ListAudit(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListAudit(r.Context(), chi.URLParam(r, "id"), 100)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+// AddImage adds an image URL.
+func (h *Handler) AddImage(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		URL  string `json:"url"`
+		Kind string `json:"kind"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || strings.TrimSpace(body.URL) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "图片 URL 不能为空")
+		return
+	}
+	im, err := h.store.AddImage(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), body.URL, body.Kind)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, im)
+}
+
+// DeleteImage removes an image.
+func (h *Handler) DeleteImage(w http.ResponseWriter, r *http.Request) {
+	err := h.store.DeleteImage(r.Context(), chi.URLParam(r, "id"), chi.URLParam(r, "imageID"), auth.UserFrom(r.Context()))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+// AddMSRP adds a suggested-retail-price snapshot.
+func (h *Handler) AddMSRP(w http.ResponseWriter, r *http.Request) {
+	var in adminstore.MSRPInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	m, err := h.store.AddMSRP(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), in)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, m)
+}
+
+// DeleteMSRP removes an MSRP snapshot.
+func (h *Handler) DeleteMSRP(w http.ResponseWriter, r *http.Request) {
+	err := h.store.DeleteMSRP(r.Context(), chi.URLParam(r, "id"), chi.URLParam(r, "msrpID"), auth.UserFrom(r.Context()))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+// ---------- barcodes ----------
+
+// AddBarcode validates and attaches a barcode to a product. A code already
+// owned by another product yields 409 with the conflicting product so the
+// operator can de-duplicate; an invalid GTIN yields 400.
+func (h *Handler) AddBarcode(w http.ResponseWriter, r *http.Request) {
+	var in adminstore.BarcodeInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	b, err := h.store.AddBarcode(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), in)
+	if h.handleBarcodeErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, b)
+}
+
+// DeleteBarcode removes a barcode; a primary one is replaced automatically.
+func (h *Handler) DeleteBarcode(w http.ResponseWriter, r *http.Request) {
+	err := h.store.DeleteBarcode(r.Context(), chi.URLParam(r, "id"), chi.URLParam(r, "barcodeID"), auth.UserFrom(r.Context()))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+// SetPrimaryBarcode marks one barcode primary and mirrors it to product.gtin.
+func (h *Handler) SetPrimaryBarcode(w http.ResponseWriter, r *http.Request) {
+	b, err := h.store.SetPrimaryBarcode(r.Context(), chi.URLParam(r, "id"), chi.URLParam(r, "barcodeID"), auth.UserFrom(r.Context()))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, b)
+}
+
+// handleBarcodeErr maps barcode-specific errors (GTIN validation, ownership
+// conflict) to client-facing statuses, falling back to handleErr otherwise.
+func (h *Handler) handleBarcodeErr(w http.ResponseWriter, err error) bool {
+	if err == nil {
+		return false
+	}
+	var conflict *adminstore.ConflictError
+	if errors.As(err, &conflict) {
+		writeJSON(w, http.StatusConflict, map[string]any{
+			"error": map[string]string{"code": "barcode_conflict", "message": err.Error()},
+			"conflict": map[string]string{
+				"gtin":         conflict.GTIN,
+				"product_id":   conflict.ProductID,
+				"product_name": conflict.ProductName,
+			},
+		})
+		return true
+	}
+	if errors.Is(err, gtin.ErrEmpty) || errors.Is(err, gtin.ErrFormat) ||
+		errors.Is(err, gtin.ErrCheck) || errors.Is(err, gtin.ErrRestricted) {
+		writeError(w, http.StatusBadRequest, "invalid_gtin", err.Error())
+		return true
+	}
+	return h.handleErr(w, err)
+}
+
+// ListBrands returns brand options.
+func (h *Handler) ListBrands(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListBrands(r.Context())
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+// ListCategories returns category options.
+func (h *Handler) ListCategories(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListCategories(r.Context())
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+// ---------- submissions ----------
+
+// CreateSubmission accepts an anonymous public contribution into the queue.
+func (h *Handler) CreateSubmission(w http.ResponseWriter, r *http.Request) {
+	if !h.submitLimit.allow(realIP(r)) {
+		writeError(w, http.StatusTooManyRequests, "rate_limited", "提交过于频繁，请稍后再试")
+		return
+	}
+	var in adminstore.SubmissionInput
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if strings.TrimSpace(in.Name) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "商品名称不能为空")
+		return
+	}
+	id, err := h.store.CreateSubmission(r.Context(), in, realIP(r))
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "internal_error", err.Error())
+		return
+	}
+	writeJSON(w, http.StatusCreated, map[string]string{"id": id, "status": "pending"})
+}
+
+// ListSubmissions returns the moderation queue (admin).
+func (h *Handler) ListSubmissions(w http.ResponseWriter, r *http.Request) {
+	status := r.URL.Query().Get("status")
+	page, size := pageParams(r)
+	items, total, err := h.store.ListSubmissions(r.Context(), status, size, (page-1)*size)
+	if h.handleErr(w, err) {
+		return
+	}
+	pending, _ := h.store.PendingSubmissionCount(r.Context())
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items": items, "page": page, "size": size, "total": total, "pending": pending,
+	})
+}
+
+// GetSubmission returns full submission detail (admin).
+func (h *Handler) GetSubmission(w http.ResponseWriter, r *http.Request) {
+	d, err := h.store.GetSubmission(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, d)
+}
+
+// ApproveSubmission applies a contribution to the product store (admin).
+func (h *Handler) ApproveSubmission(w http.ResponseWriter, r *http.Request) {
+	d, err := h.store.ApproveSubmission(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()))
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, d)
+}
+
+// RejectSubmission rejects a contribution with a reviewer note (admin).
+func (h *Handler) RejectSubmission(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Note string `json:"note"`
+	}
+	_ = json.NewDecoder(r.Body).Decode(&body)
+	err := h.store.RejectSubmission(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), body.Note)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "rejected"})
+}
+
+// ---------- helpers ----------
+
+func realIP(r *http.Request) string {
+	if ip := r.Header.Get("X-Forwarded-For"); ip != "" {
+		if i := strings.IndexByte(ip, ','); i >= 0 {
+			return strings.TrimSpace(ip[:i])
+		}
+		return strings.TrimSpace(ip)
+	}
+	if ip := r.Header.Get("X-Real-IP"); ip != "" {
+		return ip
+	}
+	return r.RemoteAddr
+}
+
+func (h *Handler) handleErr(w http.ResponseWriter, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, adminstore.ErrNotFound) {
+		writeError(w, http.StatusNotFound, "not_found", "资源不存在")
+		return true
+	}
+	if errors.Is(err, adminstore.ErrConflict) {
+		writeError(w, http.StatusConflict, "conflict", "该投稿已被处理")
+		return true
+	}
+	writeError(w, http.StatusInternalServerError, "internal_error", err.Error())
+	return true
+}
+
+func pageParams(r *http.Request) (page, size int) {
+	page = atoiDefault(r.URL.Query().Get("page"), 1)
+	if page < 1 {
+		page = 1
+	}
+	size = atoiDefault(r.URL.Query().Get("size"), 20)
+	if size < 1 {
+		size = 20
+	}
+	if size > 100 {
+		size = 100
+	}
+	return page, size
+}
+
+func atoiDefault(s string, fallback int) int {
+	if s == "" {
+		return fallback
+	}
+	n := 0
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return fallback
+		}
+		n = n*10 + int(c-'0')
+	}
+	return n
+}
+
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(body)
+}
+
+func writeError(w http.ResponseWriter, status int, code, message string) {
+	writeJSON(w, status, map[string]any{"error": map[string]string{"code": code, "message": message}})
+}
@@ -0,0 +1,41 @@
+package adminhandler
+
+import (
+	"sync"
+	"time"
+)
+
+// rateLimiter is a simple fixed-window per-key limiter used to throttle
+// anonymous public submissions (basic anti-spam; captcha can be added later).
+type rateLimiter struct {
+	mu     sync.Mutex
+	hits   map[string][]time.Time
+	limit  int
+	window time.Duration
+}
+
+func newRateLimiter(limit int, window time.Duration) *rateLimiter {
+	return &rateLimiter{hits: map[string][]time.Time{}, limit: limit, window: window}
+}
+
+// allow reports whether the key may proceed, recording the hit if so.
+func (r *rateLimiter) allow(key string) bool {
+	now := time.Now()
+	cutoff := now.Add(-r.window)
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	kept := r.hits[key][:0]
+	for _, t := range r.hits[key] {
+		if t.After(cutoff) {
+			kept = append(kept, t)
+		}
+	}
+	if len(kept) >= r.limit {
+		r.hits[key] = kept
+		return false
+	}
+	r.hits[key] = append(kept, now)
+	return true
+}
@@ -0,0 +1,289 @@
+// Package adminstore is the read/write data-access layer for the admin console.
+// Unlike the public store (read-only), it performs INSERT/UPDATE/DELETE and
+// records field-level provenance (source = "manual") plus an audit_log entry
+// for every write, then recomputes product.quality_score.
+package adminstore
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// ErrNotFound is returned when a requested row does not exist.
+var ErrNotFound = errors.New("not found")
+
+// Store wraps a pgx pool for admin operations.
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+// New constructs an admin Store.
+func New(pool *pgxpool.Pool) *Store { return &Store{pool: pool} }
+
+// Ping verifies DB connectivity.
+func (s *Store) Ping(ctx context.Context) error { return s.pool.Ping(ctx) }
+
+// CompletenessFields mirrors ingestion/opengoods/etl/quality.py COMPLETENESS_FIELDS.
+var CompletenessFields = []string{
+	"name", "gtin", "brand", "category", "net_content",
+	"country_of_origin", "nutriments", "ingredients", "image",
+}
+
+// ---------- list ----------
+
+// ProductRow is a list-view row for the admin product table.
+type ProductRow struct {
+	ID           string   `json:"id"`
+	GTIN         *string  `json:"gtin"`
+	Name         string   `json:"name"`
+	Brand        *string  `json:"brand"`
+	CategoryPath *string  `json:"category_path"`
+	Status       string   `json:"status"`
+	QualityScore float64  `json:"quality_score"`
+	Missing      []string `json:"missing"`
+	UpdatedAt    string   `json:"updated_at"`
+}
+
+// ListProducts returns a paginated, optionally name/gtin-filtered list.
+func (s *Store) ListProducts(ctx context.Context, q string, limit, offset int) ([]ProductRow, int, error) {
+	args := []any{}
+	where := "WHERE 1=1"
+	if q != "" {
+		args = append(args, q)
+		where += " AND (p.name ILIKE '%' || $1 || '%' OR p.gtin ILIKE '%' || $1 || '%')"
+	}
+
+	var total int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM product p "+where, args...).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+
+	args = append(args, limit, offset)
+	sql := `
+SELECT p.id, p.gtin, p.name, b.name, c.path::text, p.status, p.quality_score,
+       p.updated_at,
+       (p.brand_id IS NOT NULL) AS has_brand,
+       (p.category_id IS NOT NULL) AS has_cat,
+       (p.net_content_canonical IS NOT NULL) AS has_net,
+       (p.country_of_origin IS NOT NULL AND p.country_of_origin <> '') AS has_country,
+       (f.nutriments IS NOT NULL AND f.nutriments::text <> '{}') AS has_nutri,
+       (f.ingredients_text IS NOT NULL AND f.ingredients_text <> '') AS has_ing,
+       EXISTS (SELECT 1 FROM product_image pi WHERE pi.product_id = p.id) AS has_img
+FROM product p
+LEFT JOIN brand b ON b.id = p.brand_id
+LEFT JOIN category c ON c.id = p.category_id
+LEFT JOIN food_detail f ON f.product_id = p.id ` + where +
+		" ORDER BY p.updated_at DESC LIMIT $" + strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
+
+	rows, err := s.pool.Query(ctx, sql, args...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	out := []ProductRow{}
+	for rows.Next() {
+		var r ProductRow
+		var hasBrand, hasCat, hasNet, hasCountry, hasNutri, hasIng, hasImg bool
+		var updated time.Time
+		if err := rows.Scan(&r.ID, &r.GTIN, &r.Name, &r.Brand, &r.CategoryPath, &r.Status,
+			&r.QualityScore, &updated, &hasBrand, &hasCat, &hasNet, &hasCountry,
+			&hasNutri, &hasIng, &hasImg); err != nil {
+			return nil, 0, err
+		}
+		r.UpdatedAt = updated.Format(time.RFC3339)
+		present := map[string]bool{
+			"name":              r.Name != "",
+			"gtin":              r.GTIN != nil && *r.GTIN != "",
+			"brand":             hasBrand,
+			"category":          hasCat,
+			"net_content":       hasNet,
+			"country_of_origin": hasCountry,
+			"nutriments":        hasNutri,
+			"ingredients":       hasIng,
+			"image":             hasImg,
+		}
+		r.Missing = []string{}
+		for _, f := range CompletenessFields {
+			if !present[f] {
+				r.Missing = append(r.Missing, f)
+			}
+		}
+		out = append(out, r)
+	}
+	return out, total, rows.Err()
+}
+
+// ---------- detail ----------
+
+// ProductImage is one image row.
+type ProductImage struct {
+	ID      string  `json:"id"`
+	URL     string  `json:"url"`
+	Kind    string  `json:"kind"`
+	License *string `json:"license"`
+}
+
+// MSRP is one suggested-retail-price snapshot.
+type MSRP struct {
+	ID            string  `json:"id"`
+	Amount        float64 `json:"amount"`
+	Currency      string  `json:"currency"`
+	Region        string  `json:"region"`
+	EffectiveDate *string `json:"effective_date"`
+	SourceURL     *string `json:"source_url"`
+	Note          *string `json:"note"`
+}
+
+// ProductDetail is the full editable view of a product.
+type ProductDetail struct {
+	ID              string         `json:"id"`
+	GTIN            *string        `json:"gtin"`
+	Name            string         `json:"name"`
+	BrandID         *string        `json:"brand_id"`
+	Brand           *string        `json:"brand"`
+	CategoryID      *string        `json:"category_id"`
+	CategoryPath    *string        `json:"category_path"`
+	NetContentValue *float64       `json:"net_content_value"`
+	NetContentUnit  *string        `json:"net_content_unit"`
+	CountryOfOrigin *string        `json:"country_of_origin"`
+	Status          string         `json:"status"`
+	QualityScore    float64        `json:"quality_score"`
+	IngredientsText *string        `json:"ingredients_text"`
+	Allergens       []string       `json:"allergens"`
+	Additives       []string       `json:"additives"`
+	Nutriments      map[string]any `json:"nutriments"`
+	NutritionBasis  *string        `json:"nutrition_basis"`
+	ServingSize     *string        `json:"serving_size"`
+	NutriScore      *string        `json:"nutri_score"`
+	Barcodes        []Barcode      `json:"barcodes"`
+	Images          []ProductImage `json:"images"`
+	MSRP            []MSRP         `json:"msrp"`
+	Missing         []string       `json:"missing"`
+	UpdatedAt       string         `json:"updated_at"`
+}
+
+// GetProduct returns the full editable detail for one product.
+func (s *Store) GetProduct(ctx context.Context, id string) (*ProductDetail, error) {
+	var d ProductDetail
+	var nutriments []byte
+	var updated time.Time
+	err := s.pool.QueryRow(ctx, `
+SELECT p.id, p.gtin, p.name, p.brand_id, b.name, p.category_id, c.path::text,
+       p.net_content_value, p.net_content_unit, p.country_of_origin, p.status,
+       p.quality_score, p.updated_at,
+       f.ingredients_text, f.allergens, f.additives, f.nutriments,
+       f.nutrition_basis, f.serving_size, f.nutri_score
+FROM product p
+LEFT JOIN brand b ON b.id = p.brand_id
+LEFT JOIN category c ON c.id = p.category_id
+LEFT JOIN food_detail f ON f.product_id = p.id
+WHERE p.id = $1`, id).Scan(
+		&d.ID, &d.GTIN, &d.Name, &d.BrandID, &d.Brand, &d.CategoryID, &d.CategoryPath,
+		&d.NetContentValue, &d.NetContentUnit, &d.CountryOfOrigin, &d.Status,
+		&d.QualityScore, &updated,
+		&d.IngredientsText, &d.Allergens, &d.Additives, &nutriments,
+		&d.NutritionBasis, &d.ServingSize, &d.NutriScore,
+	)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	d.UpdatedAt = updated.Format(time.RFC3339)
+	if len(nutriments) > 0 {
+		_ = json.Unmarshal(nutriments, &d.Nutriments)
+	}
+	if d.Allergens == nil {
+		d.Allergens = []string{}
+	}
+	if d.Additives == nil {
+		d.Additives = []string{}
+	}
+
+	bcs, err := s.listBarcodes(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	d.Barcodes = bcs
+
+	imgs, err := s.listImages(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	d.Images = imgs
+
+	msrps, err := s.listMSRP(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	d.MSRP = msrps
+
+	d.Missing = missingFromDetail(&d)
+	return &d, nil
+}
+
+func missingFromDetail(d *ProductDetail) []string {
+	present := map[string]bool{
+		"name":              d.Name != "",
+		"gtin":              d.GTIN != nil && *d.GTIN != "",
+		"brand":             d.BrandID != nil,
+		"category":          d.CategoryID != nil,
+		"net_content":       d.NetContentValue != nil,
+		"country_of_origin": d.CountryOfOrigin != nil && *d.CountryOfOrigin != "",
+		"nutriments":        len(d.Nutriments) > 0,
+		"ingredients":       d.IngredientsText != nil && *d.IngredientsText != "",
+		"image":             len(d.Images) > 0,
+	}
+	missing := []string{}
+	for _, f := range CompletenessFields {
+		if !present[f] {
+			missing = append(missing, f)
+		}
+	}
+	return missing
+}
+
+func (s *Store) listImages(ctx context.Context, productID string) ([]ProductImage, error) {
+	rows, err := s.pool.Query(ctx,
+		"SELECT id, url, kind, license FROM product_image WHERE product_id = $1 ORDER BY id", productID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []ProductImage{}
+	for rows.Next() {
+		var im ProductImage
+		if err := rows.Scan(&im.ID, &im.URL, &im.Kind, &im.License); err != nil {
+			return nil, err
+		}
+		out = append(out, im)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) listMSRP(ctx context.Context, productID string) ([]MSRP, error) {
+	rows, err := s.pool.Query(ctx, `
+SELECT id, amount, currency, region, effective_date::text, source_url, note
+FROM product_msrp WHERE product_id = $1 ORDER BY effective_date DESC NULLS LAST`, productID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []MSRP{}
+	for rows.Next() {
+		var m MSRP
+		if err := rows.Scan(&m.ID, &m.Amount, &m.Currency, &m.Region, &m.EffectiveDate, &m.SourceURL, &m.Note); err != nil {
+			return nil, err
+		}
+		out = append(out, m)
+	}
+	return out, rows.Err()
+}
@@ -0,0 +1,130 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgconn"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+)
+
+// APIKeyRow is an admin-facing view of an issued API key (never the secret).
+type APIKeyRow struct {
+	ID              string  `json:"id"`
+	Name            string  `json:"name"`
+	KeyPrefix       string  `json:"key_prefix"`
+	OwnerEmail      *string `json:"owner_email"`
+	Tier            string  `json:"tier"`
+	RateLimitPerMin int     `json:"rate_limit_per_min"`
+	RevokedAt       *string `json:"revoked_at"`
+	CreatedBy       *string `json:"created_by"`
+	CreatedAt       string  `json:"created_at"`
+}
+
+// APIKeyInput holds the fields accepted when issuing a key.
+type APIKeyInput struct {
+	Name            string `json:"name"`
+	OwnerEmail      string `json:"owner_email"`
+	Tier            string `json:"tier"`
+	RateLimitPerMin int    `json:"rate_limit_per_min"`
+}
+
+// CreateAPIKey issues a new key, returning the one-time plaintext alongside the
+// stored row. Only the SHA-256 hash and a short display prefix are persisted.
+func (s *Store) CreateAPIKey(ctx context.Context, in APIKeyInput, createdBy string) (plaintext string, row APIKeyRow, err error) {
+	tier := in.Tier
+	if tier == "" {
+		tier = "free"
+	}
+	rate := in.RateLimitPerMin
+	if rate <= 0 {
+		rate = 120
+	}
+	var owner *string
+	if e := strings.TrimSpace(in.OwnerEmail); e != "" {
+		owner = &e
+	}
+
+	key, hash, prefix, err := apikey.Generate()
+	if err != nil {
+		return "", row, err
+	}
+
+	var revoked, created *time.Time
+	var createdByOut *string
+	err = s.pool.QueryRow(ctx, `
+INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, created_by)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_at, created_by, created_at`,
+		strings.TrimSpace(in.Name), prefix, hash, owner, tier, rate, createdBy,
+	).Scan(&row.ID, &row.Name, &row.KeyPrefix, &row.OwnerEmail, &row.Tier,
+		&row.RateLimitPerMin, &revoked, &createdByOut, &created)
+	if err != nil {
+		return "", row, err
+	}
+	row.CreatedBy = createdByOut
+	if created != nil {
+		row.CreatedAt = created.Format(time.RFC3339)
+	}
+	return key, row, nil
+}
+
+// ListAPIKeys returns all keys (active first, newest first).
+func (s *Store) ListAPIKeys(ctx context.Context) ([]APIKeyRow, error) {
+	rows, err := s.pool.Query(ctx, `
+SELECT id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_at, created_by, created_at
+FROM api_key
+ORDER BY (revoked_at IS NULL) DESC, created_at DESC`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []APIKeyRow{}
+	for rows.Next() {
+		var r APIKeyRow
+		var revoked, created *time.Time
+		if err := rows.Scan(&r.ID, &r.Name, &r.KeyPrefix, &r.OwnerEmail, &r.Tier,
+			&r.RateLimitPerMin, &revoked, &r.CreatedBy, &created); err != nil {
+			return nil, err
+		}
+		if revoked != nil {
+			v := revoked.Format(time.RFC3339)
+			r.RevokedAt = &v
+		}
+		if created != nil {
+			r.CreatedAt = created.Format(time.RFC3339)
+		}
+		out = append(out, r)
+	}
+	return out, rows.Err()
+}
+
+// RevokeAPIKey marks a key revoked. Revoking an already-revoked or missing key
+// returns ErrNotFound.
+func (s *Store) RevokeAPIKey(ctx context.Context, id string) error {
+	tag, err := s.pool.Exec(ctx,
+		"UPDATE api_key SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL", id)
+	if err != nil {
+		if isInvalidUUID(err) {
+			return ErrNotFound
+		}
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	return nil
+}
+
+// isInvalidUUID reports whether err is a Postgres invalid-UUID-text error,
+// which happens when a non-UUID id is supplied.
+func isInvalidUUID(err error) bool {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) {
+		return pgErr.Code == "22P02"
+	}
+	return false
+}
@@ -0,0 +1,270 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+
+	"github.com/jackc/pgx/v5"
+
+	"github.com/baicai2026-baicai/goods/api/internal/gtin"
+)
+
+// Barcode is one GS1 trade item number attached to a product.
+type Barcode struct {
+	ID        string  `json:"id"`
+	GTIN      string  `json:"gtin"`
+	GTINType  string  `json:"gtin_type"`
+	PackLevel string  `json:"pack_level"`
+	Region    *string `json:"region"`
+	IsPrimary bool    `json:"is_primary"`
+}
+
+// BarcodeInput is the payload for attaching a barcode to a product.
+type BarcodeInput struct {
+	GTIN      string  `json:"gtin"`
+	GTINType  string  `json:"gtin_type"`
+	PackLevel string  `json:"pack_level"`
+	Region    *string `json:"region"`
+	IsPrimary bool    `json:"is_primary"`
+}
+
+// ConflictError signals that a barcode is already attached to another product,
+// so the operator must de-duplicate instead of creating a clash.
+type ConflictError struct {
+	GTIN        string
+	ProductID   string
+	ProductName string
+}
+
+func (e *ConflictError) Error() string { return "条码已被其他商品占用：" + e.GTIN }
+
+func validPackLevel(p string) string {
+	switch p {
+	case "each", "case", "pallet":
+		return p
+	default:
+		return "each"
+	}
+}
+
+func validGTINType(t, normalized string) string {
+	switch t {
+	case "EAN8", "UPC", "EAN13", "ITF14", "GTIN14":
+		return t
+	default:
+		return gtin.InferType(normalized)
+	}
+}
+
+func (s *Store) listBarcodes(ctx context.Context, productID string) ([]Barcode, error) {
+	rows, err := s.pool.Query(ctx,
+		`SELECT id, gtin, gtin_type, pack_level, region, is_primary
+		 FROM product_barcode WHERE product_id = $1
+		 ORDER BY is_primary DESC, gtin`, productID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Barcode{}
+	for rows.Next() {
+		var b Barcode
+		if err := rows.Scan(&b.ID, &b.GTIN, &b.GTINType, &b.PackLevel, &b.Region, &b.IsPrimary); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
+// barcodeOwner returns the product currently owning a barcode, if any.
+func barcodeOwner(ctx context.Context, q pgx.Tx, code string) (productID, productName string, found bool, err error) {
+	err = q.QueryRow(ctx,
+		`SELECT pb.product_id, p.name FROM product_barcode pb
+		 JOIN product p ON p.id = pb.product_id WHERE pb.gtin = $1`, code).
+		Scan(&productID, &productName)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", "", false, nil
+	}
+	if err != nil {
+		return "", "", false, err
+	}
+	return productID, productName, true, nil
+}
+
+// AddBarcode validates and attaches a barcode to a product, recording audit.
+// A barcode already owned by another product yields a *ConflictError.
+func (s *Store) AddBarcode(ctx context.Context, productID, actor string, in BarcodeInput) (*Barcode, error) {
+	code, err := gtin.Normalize(in.GTIN)
+	if err != nil {
+		return nil, err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	// Product must exist.
+	var exists bool
+	if err := tx.QueryRow(ctx, "SELECT EXISTS(SELECT 1 FROM product WHERE id=$1)", productID).Scan(&exists); err != nil {
+		return nil, err
+	}
+	if !exists {
+		return nil, ErrNotFound
+	}
+
+	// Globally unique: a barcode owned by any product (this one included)
+	// is a conflict the operator must resolve by de-duplicating.
+	if owner, name, found, err := barcodeOwner(ctx, tx, code); err != nil {
+		return nil, err
+	} else if found {
+		return nil, &ConflictError{GTIN: code, ProductID: owner, ProductName: name}
+	}
+
+	// Make this the primary barcode when requested or when none exists yet.
+	makePrimary := in.IsPrimary
+	if !makePrimary {
+		var hasPrimary bool
+		if err := tx.QueryRow(ctx,
+			"SELECT EXISTS(SELECT 1 FROM product_barcode WHERE product_id=$1 AND is_primary)", productID).
+			Scan(&hasPrimary); err != nil {
+			return nil, err
+		}
+		makePrimary = !hasPrimary
+	}
+	if makePrimary {
+		if _, err := tx.Exec(ctx,
+			"UPDATE product_barcode SET is_primary=false WHERE product_id=$1 AND is_primary", productID); err != nil {
+			return nil, err
+		}
+	}
+
+	srcID, _ := s.manualSourceID(ctx, tx)
+	var srcArg any
+	if srcID != "" {
+		srcArg = srcID
+	}
+
+	var b Barcode
+	err = tx.QueryRow(ctx, `
+INSERT INTO product_barcode (product_id, gtin, gtin_type, pack_level, region, is_primary, source_id)
+VALUES ($1,$2,$3,$4,$5,$6,$7)
+RETURNING id, gtin, gtin_type, pack_level, region, is_primary`,
+		productID, code, validGTINType(in.GTINType, code), validPackLevel(in.PackLevel),
+		in.Region, makePrimary, srcArg).
+		Scan(&b.ID, &b.GTIN, &b.GTINType, &b.PackLevel, &b.Region, &b.IsPrimary)
+	if err != nil {
+		return nil, err
+	}
+
+	if makePrimary {
+		if _, err := tx.Exec(ctx, "UPDATE product SET gtin=$2 WHERE id=$1", productID, code); err != nil {
+			return nil, err
+		}
+	}
+	if _, err := s.recomputeQualityTx(ctx, tx, productID); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+
+	_ = s.writeAudit(ctx, actor, "add_barcode", "product", &productID, []string{"gtin"}, nil, b)
+	return &b, nil
+}
+
+// DeleteBarcode removes a barcode; if it was primary, another is promoted.
+func (s *Store) DeleteBarcode(ctx context.Context, productID, barcodeID, actor string) error {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	var code string
+	var wasPrimary bool
+	err = tx.QueryRow(ctx,
+		"DELETE FROM product_barcode WHERE id=$1 AND product_id=$2 RETURNING gtin, is_primary",
+		barcodeID, productID).Scan(&code, &wasPrimary)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return ErrNotFound
+	}
+	if err != nil {
+		return err
+	}
+
+	if wasPrimary {
+		var newID, newGTIN string
+		e := tx.QueryRow(ctx,
+			"SELECT id, gtin FROM product_barcode WHERE product_id=$1 ORDER BY gtin LIMIT 1", productID).
+			Scan(&newID, &newGTIN)
+		if e == nil {
+			if _, err := tx.Exec(ctx, "UPDATE product_barcode SET is_primary=true WHERE id=$1", newID); err != nil {
+				return err
+			}
+			if _, err := tx.Exec(ctx, "UPDATE product SET gtin=$2 WHERE id=$1", productID, newGTIN); err != nil {
+				return err
+			}
+		} else if errors.Is(e, pgx.ErrNoRows) {
+			if _, err := tx.Exec(ctx, "UPDATE product SET gtin=NULL WHERE id=$1", productID); err != nil {
+				return err
+			}
+		} else {
+			return e
+		}
+	}
+
+	if _, err := s.recomputeQualityTx(ctx, tx, productID); err != nil {
+		return err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return err
+	}
+	_ = s.writeAudit(ctx, actor, "delete_barcode", "product", &productID, []string{"gtin"},
+		map[string]string{"gtin": code}, nil)
+	return nil
+}
+
+// SetPrimaryBarcode marks one barcode primary and mirrors it to product.gtin.
+func (s *Store) SetPrimaryBarcode(ctx context.Context, productID, barcodeID, actor string) (*Barcode, error) {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var code string
+	err = tx.QueryRow(ctx, "SELECT gtin FROM product_barcode WHERE id=$1 AND product_id=$2", barcodeID, productID).Scan(&code)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "UPDATE product_barcode SET is_primary=false WHERE product_id=$1 AND is_primary", productID); err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "UPDATE product_barcode SET is_primary=true WHERE id=$1", barcodeID); err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "UPDATE product SET gtin=$2 WHERE id=$1", productID, code); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "set_primary_barcode", "product", &productID, []string{"gtin"}, nil,
+		map[string]string{"gtin": code})
+
+	bcs, err := s.listBarcodes(ctx, productID)
+	if err != nil {
+		return nil, err
+	}
+	for i := range bcs {
+		if bcs[i].ID == barcodeID {
+			return &bcs[i], nil
+		}
+	}
+	return nil, ErrNotFound
+}
@@ -0,0 +1,137 @@
+package adminstore
+
+import (
+	"context"
+	"math"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// Quality weights mirror ingestion/opengoods/etl/quality.py.
+const (
+	wCompleteness = 0.4
+	wSourceTrust  = 0.3
+	wAgreement    = 0.2
+	wFreshness    = 0.1
+)
+
+// queryer is satisfied by both *pgxpool.Pool and pgx.Tx.
+type queryer interface {
+	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
+}
+
+func agreementFromSources(n int) float64 {
+	switch {
+	case n <= 1:
+		return 0.5
+	case n == 2:
+		return 0.8
+	default:
+		return 1.0
+	}
+}
+
+func freshnessFromAge(ageDays *float64) float64 {
+	if ageDays == nil {
+		return 0.5
+	}
+	d := *ageDays
+	switch {
+	case d <= 30:
+		return 1.0
+	case d <= 180:
+		return 0.8
+	case d <= 365:
+		return 0.6
+	case d <= 730:
+		return 0.4
+	default:
+		return 0.2
+	}
+}
+
+func (s *Store) computeQuality(ctx context.Context, q queryer, productID string) (float64, error) {
+	var name, country *string
+	var gtin *string
+	var brandID, categoryID *string
+	var netCanonical *float64
+	var ingredients *string
+	var hasNutri, hasImage bool
+	err := q.QueryRow(ctx, `
+SELECT p.name, p.gtin, p.brand_id, p.category_id, p.net_content_canonical,
+       p.country_of_origin, f.ingredients_text,
+       (f.nutriments IS NOT NULL AND f.nutriments::text <> '{}'),
+       EXISTS (SELECT 1 FROM product_image pi WHERE pi.product_id = p.id)
+FROM product p LEFT JOIN food_detail f ON f.product_id = p.id
+WHERE p.id = $1`, productID).Scan(
+		&name, &gtin, &brandID, &categoryID, &netCanonical, &country,
+		&ingredients, &hasNutri, &hasImage)
+	if err != nil {
+		return 0, err
+	}
+
+	present := 0
+	bump := func(ok bool) {
+		if ok {
+			present++
+		}
+	}
+	bump(name != nil && *name != "")
+	bump(gtin != nil && *gtin != "")
+	bump(brandID != nil)
+	bump(categoryID != nil)
+	bump(netCanonical != nil)
+	bump(country != nil && *country != "")
+	bump(hasNutri)
+	bump(ingredients != nil && *ingredients != "")
+	bump(hasImage)
+	completeness := float64(present) / float64(len(CompletenessFields))
+
+	var sourceCount int
+	var sourceTrust *float64
+	var lastFetched *time.Time
+	err = q.QueryRow(ctx, `
+SELECT count(DISTINCT ps.source_id), COALESCE(max(s.trust_weight),0), max(ps.fetched_at)
+FROM product_source ps LEFT JOIN source s ON s.id = ps.source_id
+WHERE ps.product_id = $1`, productID).Scan(&sourceCount, &sourceTrust, &lastFetched)
+	if err != nil {
+		return 0, err
+	}
+	trust := 0.0
+	if sourceTrust != nil {
+		trust = *sourceTrust
+	}
+
+	var ageDays *float64
+	if lastFetched != nil {
+		d := time.Since(*lastFetched).Hours() / 24.0
+		if d < 0 {
+			d = 0
+		}
+		ageDays = &d
+	}
+
+	raw := wCompleteness*completeness + wSourceTrust*trust +
+		wAgreement*agreementFromSources(sourceCount) + wFreshness*freshnessFromAge(ageDays)
+	raw = math.Max(0, math.Min(1, raw))
+	return math.Round(raw*1000) / 1000, nil
+}
+
+func (s *Store) recomputeQualityTx(ctx context.Context, tx pgx.Tx, productID string) (float64, error) {
+	v, err := s.computeQuality(ctx, tx, productID)
+	if err != nil {
+		return 0, err
+	}
+	_, err = tx.Exec(ctx, "UPDATE product SET quality_score=$1 WHERE id=$2", v, productID)
+	return v, err
+}
+
+func (s *Store) recomputeQuality(ctx context.Context, productID string) (float64, error) {
+	v, err := s.computeQuality(ctx, s.pool, productID)
+	if err != nil {
+		return 0, err
+	}
+	_, err = s.pool.Exec(ctx, "UPDATE product SET quality_score=$1 WHERE id=$2", v, productID)
+	return v, err
+}
@@ -0,0 +1,30 @@
+package adminstore
+
+import "testing"
+
+func TestAgreementFromSources(t *testing.T) {
+	cases := map[int]float64{0: 0.5, 1: 0.5, 2: 0.8, 3: 1.0, 9: 1.0}
+	for n, want := range cases {
+		if got := agreementFromSources(n); got != want {
+			t.Errorf("agreementFromSources(%d) = %v, want %v", n, got, want)
+		}
+	}
+}
+
+func TestFreshnessFromAge(t *testing.T) {
+	mk := func(d float64) *float64 { return &d }
+	if got := freshnessFromAge(nil); got != 0.5 {
+		t.Errorf("nil age = %v, want 0.5", got)
+	}
+	cases := []struct {
+		days float64
+		want float64
+	}{
+		{10, 1.0}, {30, 1.0}, {100, 0.8}, {300, 0.6}, {500, 0.4}, {1000, 0.2},
+	}
+	for _, c := range cases {
+		if got := freshnessFromAge(mk(c.days)); got != c.want {
+			t.Errorf("freshnessFromAge(%v) = %v, want %v", c.days, got, c.want)
+		}
+	}
+}
@@ -0,0 +1,421 @@
+package adminstore
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// ErrConflict is returned when a submission has already been reviewed.
+var ErrConflict = errors.New("conflict")
+
+// SubmissionImage is one proposed image URL inside a contribution.
+type SubmissionImage struct {
+	URL  string `json:"url"`
+	Kind string `json:"kind"`
+}
+
+// SubmissionInput is the public contribution payload (no login required).
+type SubmissionInput struct {
+	GTIN             *string           `json:"gtin"`
+	Name             string            `json:"name"`
+	BrandName        *string           `json:"brand_name"`
+	CategoryID       *string           `json:"category_id"`
+	NetContentValue  *float64          `json:"net_content_value"`
+	NetContentUnit   *string           `json:"net_content_unit"`
+	CountryOfOrigin  *string           `json:"country_of_origin"`
+	IngredientsText  *string           `json:"ingredients_text"`
+	Nutriments       map[string]any    `json:"nutriments"`
+	NutritionBasis   *string           `json:"nutrition_basis"`
+	ServingSize      *string           `json:"serving_size"`
+	NutriScore       *string           `json:"nutri_score"`
+	Images           []SubmissionImage `json:"images"`
+	MSRP             []MSRPInput       `json:"msrp"`
+	SubmitterName    *string           `json:"submitter_name"`
+	SubmitterContact *string           `json:"submitter_contact"`
+	Note             *string           `json:"note"`
+}
+
+// SubmissionRow is a queue-list row for the admin review table.
+type SubmissionRow struct {
+	ID            string  `json:"id"`
+	GTIN          *string `json:"gtin"`
+	Name          string  `json:"name"`
+	Status        string  `json:"status"`
+	SubmitterName *string `json:"submitter_name"`
+	Matched       bool    `json:"matched"`
+	CreatedAt     string  `json:"created_at"`
+	ReviewedAt    *string `json:"reviewed_at"`
+}
+
+// SubmissionDetail is the full review view of one contribution.
+type SubmissionDetail struct {
+	ID               string          `json:"id"`
+	Status           string          `json:"status"`
+	GTIN             *string         `json:"gtin"`
+	Name             string          `json:"name"`
+	SubmitterName    *string         `json:"submitter_name"`
+	SubmitterContact *string         `json:"submitter_contact"`
+	Note             *string         `json:"note"`
+	ReviewNote       *string         `json:"review_note"`
+	ReviewedBy       *string         `json:"reviewed_by"`
+	ReviewedAt       *string         `json:"reviewed_at"`
+	CreatedAt        string          `json:"created_at"`
+	TargetProductID  *string         `json:"target_product_id"`
+	ResultProductID  *string         `json:"result_product_id"`
+	Payload          SubmissionInput `json:"payload"`
+	ExistingProduct  *ProductDetail  `json:"existing_product,omitempty"`
+}
+
+// CreateSubmission validates and stores a public contribution as pending.
+func (s *Store) CreateSubmission(ctx context.Context, in SubmissionInput, remoteIP string) (string, error) {
+	in.Name = strings.TrimSpace(in.Name)
+	if in.Name == "" {
+		return "", errors.New("商品名称不能为空")
+	}
+	if in.GTIN != nil {
+		g := strings.TrimSpace(*in.GTIN)
+		if g == "" {
+			in.GTIN = nil
+		} else {
+			in.GTIN = &g
+		}
+	}
+
+	// Link to an existing product when the barcode already exists (supplement).
+	var target *string
+	if in.GTIN != nil {
+		var pid string
+		err := s.pool.QueryRow(ctx, "SELECT id FROM product WHERE gtin = $1", *in.GTIN).Scan(&pid)
+		if err == nil {
+			target = &pid
+		} else if !errors.Is(err, pgx.ErrNoRows) {
+			return "", err
+		}
+	}
+
+	payload, err := json.Marshal(in)
+	if err != nil {
+		return "", err
+	}
+
+	var id string
+	err = s.pool.QueryRow(ctx, `
+INSERT INTO submission (gtin, name, payload, target_product_id, submitter_name, submitter_contact, note, remote_ip)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8) RETURNING id`,
+		in.GTIN, in.Name, payload, target, in.SubmitterName, in.SubmitterContact, in.Note, remoteIP).Scan(&id)
+	return id, err
+}
+
+// ListSubmissions returns submissions filtered by status (empty = all).
+func (s *Store) ListSubmissions(ctx context.Context, status string, limit, offset int) ([]SubmissionRow, int, error) {
+	args := []any{}
+	where := "WHERE 1=1"
+	if status != "" {
+		args = append(args, status)
+		where += " AND status = $1"
+	}
+
+	var total int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM submission "+where, args...).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+
+	args = append(args, limit, offset)
+	sql := `
+SELECT id, gtin, name, status, submitter_name, (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))
+
+	rows, err := s.pool.Query(ctx, sql, args...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	out := []SubmissionRow{}
+	for rows.Next() {
+		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 {
+			return nil, 0, err
+		}
+		r.CreatedAt = created.Format(time.RFC3339)
+		if reviewed != nil {
+			t := reviewed.Format(time.RFC3339)
+			r.ReviewedAt = &t
+		}
+		out = append(out, r)
+	}
+	return out, total, rows.Err()
+}
+
+// PendingSubmissionCount returns the number of submissions awaiting review.
+func (s *Store) PendingSubmissionCount(ctx context.Context) (int, error) {
+	var n int
+	err := s.pool.QueryRow(ctx, "SELECT count(*) FROM submission WHERE status='pending'").Scan(&n)
+	return n, err
+}
+
+// GetSubmission returns the full review detail for one submission.
+func (s *Store) GetSubmission(ctx context.Context, id string) (*SubmissionDetail, error) {
+	var d SubmissionDetail
+	var payload []byte
+	var created time.Time
+	var reviewed *time.Time
+	err := s.pool.QueryRow(ctx, `
+SELECT id, status, gtin, name, submitter_name, submitter_contact, note,
+       review_note, reviewed_by, reviewed_at, created_at, target_product_id, result_product_id, payload
+FROM submission WHERE id = $1`, id).Scan(
+		&d.ID, &d.Status, &d.GTIN, &d.Name, &d.SubmitterName, &d.SubmitterContact, &d.Note,
+		&d.ReviewNote, &d.ReviewedBy, &reviewed, &created, &d.TargetProductID, &d.ResultProductID, &payload,
+	)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	d.CreatedAt = created.Format(time.RFC3339)
+	if reviewed != nil {
+		t := reviewed.Format(time.RFC3339)
+		d.ReviewedAt = &t
+	}
+	if len(payload) > 0 {
+		_ = json.Unmarshal(payload, &d.Payload)
+	}
+	if d.TargetProductID != nil {
+		if ep, err := s.GetProduct(ctx, *d.TargetProductID); err == nil {
+			d.ExistingProduct = ep
+		}
+	}
+	return &d, nil
+}
+
+// RejectSubmission marks a pending submission as rejected with a reviewer note.
+func (s *Store) RejectSubmission(ctx context.Context, id, actor, note string) error {
+	ct, err := s.pool.Exec(ctx, `
+UPDATE submission SET status='rejected', review_note=$2, reviewed_by=$3, reviewed_at=now()
+WHERE id=$1 AND status='pending'`, id, note, actor)
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		// Distinguish missing vs already-reviewed.
+		var st string
+		if e := s.pool.QueryRow(ctx, "SELECT status FROM submission WHERE id=$1", id).Scan(&st); errors.Is(e, pgx.ErrNoRows) {
+			return ErrNotFound
+		}
+		return ErrConflict
+	}
+	_ = s.writeAudit(ctx, actor, "reject_submission", "submission", &id, []string{}, nil, map[string]string{"review_note": note})
+	return nil
+}
+
+// ApproveSubmission applies a pending contribution to the product store
+// (creating or supplementing a product), records community provenance + audit,
+// recomputes quality, and marks the submission approved.
+func (s *Store) ApproveSubmission(ctx context.Context, id, actor string) (*ProductDetail, error) {
+	sub, err := s.GetSubmission(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	if sub.Status != "pending" {
+		return nil, ErrConflict
+	}
+	in := sub.Payload
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	communityID, err := s.sourceIDTx(ctx, tx, "community")
+	if err != nil {
+		return nil, err
+	}
+
+	// Resolve the target product (existing supplement vs new create).
+	productID := ""
+	if sub.TargetProductID != nil {
+		productID = *sub.TargetProductID
+	} else if in.GTIN != nil {
+		var pid string
+		if e := tx.QueryRow(ctx, "SELECT id FROM product WHERE gtin=$1", *in.GTIN).Scan(&pid); e == nil {
+			productID = pid
+		} else if !errors.Is(e, pgx.ErrNoRows) {
+			return nil, e
+		}
+	}
+
+	var brandID *string
+	if in.BrandName != nil && strings.TrimSpace(*in.BrandName) != "" {
+		bid, err := s.ensureBrand(ctx, tx, strings.TrimSpace(*in.BrandName))
+		if err != nil {
+			return nil, err
+		}
+		brandID = &bid
+	}
+	var gpc *string
+	if in.CategoryID != nil && *in.CategoryID != "" {
+		if err := tx.QueryRow(ctx, "SELECT gpc_brick_code FROM category WHERE id=$1", *in.CategoryID).Scan(&gpc); err != nil && !errors.Is(err, pgx.ErrNoRows) {
+			return nil, err
+		}
+	}
+	canonical, err := s.netCanonical(ctx, tx, in.NetContentValue, in.NetContentUnit)
+	if err != nil {
+		return nil, err
+	}
+
+	fields := submissionFields(in)
+
+	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`,
+			in.GTIN, in.Name, brandID, in.CategoryID, gpc,
+			in.NetContentValue, in.NetContentUnit, canonical, in.CountryOfOrigin).Scan(&productID)
+		if err != nil {
+			return nil, err
+		}
+	} else {
+		// Supplement an existing product: only overwrite fields the
+		// contribution actually provides (COALESCE keeps current values).
+		_, err = tx.Exec(ctx, `
+UPDATE product SET
+   name=COALESCE(NULLIF($2,''), name),
+   brand_id=COALESCE($3, brand_id),
+   category_id=COALESCE($4, category_id),
+   gpc_brick_code=COALESCE($5, gpc_brick_code),
+   net_content_value=COALESCE($6, net_content_value),
+   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)
+WHERE id=$1`,
+			productID, in.Name, brandID, in.CategoryID, gpc,
+			in.NetContentValue, in.NetContentUnit, canonical, in.CountryOfOrigin, in.GTIN)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	// food_detail: upsert, preserving existing values where not provided.
+	var nutriJSON []byte
+	if len(in.Nutriments) > 0 {
+		nutriJSON, _ = json.Marshal(in.Nutriments)
+	}
+	_, 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)
+ON CONFLICT (product_id) DO UPDATE SET
+   ingredients_text=COALESCE(EXCLUDED.ingredients_text, food_detail.ingredients_text),
+   nutriments=COALESCE(EXCLUDED.nutriments, food_detail.nutriments),
+   nutrition_basis=COALESCE(EXCLUDED.nutrition_basis, food_detail.nutrition_basis),
+   serving_size=COALESCE(EXCLUDED.serving_size, food_detail.serving_size),
+   nutri_score=COALESCE(EXCLUDED.nutri_score, food_detail.nutri_score)`,
+		productID, in.IngredientsText, nutriJSON, in.NutritionBasis, in.ServingSize, in.NutriScore)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, im := range in.Images {
+		url := strings.TrimSpace(im.URL)
+		if url == "" {
+			continue
+		}
+		kind := im.Kind
+		if kind != "front" && kind != "ingredients" && kind != "nutrition" {
+			kind = "other"
+		}
+		if _, err := tx.Exec(ctx, `
+INSERT INTO product_image (product_id, url, kind, source_id) VALUES ($1,$2,$3,$4)`,
+			productID, url, kind, communityID); err != nil {
+			return nil, err
+		}
+	}
+
+	for _, m := range in.MSRP {
+		if m.Amount <= 0 {
+			continue
+		}
+		cur := m.Currency
+		if cur == "" {
+			cur = "CNY"
+		}
+		region := m.Region
+		if region == "" {
+			region = "CN"
+		}
+		if _, err := tx.Exec(ctx, `
+INSERT INTO product_msrp (product_id, amount, currency, region, source_id, source_url, effective_date, note)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8)`,
+			productID, m.Amount, cur, region, communityID, m.SourceURL, m.EffectiveDate, m.Note); err != nil {
+			return nil, err
+		}
+	}
+
+	if _, err := s.recomputeQualityTx(ctx, tx, productID); err != nil {
+		return nil, err
+	}
+
+	if _, err := tx.Exec(ctx, `
+UPDATE submission SET status='approved', reviewed_by=$2, reviewed_at=now(), result_product_id=$3
+WHERE id=$1`, id, actor, productID); err != nil {
+		return nil, err
+	}
+
+	// Field-level provenance for the contributed fields (community source).
+	if len(fields) > 0 {
+		if _, err := tx.Exec(ctx, `
+INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+VALUES ($1,$2,NULL,$3,now(),NULL)`, productID, communityID, fields); err != nil {
+			return nil, err
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+
+	_ = s.writeAudit(ctx, actor, "approve_submission", "product", &productID, fields,
+		map[string]string{"submission_id": id}, map[string]string{"product_id": productID})
+
+	return s.GetProduct(ctx, productID)
+}
+
+func (s *Store) sourceIDTx(ctx context.Context, tx pgx.Tx, name string) (string, error) {
+	var id string
+	err := tx.QueryRow(ctx, "SELECT id FROM source WHERE name=$1", name).Scan(&id)
+	return id, err
+}
+
+// submissionFields lists the product fields a contribution provides values for.
+func submissionFields(in SubmissionInput) []string {
+	fields := []string{"name"}
+	add := func(name string, present bool) {
+		if present {
+			fields = append(fields, name)
+		}
+	}
+	add("gtin", in.GTIN != nil && *in.GTIN != "")
+	add("brand", in.BrandName != nil && strings.TrimSpace(*in.BrandName) != "")
+	add("category", in.CategoryID != nil && *in.CategoryID != "")
+	add("net_content", in.NetContentValue != nil)
+	add("country_of_origin", in.CountryOfOrigin != nil && *in.CountryOfOrigin != "")
+	add("ingredients", in.IngredientsText != nil && *in.IngredientsText != "")
+	add("nutriments", len(in.Nutriments) > 0)
+	add("image", len(in.Images) > 0)
+	return fields
+}
@@ -0,0 +1,415 @@
+package adminstore
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// ProductInput is the editable payload accepted from the admin UI.
+type ProductInput struct {
+	GTIN            *string        `json:"gtin"`
+	Name            string         `json:"name"`
+	BrandID         *string        `json:"brand_id"`
+	BrandName       *string        `json:"brand_name"`
+	CategoryID      *string        `json:"category_id"`
+	NetContentValue *float64       `json:"net_content_value"`
+	NetContentUnit  *string        `json:"net_content_unit"`
+	CountryOfOrigin *string        `json:"country_of_origin"`
+	Status          string         `json:"status"`
+	IngredientsText *string        `json:"ingredients_text"`
+	Allergens       []string       `json:"allergens"`
+	Additives       []string       `json:"additives"`
+	Nutriments      map[string]any `json:"nutriments"`
+	NutritionBasis  *string        `json:"nutrition_basis"`
+	ServingSize     *string        `json:"serving_size"`
+	NutriScore      *string        `json:"nutri_score"`
+}
+
+func normBrand(name string) string { return strings.Join(strings.Fields(strings.ToLower(name)), " ") }
+
+func (s *Store) ensureBrand(ctx context.Context, tx pgx.Tx, name string) (string, error) {
+	var id string
+	err := tx.QueryRow(ctx, `
+INSERT INTO brand (name, normalized_name) VALUES ($1, $2)
+ON CONFLICT (normalized_name) DO UPDATE SET name = brand.name
+RETURNING id`, name, normBrand(name)).Scan(&id)
+	return id, err
+}
+
+func (s *Store) manualSourceID(ctx context.Context, tx pgx.Tx) (string, error) {
+	var id string
+	err := tx.QueryRow(ctx, "SELECT id FROM source WHERE name = 'manual'").Scan(&id)
+	return id, err
+}
+
+// netCanonical converts value+unit to the canonical base unit via the unit table.
+func (s *Store) netCanonical(ctx context.Context, tx pgx.Tx, value *float64, unit *string) (*float64, error) {
+	if value == nil || unit == nil || *unit == "" {
+		return nil, nil
+	}
+	var factor *float64
+	err := tx.QueryRow(ctx, "SELECT to_canonical_factor FROM unit WHERE code = $1", *unit).Scan(&factor)
+	if errors.Is(err, pgx.ErrNoRows) || factor == nil {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	c := *value * *factor
+	return &c, nil
+}
+
+// UpdateProduct applies an edit, records provenance + audit, and recomputes quality.
+func (s *Store) UpdateProduct(ctx context.Context, id, actor string, in ProductInput) (*ProductDetail, error) {
+	before, err := s.GetProduct(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	// Resolve brand (create-by-name takes precedence over id).
+	brandID := in.BrandID
+	if in.BrandName != nil && strings.TrimSpace(*in.BrandName) != "" {
+		bid, err := s.ensureBrand(ctx, tx, strings.TrimSpace(*in.BrandName))
+		if err != nil {
+			return nil, err
+		}
+		brandID = &bid
+	}
+
+	// Resolve category gpc brick code.
+	var gpc *string
+	if in.CategoryID != nil && *in.CategoryID != "" {
+		if err := tx.QueryRow(ctx, "SELECT gpc_brick_code FROM category WHERE id = $1", *in.CategoryID).Scan(&gpc); err != nil && !errors.Is(err, pgx.ErrNoRows) {
+			return nil, err
+		}
+	}
+
+	canonical, err := s.netCanonical(ctx, tx, in.NetContentValue, in.NetContentUnit)
+	if err != nil {
+		return nil, err
+	}
+
+	status := in.Status
+	if status == "" {
+		status = before.Status
+	}
+
+	_, err = tx.Exec(ctx, `
+UPDATE product SET gtin=$1, name=$2, brand_id=$3, category_id=$4, gpc_brick_code=$5,
+   net_content_value=$6, net_content_unit=$7, net_content_canonical=$8,
+   country_of_origin=$9, status=$10
+WHERE id=$11`,
+		in.GTIN, in.Name, brandID, in.CategoryID, gpc,
+		in.NetContentValue, in.NetContentUnit, canonical,
+		in.CountryOfOrigin, status, id)
+	if err != nil {
+		return nil, err
+	}
+
+	var nutriJSON []byte
+	if in.Nutriments != nil {
+		nutriJSON, _ = json.Marshal(in.Nutriments)
+	}
+	allergens := in.Allergens
+	if allergens == nil {
+		allergens = []string{}
+	}
+	additives := in.Additives
+	if additives == nil {
+		additives = []string{}
+	}
+	_, err = tx.Exec(ctx, `
+INSERT INTO food_detail (product_id, ingredients_text, allergens, additives,
+   nutriments, nutrition_basis, serving_size, nutri_score)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
+ON CONFLICT (product_id) DO UPDATE SET
+   ingredients_text=EXCLUDED.ingredients_text,
+   allergens=EXCLUDED.allergens,
+   additives=EXCLUDED.additives,
+   nutriments=EXCLUDED.nutriments,
+   nutrition_basis=EXCLUDED.nutrition_basis,
+   serving_size=EXCLUDED.serving_size,
+   nutri_score=EXCLUDED.nutri_score`,
+		id, in.IngredientsText, allergens, additives,
+		nutriJSON, in.NutritionBasis, in.ServingSize, in.NutriScore)
+	if err != nil {
+		return nil, err
+	}
+
+	if _, err := s.recomputeQualityTx(ctx, tx, id); err != nil {
+		return nil, err
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+
+	after, err := s.GetProduct(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	changed := diffFields(before, after)
+	if len(changed) > 0 {
+		if err := s.recordProvenance(ctx, id, changed); err != nil {
+			return nil, err
+		}
+	}
+	if err := s.writeAudit(ctx, actor, "update", "product", &id, changed, before, after); err != nil {
+		return nil, err
+	}
+	return after, nil
+}
+
+func strEq(a, b *string) bool {
+	if a == nil && b == nil {
+		return true
+	}
+	if a == nil || b == nil {
+		return false
+	}
+	return *a == *b
+}
+
+func floatEq(a, b *float64) bool {
+	if a == nil && b == nil {
+		return true
+	}
+	if a == nil || b == nil {
+		return false
+	}
+	return *a == *b
+}
+
+func diffFields(a, b *ProductDetail) []string {
+	changed := []string{}
+	add := func(name string, eq bool) {
+		if !eq {
+			changed = append(changed, name)
+		}
+	}
+	add("gtin", strEq(a.GTIN, b.GTIN))
+	add("name", a.Name == b.Name)
+	add("brand", strEq(a.BrandID, b.BrandID))
+	add("category", strEq(a.CategoryID, b.CategoryID))
+	add("net_content", floatEq(a.NetContentValue, b.NetContentValue) && strEq(a.NetContentUnit, b.NetContentUnit))
+	add("country_of_origin", strEq(a.CountryOfOrigin, b.CountryOfOrigin))
+	add("status", a.Status == b.Status)
+	add("ingredients", strEq(a.IngredientsText, b.IngredientsText))
+	ja, _ := json.Marshal(a.Nutriments)
+	jb, _ := json.Marshal(b.Nutriments)
+	add("nutriments", string(ja) == string(jb))
+	add("nutrition_basis", strEq(a.NutritionBasis, b.NutritionBasis))
+	add("serving_size", strEq(a.ServingSize, b.ServingSize))
+	add("nutri_score", strEq(a.NutriScore, b.NutriScore))
+	return changed
+}
+
+func (s *Store) recordProvenance(ctx context.Context, productID string, fields []string) error {
+	var srcID string
+	if err := s.pool.QueryRow(ctx, "SELECT id FROM source WHERE name = 'manual'").Scan(&srcID); err != nil {
+		return err
+	}
+	_, err := s.pool.Exec(ctx, `
+INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+VALUES ($1, $2, NULL, $3, now(), NULL)`, productID, srcID, fields)
+	return err
+}
+
+func (s *Store) writeAudit(ctx context.Context, actor, action, entity string, entityID *string, fields []string, before, after any) error {
+	bj, _ := json.Marshal(before)
+	aj, _ := json.Marshal(after)
+	if fields == nil {
+		fields = []string{}
+	}
+	_, err := s.pool.Exec(ctx, `
+INSERT INTO audit_log (actor, action, entity, entity_id, fields, before, after)
+VALUES ($1,$2,$3,$4,$5,$6,$7)`, actor, action, entity, entityID, fields, bj, aj)
+	return err
+}
+
+// ---------- images ----------
+
+// AddImage inserts an image URL (manual source) and recomputes quality.
+func (s *Store) AddImage(ctx context.Context, productID, actor, url, kind string) (*ProductImage, error) {
+	if kind == "" {
+		kind = "other"
+	}
+	var srcID string
+	if err := s.pool.QueryRow(ctx, "SELECT id FROM source WHERE name = 'manual'").Scan(&srcID); err != nil {
+		return nil, err
+	}
+	var im ProductImage
+	err := s.pool.QueryRow(ctx, `
+INSERT INTO product_image (product_id, url, kind, license, source_id)
+VALUES ($1,$2,$3,NULL,$4) RETURNING id, url, kind, license`,
+		productID, url, kind, srcID).Scan(&im.ID, &im.URL, &im.Kind, &im.License)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := s.recomputeQuality(ctx, productID); err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "add_image", "product", &productID, []string{"image"}, nil, im)
+	return &im, nil
+}
+
+// DeleteImage removes an image and recomputes quality.
+func (s *Store) DeleteImage(ctx context.Context, productID, imageID, actor string) error {
+	ct, err := s.pool.Exec(ctx, "DELETE FROM product_image WHERE id=$1 AND product_id=$2", imageID, productID)
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	if _, err := s.recomputeQuality(ctx, productID); err != nil {
+		return err
+	}
+	_ = s.writeAudit(ctx, actor, "delete_image", "product", &productID, []string{"image"}, map[string]string{"image_id": imageID}, nil)
+	return nil
+}
+
+// ---------- msrp ----------
+
+// MSRPInput is the payload for adding an MSRP snapshot.
+type MSRPInput struct {
+	Amount        float64 `json:"amount"`
+	Currency      string  `json:"currency"`
+	Region        string  `json:"region"`
+	EffectiveDate *string `json:"effective_date"`
+	SourceURL     *string `json:"source_url"`
+	Note          *string `json:"note"`
+}
+
+// AddMSRP inserts a suggested-retail-price snapshot.
+func (s *Store) AddMSRP(ctx context.Context, productID, actor string, in MSRPInput) (*MSRP, error) {
+	if in.Currency == "" {
+		in.Currency = "CNY"
+	}
+	if in.Region == "" {
+		in.Region = "CN"
+	}
+	var srcID string
+	_ = s.pool.QueryRow(ctx, "SELECT id FROM source WHERE name = 'manual'").Scan(&srcID)
+	var m MSRP
+	err := s.pool.QueryRow(ctx, `
+INSERT INTO product_msrp (product_id, amount, currency, region, source_id, source_url, effective_date, note)
+VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
+RETURNING id, amount, currency, region, effective_date::text, source_url, note`,
+		productID, in.Amount, in.Currency, in.Region, srcID, in.SourceURL, in.EffectiveDate, in.Note).
+		Scan(&m.ID, &m.Amount, &m.Currency, &m.Region, &m.EffectiveDate, &m.SourceURL, &m.Note)
+	if err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "add_msrp", "product", &productID, []string{"msrp"}, nil, m)
+	return &m, nil
+}
+
+// DeleteMSRP removes an MSRP snapshot.
+func (s *Store) DeleteMSRP(ctx context.Context, productID, msrpID, actor string) error {
+	ct, err := s.pool.Exec(ctx, "DELETE FROM product_msrp WHERE id=$1 AND product_id=$2", msrpID, productID)
+	if err != nil {
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	_ = s.writeAudit(ctx, actor, "delete_msrp", "product", &productID, []string{"msrp"}, map[string]string{"msrp_id": msrpID}, nil)
+	return nil
+}
+
+// ---------- dictionaries ----------
+
+// Brand is a brand option for the edit form.
+type Brand struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+// ListBrands returns all brands ordered by name.
+func (s *Store) ListBrands(ctx context.Context) ([]Brand, error) {
+	rows, err := s.pool.Query(ctx, "SELECT id, name FROM brand ORDER BY name")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Brand{}
+	for rows.Next() {
+		var b Brand
+		if err := rows.Scan(&b.ID, &b.Name); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
+// Category is a category option for the edit form.
+type Category struct {
+	ID     string  `json:"id"`
+	NameZH string  `json:"name_zh"`
+	NameEN *string `json:"name_en"`
+	Path   string  `json:"path"`
+	Level  int     `json:"level"`
+}
+
+// ListCategories returns the full category tree.
+func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
+	rows, err := s.pool.Query(ctx,
+		"SELECT id, name_zh, name_en, path::text, level FROM category ORDER BY path")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Category{}
+	for rows.Next() {
+		var c Category
+		if err := rows.Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level); err != nil {
+			return nil, err
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+// ---------- audit ----------
+
+// AuditEntry is one audit-log row for the history view.
+type AuditEntry struct {
+	ID        string   `json:"id"`
+	Actor     string   `json:"actor"`
+	Action    string   `json:"action"`
+	Fields    []string `json:"fields"`
+	CreatedAt string   `json:"created_at"`
+}
+
+// ListAudit returns audit history for one product, newest first.
+func (s *Store) ListAudit(ctx context.Context, productID string, limit int) ([]AuditEntry, error) {
+	rows, err := s.pool.Query(ctx, `
+SELECT id, actor, action, fields, created_at::text
+FROM audit_log WHERE entity='product' AND entity_id=$1
+ORDER BY created_at DESC LIMIT $2`, productID, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []AuditEntry{}
+	for rows.Next() {
+		var e AuditEntry
+		if err := rows.Scan(&e.ID, &e.Actor, &e.Action, &e.Fields, &e.CreatedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, e)
+	}
+	return out, rows.Err()
+}
@@ -0,0 +1,7 @@
+<!doctype html>
+<html lang="zh">
+  <head><meta charset="utf-8" /><title>OpenGoods 管理后台</title></head>
+  <body>
+    <p>管理后台前端尚未构建。Docker 构建会在此处放入真正的前端产物。</p>
+  </body>
+</html>
@@ -0,0 +1,21 @@
+// Package adminweb embeds the built admin SPA (Vite dist). During Docker builds
+// the real dist/ is produced by the node stage and copied in before go build;
+// the committed placeholder keeps the package compilable for `go build ./...`.
+package adminweb
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:dist
+var distFS embed.FS
+
+// Dist returns the embedded SPA filesystem rooted at dist/.
+func Dist() fs.FS {
+	sub, err := fs.Sub(distFS, "dist")
+	if err != nil {
+		panic(err)
+	}
+	return sub
+}
@@ -0,0 +1,49 @@
+// Package apikey handles generation and hashing of public-API keys.
+//
+// A key looks like "og_live_<random>". Only the SHA-256 hash is ever persisted;
+// the plaintext is returned once at creation time and cannot be recovered.
+package apikey
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"strings"
+)
+
+// Prefix is the human-readable scheme prefix every key carries.
+const Prefix = "og_live_"
+
+// prefixLen is how many leading characters (including Prefix) are stored in
+// api_key.key_prefix for identifying a key without revealing its secret.
+const prefixLen = 12
+
+// Generate returns a new random key (plaintext), its SHA-256 hash, and a short
+// display prefix. The plaintext must be shown to the caller exactly once.
+func Generate() (key, hash, displayPrefix string, err error) {
+	buf := make([]byte, 24)
+	if _, err = rand.Read(buf); err != nil {
+		return "", "", "", err
+	}
+	// URL-safe, no padding => stable, copy-pasteable token body.
+	body := base64.RawURLEncoding.EncodeToString(buf)
+	key = Prefix + body
+	hash = Hash(key)
+	displayPrefix = key
+	if len(displayPrefix) > prefixLen {
+		displayPrefix = displayPrefix[:prefixLen]
+	}
+	return key, hash, displayPrefix, nil
+}
+
+// Hash returns the hex-encoded SHA-256 of a key, used for storage and lookup.
+func Hash(key string) string {
+	sum := sha256.Sum256([]byte(strings.TrimSpace(key)))
+	return hex.EncodeToString(sum[:])
+}
+
+// Looks like a key issued by this service (cheap pre-check before hashing).
+func IsWellFormed(key string) bool {
+	return strings.HasPrefix(key, Prefix) && len(key) > len(Prefix)+8
+}
@@ -0,0 +1,60 @@
+package apikey
+
+import "testing"
+
+func TestGenerate(t *testing.T) {
+	key, hash, prefix, err := Generate()
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if !IsWellFormed(key) {
+		t.Fatalf("generated key not well-formed: %q", key)
+	}
+	if Hash(key) != hash {
+		t.Fatalf("Hash(key) != returned hash")
+	}
+	if len(prefix) != prefixLen || key[:prefixLen] != prefix {
+		t.Fatalf("prefix %q not a %d-char prefix of key %q", prefix, prefixLen, key)
+	}
+	if len(hash) != 64 {
+		t.Fatalf("hash not hex sha-256: %q", hash)
+	}
+}
+
+func TestGenerateUnique(t *testing.T) {
+	seen := map[string]bool{}
+	for i := 0; i < 100; i++ {
+		k, _, _, err := Generate()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if seen[k] {
+			t.Fatalf("duplicate key generated: %q", k)
+		}
+		seen[k] = true
+	}
+}
+
+func TestHashStableAndTrimmed(t *testing.T) {
+	if Hash("og_live_abc") != Hash("  og_live_abc  ") {
+		t.Fatal("Hash should ignore surrounding whitespace")
+	}
+	if Hash("a") == Hash("b") {
+		t.Fatal("distinct inputs must hash differently")
+	}
+}
+
+func TestIsWellFormed(t *testing.T) {
+	cases := map[string]bool{
+		"og_live_abcdefghijkl": true,  // body longer than 8 chars
+		"og_live_":             false, // empty body
+		"og_live_abc":          false, // body too short
+		"nope_abcdefghijkl":    false, // wrong prefix
+		"":                     false,
+	}
+	for in, want := range cases {
+		if got := IsWellFormed(in); got != want {
+			t.Errorf("IsWellFormed(%q) = %v, want %v", in, got, want)
+		}
+	}
+}
@@ -0,0 +1,126 @@
+// Package auth provides minimal single-account authentication for the admin
+// console: a bcrypt-verified login and a stdlib HMAC-SHA256 signed token
+// (JWT-compatible) plus a chi middleware that guards write routes.
+package auth
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+// Authenticator holds the single admin credential and token signing secret.
+type Authenticator struct {
+	username     string
+	passwordHash []byte
+	secret       []byte
+	ttl          time.Duration
+}
+
+// New builds an Authenticator. passwordHash must be a bcrypt hash.
+func New(username string, passwordHash, secret []byte, ttl time.Duration) *Authenticator {
+	return &Authenticator{username: username, passwordHash: passwordHash, secret: secret, ttl: ttl}
+}
+
+// ErrInvalidCredentials is returned when login fails.
+var ErrInvalidCredentials = errors.New("invalid credentials")
+
+// Login verifies the username/password and returns a signed token on success.
+func (a *Authenticator) Login(username, password string) (string, error) {
+	if username != a.username {
+		// Still run bcrypt to keep timing roughly constant.
+		_ = bcrypt.CompareHashAndPassword(a.passwordHash, []byte(password))
+		return "", ErrInvalidCredentials
+	}
+	if err := bcrypt.CompareHashAndPassword(a.passwordHash, []byte(password)); err != nil {
+		return "", ErrInvalidCredentials
+	}
+	return a.issue(username)
+}
+
+type claims struct {
+	Sub string `json:"sub"`
+	Exp int64  `json:"exp"`
+}
+
+func b64(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+func (a *Authenticator) sign(signingInput string) string {
+	mac := hmac.New(sha256.New, a.secret)
+	mac.Write([]byte(signingInput))
+	return b64(mac.Sum(nil))
+}
+
+func (a *Authenticator) issue(sub string) (string, error) {
+	header := b64([]byte(`{"alg":"HS256","typ":"JWT"}`))
+	payloadJSON, err := json.Marshal(claims{Sub: sub, Exp: time.Now().Add(a.ttl).Unix()})
+	if err != nil {
+		return "", err
+	}
+	payload := b64(payloadJSON)
+	signingInput := header + "." + payload
+	return signingInput + "." + a.sign(signingInput), nil
+}
+
+// Verify checks a token's signature and expiry, returning the subject.
+func (a *Authenticator) Verify(token string) (string, error) {
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return "", errors.New("malformed token")
+	}
+	signingInput := parts[0] + "." + parts[1]
+	if !hmac.Equal([]byte(a.sign(signingInput)), []byte(parts[2])) {
+		return "", errors.New("bad signature")
+	}
+	payload, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return "", err
+	}
+	var c claims
+	if err := json.Unmarshal(payload, &c); err != nil {
+		return "", err
+	}
+	if time.Now().Unix() >= c.Exp {
+		return "", errors.New("token expired")
+	}
+	return c.Sub, nil
+}
+
+type ctxKey int
+
+const userKey ctxKey = 0
+
+// UserFrom returns the authenticated subject from the request context.
+func UserFrom(ctx context.Context) string {
+	if v, ok := ctx.Value(userKey).(string); ok {
+		return v
+	}
+	return ""
+}
+
+// Middleware rejects requests without a valid Bearer token.
+func (a *Authenticator) Middleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		h := r.Header.Get("Authorization")
+		token := strings.TrimPrefix(h, "Bearer ")
+		if token == h || token == "" {
+			http.Error(w, `{"error":{"code":"unauthorized","message":"missing token"}}`, http.StatusUnauthorized)
+			return
+		}
+		sub, err := a.Verify(token)
+		if err != nil {
+			http.Error(w, `{"error":{"code":"unauthorized","message":"invalid token"}}`, http.StatusUnauthorized)
+			return
+		}
+		ctx := context.WithValue(r.Context(), userKey, sub)
+		next.ServeHTTP(w, r.WithContext(ctx))
+	})
+}
@@ -0,0 +1,62 @@
+package auth
+
+import (
+	"testing"
+	"time"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+func newTestAuth(t *testing.T, ttl time.Duration) *Authenticator {
+	t.Helper()
+	hash, err := bcrypt.GenerateFromPassword([]byte("s3cret"), bcrypt.MinCost)
+	if err != nil {
+		t.Fatalf("hash: %v", err)
+	}
+	return New("admin", hash, []byte("test-secret"), ttl)
+}
+
+func TestLoginAndVerify(t *testing.T) {
+	a := newTestAuth(t, time.Hour)
+
+	token, err := a.Login("admin", "s3cret")
+	if err != nil {
+		t.Fatalf("login: %v", err)
+	}
+	sub, err := a.Verify(token)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if sub != "admin" {
+		t.Fatalf("sub = %q, want admin", sub)
+	}
+}
+
+func TestLoginWrongCredentials(t *testing.T) {
+	a := newTestAuth(t, time.Hour)
+	if _, err := a.Login("admin", "nope"); err == nil {
+		t.Fatal("expected error for wrong password")
+	}
+	if _, err := a.Login("other", "s3cret"); err == nil {
+		t.Fatal("expected error for wrong username")
+	}
+}
+
+func TestVerifyRejectsTampered(t *testing.T) {
+	a := newTestAuth(t, time.Hour)
+	token, _ := a.Login("admin", "s3cret")
+	if _, err := a.Verify(token + "x"); err == nil {
+		t.Fatal("expected bad signature error")
+	}
+	if _, err := a.Verify("not.a.token"); err == nil {
+		t.Fatal("expected malformed/decoding error")
+	}
+}
+
+func TestVerifyRejectsExpired(t *testing.T) {
+	a := newTestAuth(t, -time.Minute)
+	token, _ := a.Login("admin", "s3cret")
+	if _, err := a.Verify(token); err == nil {
+		t.Fatal("expected expired token error")
+	}
+}
@@ -2,26 +2,38 @@ package config

 import (
 	"os"
+	"strconv"
 )

 // Config holds runtime configuration for the OpenGoods API server.
 // Values are read from environment variables with sensible defaults so the
 // server can boot in a local Docker Compose setup without extra configuration.
 type Config struct {
-	Addr        string
-	DatabaseURL string
-	RedisURL    string
+	Addr                string
+	DatabaseURL         string
+	RedisURL            string
+	AnonRateLimitPerMin int
 }

 // Load reads configuration from the environment.
 func Load() Config {
 	return Config{
-		Addr:        getenv("OPENGOODS_ADDR", ":8080"),
-		DatabaseURL: getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
-		RedisURL:    getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
+		Addr:                getenv("OPENGOODS_ADDR", ":8080"),
+		DatabaseURL:         getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
+		RedisURL:            getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
+		AnonRateLimitPerMin: getenvInt("OPENGOODS_ANON_RATE_LIMIT_PER_MIN", 60),
 	}
 }

+func getenvInt(key string, fallback int) int {
+	if v, ok := os.LookupEnv(key); ok && v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			return n
+		}
+	}
+	return fallback
+}
+
 func getenv(key, fallback string) string {
 	if v, ok := os.LookupEnv(key); ok && v != "" {
 		return v
@@ -0,0 +1,110 @@
+// Package gtin validates and normalizes GS1 trade item numbers (GTIN-8/12/13/14).
+// Only globally-unique GS1 codes are accepted: store-internal / variable-weight /
+// coupon codes (which are not globally unique) are rejected on purpose.
+package gtin
+
+import (
+	"errors"
+	"strings"
+)
+
+// Validation errors.
+var (
+	ErrEmpty      = errors.New("条码不能为空")
+	ErrFormat     = errors.New("条码必须为 8/12/13/14 位数字")
+	ErrCheck      = errors.New("条码校验位不正确")
+	ErrRestricted = errors.New("店内码/变量重量码/优惠券码等非全球唯一码，不予收录")
+)
+
+// Normalize trims and validates a GTIN, returning the cleaned digit string.
+// It enforces length, the GS1 mod-10 check digit, and rejects restricted
+// (non-globally-unique) number ranges.
+func Normalize(raw string) (string, error) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return "", ErrEmpty
+	}
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return "", ErrFormat
+		}
+	}
+	switch len(s) {
+	case 8, 12, 13, 14:
+	default:
+		return "", ErrFormat
+	}
+	if !validCheckDigit(s) {
+		return "", ErrCheck
+	}
+	if restricted(s) {
+		return "", ErrRestricted
+	}
+	return s, nil
+}
+
+// InferType returns the conventional GTIN type label for a normalized code.
+func InferType(s string) string {
+	switch len(s) {
+	case 8:
+		return "EAN8"
+	case 12:
+		return "UPC"
+	case 14:
+		return "GTIN14"
+	default:
+		return "EAN13"
+	}
+}
+
+// validCheckDigit verifies the trailing GS1 mod-10 check digit. The digit
+// immediately left of the check digit carries weight 3, then weights alternate.
+func validCheckDigit(s string) bool {
+	n := len(s)
+	sum := 0
+	for i := 0; i < n-1; i++ {
+		d := int(s[i] - '0')
+		if (n-1-i)%2 == 1 {
+			sum += d * 3
+		} else {
+			sum += d
+		}
+	}
+	check := (10 - (sum % 10)) % 10
+	return check == int(s[n-1]-'0')
+}
+
+// restricted reports whether a (length/check-digit valid) code falls in a
+// number range reserved for non-globally-unique use.
+func restricted(s string) bool {
+	switch len(s) {
+	case 13:
+		p2 := s[:2]
+		switch {
+		case s[0] == '2': // 20-29 restricted distribution / in-store
+			return true
+		case p2 == "02": // 020-029 variable-measure within a store
+			return true
+		case p2 == "04": // 040-049 restricted circulation within a company
+			return true
+		case p2 == "05": // 050-059 coupons
+			return true
+		case p2 == "98" || p2 == "99": // 980-989/99 coupons & refund receipts
+			return true
+		}
+	case 12: // UPC-A: leading number-system digit
+		switch s[0] {
+		case '2': // in-store / random weight
+			return true
+		case '4': // unrestricted in-store use
+			return true
+		case '5': // coupons
+			return true
+		}
+	case 8: // EAN-8: 0/2 prefixes reserved for in-store use
+		if s[0] == '0' || s[0] == '2' {
+			return true
+		}
+	}
+	return false
+}
@@ -0,0 +1,49 @@
+package gtin
+
+import "testing"
+
+func TestNormalizeValid(t *testing.T) {
+	cases := []struct{ in, want, typ string }{
+		{" 5449000000996 ", "5449000000996", "EAN13"}, // Coca-Cola EAN-13
+		{"3017624010701", "3017624010701", "EAN13"},   // Nutella EAN-13
+		{"036000291452", "036000291452", "UPC"},       // UPC-A
+		{"96385074", "96385074", "EAN8"},              // EAN-8
+		{"00012345600012", "00012345600012", "GTIN14"},
+		{"6901234567892", "6901234567892", "EAN13"}, // China 690 prefix
+	}
+	for _, c := range cases {
+		got, err := Normalize(c.in)
+		if err != nil {
+			t.Errorf("Normalize(%q) unexpected error: %v", c.in, err)
+			continue
+		}
+		if got != c.want {
+			t.Errorf("Normalize(%q) = %q, want %q", c.in, got, c.want)
+		}
+		if InferType(got) != c.typ {
+			t.Errorf("InferType(%q) = %q, want %q", got, InferType(got), c.typ)
+		}
+	}
+}
+
+func TestNormalizeRejects(t *testing.T) {
+	cases := []struct {
+		in   string
+		want error
+	}{
+		{"", ErrEmpty},
+		{"12ab5678", ErrFormat},
+		{"12345", ErrFormat},
+		{"5449000000997", ErrCheck},      // bad check digit
+		{"2012345678903", ErrRestricted}, // 20-29 in-store EAN-13
+		{"0212345678909", ErrRestricted}, // 02x variable measure
+		{"212345678909", ErrRestricted},  // UPC number system 2
+		{"02345673", ErrRestricted},      // EAN-8 in-store
+	}
+	for _, c := range cases {
+		_, err := Normalize(c.in)
+		if err != c.want {
+			t.Errorf("Normalize(%q) error = %v, want %v", c.in, err, c.want)
+		}
+	}
+}
@@ -1,54 +1,263 @@
 // Package handler wires up the public, read-only OpenGoods HTTP API.
-//
 // The OpenGoods service is a public-good product information API: it only
 // collects and serves product facts. It exposes no purchase, checkout, or
 // commerce endpoints by design.
 package handler

 import (
+	_ "embed"
 	"encoding/json"
+	"errors"
+	"io/fs"
 	"net/http"
+	"strconv"
+	"strings"

 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
+
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+	"github.com/baicai2026-baicai/goods/api/internal/store"
 )

+//go:embed openapi.json
+var openAPISpec []byte
+
 // APIVersion is the current public API version prefix.
 const APIVersion = "v1"

+const (
+	defaultPageSize = 20
+	maxPageSize     = 100
+
+	// defaultAnonLimit is the per-minute request budget for unauthenticated
+	// callers (identified by client IP) when none is configured.
+	defaultAnonLimit = 60
+)
+
+// Handler holds dependencies shared by the HTTP routes.
+type Handler struct {
+	store     *store.Store
+	spa       fs.FS
+	limiter   *ratelimit.Limiter
+	anonLimit int
+}
+
+// New constructs a Handler backed by the given store. spa may be nil (JSON-only).
+// Rate limiting is disabled until WithRateLimit is called.
+func New(s *store.Store, spa fs.FS) *Handler {
+	return &Handler{store: s, spa: spa, anonLimit: defaultAnonLimit}
+}
+
+// WithRateLimit attaches a Redis-backed limiter and the anonymous per-minute
+// budget, enabling rate limiting + usage tracking on the public API routes.
+// A non-positive anonPerMin keeps the default.
+func (h *Handler) WithRateLimit(l *ratelimit.Limiter, anonPerMin int) *Handler {
+	h.limiter = l
+	if anonPerMin > 0 {
+		h.anonLimit = anonPerMin
+	}
+	return h
+}
+
 // Router builds the top-level HTTP handler with middleware and routes mounted.
-func Router() http.Handler {
+func (h *Handler) Router() http.Handler {
 	r := chi.NewRouter()
 	r.Use(middleware.RequestID)
 	r.Use(middleware.RealIP)
 	r.Use(middleware.Recoverer)

-	r.Get("/healthz", Healthz)
+	r.Get("/healthz", h.Healthz)

 	r.Route("/api/"+APIVersion, func(r chi.Router) {
-		r.Route("/products", func(r chi.Router) {
-			r.Get("/barcode/{gtin}", notImplemented)
-			r.Get("/search", notImplemented)
-			r.Get("/{id}", notImplemented)
-			r.Get("/{id}/nutriments", notImplemented)
-			r.Get("/{id}/msrp", notImplemented)
+		// Machine-readable spec; not rate limited so tooling can always fetch it.
+		r.Get("/openapi.json", h.OpenAPI)
+
+		r.Group(func(r chi.Router) {
+			r.Use(h.rateLimit)
+			r.Route("/products", func(r chi.Router) {
+				r.Get("/barcode/{gtin}", h.ProductByBarcode)
+				r.Get("/search", h.SearchProducts)
+				r.Get("/{id}", h.ProductByID)
+				r.Get("/{id}/nutriments", h.ProductNutriments)
+				r.Get("/{id}/msrp", h.ProductMSRP)
+			})
+			r.Get("/brands", h.ListBrands)
+			r.Get("/categories", h.ListCategories)
+			r.Get("/sources/{id}", h.SourceByID)
 		})
-		r.Get("/brands", notImplemented)
-		r.Get("/categories", notImplemented)
-		r.Get("/sources/{id}", notImplemented)
 	})

+	// Public SPA (homepage + search + contribute). API routes above take
+	// precedence; everything else falls back to the embedded single-page app.
+	if h.spa != nil {
+		r.Handle("/*", http.HandlerFunc(h.serveSPA))
+	}
+
 	return r
 }

+func (h *Handler) serveSPA(w http.ResponseWriter, r *http.Request) {
+	rel := strings.TrimPrefix(r.URL.Path, "/")
+	if rel == "" {
+		rel = "index.html"
+	}
+	if f, err := h.spa.Open(rel); err == nil {
+		f.Close()
+		http.FileServer(http.FS(h.spa)).ServeHTTP(w, r)
+		return
+	}
+	// SPA fallback: serve index.html for client-side routes.
+	data, err := fs.ReadFile(h.spa, "index.html")
+	if err != nil {
+		http.NotFound(w, r)
+		return
+	}
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	_, _ = w.Write(data)
+}
+
 // Healthz reports liveness of the service.
-func Healthz(w http.ResponseWriter, r *http.Request) {
+func (h *Handler) Healthz(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
 }

-// notImplemented is a placeholder for endpoints scoped to later milestones.
-func notImplemented(w http.ResponseWriter, r *http.Request) {
-	writeError(w, r, http.StatusNotImplemented, "not_implemented", "endpoint not implemented yet")
+// OpenAPI serves the embedded OpenAPI 3 specification for the public API.
+func (h *Handler) OpenAPI(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	_, _ = w.Write(openAPISpec)
+}
+
+// ProductByBarcode returns a product by its GTIN.
+func (h *Handler) ProductByBarcode(w http.ResponseWriter, r *http.Request) {
+	p, err := h.store.ProductByGTIN(r.Context(), chi.URLParam(r, "gtin"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, p)
+}
+
+// ProductByID returns a product by its UUID.
+func (h *Handler) ProductByID(w http.ResponseWriter, r *http.Request) {
+	p, err := h.store.ProductByID(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, p)
+}
+
+// SearchProducts runs a trigram-fuzzy name search with optional
+// category/brand/country filters, ranked by relevance, plus paging.
+func (h *Handler) SearchProducts(w http.ResponseWriter, r *http.Request) {
+	qv := r.URL.Query()
+	filters := store.SearchFilters{
+		Query:    strings.TrimSpace(qv.Get("q")),
+		Category: strings.TrimSpace(qv.Get("category")),
+		Brand:    strings.TrimSpace(qv.Get("brand")),
+		Country:  strings.TrimSpace(qv.Get("country")),
+	}
+	page, size := pageParams(r)
+
+	items, total, err := h.store.SearchProducts(r.Context(), filters, size, (page-1)*size)
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items": items,
+		"page":  page,
+		"size":  size,
+		"total": total,
+	})
+}
+
+// ProductNutriments returns just the nutrition facts of a product.
+func (h *Handler) ProductNutriments(w http.ResponseWriter, r *http.Request) {
+	n, err := h.store.Nutriments(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, n)
+}
+
+// ProductMSRP returns official suggested retail price snapshots (no purchase link).
+func (h *Handler) ProductMSRP(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListMSRP(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items":      items,
+		"disclaimer": "厂商建议零售价历史快照，仅供参考，不构成购买建议，本服务不提供任何购买入口。",
+	})
+}
+
+// ListBrands returns a paginated list of brands.
+func (h *Handler) ListBrands(w http.ResponseWriter, r *http.Request) {
+	page, size := pageParams(r)
+	items, total, err := h.store.ListBrands(r.Context(), size, (page-1)*size)
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"items": items, "page": page, "size": size, "total": total,
+	})
+}
+
+// ListCategories returns the full category tree.
+func (h *Handler) ListCategories(w http.ResponseWriter, r *http.Request) {
+	items, err := h.store.ListCategories(r.Context())
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+// SourceByID returns a single data source.
+func (h *Handler) SourceByID(w http.ResponseWriter, r *http.Request) {
+	src, err := h.store.SourceByID(r.Context(), chi.URLParam(r, "id"))
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, src)
+}
+
+// handleErr writes an appropriate error response; returns true if it handled one.
+func (h *Handler) handleErr(w http.ResponseWriter, r *http.Request, err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, store.ErrNotFound) {
+		writeError(w, r, http.StatusNotFound, "not_found", "resource not found")
+		return true
+	}
+	writeError(w, r, http.StatusInternalServerError, "internal_error", "internal server error")
+	return true
+}
+
+func pageParams(r *http.Request) (page, size int) {
+	page = atoiDefault(r.URL.Query().Get("page"), 1)
+	if page < 1 {
+		page = 1
+	}
+	size = atoiDefault(r.URL.Query().Get("size"), defaultPageSize)
+	if size < 1 {
+		size = defaultPageSize
+	}
+	if size > maxPageSize {
+		size = maxPageSize
+	}
+	return page, size
+}
+
+func atoiDefault(s string, fallback int) int {
+	if s == "" {
+		return fallback
+	}
+	v, err := strconv.Atoi(s)
+	if err != nil {
+		return fallback
+	}
+	return v
 }

 func writeJSON(w http.ResponseWriter, status int, body any) {
@@ -0,0 +1,229 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/baicai2026-baicai/goods/api/internal/store"
+)
+
+// newTestHandler connects to the test database, skipping if unavailable or
+// unmigrated. It inserts a known product (cleaned up via t.Cleanup) so the
+// endpoint assertions are deterministic.
+func newTestHandler(t *testing.T) (*Handler, string) {
+	t.Helper()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Skipf("no database: %v", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		t.Skipf("database not reachable: %v", err)
+	}
+
+	var hasProduct bool
+	if err := pool.QueryRow(ctx, "SELECT to_regclass('public.product') IS NOT NULL").Scan(&hasProduct); err != nil || !hasProduct {
+		pool.Close()
+		t.Skip("migrations not applied")
+	}
+
+	gtin := "4006381333931"
+	_, err = pool.Exec(context.Background(), `
+		INSERT INTO product (gtin, name, category_id, net_content_value, net_content_unit)
+		VALUES ($1, 'Test Cola', (SELECT id FROM category WHERE path='food.beverages.carbonated'), 330, 'ml')
+		ON CONFLICT (gtin) WHERE gtin IS NOT NULL DO UPDATE SET name = EXCLUDED.name`, gtin)
+	if err != nil {
+		pool.Close()
+		t.Fatalf("seed insert failed: %v", err)
+	}
+	var pid string
+	_ = pool.QueryRow(context.Background(), "SELECT id FROM product WHERE gtin=$1", gtin).Scan(&pid)
+	_, _ = pool.Exec(context.Background(), `
+		INSERT INTO food_detail (product_id, nutrition_basis, nutriments)
+		VALUES ($1, 'per_100ml', '{"energy_kcal": 42}'::jsonb)
+		ON CONFLICT (product_id) DO UPDATE SET nutriments = EXCLUDED.nutriments`, pid)
+
+	t.Cleanup(func() {
+		_, _ = pool.Exec(context.Background(), "DELETE FROM product WHERE gtin=$1", gtin)
+		pool.Close()
+	})
+	return New(store.New(pool), nil), gtin
+}
+
+func doGET(t *testing.T, h *Handler, path string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, nil)
+	rec := httptest.NewRecorder()
+	h.Router().ServeHTTP(rec, req)
+	return rec
+}
+
+func TestProductByBarcode(t *testing.T) {
+	h, gtin := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/products/barcode/"+gtin)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rec.Code, rec.Body.String())
+	}
+	var p store.Product
+	if err := json.NewDecoder(rec.Body).Decode(&p); err != nil {
+		t.Fatal(err)
+	}
+	if p.Name != "Test Cola" || p.GTIN == nil || *p.GTIN != gtin {
+		t.Fatalf("unexpected product: %+v", p)
+	}
+	if p.CategoryPath == nil || *p.CategoryPath != "food.beverages.carbonated" {
+		t.Fatalf("category not joined: %+v", p.CategoryPath)
+	}
+}
+
+func TestProductByBarcodeNotFound(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/products/barcode/0000000000000")
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", rec.Code)
+	}
+}
+
+func TestSearchProducts(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/products/search?q=Cola&category=food.beverages")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var body struct {
+		Items []store.ProductSummary `json:"items"`
+		Total int                    `json:"total"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	if body.Total < 1 {
+		t.Fatalf("expected at least 1 result, got %d", body.Total)
+	}
+}
+
+func TestSearchFuzzyAndFilters(t *testing.T) {
+	h, _ := newTestHandler(t)
+	ctx := context.Background()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Skipf("no database: %v", err)
+	}
+	defer pool.Close()
+
+	_, err = pool.Exec(ctx,
+		"INSERT INTO brand (name, normalized_name) VALUES ('ZZ Test Brand','zz test brand') ON CONFLICT DO NOTHING")
+	if err != nil {
+		t.Fatalf("seed brand: %v", err)
+	}
+	_, err = pool.Exec(ctx, `
+		INSERT INTO product (name, brand_id, country_of_origin, quality_score, status)
+		VALUES ('ZZ Hazelnut Chocolate', (SELECT id FROM brand WHERE name='ZZ Test Brand'), 'Testland', 0.5, 'active')`)
+	if err != nil {
+		t.Fatalf("seed product: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, "DELETE FROM product WHERE name='ZZ Hazelnut Chocolate'")
+		_, _ = pool.Exec(ctx, "DELETE FROM brand WHERE name='ZZ Test Brand'")
+	})
+
+	decode := func(path string) []store.ProductSummary {
+		rec := doGET(t, h, path)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("%s -> status %d", path, rec.Code)
+		}
+		var body struct {
+			Items []store.ProductSummary `json:"items"`
+		}
+		if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+			t.Fatal(err)
+		}
+		return body.Items
+	}
+	has := func(items []store.ProductSummary, name string) *store.ProductSummary {
+		for i := range items {
+			if items[i].Name == name {
+				return &items[i]
+			}
+		}
+		return nil
+	}
+
+	// Typo "choclate" should fuzzy-match via word_similarity and carry a score.
+	got := has(decode("/api/"+APIVersion+"/products/search?q=choclate"), "ZZ Hazelnut Chocolate")
+	if got == nil {
+		t.Fatal("fuzzy query 'choclate' did not match 'ZZ Hazelnut Chocolate'")
+	}
+	if got.Score == nil || *got.Score <= 0 {
+		t.Fatalf("expected positive fuzzy score, got %v", got.Score)
+	}
+
+	// Brand filter.
+	if has(decode("/api/"+APIVersion+"/products/search?brand=ZZ+Test+Brand"), "ZZ Hazelnut Chocolate") == nil {
+		t.Fatal("brand filter did not return the product")
+	}
+	// Country filter (case-insensitive prefix).
+	if has(decode("/api/"+APIVersion+"/products/search?country=test"), "ZZ Hazelnut Chocolate") == nil {
+		t.Fatal("country filter did not return the product")
+	}
+	// Non-matching country excludes it.
+	if has(decode("/api/"+APIVersion+"/products/search?country=france"), "ZZ Hazelnut Chocolate") != nil {
+		t.Fatal("country filter 'france' should not return the product")
+	}
+}
+
+func TestOpenAPISpec(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/openapi.json")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var spec struct {
+		OpenAPI string         `json:"openapi"`
+		Paths   map[string]any `json:"paths"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&spec); err != nil {
+		t.Fatalf("openapi.json is not valid JSON: %v", err)
+	}
+	if spec.OpenAPI == "" || len(spec.Paths) == 0 {
+		t.Fatalf("unexpected spec: %+v", spec)
+	}
+	if _, ok := spec.Paths["/products/search"]; !ok {
+		t.Fatal("spec missing /products/search path")
+	}
+}
+
+func TestListCategories(t *testing.T) {
+	h, _ := newTestHandler(t)
+	rec := doGET(t, h, "/api/"+APIVersion+"/categories")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var body struct {
+		Items []store.Category `json:"items"`
+	}
+	if err := json.NewDecoder(rec.Body).Decode(&body); err != nil {
+		t.Fatal(err)
+	}
+	if len(body.Items) < 20 {
+		t.Fatalf("expected seeded categories, got %d", len(body.Items))
+	}
+}
@@ -11,7 +11,7 @@ func TestHealthz(t *testing.T) {
 	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
 	rec := httptest.NewRecorder()

-	Router().ServeHTTP(rec, req)
+	New(nil, nil).Router().ServeHTTP(rec, req)

 	if rec.Code != http.StatusOK {
 		t.Fatalf("expected status %d, got %d", http.StatusOK, rec.Code)
@@ -26,13 +26,23 @@ func TestHealthz(t *testing.T) {
 	}
 }

-func TestProductEndpointNotImplemented(t *testing.T) {
-	req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/products/barcode/3017624010701", nil)
-	rec := httptest.NewRecorder()
-
-	Router().ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusNotImplemented {
-		t.Fatalf("expected status %d, got %d", http.StatusNotImplemented, rec.Code)
+func TestPageParams(t *testing.T) {
+	cases := []struct {
+		query            string
+		wantPage, wantSz int
+	}{
+		{"", 1, defaultPageSize},
+		{"page=3&size=10", 3, 10},
+		{"page=0&size=-5", 1, defaultPageSize},
+		{"size=1000", 1, maxPageSize},
+		{"page=abc", 1, defaultPageSize},
+	}
+	for _, c := range cases {
+		req := httptest.NewRequest(http.MethodGet, "/?"+c.query, nil)
+		page, size := pageParams(req)
+		if page != c.wantPage || size != c.wantSz {
+			t.Errorf("query %q: got page=%d size=%d, want page=%d size=%d",
+				c.query, page, size, c.wantPage, c.wantSz)
+		}
 	}
 }
@@ -0,0 +1,90 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+	"github.com/baicai2026-baicai/goods/api/internal/store"
+)
+
+type ctxKey int
+
+const apiKeyIDKey ctxKey = 0
+
+// rateLimit authenticates an optional API key and enforces a per-minute budget
+// on the public API. Anonymous callers are limited by client IP at a lower
+// budget; a valid key raises the budget and attributes usage. An API key that
+// is present but invalid or revoked is rejected with 401. Rate-limit headers
+// are set on every response; over-budget callers get 429 + Retry-After.
+func (h *Handler) rateLimit(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		id := "ip:" + clientIP(r)
+		limit := h.anonLimit
+		keyID := ""
+
+		if raw := presentedKey(r); raw != "" {
+			if !apikey.IsWellFormed(raw) {
+				writeError(w, r, http.StatusUnauthorized, "invalid_api_key", "API key 格式无效")
+				return
+			}
+			k, err := h.store.APIKeyByHash(r.Context(), apikey.Hash(raw))
+			if errors.Is(err, store.ErrNotFound) {
+				writeError(w, r, http.StatusUnauthorized, "invalid_api_key", "API key 无效或已吊销")
+				return
+			}
+			if err != nil {
+				writeError(w, r, http.StatusInternalServerError, "internal_error", "internal server error")
+				return
+			}
+			keyID = k.ID
+			limit = k.RateLimitPerMin
+			id = "key:" + k.ID
+		}
+
+		res := h.limiter.Allow(r.Context(), id, limit, time.Minute)
+		w.Header().Set("X-RateLimit-Limit", strconv.Itoa(res.Limit))
+		w.Header().Set("X-RateLimit-Remaining", strconv.Itoa(res.Remaining))
+		w.Header().Set("X-RateLimit-Reset", strconv.FormatInt(res.ResetUnix, 10))
+		if !res.Allowed {
+			retry := res.ResetUnix - time.Now().Unix()
+			if retry < 1 {
+				retry = 1
+			}
+			w.Header().Set("Retry-After", strconv.FormatInt(retry, 10))
+			writeError(w, r, http.StatusTooManyRequests, "rate_limited", "请求过于频繁，请稍后再试")
+			return
+		}
+
+		if keyID != "" {
+			h.limiter.RecordUsage(r.Context(), keyID)
+			next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), apiKeyIDKey, keyID)))
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// presentedKey extracts an API key from the X-API-Key header or a Bearer token.
+func presentedKey(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 ""
+}
+
+// clientIP returns the caller IP, preferring chi's RealIP-normalized RemoteAddr.
+func clientIP(r *http.Request) string {
+	if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		return host
+	}
+	return r.RemoteAddr
+}
@@ -0,0 +1,120 @@
+package handler
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+	"github.com/baicai2026-baicai/goods/api/internal/store"
+)
+
+// newRateLimitedHandler builds a handler backed by the test DB and a live Redis
+// limiter, plus a freshly issued API key with the given per-minute limit. It
+// skips when either backend is unavailable.
+func newRateLimitedHandler(t *testing.T, keyLimit int) (h *Handler, plaintextKey string) {
+	t.Helper()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Skipf("no database: %v", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		t.Skipf("database not reachable: %v", err)
+	}
+	var hasTable bool
+	if err := pool.QueryRow(ctx, "SELECT to_regclass('public.api_key') IS NOT NULL").Scan(&hasTable); err != nil || !hasTable {
+		pool.Close()
+		t.Skip("migrations not applied (api_key missing)")
+	}
+
+	redisURL := os.Getenv("OPENGOODS_REDIS_URL")
+	if redisURL == "" {
+		redisURL = "redis://localhost:6379/0"
+	}
+	limiter := ratelimit.New(redisURL)
+	pingCtx, pingCancel := context.WithTimeout(context.Background(), time.Second)
+	defer pingCancel()
+	if err := limiter.Ping(pingCtx); err != nil {
+		pool.Close()
+		t.Skipf("redis not reachable: %v", err)
+	}
+
+	key, hash, prefix, err := apikey.Generate()
+	if err != nil {
+		pool.Close()
+		t.Fatal(err)
+	}
+	name := fmt.Sprintf("test-key-%d", time.Now().UnixNano())
+	if _, err := pool.Exec(context.Background(),
+		`INSERT INTO api_key (name, key_prefix, key_hash, rate_limit_per_min) VALUES ($1,$2,$3,$4)`,
+		name, prefix, hash, keyLimit); err != nil {
+		pool.Close()
+		t.Fatalf("insert api_key: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(context.Background(), "DELETE FROM api_key WHERE key_hash=$1", hash)
+		pool.Close()
+	})
+
+	return New(store.New(pool), nil).WithRateLimit(limiter, 60), key
+}
+
+func TestRateLimitHeadersAndKeyAuth(t *testing.T) {
+	h, key := newRateLimitedHandler(t, 100)
+	req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/categories", nil)
+	req.Header.Set("X-API-Key", key)
+	rec := httptest.NewRecorder()
+	h.Router().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", rec.Code, rec.Body.String())
+	}
+	if got := rec.Header().Get("X-RateLimit-Limit"); got != "100" {
+		t.Fatalf("X-RateLimit-Limit = %q, want 100 (key limit)", got)
+	}
+	if rec.Header().Get("X-RateLimit-Remaining") == "" {
+		t.Fatal("missing X-RateLimit-Remaining header")
+	}
+}
+
+func TestInvalidKeyRejected(t *testing.T) {
+	h, _ := newRateLimitedHandler(t, 100)
+	req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/categories", nil)
+	req.Header.Set("X-API-Key", "og_live_thiskeydoesnotexist123456")
+	rec := httptest.NewRecorder()
+	h.Router().ServeHTTP(rec, req)
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status = %d, want 401; body = %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestRateLimitExceeded(t *testing.T) {
+	h, key := newRateLimitedHandler(t, 1)
+	do := func() int {
+		req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/categories", nil)
+		req.Header.Set("X-API-Key", key)
+		rec := httptest.NewRecorder()
+		h.Router().ServeHTTP(rec, req)
+		return rec.Code
+	}
+	if code := do(); code != http.StatusOK {
+		t.Fatalf("first request status = %d, want 200", code)
+	}
+	if code := do(); code != http.StatusTooManyRequests {
+		t.Fatalf("second request status = %d, want 429", code)
+	}
+}
@@ -0,0 +1,186 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "OpenGoods / 天工商品档案公共仓 API",
+    "version": "1.0.0",
+    "description": "Public, read-only product-facts REST API. Anonymous access is allowed at a lower per-minute rate; an optional API key grants a higher rate limit and attributes usage. No purchase or commerce endpoints by design.",
+    "license": { "name": "Data under each source's license (e.g. ODbL)" }
+  },
+  "servers": [{ "url": "https://goods.tangshasha.com/api/v1" }],
+  "tags": [
+    { "name": "products" },
+    { "name": "catalog" },
+    { "name": "meta" }
+  ],
+  "security": [{ "ApiKeyHeader": [] }, { "BearerKey": [] }, {}],
+  "paths": {
+    "/products/search": {
+      "get": {
+        "tags": ["products"],
+        "summary": "Search products",
+        "description": "Trigram-fuzzy name search (typo-tolerant) with optional category/brand/country filters, ranked by name similarity blended with data quality_score.",
+        "parameters": [
+          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keyword (name or barcode); fuzzy-matched. Empty returns all, ordered by quality_score." },
+          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category code (matches the subtree), e.g. food.beverages." },
+          { "name": "brand", "in": "query", "schema": { "type": "string" }, "description": "Brand name (fuzzy)." },
+          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country of origin (case-insensitive prefix)." },
+          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } },
+          { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
+        ],
+        "responses": {
+          "200": {
+            "description": "Paged search results.",
+            "headers": {
+              "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Max requests in the current window." },
+              "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the window." },
+              "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix timestamp when the window resets." }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } },
+                    "page": { "type": "integer" },
+                    "size": { "type": "integer" },
+                    "total": { "type": "integer" }
+                  }
+                }
+              }
+            }
+          },
+          "401": { "$ref": "#/components/responses/InvalidApiKey" },
+          "429": { "$ref": "#/components/responses/RateLimited" }
+        }
+      }
+    },
+    "/products/barcode/{gtin}": {
+      "get": {
+        "tags": ["products"],
+        "summary": "Get product by barcode (GTIN)",
+        "parameters": [{ "name": "gtin", "in": "path", "required": true, "schema": { "type": "string" } }],
+        "responses": {
+          "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "429": { "$ref": "#/components/responses/RateLimited" }
+        }
+      }
+    },
+    "/products/{id}": {
+      "get": {
+        "tags": ["products"],
+        "summary": "Get product detail by UUID",
+        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
+        "responses": {
+          "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } },
+          "404": { "$ref": "#/components/responses/NotFound" }
+        }
+      }
+    },
+    "/products/{id}/nutriments": {
+      "get": {
+        "tags": ["products"],
+        "summary": "Get product nutriments",
+        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
+        "responses": { "200": { "description": "Nutriments" }, "404": { "$ref": "#/components/responses/NotFound" } }
+      }
+    },
+    "/products/{id}/msrp": {
+      "get": {
+        "tags": ["products"],
+        "summary": "Get manufacturer suggested retail price snapshots (reference only)",
+        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
+        "responses": { "200": { "description": "MSRP snapshots" } }
+      }
+    },
+    "/brands": {
+      "get": {
+        "tags": ["catalog"],
+        "summary": "List brands",
+        "parameters": [
+          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
+          { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
+        ],
+        "responses": { "200": { "description": "Paged brands" } }
+      }
+    },
+    "/categories": {
+      "get": { "tags": ["catalog"], "summary": "List the category tree", "responses": { "200": { "description": "Category tree" } } }
+    },
+    "/sources/{id}": {
+      "get": {
+        "tags": ["meta"],
+        "summary": "Get a data source",
+        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
+        "responses": { "200": { "description": "Source" }, "404": { "$ref": "#/components/responses/NotFound" } }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key, e.g. og_live_xxx. Optional." },
+      "BearerKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer og_live_xxx. Optional." }
+    },
+    "responses": {
+      "NotFound": {
+        "description": "Resource not found.",
+        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+      },
+      "RateLimited": {
+        "description": "Rate limit exceeded.",
+        "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } },
+        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+      },
+      "InvalidApiKey": {
+        "description": "API key invalid or revoked.",
+        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+      }
+    },
+    "schemas": {
+      "Error": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": { "type": "string" },
+              "message": { "type": "string" },
+              "request_id": { "type": "string" }
+            }
+          }
+        }
+      },
+      "ProductSummary": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "format": "uuid" },
+          "gtin": { "type": "string", "nullable": true },
+          "name": { "type": "string" },
+          "brand": { "type": "string", "nullable": true },
+          "category_path": { "type": "string", "nullable": true },
+          "country_of_origin": { "type": "string", "nullable": true },
+          "quality_score": { "type": "number", "format": "float" },
+          "score": { "type": "number", "format": "float", "nullable": true, "description": "Relevance (name word-similarity) when q is provided; null otherwise." }
+        }
+      },
+      "Product": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "format": "uuid" },
+          "gtin": { "type": "string", "nullable": true },
+          "name": { "type": "string" },
+          "brand": { "type": "string", "nullable": true },
+          "category_path": { "type": "string", "nullable": true },
+          "net_content_value": { "type": "number", "nullable": true },
+          "net_content_unit": { "type": "string", "nullable": true },
+          "country_of_origin": { "type": "string", "nullable": true },
+          "quality_score": { "type": "number", "format": "float" },
+          "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 }
+        }
+      }
+    }
+  }
+}
@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <title>OpenGoods</title>
+  </head>
+  <body>
+    <div id="root">OpenGoods public site placeholder. Built assets are injected during Docker build.</div>
+  </body>
+</html>
@@ -0,0 +1,22 @@
+// Package publicweb embeds the built public SPA (Vite dist). During Docker
+// builds the real dist/ is produced by the node stage and copied in before go
+// build; the committed placeholder keeps the package compilable for
+// `go build ./...`.
+package publicweb
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:dist
+var distFS embed.FS
+
+// Dist returns the embedded SPA filesystem rooted at dist/.
+func Dist() fs.FS {
+	sub, err := fs.Sub(distFS, "dist")
+	if err != nil {
+		panic(err)
+	}
+	return sub
+}
@@ -0,0 +1,132 @@
+// Package ratelimit provides a Redis-backed fixed-window rate limiter and
+// lightweight per-key usage counters for the public API.
+//
+// All state lives in Redis so it is shared across API replicas and visible to
+// the admin console, and so the public server keeps its read-only contract
+// against PostgreSQL. Every operation fails open: if Redis is unavailable the
+// limiter allows the request rather than taking the API down.
+package ratelimit
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// Limiter throttles callers and records usage. A nil-backed Limiter (when Redis
+// could not be configured) disables limiting and usage tracking.
+type Limiter struct {
+	rdb *redis.Client
+}
+
+// Result describes the outcome of an Allow check and the headers to surface.
+type Result struct {
+	Allowed   bool
+	Limit     int
+	Remaining int
+	ResetUnix int64
+}
+
+// UsageStat is the aggregated usage for a single API key.
+type UsageStat struct {
+	Total      int64  `json:"total"`
+	Today      int64  `json:"today"`
+	LastUsedAt *int64 `json:"last_used_at,omitempty"`
+}
+
+// New builds a Limiter from a redis:// URL. On a parse error it logs and returns
+// a fail-open limiter (Redis disabled) so the server still boots.
+func New(redisURL string) *Limiter {
+	opt, err := redis.ParseURL(redisURL)
+	if err != nil {
+		log.Printf("ratelimit: invalid redis url %q: %v (rate limiting disabled)", redisURL, err)
+		return &Limiter{}
+	}
+	return &Limiter{rdb: redis.NewClient(opt)}
+}
+
+// Enabled reports whether a Redis backend is configured.
+func (l *Limiter) Enabled() bool { return l != nil && l.rdb != nil }
+
+// Ping verifies the Redis backend is reachable. Returns an error if disabled or
+// unreachable.
+func (l *Limiter) Ping(ctx context.Context) error {
+	if !l.Enabled() {
+		return redis.ErrClosed
+	}
+	return l.rdb.Ping(ctx).Err()
+}
+
+// Allow records a hit for id within a fixed window and reports whether the
+// caller is under limit. Fails open (Allowed=true) on any Redis error.
+func (l *Limiter) Allow(ctx context.Context, id string, limit int, window time.Duration) Result {
+	reset := func() int64 {
+		win := int64(window / time.Second)
+		if win < 1 {
+			win = 1
+		}
+		return (time.Now().Unix()/win + 1) * win
+	}
+	if !l.Enabled() {
+		return Result{Allowed: true, Limit: limit, Remaining: limit, ResetUnix: reset()}
+	}
+	win := int64(window / time.Second)
+	if win < 1 {
+		win = 1
+	}
+	bucket := time.Now().Unix() / win
+	key := fmt.Sprintf("rl:%s:%d", id, bucket)
+
+	n, err := l.rdb.Incr(ctx, key).Result()
+	if err != nil {
+		return Result{Allowed: true, Limit: limit, Remaining: limit, ResetUnix: (bucket + 1) * win}
+	}
+	if n == 1 {
+		l.rdb.Expire(ctx, key, time.Duration(win)*time.Second)
+	}
+	remaining := limit - int(n)
+	if remaining < 0 {
+		remaining = 0
+	}
+	return Result{
+		Allowed:   int(n) <= limit,
+		Limit:     limit,
+		Remaining: remaining,
+		ResetUnix: (bucket + 1) * win,
+	}
+}
+
+// RecordUsage increments total/daily counters and stamps last-used for a key.
+// Best-effort: errors are ignored.
+func (l *Limiter) RecordUsage(ctx context.Context, keyID string) {
+	if !l.Enabled() || keyID == "" {
+		return
+	}
+	now := time.Now()
+	day := now.Format("20060102")
+	pipe := l.rdb.Pipeline()
+	pipe.Incr(ctx, "usage:total:"+keyID)
+	dayKey := "usage:day:" + keyID + ":" + day
+	pipe.Incr(ctx, dayKey)
+	pipe.Expire(ctx, dayKey, 90*24*time.Hour)
+	pipe.Set(ctx, "usage:last:"+keyID, now.Unix(), 0)
+	_, _ = pipe.Exec(ctx)
+}
+
+// Usage reads aggregated usage for a key. Returns a zero-value stat on error.
+func (l *Limiter) Usage(ctx context.Context, keyID string) UsageStat {
+	var st UsageStat
+	if !l.Enabled() || keyID == "" {
+		return st
+	}
+	day := time.Now().Format("20060102")
+	st.Total, _ = l.rdb.Get(ctx, "usage:total:"+keyID).Int64()
+	st.Today, _ = l.rdb.Get(ctx, "usage:day:"+keyID+":"+day).Int64()
+	if v, err := l.rdb.Get(ctx, "usage:last:"+keyID).Int64(); err == nil {
+		st.LastUsedAt = &v
+	}
+	return st
+}
@@ -0,0 +1,94 @@
+package ratelimit
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+)
+
+// TestDisabledFailsOpen verifies that a Limiter without a Redis backend allows
+// all requests and reports usage as zero rather than erroring.
+func TestDisabledFailsOpen(t *testing.T) {
+	l := New("not-a-valid-url") // parse error => disabled
+	if l.Enabled() {
+		t.Fatal("expected limiter to be disabled for invalid url")
+	}
+	res := l.Allow(context.Background(), "x", 1, time.Minute)
+	if !res.Allowed || res.Remaining != 1 {
+		t.Fatalf("disabled limiter must fail open: %+v", res)
+	}
+	// Must not panic and must return zero usage.
+	l.RecordUsage(context.Background(), "k1")
+	if u := l.Usage(context.Background(), "k1"); u.Total != 0 {
+		t.Fatalf("disabled usage should be zero, got %+v", u)
+	}
+}
+
+// TestNilReceiverSafe ensures a nil *Limiter is safe to use (handler default).
+func TestNilReceiverSafe(t *testing.T) {
+	var l *Limiter
+	if l.Enabled() {
+		t.Fatal("nil limiter must report disabled")
+	}
+	res := l.Allow(context.Background(), "x", 5, time.Minute)
+	if !res.Allowed {
+		t.Fatal("nil limiter must fail open")
+	}
+	l.RecordUsage(context.Background(), "k")
+	_ = l.Usage(context.Background(), "k")
+}
+
+func testLimiter(t *testing.T) *Limiter {
+	t.Helper()
+	url := os.Getenv("OPENGOODS_REDIS_URL")
+	if url == "" {
+		url = "redis://localhost:6379/0"
+	}
+	l := New(url)
+	if !l.Enabled() {
+		t.Skip("redis not configured")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if err := l.rdb.Ping(ctx).Err(); err != nil {
+		t.Skipf("redis not reachable: %v", err)
+	}
+	return l
+}
+
+func TestAllowFixedWindow(t *testing.T) {
+	l := testLimiter(t)
+	ctx := context.Background()
+	id := fmt.Sprintf("test:%d", time.Now().UnixNano())
+
+	for i := 1; i <= 2; i++ {
+		if res := l.Allow(ctx, id, 2, time.Minute); !res.Allowed {
+			t.Fatalf("request %d should be allowed: %+v", i, res)
+		}
+	}
+	res := l.Allow(ctx, id, 2, time.Minute)
+	if res.Allowed {
+		t.Fatalf("3rd request over limit 2 should be denied: %+v", res)
+	}
+	if res.Remaining != 0 {
+		t.Fatalf("remaining should be 0 when over limit, got %d", res.Remaining)
+	}
+}
+
+func TestRecordAndReadUsage(t *testing.T) {
+	l := testLimiter(t)
+	ctx := context.Background()
+	key := fmt.Sprintf("usagekey:%d", time.Now().UnixNano())
+
+	l.RecordUsage(ctx, key)
+	l.RecordUsage(ctx, key)
+	u := l.Usage(ctx, key)
+	if u.Total != 2 || u.Today != 2 {
+		t.Fatalf("expected total=2 today=2, got %+v", u)
+	}
+	if u.LastUsedAt == nil {
+		t.Fatal("expected last-used timestamp to be set")
+	}
+}
@@ -0,0 +1,399 @@
+// Package store is the read-only data access layer for the OpenGoods API.
+// It only issues SELECT queries; all writes happen in the Python ingestion path.
+package store
+
+import (
+	"context"
+	"errors"
+	"strconv"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// ErrNotFound is returned when a requested row does not exist.
+var ErrNotFound = errors.New("not found")
+
+// Store wraps a PostgreSQL connection pool.
+type Store struct {
+	pool *pgxpool.Pool
+}
+
+// New constructs a Store from an existing pgx pool.
+func New(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool}
+}
+
+// Ping verifies database connectivity.
+func (s *Store) Ping(ctx context.Context) error {
+	return s.pool.Ping(ctx)
+}
+
+// Barcode is one GS1 trade item number attached to a product.
+type Barcode struct {
+	GTIN      string  `json:"gtin"`
+	GTINType  string  `json:"gtin_type"`
+	PackLevel string  `json:"pack_level"`
+	Region    *string `json:"region"`
+	IsPrimary bool    `json:"is_primary"`
+}
+
+// Product is the full public view of a product.
+type Product struct {
+	ID              string         `json:"id"`
+	GTIN            *string        `json:"gtin"`
+	Name            string         `json:"name"`
+	Brand           *string        `json:"brand"`
+	CategoryPath    *string        `json:"category_path"`
+	GPCBrickCode    *string        `json:"gpc_brick_code"`
+	NetContentValue *float64       `json:"net_content_value"`
+	NetContentUnit  *string        `json:"net_content_unit"`
+	CountryOfOrigin *string        `json:"country_of_origin"`
+	QualityScore    float64        `json:"quality_score"`
+	Barcodes        []Barcode      `json:"barcodes"`
+	Nutriments      map[string]any `json:"nutriments,omitempty"`
+	NutritionBasis  *string        `json:"nutrition_basis,omitempty"`
+	NutriScore      *string        `json:"nutri_score,omitempty"`
+	Ingredients     *string        `json:"ingredients_text,omitempty"`
+	Allergens       []string       `json:"allergens,omitempty"`
+	Additives       []string       `json:"additives,omitempty"`
+}
+
+// ProductBarcodes returns every barcode attached to a product, primary first.
+func (s *Store) ProductBarcodes(ctx context.Context, productID string) ([]Barcode, error) {
+	rows, err := s.pool.Query(ctx,
+		`SELECT gtin, gtin_type, pack_level, region, is_primary
+		 FROM product_barcode WHERE product_id = $1
+		 ORDER BY is_primary DESC, gtin`, productID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []Barcode{}
+	for rows.Next() {
+		var b Barcode
+		if err := rows.Scan(&b.GTIN, &b.GTINType, &b.PackLevel, &b.Region, &b.IsPrimary); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
+// ProductSummary is a lightweight row used in search/listing responses.
+type ProductSummary struct {
+	ID           string   `json:"id"`
+	GTIN         *string  `json:"gtin"`
+	Name         string   `json:"name"`
+	Brand        *string  `json:"brand"`
+	CategoryPath *string  `json:"category_path"`
+	Country      *string  `json:"country_of_origin"`
+	QualityScore float64  `json:"quality_score"`
+	Score        *float64 `json:"score,omitempty"`
+}
+
+// SearchFilters bundles the optional filters accepted by SearchProducts.
+type SearchFilters struct {
+	Query    string // fuzzy name / barcode query
+	Category string // ltree path; matches the subtree
+	Brand    string // fuzzy brand name
+	Country  string // country_of_origin prefix (case-insensitive)
+}
+
+const productSelect = `
+SELECT p.id, p.gtin, p.name, b.name, c.path::text, p.gpc_brick_code,
+       p.net_content_value, p.net_content_unit, p.country_of_origin, p.quality_score,
+       f.nutriments, f.nutrition_basis, f.nutri_score, f.ingredients_text,
+       f.allergens, f.additives
+FROM product p
+LEFT JOIN brand b ON b.id = p.brand_id
+LEFT JOIN category c ON c.id = p.category_id
+LEFT JOIN food_detail f ON f.product_id = p.id
+`
+
+func scanProduct(row pgx.Row) (*Product, error) {
+	var p Product
+	err := row.Scan(
+		&p.ID, &p.GTIN, &p.Name, &p.Brand, &p.CategoryPath, &p.GPCBrickCode,
+		&p.NetContentValue, &p.NetContentUnit, &p.CountryOfOrigin, &p.QualityScore,
+		&p.Nutriments, &p.NutritionBasis, &p.NutriScore, &p.Ingredients,
+		&p.Allergens, &p.Additives,
+	)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &p, nil
+}
+
+// ProductByGTIN looks up an active product by any of its barcodes.
+func (s *Store) ProductByGTIN(ctx context.Context, gtin string) (*Product, error) {
+	row := s.pool.QueryRow(ctx, productSelect+`
+ WHERE p.status = 'active'
+   AND (p.gtin = $1 OR EXISTS (
+         SELECT 1 FROM product_barcode pb
+         WHERE pb.product_id = p.id AND pb.gtin = $1))
+ LIMIT 1`, gtin)
+	p, err := scanProduct(row)
+	if err != nil {
+		return nil, err
+	}
+	if p.Barcodes, err = s.ProductBarcodes(ctx, p.ID); err != nil {
+		return nil, err
+	}
+	return p, nil
+}
+
+// ProductByID looks up a product by its UUID.
+func (s *Store) ProductByID(ctx context.Context, id string) (*Product, error) {
+	row := s.pool.QueryRow(ctx, productSelect+" WHERE p.id = $1", id)
+	p, err := scanProduct(row)
+	if err != nil {
+		return nil, err
+	}
+	if p.Barcodes, err = s.ProductBarcodes(ctx, p.ID); err != nil {
+		return nil, err
+	}
+	return p, nil
+}
+
+// fuzzyThreshold is the minimum word_similarity for a name to be considered a
+// fuzzy match. ~0.42 tolerates common typos (e.g. "choclate"→"Chocolate")
+// without returning unrelated products.
+const fuzzyThreshold = "0.42"
+
+// SearchProducts runs a trigram-fuzzy name search with optional category /
+// brand / country filters. When a query is present, matching is inclusive
+// (substring OR trigram-similar OR barcode), and results are ranked by name
+// 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) {
+	args := []any{}
+	where := "WHERE p.status = 'active'"
+
+	qIdx := 0
+	if f.Query != "" {
+		args = append(args, f.Query)
+		qIdx = len(args)
+		q := "$" + strconv.Itoa(qIdx)
+		where += ` AND (p.name ILIKE '%' || ` + q + ` || '%'
+			OR word_similarity(` + q + `, p.name) >= ` + fuzzyThreshold + `
+			OR EXISTS (SELECT 1 FROM product_barcode pb
+			           WHERE pb.product_id = p.id AND pb.gtin ILIKE '%' || ` + q + ` || '%'))`
+	}
+	if f.Category != "" {
+		args = append(args, f.Category)
+		where += " AND c.path <@ $" + strconv.Itoa(len(args)) + "::ltree"
+	}
+	if f.Brand != "" {
+		args = append(args, f.Brand)
+		where += " AND b.name ILIKE '%' || $" + strconv.Itoa(len(args)) + " || '%'"
+	}
+	if f.Country != "" {
+		args = append(args, f.Country)
+		where += " AND p.country_of_origin ILIKE $" + strconv.Itoa(len(args)) + " || '%'"
+	}
+
+	from := `FROM product p
+LEFT JOIN brand b ON b.id = p.brand_id
+LEFT JOIN category c ON c.id = p.category_id `
+
+	var total int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) "+from+where, args...).Scan(&total); err != nil {
+		return nil, 0, err
+	}
+
+	// Ranking: when querying, similarity drives order, multiplied by a
+	// quality factor floored at 0.5 so low-quality records aren't zeroed out.
+	scoreExpr := "NULL::real"
+	orderBy := "p.quality_score DESC, p.name"
+	if f.Query != "" {
+		q := "$" + strconv.Itoa(qIdx)
+		scoreExpr = "word_similarity(" + q + ", p.name)"
+		orderBy = scoreExpr + " * (0.5 + p.quality_score) DESC, p.quality_score DESC, p.name"
+	}
+
+	args = append(args, limit, offset)
+	listSQL := "SELECT p.id, p.gtin, p.name, b.name, c.path::text, p.country_of_origin, p.quality_score, " +
+		scoreExpr + " AS score " + from + where +
+		" ORDER BY " + orderBy +
+		" LIMIT $" + strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
+
+	rows, err := s.pool.Query(ctx, listSQL, args...)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+
+	out := []ProductSummary{}
+	for rows.Next() {
+		var ps ProductSummary
+		if err := rows.Scan(&ps.ID, &ps.GTIN, &ps.Name, &ps.Brand, &ps.CategoryPath,
+			&ps.Country, &ps.QualityScore, &ps.Score); err != nil {
+			return nil, 0, err
+		}
+		out = append(out, ps)
+	}
+	return out, total, rows.Err()
+}
+
+// Nutriments returns just the nutrition payload for a product.
+type Nutriments struct {
+	ProductID  string         `json:"product_id"`
+	Basis      *string        `json:"basis"`
+	NutriScore *string        `json:"nutri_score"`
+	Values     map[string]any `json:"values"`
+}
+
+// Nutriments fetches the nutrition facts of a product.
+func (s *Store) Nutriments(ctx context.Context, id string) (*Nutriments, error) {
+	var n Nutriments
+	n.ProductID = id
+	err := s.pool.QueryRow(ctx,
+		"SELECT nutriments, nutrition_basis, nutri_score FROM food_detail WHERE product_id = $1", id,
+	).Scan(&n.Values, &n.Basis, &n.NutriScore)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &n, nil
+}
+
+// MSRP is an official suggested retail price snapshot (never a purchase link).
+type MSRP struct {
+	Amount        float64 `json:"amount"`
+	Currency      string  `json:"currency"`
+	Region        string  `json:"region"`
+	EffectiveDate *string `json:"effective_date"`
+	SourceURL     *string `json:"source_url"`
+	Note          *string `json:"note"`
+}
+
+// ListMSRP returns all MSRP snapshots for a product.
+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)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []MSRP{}
+	for rows.Next() {
+		var m MSRP
+		if err := rows.Scan(&m.Amount, &m.Currency, &m.Region, &m.EffectiveDate, &m.SourceURL, &m.Note); err != nil {
+			return nil, err
+		}
+		out = append(out, m)
+	}
+	return out, rows.Err()
+}
+
+// Brand is a public brand entry.
+type Brand struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+// ListBrands returns brands ordered by name.
+func (s *Store) ListBrands(ctx context.Context, limit, offset int) ([]Brand, int, error) {
+	var total int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM brand").Scan(&total); err != nil {
+		return nil, 0, err
+	}
+	rows, err := s.pool.Query(ctx, "SELECT id, name FROM brand ORDER BY name LIMIT $1 OFFSET $2", limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+	out := []Brand{}
+	for rows.Next() {
+		var b Brand
+		if err := rows.Scan(&b.ID, &b.Name); err != nil {
+			return nil, 0, err
+		}
+		out = append(out, b)
+	}
+	return out, total, rows.Err()
+}
+
+// Category is a node in the self-built category tree.
+type Category struct {
+	ID           string  `json:"id"`
+	NameZH       string  `json:"name_zh"`
+	NameEN       *string `json:"name_en"`
+	Path         string  `json:"path"`
+	GPCBrickCode *string `json:"gpc_brick_code"`
+	Level        int     `json:"level"`
+}
+
+// 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")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	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 {
+			return nil, err
+		}
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+// APIKey is the minimal metadata the public API needs to authorize a caller.
+type APIKey struct {
+	ID              string
+	Name            string
+	RateLimitPerMin int
+}
+
+// APIKeyByHash returns the active (non-revoked) key matching a SHA-256 hash,
+// or ErrNotFound if no such active key exists.
+func (s *Store) APIKeyByHash(ctx context.Context, hash string) (*APIKey, error) {
+	var k APIKey
+	err := s.pool.QueryRow(ctx,
+		`SELECT id, name, rate_limit_per_min
+		 FROM api_key WHERE key_hash = $1 AND revoked_at IS NULL`, hash,
+	).Scan(&k.ID, &k.Name, &k.RateLimitPerMin)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &k, nil
+}
+
+// Source describes a data source with its license and trust weight.
+type Source struct {
+	ID          string  `json:"id"`
+	Name        string  `json:"name"`
+	Homepage    *string `json:"homepage"`
+	License     *string `json:"license"`
+	TrustWeight float64 `json:"trust_weight"`
+}
+
+// SourceByID fetches a single data source.
+func (s *Store) SourceByID(ctx context.Context, id string) (*Source, error) {
+	var src Source
+	err := s.pool.QueryRow(ctx,
+		"SELECT id, name, homepage, license, trust_weight FROM source WHERE id = $1", id,
+	).Scan(&src.ID, &src.Name, &src.Homepage, &src.License, &src.TrustWeight)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &src, nil
+}
@@ -0,0 +1,79 @@
+name: goods
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  minio:
+    image: minio/minio:latest
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
+    volumes:
+      - miniodata:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  api:
+    build:
+      context: .
+      dockerfile: api/Dockerfile.prod
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    environment:
+      OPENGOODS_ADDR: ":8080"
+      OPENGOODS_DATABASE_URL: "postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
+      OPENGOODS_REDIS_URL: "redis://redis:6379/0"
+    ports:
+      - "127.0.0.1:8120:8080"
+
+  admin:
+    build:
+      context: .
+      dockerfile: api/Dockerfile.admin
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      GOODS_ADMIN_ADDR: ":8080"
+      OPENGOODS_DATABASE_URL: "postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
+      GOODS_ADMIN_BASE_PATH: "/ping"
+      GOODS_ADMIN_USER: "${GOODS_ADMIN_USER}"
+      GOODS_ADMIN_PASSWORD: "${GOODS_ADMIN_PASSWORD}"
+      GOODS_ADMIN_JWT_SECRET: "${GOODS_ADMIN_JWT_SECRET}"
+    ports:
+      - "127.0.0.1:8121:8080"
+
+volumes:
+  pgdata:
+  miniodata:
@@ -0,0 +1,117 @@
+# OpenGoods 公共 API 开发者文档
+
+天工商品档案公共仓（OpenGoods）提供**公开、只读**的商品事实 REST API：按条码/名称查询商品的客观资料（品牌、品类、净含量、产地、配料、营养成分、Nutri-Score、厂商建议零售价快照等）。返回均为 JSON（UTF-8）。**本服务不含任何购买/交易接口。**
+
+- 基础地址：`https://goods.tangshasha.com/api/v1`
+- 机器可读规范（OpenAPI 3）：`GET /api/v1/openapi.json`
+- 交互式文档：站点「API 调用说明」页
+
+## 鉴权
+
+API 默认**匿名可用**，无需任何凭证即可调用。匿名请求按来源 IP 计入一个较低的默认每分钟额度。
+
+如需更高额度并让用量归属到你，可向运营方申请一枚 **API Key**（形如 `og_live_xxxxxxxx`），请求时二选一携带：
+
+```bash
+curl -H "X-API-Key: og_live_xxxxxxxx" \
+  "https://goods.tangshasha.com/api/v1/products/search?q=牛奶"
+
+# 或
+curl -H "Authorization: Bearer og_live_xxxxxxxx" \
+  "https://goods.tangshasha.com/api/v1/products/search?q=牛奶"
+```
+
+> 仅在创建时返回一次明文 Key，请妥善保存。服务端只存储其 SHA-256 哈希。
+
+## 限流
+
+采用**固定窗口**限流（每分钟）。每个响应都会回写以下响应头：
+
+| 响应头 | 含义 |
+| --- | --- |
+| `X-RateLimit-Limit` | 当前窗口允许的最大请求数 |
+| `X-RateLimit-Remaining` | 当前窗口剩余可用次数 |
+| `X-RateLimit-Reset` | 窗口重置的 Unix 时间戳（秒） |
+| `Retry-After` | 仅在超额（429）时返回，建议等待的秒数 |
+
+- 超过额度：`429 Too Many Requests`，错误码 `rate_limited`。
+- Key 无效或已吊销：`401 Unauthorized`，错误码 `invalid_api_key`。
+
+## 错误格式
+
+非 2xx 响应体统一为：
+
+```json
+{ "error": { "code": "not_found", "message": "…", "request_id": "…" } }
+```
+
+## 分页
+
+列表类接口支持 `page`（默认 `1`）与 `size`（默认 `20`，最大 `100`），响应含 `page`/`size`/`total`。
+
+## 端点
+
+### `GET /products/search` — 搜索商品
+
+按名称做三元组（trigram）模糊搜索，**可容忍错别字**；支持品类/品牌/产地过滤；结果按相关度（名称相似度 × 数据质量分）排序。
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `q` | 否 | 关键词（名称/条码），模糊匹配；留空则按质量分返回全部 |
+| `category` | 否 | 品类编码（含子树），如 `food.beverages` |
+| `brand` | 否 | 品牌名（模糊匹配），如 `Ferrero` |
+| `country` | 否 | 产地前缀（不区分大小写），如 `China` |
+| `page` | 否 | 页码，默认 1 |
+| `size` | 否 | 每页条数，默认 20，最大 100 |
+
+```bash
+curl "https://goods.tangshasha.com/api/v1/products/search?q=nutela&country=Italy"
+```
+
+```json
+{
+  "items": [
+    {
+      "id": "…",
+      "gtin": "3017624010701",
+      "name": "Nutella",
+      "brand": "Ferrero",
+      "category_path": "food.snacks.chocolate",
+      "country_of_origin": "Italy",
+      "quality_score": 0.81,
+      "score": 0.71
+    }
+  ],
+  "page": 1,
+  "size": 20,
+  "total": 1
+}
+```
+
+`score` 为名称相关度（提供 `q` 时返回，0–1），未提供 `q` 时为 `null`。
+
+### `GET /products/barcode/{gtin}` — 按条码查询
+
+```bash
+curl "https://goods.tangshasha.com/api/v1/products/barcode/5449000000996"
+```
+
+### `GET /products/{id}` — 商品详情
+
+按商品 UUID 获取完整档案（含配料、营养、添加剂、图片、MSRP 等）。
+
+### `GET /products/{id}/nutriments` — 商品营养成分
+
+### `GET /products/{id}/msrp` — 厂商建议零售价快照
+
+官方建议零售价历史快照，仅供参考，不含任何购买入口。
+
+### `GET /brands` — 品牌列表（分页）
+
+### `GET /categories` — 品类树
+
+### `GET /sources/{id}` — 数据来源
+
+## 免责声明
+
+数据可能存在误差或滞后，按「现状」提供，不构成医疗/购买建议。商品资料版权归各原始来源所有，请遵循其许可（如 OpenFoodFacts 的 ODbL），引用时请注明天工商品档案公共仓及原始来源。
@@ -0,0 +1,34 @@
+# 生产部署 (Docker)
+
+用 `docker-compose.prod.yml` 部署，与本地 `docker-compose.yml` 的区别：
+
+- 仅 `api` 映射宿主端口，且绑定 `127.0.0.1:8120`（由外层 nginx 反代 + HTTPS）；`postgres`/`redis`/`minio` 不对外暴露端口，仅容器内网互通。
+- 所有服务 `restart: unless-stopped`。
+- 凭据从 `.env` 注入（见 `.env.example`），不写入仓库。
+- `api` 使用 `api/Dockerfile.prod`：运行镜像用 `scratch`（从构建镜像拷贝 ca-certs），适用于 `gcr.io/distroless` 不可达的环境；Go 模块走 `goproxy.cn`。
+- `admin`（运营后台）：带登录的写入服务 + 内嵌前端，绑定 `127.0.0.1:8121`，由 nginx 反代到公开站点的 `/ping` 路径。镜像 `api/Dockerfile.admin`（node 构建前端 → 内嵌进 Go 二进制 → scratch 运行）。仅 `admin` 可写库（人工编辑以 `source=manual` 记录字段级溯源 + `audit_log` 留痕），公开 `api` 仍只读。
+
+## 步骤
+
+```bash
+cp .env.example .env   # 填入真实随机密码
+docker compose -f docker-compose.prod.yml up -d --build
+
+# 迁移（migrate 容器接入同一网络，DSN 指向 postgres 服务）
+set -a; . ./.env; set +a
+DBURL="postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
+docker run --rm --network goods_default -v "$PWD/migrations:/migrations" \
+  migrate/migrate -path=/migrations -database "$DBURL" up
+
+curl -s http://127.0.0.1:8120/healthz   # {"status":"ok"}
+```
+
+nginx 反代（子域 + HTTPS）：80 端口 301 跳转到 443，443 `proxy_pass http://127.0.0.1:8120`，证书用 acme.sh 签发并配 `--reloadcmd "nginx -s reload"` 自动续期。
+
+运营后台 `/ping`（同域复用证书）：在 443 server 块内加一段
+
+```nginx
+location /ping { proxy_pass http://127.0.0.1:8121; }
+```
+
+后台凭据见 `.env` 的 `GOODS_ADMIN_USER` / `GOODS_ADMIN_PASSWORD` / `GOODS_ADMIN_JWT_SECRET`。新增迁移 `0005_admin`（`audit_log` 表 + `manual` 来源）随 `migrate ... up` 自动应用。
@@ -0,0 +1,38 @@
+# ETL: Open Food Facts 导入 (M2)
+
+把 Open Food Facts (OFF, ODbL 许可) 的食品数据采集、转换并入库。只有 Python 采集侧写库，每条记录都以 `openfoodfacts` 为来源记录**字段级溯源**。
+
+## 流程
+```
+OFF API / dump(jsonl[.gz])
+  → adapters/openfoodfacts.py   # 读取(限速 + User-Agent) / 解析 dump
+  → etl/transform.py            # 字段映射 + 单位归一 + 营养 per_100g + 分类映射(关键词)
+  → etl/load.py                 # psycopg upsert(product/food_detail/product_image) + product_source 溯源
+```
+
+## 运行
+先确保本地依赖与迁移就绪：`docker compose up -d postgres` + `migrate ... up`。
+
+```bash
+# 用 OFF API 拉指定条码(客户端限速, 默认 4s/次)
+python -m opengoods.jobs.seed_off --barcodes 3017624010701 5449000000996
+
+# 用下载好的 OFF dump 批量导入(可 .gz), 限制条数
+python -m opengoods.jobs.seed_off --dump products.jsonl.gz --limit 1000
+```
+DSN 默认读 `OPENGOODS_DATABASE_URL`。
+
+## 字段映射要点
+| OFF | OpenGoods | 处理 |
+|-----|-----------|------|
+| `code` | `product.gtin` | GTIN-8/12/13/14 校验位验证, 不合法则不作为 gtin |
+| `product_name_zh/_/_en` | `product.name` | 优先中文 |
+| `brands` | `brand` | 取第一个, normalized_name 去重 |
+| `quantity` | `net_content_*` | 解析 "500 g"/"1,5 L" → 经 `units.py` 归一(原始+归一双存) |
+| `nutriments.*_100g` | `food_detail.nutriments` | per_100g; 能量 kJ/kcal 双存, 缺一自动换算 |
+| `allergens_tags`/`additives_tags` | `allergens`/`additives` | 去 `en:` 前缀 |
+| `nutriscore_grade` | `nutri_score` | 大写单字母 |
+| `categories*`/name | `category_id` | 关键词映射到自建品类树(起步版, 后续换 OFF 分类→GPC 映射表) |
+| `image_front_url` | `product_image` | 标 CC-BY-SA 许可 |
+
+> 全量 dump 约数 GB；CI 与单测用 fixture 离线验证 transform，DB 集成测试在无库时自动跳过。
@@ -0,0 +1,76 @@
+# 采集管理 (M4)
+
+M4 在 M2（Open Food Facts 首次导入）基础上，补齐"持续运营"所需的采集能力：
+增量更新、第二数据源补全（GS1）、去重合并与字段级冲突解决、数据质量评分，
+以及把这些串起来的定时调度。全部为 Python 侧（`ingestion/`），只写库、可单测。
+
+## 组成
+
+| 能力 | 模块 | 说明 |
+|------|------|------|
+| 增量采集 | `adapters/openfoodfacts.py: fetch_modified_since()` | 按 `last_modified_t` 拉取自上次水位后变更的商品 |
+| 采集水位 | `etl/state.py` + `ingest_state` 表 | 每个源持久化 `last_modified_t`，只前进不回退 |
+| GS1 补全 | `adapters/gs1.py` + `etl/supplement.py` | 用权威条码源补**缺失**字段（品牌/厂商/GPC/产地/净含量），不覆盖已有值 |
+| 去重合并 | `etl/dedup.py` | 非 GTIN 重复（同名+品牌+净含量）合并到质量最高的主记录 |
+| 冲突解决 | `etl/merge.py` | 多源同字段按"源权重 > 新鲜度"择优，保留字段级溯源 |
+| 质量评分 | `etl/quality.py` | 0~1 分，落到 `product.quality_score` |
+| 定时调度 | `jobs/schedule.py` | 固定周期跑"增量 + 去重"一轮，零额外依赖 |
+
+## 质量评分
+
+锁定公式（各分量均归一到 0~1）：
+
+```
+quality = 0.4 * 完整度 + 0.3 * 源权重 + 0.2 * 多源一致 + 0.1 * 新鲜度
+```
+
+- **完整度**：`name/gtin/brand/category/net_content/country/nutriments/ingredients/image` 9 项的命中比例。
+- **源权重**：贡献该商品的源中最高 `source.trust_weight`（OFF=0.7，GS1=0.9）。
+- **多源一致**：源数量代理——单源 0.5、两源 0.8、三源及以上 1.0（单源无法互证）。
+- **新鲜度**：最近一次 `product_source.fetched_at` 的时间衰减（≤30d=1.0 … >730d=0.2）。
+
+`load_record()` 与 `merge_products()` 写入后都会调 `update_quality()` 重算。
+
+## 增量水位
+
+`ingest_state`（迁移 `0004`）每源一行，记录 `last_modified_t`、`last_run_at`、`stats`。
+`set_watermark()` 用 `GREATEST(...)` 保证水位只前进，避免乱序/中断的运行回退进度。
+
+## 运行
+
+前置：`docker compose up -d postgres` 且迁移已 `up`（含 `0004`）。DSN 默认读 `OPENGOODS_DATABASE_URL`。
+
+```bash
+# 增量更新 OFF（从持久化水位开始；--since 可覆盖）
+python -m opengoods.jobs.update_off --max-pages 5
+python -m opengoods.jobs.update_off --since 1700000000
+
+# 去重合并（--dry-run 只报告不写库）
+python -m opengoods.jobs.dedup --dry-run
+python -m opengoods.jobs.dedup --actor nightly
+
+# 定时调度：单轮 / 周期循环（增量 + 去重）
+python -m opengoods.jobs.schedule --once
+python -m opengoods.jobs.schedule --interval 3600
+```
+
+## GS1 补全
+
+GS1 为付费、分区域的授权数据，适配器支持两种模式：
+
+- **离线**（默认）：从本地 JSON 映射 `{gtin: {...}}` 查（`GS1Adapter.from_file(path)`），
+  供测试与内网环境使用。
+- **在线**：传 `base_url` + `client`（+ `api_key`），`GET {base_url}/{gtin}`，按
+  Verified-by-GS1 风格字段解析。
+
+补全只填**空缺**字段并在 `product_source` 记字段级溯源，源标记为 `gs1`。
+
+## 测试
+
+```bash
+cd ingestion && pip install -e ".[dev]"
+ruff check . && ruff format --check . && pytest -q
+```
+
+纯函数测试（质量/冲突/增量分页）始终运行；依赖库的测试（水位/质量落库/去重/GS1 补全）
+在无数据库或未应用 M4 迁移时自动跳过。
@@ -0,0 +1,124 @@
+"""GS1 barcode supplement adapter.
+
+GS1 (e.g. *Verified by GS1* / GS1 China) is the authoritative registry that maps
+a GTIN to its brand owner, product description and GPC category. We use it to
+*supplement* — fill gaps in — records gathered from crowd sources like Open Food
+Facts, never to overwrite existing values.
+
+Real GS1 access is credentialed and region-specific, so this adapter supports
+two modes:
+
+* **offline** (default): look barcodes up in a local JSON mapping file. This is
+  what tests and air-gapped runs use.
+* **online**: GET ``{base_url}/{gtin}`` with an API key header, then normalize
+  the response. Enabled by passing ``base_url`` + ``client``.
+
+Either way :meth:`fetch_barcode` returns a normalized *supplement* dict (or
+``None``); :mod:`opengoods.etl.supplement` applies it to the database.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from pathlib import Path
+
+import httpx
+
+SOURCE_NAME = "gs1"
+GS1_HOMEPAGE = "https://www.gs1.org"
+GS1_LICENSE = "proprietary"
+# GS1 is the authoritative barcode registry -> high trust.
+GS1_TRUST = 0.9
+
+# Keys of a normalized supplement record.
+_SUPPLEMENT_KEYS = (
+    "gtin",
+    "name",
+    "brand",
+    "manufacturer",
+    "gpc_brick_code",
+    "country_of_origin",
+    "net_content_value",
+    "net_content_unit",
+)
+
+
+def _normalize(code: str, data: dict) -> dict:
+    """Project a raw mapping/record onto the supplement schema (non-empty only)."""
+    rec: dict = {"gtin": code}
+    for key in _SUPPLEMENT_KEYS:
+        if key == "gtin":
+            continue
+        value = data.get(key)
+        if value not in (None, "", []):
+            rec[key] = value
+    return rec
+
+
+def _parse_api(code: str, payload: dict) -> dict:
+    """Best-effort mapping of a Verified-by-GS1 style payload to our schema."""
+    item = payload
+    if isinstance(payload.get("gtinRecords"), list) and payload["gtinRecords"]:
+        item = payload["gtinRecords"][0]
+    return _normalize(
+        code,
+        {
+            "name": item.get("productDescription") or item.get("description"),
+            "brand": item.get("brandName"),
+            "manufacturer": item.get("companyName") or item.get("licenseeName"),
+            "gpc_brick_code": item.get("gpcCategoryCode"),
+            "country_of_origin": item.get("countryOfSaleCode") or item.get("countryCode"),
+            "net_content_value": item.get("netContent"),
+            "net_content_unit": item.get("netContentUnit"),
+        },
+    )
+
+
+class GS1Adapter:
+    """Look up GTIN supplements from a local mapping or a GS1-style API."""
+
+    source_name = SOURCE_NAME
+
+    def __init__(
+        self,
+        mapping: dict | None = None,
+        *,
+        client: httpx.Client | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        self._mapping = mapping or {}
+        self._client = client
+        self._base_url = base_url.rstrip("/") if base_url else None
+        self._api_key = api_key
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> GS1Adapter:
+        """Build an offline adapter from a JSON ``{gtin: {...}}`` mapping file."""
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        return cls(mapping=data)
+
+    def fetch_barcode(self, code: str) -> dict | None:
+        """Return a normalized supplement dict for ``code`` (or ``None``)."""
+        if self._base_url and self._client is not None:
+            headers = {"apikey": self._api_key} if self._api_key else {}
+            resp = self._client.get(f"{self._base_url}/{code}", headers=headers)
+            if resp.status_code == 404:
+                return None
+            resp.raise_for_status()
+            rec = _parse_api(code, resp.json())
+        else:
+            data = self._mapping.get(code)
+            if not data:
+                return None
+            rec = _normalize(code, data)
+        # A record with only the GTIN carries no supplement.
+        return rec if len(rec) > 1 else None
+
+    def fetch(self, barcodes: list[str]) -> Iterator[dict]:
+        """Yield supplement records for the given barcodes."""
+        for code in barcodes:
+            rec = self.fetch_barcode(code)
+            if rec is not None:
+                yield rec
@@ -0,0 +1,232 @@
+"""Open Food Facts (OFF) source adapter.
+
+Fetches raw product records either from the OFF read API (one product per
+barcode) or from a downloaded JSONL dump file. OFF data is licensed under the
+Open Database License (ODbL); product images are CC-BY-SA. We record OFF as the
+source for every field we ingest.
+
+The adapter is read-only and rate-limited to stay well within OFF's API limits
+(<= ~15 req/min/IP for product reads) and to be a good citizen.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Iterator
+from pathlib import Path
+
+import httpx
+
+SOURCE_NAME = "openfoodfacts"
+OFF_LICENSE = "ODbL"
+USER_AGENT = "OpenGoods/0.1 (+https://github.com/baicai2026-baicai/goods) public-good product API"
+
+# Conservative client-side spacing between API calls (seconds).
+_DEFAULT_MIN_INTERVAL = 4.0
+_API_URL = "https://world.openfoodfacts.org/api/v2/product/{barcode}.json"
+_SEARCH_URL = "https://world.openfoodfacts.org/api/v2/search"
+
+# HTTP statuses worth retrying: rate limiting and transient server errors.
+_RETRY_STATUS = frozenset({429, 500, 502, 503, 504})
+
+# Fields requested from the search API so a returned product can be transformed
+# without an extra per-barcode round trip.
+_SEARCH_FIELDS = (
+    "code,product_name,product_name_en,product_name_zh,brands,quantity,"
+    "categories,categories_tags,countries,ingredients_text,allergens_tags,"
+    "additives_tags,nutriments,nutriscore_grade,serving_size,"
+    "image_front_url,image_url,last_modified_t"
+)
+
+
+class OpenFoodFactsAdapter:
+    """Read product records from the OFF API."""
+
+    source_name = SOURCE_NAME
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        min_interval: float = _DEFAULT_MIN_INTERVAL,
+        max_retries: int = 4,
+        backoff_base: float = 2.0,
+    ) -> None:
+        self._client = client or httpx.Client(headers={"User-Agent": USER_AGENT}, timeout=30.0)
+        self._min_interval = min_interval
+        self._max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._last_call = 0.0
+
+    def _throttle(self) -> None:
+        elapsed = time.monotonic() - self._last_call
+        wait = self._min_interval - elapsed
+        if wait > 0:
+            time.sleep(wait)
+        self._last_call = time.monotonic()
+
+    def _get(self, url: str, params: dict | None = None) -> httpx.Response:
+        """GET with throttling and retry/backoff on transient errors.
+
+        Retries on connection/timeout errors and on retryable HTTP statuses
+        (429 and 5xx, which OFF returns intermittently when overloaded), using
+        exponential backoff that honours a ``Retry-After`` header when present.
+        """
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            self._throttle()
+            try:
+                resp = self._client.get(url, params=params)
+            except httpx.TransportError as exc:
+                last_exc = exc
+            else:
+                if resp.status_code < 400 or resp.status_code not in _RETRY_STATUS:
+                    resp.raise_for_status()
+                    return resp
+                last_exc = httpx.HTTPStatusError(
+                    f"retryable status {resp.status_code}", request=resp.request, response=resp
+                )
+            if attempt < self._max_retries:
+                retry_after = self._retry_after(last_exc)
+                time.sleep(retry_after if retry_after is not None else self._backoff_base**attempt)
+        assert last_exc is not None
+        raise last_exc
+
+    @staticmethod
+    def _retry_after(exc: Exception | None) -> float | None:
+        resp = getattr(exc, "response", None)
+        if resp is None:
+            return None
+        value = resp.headers.get("Retry-After")
+        if not value:
+            return None
+        try:
+            return float(value)
+        except ValueError:
+            return None
+
+    def fetch_barcode(self, barcode: str) -> dict | None:
+        """Fetch a single product by barcode; return the raw `product` dict."""
+        resp = self._get(_API_URL.format(barcode=barcode))
+        payload = resp.json()
+        if payload.get("status") != 1:
+            return None
+        return payload["product"]
+
+    def fetch(self, barcodes: list[str]) -> Iterator[dict]:
+        """Yield raw product records for the given barcodes."""
+        for code in barcodes:
+            record = self.fetch_barcode(code)
+            if record is not None:
+                yield record
+
+    def fetch_modified_since(
+        self,
+        since_t: int,
+        *,
+        page_size: int = 100,
+        max_pages: int = 10,
+    ) -> Iterator[dict]:
+        """Yield products modified after ``since_t`` (unix ``last_modified_t``).
+
+        Uses the OFF search API sorted by ``last_modified_t`` (most recent
+        first) and paginates until it reaches products at or before the
+        watermark, an empty/short page, or ``max_pages``. This is the
+        incremental ingestion path: callers persist the highest
+        ``last_modified_t`` they processed as the next watermark.
+        """
+        for page in range(1, max_pages + 1):
+            resp = self._get(
+                _SEARCH_URL,
+                params={
+                    "fields": _SEARCH_FIELDS,
+                    "sort_by": "last_modified_t",
+                    "page": page,
+                    "page_size": page_size,
+                },
+            )
+            products = resp.json().get("products") or []
+            if not products:
+                return
+            reached_old = False
+            for prod in products:
+                if int(prod.get("last_modified_t") or 0) <= since_t:
+                    reached_old = True
+                    break
+                yield prod
+            if reached_old or len(products) < page_size:
+                return
+
+    def fetch_by_country(
+        self,
+        country: str,
+        *,
+        page_size: int = 100,
+        max_pages: int = 10,
+        sort_by: str = "unique_scans_n",
+    ) -> Iterator[dict]:
+        """Yield products sold in ``country`` (an OFF ``countries_tags_en`` slug).
+
+        Used to seed a market-specific catalogue (e.g. ``china``). Results are
+        sorted by ``sort_by`` (default ``unique_scans_n`` so the most-scanned,
+        best-known products come first) and de-duplicated across pages, since
+        OFF's popularity ordering is not stable between page requests.
+        """
+        seen: set[str] = set()
+        for page in range(1, max_pages + 1):
+            resp = self._get(
+                _SEARCH_URL,
+                params={
+                    "fields": _SEARCH_FIELDS,
+                    "countries_tags_en": country,
+                    "sort_by": sort_by,
+                    "page": page,
+                    "page_size": page_size,
+                },
+            )
+            products = resp.json().get("products") or []
+            if not products:
+                return
+            new_on_page = 0
+            for prod in products:
+                code = str(prod.get("code") or "")
+                if code and code in seen:
+                    continue
+                if code:
+                    seen.add(code)
+                new_on_page += 1
+                yield prod
+            if len(products) < page_size or new_on_page == 0:
+                return
+
+
+def is_cn_gs1(code: str | None) -> bool:
+    """Return True for a GS1 China company prefix (barcodes starting 690-699).
+
+    These identify products registered with GS1 China, i.e. genuinely domestic
+    items, as opposed to imported goods merely tagged as sold in China.
+    """
+    if not code:
+        return False
+    code = code.strip()
+    return len(code) >= 3 and code[:2] == "69" and code[2].isdigit()
+
+
+def read_dump(path: str | Path) -> Iterator[dict]:
+    """Yield raw product records from an OFF JSONL dump file.
+
+    Each line is one product JSON object (the format of OFF's .jsonl export).
+    Supports plain or .gz files.
+    """
+    p = Path(path)
+    if p.suffix == ".gz":
+        import gzip
+
+        opener = lambda: gzip.open(p, "rt", encoding="utf-8")  # noqa: E731
+    else:
+        opener = lambda: open(p, encoding="utf-8")  # noqa: E731
+    with opener() as fh:
+        for line in fh:
+            line = line.strip()
+            if line:
+                yield json.loads(line)
@@ -0,0 +1,139 @@
+"""Duplicate detection and product merging.
+
+Barcodes (GTIN) are already unique at the schema level, so duplicates here are
+non-GTIN records that describe the same product (same normalized name + brand +
+net content). For each duplicate group we keep the highest-quality product as
+canonical and merge the rest into it: child rows (provenance, images, MSRP) are
+re-pointed to the canonical product, the merged product is marked ``merged``
+with ``canonical_id`` set, and a row is written to ``merge_log``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import psycopg
+
+from opengoods.etl.quality import update_quality
+
+
+def _norm(text: str | None) -> str:
+    return " ".join((text or "").lower().split())
+
+
+def product_signature(name: str | None, brand: str | None, net_canonical: Any | None) -> str | None:
+    """Stable signature for non-GTIN dedup, or ``None`` if too sparse to match."""
+    n = _norm(name)
+    if not n:
+        return None
+    net = "" if net_canonical is None else str(net_canonical)
+    return f"{n}|{_norm(brand)}|{net}"
+
+
+def choose_canonical(members: list[dict]) -> dict:
+    """Pick the canonical product: best quality, then oldest, then lowest id."""
+    return min(
+        members,
+        key=lambda m: (
+            -float(m.get("quality_score") or 0.0),
+            m.get("created_at"),
+            str(m.get("id")),
+        ),
+    )
+
+
+def find_duplicate_groups(conn: psycopg.Connection) -> list[list[dict]]:
+    """Return groups (size >= 2) of active products sharing a signature."""
+    rows = conn.execute(
+        """
+        SELECT p.id, p.name, b.normalized_name, p.net_content_canonical,
+               p.quality_score, p.created_at
+        FROM product p
+        LEFT JOIN brand b ON b.id = p.brand_id
+        WHERE p.status = 'active'
+        """
+    ).fetchall()
+
+    groups: dict[str, list[dict]] = {}
+    for r in rows:
+        sig = product_signature(r[1], r[2], r[3])
+        if sig is None:
+            continue
+        member = {
+            "id": r[0],
+            "name": r[1],
+            "quality_score": r[4],
+            "created_at": r[5],
+        }
+        groups.setdefault(sig, []).append(member)
+
+    return [m for m in groups.values() if len(m) >= 2]
+
+
+def merge_products(
+    conn: psycopg.Connection,
+    kept_id: str,
+    merged_id: str,
+    reason: str = "auto-dedup",
+    actor: str = "ingestion",
+) -> None:
+    """Merge ``merged_id`` into ``kept_id`` (re-point children, mark merged)."""
+    if kept_id == merged_id:
+        return
+
+    # Re-point provenance, images and MSRP to the canonical product.
+    conn.execute(
+        "UPDATE product_source SET product_id = %s WHERE product_id = %s",
+        (kept_id, merged_id),
+    )
+    conn.execute(
+        "UPDATE product_image SET product_id = %s WHERE product_id = %s",
+        (kept_id, merged_id),
+    )
+    conn.execute(
+        "UPDATE product_msrp SET product_id = %s WHERE product_id = %s",
+        (kept_id, merged_id),
+    )
+
+    # food_detail has product_id as PK, so it can only move if the canonical
+    # product does not already have one.
+    kept_has_food = conn.execute(
+        "SELECT 1 FROM food_detail WHERE product_id = %s", (kept_id,)
+    ).fetchone()
+    if not kept_has_food:
+        conn.execute(
+            "UPDATE food_detail SET product_id = %s WHERE product_id = %s",
+            (kept_id, merged_id),
+        )
+
+    conn.execute(
+        "UPDATE product SET status = 'merged', canonical_id = %s WHERE id = %s",
+        (kept_id, merged_id),
+    )
+    conn.execute(
+        """
+        INSERT INTO merge_log (kept_id, merged_id, reason, actor)
+        VALUES (%s, %s, %s, %s)
+        """,
+        (kept_id, merged_id, reason, actor),
+    )
+
+    # The canonical product gained sources, so its quality may have changed.
+    update_quality(conn, kept_id)
+
+
+def dedup_all(
+    conn: psycopg.Connection, actor: str = "ingestion", dry_run: bool = False
+) -> dict[str, int]:
+    """Merge every duplicate group. Returns counts of groups and merges."""
+    groups = find_duplicate_groups(conn)
+    merged = 0
+    for members in groups:
+        canonical = choose_canonical(members)
+        for m in members:
+            if m["id"] == canonical["id"]:
+                continue
+            if not dry_run:
+                merge_products(conn, canonical["id"], m["id"], actor=actor)
+            merged += 1
+    return {"groups": len(groups), "merged": merged}
@@ -0,0 +1,235 @@
+"""Load transformed product records into the OpenGoods PostgreSQL database.
+
+Only the ingestion side writes to the database. Every load records OFF as the
+source with field-level provenance in `product_source`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+import psycopg
+from psycopg.types.json import Jsonb
+
+from opengoods.adapters.openfoodfacts import OFF_LICENSE, SOURCE_NAME
+from opengoods.etl.quality import update_quality
+
+OFF_HOMEPAGE = "https://world.openfoodfacts.org"
+
+logger = logging.getLogger(__name__)
+
+
+def default_dsn() -> str:
+    return os.environ.get(
+        "OPENGOODS_DATABASE_URL",
+        "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable",
+    )
+
+
+def _normalize_brand(name: str) -> str:
+    return " ".join(name.lower().split())
+
+
+def ensure_source_named(
+    conn: psycopg.Connection,
+    name: str,
+    homepage: str,
+    license: str,
+    trust_weight: float,
+) -> str:
+    """Upsert a source row by name and return its id."""
+    row = conn.execute(
+        """
+        INSERT INTO source (name, homepage, license, trust_weight)
+        VALUES (%s, %s, %s, %s)
+        ON CONFLICT (name) DO UPDATE SET homepage = EXCLUDED.homepage
+        RETURNING id
+        """,
+        (name, homepage, license, trust_weight),
+    ).fetchone()
+    return row[0]
+
+
+def ensure_source(conn: psycopg.Connection) -> str:
+    """Upsert the Open Food Facts source row and return its id."""
+    return ensure_source_named(conn, SOURCE_NAME, OFF_HOMEPAGE, OFF_LICENSE, 0.7)
+
+
+def _ensure_brand(conn: psycopg.Connection, name: str | None) -> str | None:
+    if not name:
+        return None
+    row = conn.execute(
+        """
+        INSERT INTO brand (name, normalized_name)
+        VALUES (%s, %s)
+        ON CONFLICT (normalized_name) DO UPDATE SET name = brand.name
+        RETURNING id
+        """,
+        (name, _normalize_brand(name)),
+    ).fetchone()
+    return row[0]
+
+
+def _category_id(conn: psycopg.Connection, path: str | None) -> tuple[str | None, str | None]:
+    if not path:
+        return None, None
+    row = conn.execute(
+        "SELECT id, gpc_brick_code FROM category WHERE path = %s::ltree", (path,)
+    ).fetchone()
+    return (row[0], row[1]) if row else (None, None)
+
+
+def load_record(conn: psycopg.Connection, rec: dict[str, Any], source_id: str, raw: dict) -> str:
+    """Upsert one transformed record; return the product id."""
+    brand_id = _ensure_brand(conn, rec.get("brand"))
+    category_id, gpc_brick = _category_id(conn, rec.get("category_path"))
+
+    fields = ["name", "brand", "net_content", "category", "country_of_origin"]
+
+    if rec.get("gtin"):
+        prod = conn.execute(
+            """
+            INSERT INTO product (gtin, name, brand_id, category_id, gpc_brick_code,
+                net_content_value, net_content_unit, net_content_canonical,
+                country_of_origin, attributes)
+            VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)
+            ON CONFLICT (gtin) WHERE gtin IS NOT NULL DO UPDATE SET
+                name = EXCLUDED.name,
+                brand_id = COALESCE(EXCLUDED.brand_id, product.brand_id),
+                category_id = COALESCE(EXCLUDED.category_id, product.category_id),
+                gpc_brick_code = COALESCE(EXCLUDED.gpc_brick_code, product.gpc_brick_code),
+                net_content_value = EXCLUDED.net_content_value,
+                net_content_unit = EXCLUDED.net_content_unit,
+                net_content_canonical = EXCLUDED.net_content_canonical,
+                country_of_origin = EXCLUDED.country_of_origin
+            RETURNING id
+            """,
+            (
+                rec["gtin"],
+                rec["name"],
+                brand_id,
+                category_id,
+                gpc_brick,
+                rec.get("net_content_value"),
+                rec.get("net_content_unit"),
+                rec.get("net_content_canonical"),
+                rec.get("country_of_origin"),
+                Jsonb({}),
+            ),
+        ).fetchone()
+    else:
+        prod = conn.execute(
+            """
+            INSERT INTO product (name, brand_id, category_id, gpc_brick_code,
+                net_content_value, net_content_unit, net_content_canonical,
+                country_of_origin, attributes)
+            VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)
+            RETURNING id
+            """,
+            (
+                rec["name"],
+                brand_id,
+                category_id,
+                gpc_brick,
+                rec.get("net_content_value"),
+                rec.get("net_content_unit"),
+                rec.get("net_content_canonical"),
+                rec.get("country_of_origin"),
+                Jsonb({}),
+            ),
+        ).fetchone()
+    product_id = prod[0]
+
+    food = rec.get("food") or {}
+    conn.execute(
+        """
+        INSERT INTO food_detail (product_id, ingredients_text, allergens, additives,
+            nutriments, nutrition_basis, serving_size, nutri_score)
+        VALUES (%s,%s,%s,%s,%s,%s,%s,%s)
+        ON CONFLICT (product_id) DO UPDATE SET
+            ingredients_text = EXCLUDED.ingredients_text,
+            allergens = EXCLUDED.allergens,
+            additives = EXCLUDED.additives,
+            nutriments = EXCLUDED.nutriments,
+            nutrition_basis = EXCLUDED.nutrition_basis,
+            serving_size = EXCLUDED.serving_size,
+            nutri_score = EXCLUDED.nutri_score
+        """,
+        (
+            product_id,
+            food.get("ingredients_text"),
+            food.get("allergens") or [],
+            food.get("additives") or [],
+            Jsonb(food.get("nutriments") or {}),
+            food.get("nutrition_basis"),
+            food.get("serving_size"),
+            food.get("nutri_score"),
+        ),
+    )
+
+    if rec.get("image_url"):
+        conn.execute(
+            """
+            INSERT INTO product_image (product_id, url, kind, license, source_id)
+            VALUES (%s,%s,'front',%s,%s)
+            """,
+            (product_id, rec["image_url"], "CC-BY-SA", source_id),
+        )
+        fields.append("image")
+
+    conn.execute(
+        """
+        INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+        VALUES (%s,%s,%s,%s, now(), %s)
+        """,
+        (
+            product_id,
+            source_id,
+            f"{OFF_HOMEPAGE}/product/{rec.get('gtin') or ''}",
+            fields,
+            Jsonb(_jsonable(raw)),
+        ),
+    )
+
+    # Recompute the data-quality score now that all facts + provenance exist.
+    update_quality(conn, product_id)
+    return product_id
+
+
+def load_record_safe(
+    conn: psycopg.Connection, rec: dict[str, Any], source_id: str, raw: dict
+) -> bool:
+    """Load one record inside a savepoint.
+
+    On success the record's writes stay in the surrounding transaction. On any
+    error, only this record's writes are rolled back (to the savepoint) and the
+    batch continues, so a single malformed source record cannot abort a large
+    import. Returns True if loaded, False if skipped due to an error.
+    """
+    try:
+        with conn.transaction():
+            load_record(conn, rec, source_id, raw)
+        return True
+    except Exception as exc:  # noqa: BLE001 - per-record isolation is intentional
+        logger.warning("skipping record gtin=%s: %s", rec.get("gtin"), exc)
+        return False
+
+
+def _jsonable(raw: dict) -> dict:
+    """Drop values that are not JSON-serializable from a raw record."""
+    try:
+        json.dumps(raw)
+        return raw
+    except (TypeError, ValueError):
+        return {k: v for k, v in raw.items() if _is_jsonable(v)}
+
+
+def _is_jsonable(v: object) -> bool:
+    try:
+        json.dumps(v)
+        return True
+    except (TypeError, ValueError):
+        return False
@@ -0,0 +1,104 @@
+"""Field-level conflict resolution for multi-source records.
+
+When more than one source describes the same product, each field may have
+several candidate values. We pick a winner per field by source trust first,
+then recency, ignoring empty values, and keep a provenance trail of which
+source won each field.
+
+These are pure functions (no DB / no network) so they are easy to unit-test;
+the DB-level record merge lives in :mod:`opengoods.etl.dedup`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """One source's proposed value for a field."""
+
+    value: object
+    source: str
+    trust: float = 0.5
+    fetched_at: datetime | None = None
+
+
+@dataclass
+class FieldResolution:
+    """The winning value for a field plus the source it came from."""
+
+    value: object
+    source: str | None = None
+
+
+@dataclass
+class MergedRecord:
+    """A merged record with per-field provenance (field name -> source)."""
+
+    values: dict[str, object] = field(default_factory=dict)
+    provenance: dict[str, str] = field(default_factory=dict)
+
+
+def _is_empty(value: object) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, str):
+        return value.strip() == ""
+    if isinstance(value, (list, dict, tuple, set)):
+        return len(value) == 0
+    return False
+
+
+def _sort_key(c: Candidate) -> tuple[float, float]:
+    ts = c.fetched_at.timestamp() if c.fetched_at is not None else float("-inf")
+    return (c.trust, ts)
+
+
+def resolve_field(candidates: list[Candidate]) -> FieldResolution | None:
+    """Pick the best non-empty candidate for one field.
+
+    Ranking: highest source trust, then most recent ``fetched_at``. Returns
+    ``None`` when there is no usable (non-empty) candidate.
+    """
+    usable = [c for c in candidates if not _is_empty(c.value)]
+    if not usable:
+        return None
+    winner = max(usable, key=_sort_key)
+    return FieldResolution(value=winner.value, source=winner.source)
+
+
+def merge_records(records: list[dict], *, fields: list[str] | None = None) -> MergedRecord:
+    """Merge several ``{field: Candidate|value}`` records into one.
+
+    Each input record maps field name -> :class:`Candidate` (preferred) or a
+    bare value (treated as trust 0.5, no timestamp). The result keeps, for each
+    field, the winning value and the name of the source that supplied it.
+    """
+    keys: list[str]
+    if fields is not None:
+        keys = list(fields)
+    else:
+        seen: dict[str, None] = {}
+        for rec in records:
+            for k in rec:
+                seen.setdefault(k, None)
+        keys = list(seen)
+
+    merged = MergedRecord()
+    for key in keys:
+        candidates: list[Candidate] = []
+        for rec in records:
+            if key not in rec:
+                continue
+            cand = rec[key]
+            if not isinstance(cand, Candidate):
+                cand = Candidate(value=cand, source="unknown")
+            candidates.append(cand)
+        resolution = resolve_field(candidates)
+        if resolution is not None:
+            merged.values[key] = resolution.value
+            if resolution.source is not None:
+                merged.provenance[key] = resolution.source
+    return merged
@@ -0,0 +1,176 @@
+"""Product data-quality scoring.
+
+The quality score is a 0..1 number combining four signals, per the locked
+project decision:
+
+    quality = 0.4 * completeness
+            + 0.3 * source_trust
+            + 0.2 * multi_source_agreement
+            + 0.1 * freshness
+
+Each component is itself normalized to 0..1. The pure helpers below are
+unit-testable; :func:`compute_quality` / :func:`update_quality` read the signals
+for a product out of the database and persist the result on ``product``.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import psycopg
+
+W_COMPLETENESS = 0.4
+W_SOURCE_TRUST = 0.3
+W_AGREEMENT = 0.2
+W_FRESHNESS = 0.1
+
+# Fields that count towards completeness (weighted equally).
+COMPLETENESS_FIELDS = (
+    "name",
+    "gtin",
+    "brand",
+    "category",
+    "net_content",
+    "country_of_origin",
+    "nutriments",
+    "ingredients",
+    "image",
+)
+
+
+def completeness(present: set[str]) -> float:
+    """Fraction of :data:`COMPLETENESS_FIELDS` that are present for a product."""
+    if not COMPLETENESS_FIELDS:
+        return 0.0
+    hits = sum(1 for f in COMPLETENESS_FIELDS if f in present)
+    return hits / len(COMPLETENESS_FIELDS)
+
+
+def agreement_from_sources(source_count: int) -> float:
+    """Multi-source corroboration proxy from the number of distinct sources.
+
+    A single source cannot be corroborated, so it scores a neutral 0.5; more
+    independent sources that describe the same product raise confidence.
+    """
+    if source_count <= 1:
+        return 0.5
+    if source_count == 2:
+        return 0.8
+    return 1.0
+
+
+def freshness_from_age(age_days: float | None) -> float:
+    """Recency score from the age (in days) of the most recent source fetch."""
+    if age_days is None:
+        return 0.5
+    if age_days <= 30:
+        return 1.0
+    if age_days <= 180:
+        return 0.8
+    if age_days <= 365:
+        return 0.6
+    if age_days <= 730:
+        return 0.4
+    return 0.2
+
+
+def score(
+    *,
+    completeness_score: float,
+    source_trust: float,
+    agreement: float,
+    freshness: float,
+) -> float:
+    """Combine the four normalized components into a 0..1 quality score."""
+    raw = (
+        W_COMPLETENESS * completeness_score
+        + W_SOURCE_TRUST * source_trust
+        + W_AGREEMENT * agreement
+        + W_FRESHNESS * freshness
+    )
+    return round(max(0.0, min(1.0, raw)), 3)
+
+
+def _present_fields(prod: dict, has_image: bool) -> set[str]:
+    present: set[str] = set()
+    if prod.get("name"):
+        present.add("name")
+    if prod.get("gtin"):
+        present.add("gtin")
+    if prod.get("brand_id"):
+        present.add("brand")
+    if prod.get("category_id"):
+        present.add("category")
+    if prod.get("net_content_canonical") is not None:
+        present.add("net_content")
+    if prod.get("country_of_origin"):
+        present.add("country_of_origin")
+    if prod.get("nutriments"):
+        present.add("nutriments")
+    if prod.get("ingredients_text"):
+        present.add("ingredients")
+    if has_image:
+        present.add("image")
+    return present
+
+
+def compute_quality(conn: psycopg.Connection, product_id: str) -> float:
+    """Compute (but do not persist) the quality score for one product."""
+    row = conn.execute(
+        """
+        SELECT p.name, p.gtin, p.brand_id, p.category_id, p.net_content_canonical,
+               p.country_of_origin, f.nutriments, f.ingredients_text,
+               EXISTS (SELECT 1 FROM product_image pi WHERE pi.product_id = p.id)
+        FROM product p
+        LEFT JOIN food_detail f ON f.product_id = p.id
+        WHERE p.id = %s
+        """,
+        (product_id,),
+    ).fetchone()
+    if row is None:
+        return 0.0
+    prod = {
+        "name": row[0],
+        "gtin": row[1],
+        "brand_id": row[2],
+        "category_id": row[3],
+        "net_content_canonical": row[4],
+        "country_of_origin": row[5],
+        "nutriments": row[6],
+        "ingredients_text": row[7],
+    }
+    has_image = bool(row[8])
+
+    src = conn.execute(
+        """
+        SELECT count(DISTINCT ps.source_id), COALESCE(max(s.trust_weight), 0), max(ps.fetched_at)
+        FROM product_source ps
+        LEFT JOIN source s ON s.id = ps.source_id
+        WHERE ps.product_id = %s
+        """,
+        (product_id,),
+    ).fetchone()
+    source_count = int(src[0] or 0)
+    source_trust = float(src[1] or 0.0)
+    last_fetched: datetime | None = src[2]
+
+    age_days: float | None = None
+    if last_fetched is not None:
+        now = datetime.now(UTC)
+        if last_fetched.tzinfo is None:
+            last_fetched = last_fetched.replace(tzinfo=UTC)
+        age_days = max(0.0, (now - last_fetched).total_seconds() / 86400.0)
+
+    return score(
+        completeness_score=completeness(_present_fields(prod, has_image)),
+        source_trust=source_trust,
+        agreement=agreement_from_sources(source_count),
+        freshness=freshness_from_age(age_days),
+    )
+
+
+def update_quality(conn: psycopg.Connection, product_id: str) -> float:
+    """Compute the quality score and write it to ``product.quality_score``."""
+    value = compute_quality(conn, product_id)
+    conn.execute("UPDATE product SET quality_score = %s WHERE id = %s", (value, product_id))
+    return value
@@ -0,0 +1,45 @@
+"""Persistent ingestion watermark stored in the ``ingest_state`` table.
+
+The incremental updater uses this to remember how far it got for each source
+(e.g. Open Food Facts exposes a ``last_modified_t`` unix timestamp on every
+product) so repeated runs only fetch what changed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import psycopg
+from psycopg.types.json import Jsonb
+
+
+def get_watermark(conn: psycopg.Connection, source: str) -> int:
+    """Return the last processed ``last_modified_t`` for *source* (0 if none)."""
+    row = conn.execute(
+        "SELECT last_modified_t FROM ingest_state WHERE source = %s", (source,)
+    ).fetchone()
+    return int(row[0]) if row else 0
+
+
+def set_watermark(
+    conn: psycopg.Connection,
+    source: str,
+    last_modified_t: int,
+    stats: dict[str, Any] | None = None,
+) -> None:
+    """Upsert the watermark and run metadata for *source*.
+
+    The watermark only ever moves forward: a lower ``last_modified_t`` is
+    ignored so an out-of-order or partial run cannot rewind progress.
+    """
+    conn.execute(
+        """
+        INSERT INTO ingest_state (source, last_modified_t, last_run_at, stats)
+        VALUES (%s, %s, now(), %s)
+        ON CONFLICT (source) DO UPDATE SET
+            last_modified_t = GREATEST(ingest_state.last_modified_t, EXCLUDED.last_modified_t),
+            last_run_at = now(),
+            stats = EXCLUDED.stats
+        """,
+        (source, int(last_modified_t), Jsonb(stats or {})),
+    )
@@ -0,0 +1,133 @@
+"""Apply GS1 (or other authoritative) supplements to existing products.
+
+A supplement only fills *gaps*: a field is written only when the product does
+not already have a value. Each applied supplement records field-level provenance
+in ``product_source`` and refreshes the product's quality score.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation
+from typing import Any
+
+import psycopg
+from psycopg.types.json import Jsonb
+
+from opengoods import units
+from opengoods.adapters.gs1 import GS1_HOMEPAGE, GS1_LICENSE, GS1_TRUST, SOURCE_NAME
+from opengoods.etl.load import _ensure_brand, _normalize_brand, ensure_source_named
+from opengoods.etl.quality import update_quality
+
+
+def ensure_gs1_source(conn: psycopg.Connection) -> str:
+    """Upsert the GS1 source row and return its id."""
+    return ensure_source_named(conn, SOURCE_NAME, GS1_HOMEPAGE, GS1_LICENSE, GS1_TRUST)
+
+
+def _ensure_manufacturer(conn: psycopg.Connection, name: str | None) -> str | None:
+    if not name:
+        return None
+    row = conn.execute(
+        """
+        INSERT INTO manufacturer (name, normalized_name)
+        VALUES (%s, %s)
+        ON CONFLICT (normalized_name) DO UPDATE SET name = manufacturer.name
+        RETURNING id
+        """,
+        (name, _normalize_brand(name)),
+    ).fetchone()
+    return row[0]
+
+
+def _net_content(rec: dict) -> tuple[Decimal, str, Decimal | None] | None:
+    raw_value = rec.get("net_content_value")
+    unit = rec.get("net_content_unit")
+    if raw_value is None or not unit:
+        return None
+    try:
+        value = Decimal(str(raw_value))
+    except (InvalidOperation, ValueError):
+        return None
+    try:
+        canonical = units.normalize(value, unit).canonical_value
+    except units.UnitError:
+        canonical = None
+    return value, unit, canonical
+
+
+def apply_supplement(conn: psycopg.Connection, rec: dict[str, Any], source_id: str) -> list[str]:
+    """Fill missing fields of the GTIN-matched product from ``rec``.
+
+    Returns the list of field names actually filled (empty if the product is
+    unknown or already complete for the supplied fields).
+    """
+    gtin = rec.get("gtin")
+    if not gtin:
+        return []
+    prod = conn.execute(
+        """
+        SELECT id, brand_id, manufacturer_id, gpc_brick_code, country_of_origin,
+               net_content_value
+        FROM product
+        WHERE gtin = %s AND status = 'active'
+        """,
+        (gtin,),
+    ).fetchone()
+    if prod is None:
+        return []
+
+    product_id, brand_id, manufacturer_id, gpc, country, net_value = prod
+    sets: list[str] = []
+    params: list[Any] = []
+    filled: list[str] = []
+
+    if brand_id is None and rec.get("brand"):
+        new_brand_id = _ensure_brand(conn, rec["brand"])
+        if new_brand_id is not None:
+            sets.append("brand_id = %s")
+            params.append(new_brand_id)
+            filled.append("brand")
+
+    if manufacturer_id is None and rec.get("manufacturer"):
+        new_mfr_id = _ensure_manufacturer(conn, rec["manufacturer"])
+        if new_mfr_id is not None:
+            sets.append("manufacturer_id = %s")
+            params.append(new_mfr_id)
+            filled.append("manufacturer")
+
+    if gpc is None and rec.get("gpc_brick_code"):
+        sets.append("gpc_brick_code = %s")
+        params.append(rec["gpc_brick_code"])
+        filled.append("gpc_brick_code")
+
+    if country is None and rec.get("country_of_origin"):
+        sets.append("country_of_origin = %s")
+        params.append(rec["country_of_origin"])
+        filled.append("country_of_origin")
+
+    if net_value is None:
+        net = _net_content(rec)
+        if net is not None:
+            value, unit, canonical = net
+            sets += [
+                "net_content_value = %s",
+                "net_content_unit = %s",
+                "net_content_canonical = %s",
+            ]
+            params += [value, unit, canonical]
+            filled.append("net_content")
+
+    if not filled:
+        return []
+
+    params.append(product_id)
+    conn.execute(f"UPDATE product SET {', '.join(sets)} WHERE id = %s", params)
+    conn.execute(
+        """
+        INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+        VALUES (%s, %s, %s, %s, now(), %s)
+        """,
+        (product_id, source_id, GS1_HOMEPAGE, filled, Jsonb(rec)),
+    )
+    update_quality(conn, product_id)
+    return filled
@@ -0,0 +1,167 @@
+"""Transform raw Open Food Facts records into the OpenGoods internal shape.
+
+Pure functions (no DB, no network) so they are easy to unit-test against
+fixtures. The output dict mirrors the columns the loader writes.
+"""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+
+from opengoods.units import UnitError, normalize
+
+# OFF nutriment key -> our attribute key. Energy handled separately.
+_NUTRIMENT_KEYS = {
+    "proteins_100g": "proteins",
+    "fat_100g": "fat",
+    "saturated-fat_100g": "saturated_fat",
+    "carbohydrates_100g": "carbohydrates",
+    "sugars_100g": "sugars",
+    "salt_100g": "salt",
+}
+
+# Very small keyword -> category path map (starter; replaced by a proper
+# OFF taxonomy -> GPC mapping table later).
+_CATEGORY_KEYWORDS: list[tuple[tuple[str, ...], str]] = [
+    (("water", "eau", "饮用水", "矿泉水"), "food.beverages.water"),
+    (("soda", "carbonated", "汽水", "碳酸"), "food.beverages.carbonated"),
+    (("juice", "jus", "果汁"), "food.beverages.juice"),
+    (("milk", "lait", "牛奶"), "food.dairy.milk"),
+    (("yogurt", "yoghurt", "yaourt", "酸奶"), "food.dairy.yogurt"),
+    (("cheese", "fromage", "奶酪", "干酪"), "food.dairy.cheese"),
+    (("bread", "pain", "面包"), "food.bakery.bread"),
+    (("biscuit", "cookie", "饼干"), "food.bakery.biscuits"),
+    (("chips", "crisps", "薯片", "膨化"), "food.snacks.chips"),
+    (("chocolate", "chocolat", "巧克力"), "food.snacks.chocolate"),
+    (("rice", "riz", "大米", "稻米"), "food.staple.rice"),
+    (("noodle", "pasta", "面条", "挂面"), "food.staple.noodles"),
+    (("oil", "huile", "食用油", "食油"), "food.staple.cooking_oil"),
+    (("soy sauce", "酱油"), "food.condiments.soy_sauce"),
+    (("salt", "sel", "食盐"), "food.condiments.salt"),
+]
+
+_QTY_RE = re.compile(r"(?P<value>\d+(?:[.,]\d+)?)\s*(?P<unit>[a-zA-Z\u4e00-\u9fff%]+)")
+
+
+def is_valid_gtin(code: str) -> bool:
+    """Validate a GTIN-8/12/13/14 using the standard check digit."""
+    if not code.isdigit() or len(code) not in (8, 12, 13, 14):
+        return False
+    digits = [int(c) for c in code]
+    check = digits[-1]
+    body = digits[:-1][::-1]
+    total = sum(d * (3 if i % 2 == 0 else 1) for i, d in enumerate(body))
+    return (10 - total % 10) % 10 == check
+
+
+def parse_quantity(text: str) -> tuple[Decimal, str] | None:
+    """Parse a free-text quantity like '500 g' or '1,5 L' -> (value, unit)."""
+    if not text:
+        return None
+    m = _QTY_RE.search(text)
+    if not m:
+        return None
+    value = Decimal(m.group("value").replace(",", "."))
+    return value, m.group("unit")
+
+
+def map_category(raw: dict) -> str | None:
+    """Best-effort map OFF categories/name to a self-built category path."""
+    haystack = " ".join(
+        str(raw.get(k, ""))
+        for k in ("categories", "categories_tags", "product_name", "product_name_en")
+    ).lower()
+    for keywords, path in _CATEGORY_KEYWORDS:
+        if any(kw.lower() in haystack for kw in keywords):
+            return path
+    return None
+
+
+def _clamp(value: str | None, max_len: int) -> str | None:
+    """Trim a string to fit a bounded DB column; external data length varies."""
+    if value is None:
+        return None
+    value = value.strip()
+    return value[:max_len] or None
+
+
+def _clean_tags(tags: list[str] | None, prefix: str = "") -> list[str]:
+    out: list[str] = []
+    for t in tags or []:
+        v = t.split(":", 1)[-1] if ":" in t else t
+        v = v.strip().replace("-", " ")
+        if v:
+            out.append(v)
+    return out
+
+
+def transform_nutriments(off_nutriments: dict) -> dict:
+    """Build a nutriments dict on a per_100g basis with dual energy units."""
+    out: dict[str, object] = {}
+    for off_key, our_key in _NUTRIMENT_KEYS.items():
+        if off_key in off_nutriments and off_nutriments[off_key] is not None:
+            out[our_key] = float(off_nutriments[off_key])
+
+    kj = off_nutriments.get("energy-kj_100g")
+    kcal = off_nutriments.get("energy-kcal_100g")
+    if kj is None and kcal is not None:
+        kj = float(Decimal(str(kcal)) * Decimal("4.184"))
+    if kcal is None and kj is not None:
+        kcal = float(Decimal(str(kj)) / Decimal("4.184"))
+    if kj is not None:
+        out["energy_kj"] = round(float(kj), 3)
+    if kcal is not None:
+        out["energy_kcal"] = round(float(kcal), 3)
+    return out
+
+
+def transform(raw: dict) -> dict | None:
+    """Transform one raw OFF product record into an internal product dict.
+
+    Returns None if the record lacks a usable name.
+    """
+    name = raw.get("product_name_zh") or raw.get("product_name") or raw.get("product_name_en")
+    if not name:
+        return None
+
+    code = str(raw.get("code", "")).strip()
+    gtin = code if code and is_valid_gtin(code) else None
+
+    brands = raw.get("brands") or ""
+    brand = brands.split(",")[0].strip() or None
+
+    net_value = net_unit = net_canonical = None
+    parsed = parse_quantity(raw.get("quantity", ""))
+    if parsed:
+        value, unit = parsed
+        try:
+            norm = normalize(value, unit)
+            net_value, net_unit, net_canonical = (
+                norm.value,
+                norm.unit,
+                norm.canonical_value,
+            )
+        except UnitError:
+            net_value, net_unit = value, unit
+
+    return {
+        "gtin": gtin,
+        "name": str(name).strip(),
+        "brand": brand,
+        "category_path": map_category(raw),
+        "net_content_value": net_value,
+        "net_content_unit": _clamp(net_unit, 16),
+        "net_content_canonical": net_canonical,
+        "country_of_origin": _clamp((raw.get("countries") or "").split(",")[0].strip() or None, 64),
+        "food": {
+            "ingredients_text": raw.get("ingredients_text") or None,
+            "allergens": _clean_tags(raw.get("allergens_tags")),
+            "additives": _clean_tags(raw.get("additives_tags")),
+            "nutriments": transform_nutriments(raw.get("nutriments") or {}),
+            "nutrition_basis": "per_100g",
+            "serving_size": _clamp(raw.get("serving_size") or None, 32),
+            "nutri_score": (raw.get("nutriscore_grade") or "").upper()[:1] or None,
+        },
+        "image_url": raw.get("image_front_url") or raw.get("image_url") or None,
+    }
@@ -0,0 +1,40 @@
+"""Deduplicate products: merge non-GTIN duplicates into a canonical record.
+
+Usage:
+    python -m opengoods.jobs.dedup --dry-run
+    python -m opengoods.jobs.dedup --actor nightly
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import psycopg
+
+from opengoods.etl.dedup import dedup_all
+from opengoods.etl.load import default_dsn
+
+
+def run(args: argparse.Namespace) -> int:
+    with psycopg.connect(args.dsn, autocommit=False) as conn:
+        summary = dedup_all(conn, actor=args.actor, dry_run=args.dry_run)
+        if args.dry_run:
+            conn.rollback()
+        else:
+            conn.commit()
+    mode = "dry-run" if args.dry_run else "applied"
+    print(f"{mode} groups={summary['groups']} merged={summary['merged']}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Deduplicate OpenGoods products")
+    parser.add_argument("--actor", default="ingestion", help="merge_log actor label")
+    parser.add_argument("--dry-run", action="store_true", help="report only, do not write")
+    parser.add_argument("--dsn", default=default_dsn(), help="PostgreSQL DSN")
+    return run(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,66 @@
+"""Lightweight recurring ingestion scheduler.
+
+Runs one ingestion cycle (incremental OFF update, then dedup) on a fixed
+interval. Dependency-free: a plain sleep loop rather than a cron/APScheduler
+dependency, so it is trivial to run in a container or under systemd/supervisor.
+
+Usage:
+    python -m opengoods.jobs.schedule --once            # single cycle, then exit
+    python -m opengoods.jobs.schedule --interval 3600   # every hour
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from datetime import UTC, datetime
+
+from opengoods.etl.load import default_dsn
+from opengoods.jobs import dedup as dedup_job
+from opengoods.jobs import update_off as update_job
+
+
+def _cycle(args: argparse.Namespace) -> None:
+    ts = datetime.now(UTC).isoformat(timespec="seconds")
+    print(f"[{ts}] cycle start")
+    update_job.run(
+        argparse.Namespace(
+            since=None,
+            page_size=args.page_size,
+            max_pages=args.max_pages,
+            min_interval=args.min_interval,
+            dsn=args.dsn,
+        )
+    )
+    if not args.skip_dedup:
+        dedup_job.run(argparse.Namespace(actor="scheduler", dry_run=False, dsn=args.dsn))
+
+
+def run(args: argparse.Namespace) -> int:
+    _cycle(args)
+    if args.once:
+        return 0
+    while True:
+        time.sleep(args.interval)
+        try:
+            _cycle(args)
+        except Exception as exc:  # noqa: BLE001 - keep the loop alive across failures
+            print(f"cycle error: {exc}", file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Recurring OpenGoods ingestion")
+    parser.add_argument("--interval", type=int, default=3600, help="seconds between cycles")
+    parser.add_argument("--once", action="store_true", help="run a single cycle and exit")
+    parser.add_argument("--skip-dedup", action="store_true", help="run update only")
+    parser.add_argument("--page-size", type=int, default=100, help="search page size")
+    parser.add_argument("--max-pages", type=int, default=10, help="max pages to scan")
+    parser.add_argument("--min-interval", type=float, default=4.0, help="API throttle seconds")
+    parser.add_argument("--dsn", default=default_dsn(), help="PostgreSQL DSN")
+    return run(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,97 @@
+"""Seed the database with Open Food Facts data.
+
+Usage:
+    # from a list of barcodes via the OFF API
+    python -m opengoods.jobs.seed_off --barcodes 3017624010701 5449000000996
+
+    # from a downloaded OFF JSONL dump (optionally .gz), limited to N records
+    python -m opengoods.jobs.seed_off --dump products.jsonl.gz --limit 1000
+
+    # market-focused: the most-scanned products sold in China, restricted to
+    # genuine GS1-China (69x) barcodes
+    python -m opengoods.jobs.seed_off --country china --domestic-only \
+        --max-pages 20 --limit 1000
+
+The OFF read API is rate-limited client-side; for large imports use a dump.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Iterator
+
+import psycopg
+
+from opengoods.adapters.openfoodfacts import (
+    OpenFoodFactsAdapter,
+    is_cn_gs1,
+    read_dump,
+)
+from opengoods.etl.load import default_dsn, ensure_source, load_record_safe
+from opengoods.etl.transform import transform
+
+
+def _raw_records(args: argparse.Namespace) -> Iterator[dict]:
+    if args.dump:
+        records: Iterator[dict] = read_dump(args.dump)
+    elif args.country:
+        adapter = OpenFoodFactsAdapter(min_interval=args.min_interval)
+        records = adapter.fetch_by_country(
+            args.country, page_size=args.page_size, max_pages=args.max_pages
+        )
+    else:
+        adapter = OpenFoodFactsAdapter(min_interval=args.min_interval)
+        records = adapter.fetch(args.barcodes)
+    yielded = 0
+    for rec in records:
+        if args.domestic_only and not is_cn_gs1(str(rec.get("code") or "")):
+            continue
+        if args.limit and yielded >= args.limit:
+            break
+        yielded += 1
+        yield rec
+
+
+def run(args: argparse.Namespace) -> int:
+    loaded = skipped = errored = 0
+    with psycopg.connect(args.dsn, autocommit=False) as conn:
+        source_id = ensure_source(conn)
+        for raw in _raw_records(args):
+            rec = transform(raw)
+            if rec is None:
+                skipped += 1
+                continue
+            if load_record_safe(conn, rec, source_id, raw):
+                loaded += 1
+            else:
+                errored += 1
+        conn.commit()
+    print(f"loaded={loaded} skipped={skipped} errored={errored}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Seed OpenGoods from Open Food Facts")
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument("--barcodes", nargs="+", help="barcodes to fetch via the OFF API")
+    src.add_argument("--dump", help="path to an OFF JSONL dump (.jsonl or .jsonl.gz)")
+    src.add_argument(
+        "--country",
+        help="OFF countries_tags_en slug to seed from, e.g. 'china' (most-scanned first)",
+    )
+    parser.add_argument(
+        "--domestic-only",
+        action="store_true",
+        help="keep only genuine GS1-China (69x) barcodes; drop imported goods",
+    )
+    parser.add_argument("--limit", type=int, default=0, help="max records to load (0 = all)")
+    parser.add_argument("--page-size", type=int, default=100, help="search page size")
+    parser.add_argument("--max-pages", type=int, default=10, help="max search pages (country mode)")
+    parser.add_argument("--min-interval", type=float, default=4.0, help="API throttle seconds")
+    parser.add_argument("--dsn", default=default_dsn(), help="PostgreSQL DSN")
+    return run(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,70 @@
+"""Incremental Open Food Facts update.
+
+Fetches products modified since the persisted watermark, loads them, then
+advances the watermark to the newest ``last_modified_t`` processed so the next
+run only sees what changed.
+
+Usage:
+    python -m opengoods.jobs.update_off --max-pages 5
+    python -m opengoods.jobs.update_off --since 1700000000   # override watermark
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import psycopg
+
+from opengoods.adapters.openfoodfacts import SOURCE_NAME, OpenFoodFactsAdapter
+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
+
+
+def run(args: argparse.Namespace) -> int:
+    adapter = OpenFoodFactsAdapter(min_interval=args.min_interval)
+    loaded = skipped = errored = 0
+    high_watermark = 0
+    with psycopg.connect(args.dsn, autocommit=False) as conn:
+        source_id = ensure_source(conn)
+        since = args.since if args.since is not None else get_watermark(conn, SOURCE_NAME)
+        high_watermark = since
+        for raw in adapter.fetch_modified_since(
+            since, page_size=args.page_size, max_pages=args.max_pages
+        ):
+            high_watermark = max(high_watermark, int(raw.get("last_modified_t") or 0))
+            rec = transform(raw)
+            if rec is None:
+                skipped += 1
+                continue
+            if load_record_safe(conn, rec, source_id, raw):
+                loaded += 1
+            else:
+                errored += 1
+        set_watermark(
+            conn,
+            SOURCE_NAME,
+            high_watermark,
+            stats={"loaded": loaded, "skipped": skipped, "errored": errored, "since": since},
+        )
+        conn.commit()
+    print(
+        f"since={since} loaded={loaded} skipped={skipped} "
+        f"errored={errored} watermark={high_watermark}"
+    )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Incremental OFF update")
+    parser.add_argument("--since", type=int, default=None, help="override watermark (unix ts)")
+    parser.add_argument("--page-size", type=int, default=100, help="search page size")
+    parser.add_argument("--max-pages", type=int, default=10, help="max pages to scan")
+    parser.add_argument("--min-interval", type=float, default=4.0, help="API throttle seconds")
+    parser.add_argument("--dsn", default=default_dsn(), help="PostgreSQL DSN")
+    return run(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -5,6 +5,7 @@ description = "OpenGoods (天工·商品标签) ingestion & ETL: collect product
 requires-python = ">=3.11"
 dependencies = [
    "httpx>=0.27",
+    "psycopg[binary]>=3.2",
 ]

 [project.optional-dependencies]
@@ -0,0 +1,31 @@
+"""Shared test fixtures.
+
+`db_conn` yields a psycopg connection inside a transaction that is rolled back
+after each test, so DB tests stay isolated and leave no residue. Tests are
+skipped automatically when no database is reachable or M4 migrations are not
+applied (e.g. local runs without docker).
+"""
+
+from __future__ import annotations
+
+import psycopg
+import pytest
+
+from opengoods.etl.load import default_dsn
+
+
+@pytest.fixture()
+def db_conn():
+    try:
+        conn = psycopg.connect(default_dsn(), connect_timeout=3)
+    except psycopg.OperationalError as exc:  # pragma: no cover - env dependent
+        pytest.skip(f"no database available: {exc}")
+    has_state = conn.execute("SELECT to_regclass('public.ingest_state') IS NOT NULL").fetchone()[0]
+    if not has_state:
+        conn.close()
+        pytest.skip("M4 migrations not applied")
+    try:
+        yield conn
+    finally:
+        conn.rollback()
+        conn.close()
@@ -0,0 +1,14 @@
+{
+  "06901234567892": {
+    "name": "示例矿泉水 550ml",
+    "brand": "示例品牌",
+    "manufacturer": "示例饮品有限公司",
+    "gpc_brick_code": "10000224",
+    "country_of_origin": "China",
+    "net_content_value": 550,
+    "net_content_unit": "ml"
+  },
+  "00000000000000": {
+    "brand": ""
+  }
+}
@@ -0,0 +1,26 @@
+{
+  "code": "3017624010701",
+  "product_name": "Nutella",
+  "product_name_en": "Nutella hazelnut spread",
+  "brands": "Ferrero, Nutella",
+  "quantity": "400 g",
+  "countries": "France, China",
+  "categories": "Spreads, Hazelnut spreads, Chocolate spreads",
+  "categories_tags": ["en:spreads", "en:chocolate-spreads"],
+  "ingredients_text": "Sugar, palm oil, hazelnuts, cocoa, skimmed milk powder",
+  "allergens_tags": ["en:milk", "en:nuts"],
+  "additives_tags": ["en:e322"],
+  "serving_size": "15 g",
+  "nutriscore_grade": "e",
+  "image_front_url": "https://images.openfoodfacts.org/images/products/301/762/401/0701/front_en.jpg",
+  "nutriments": {
+    "energy-kj_100g": 2252,
+    "energy-kcal_100g": 539,
+    "fat_100g": 30.9,
+    "saturated-fat_100g": 10.6,
+    "carbohydrates_100g": 57.5,
+    "sugars_100g": 56.3,
+    "proteins_100g": 6.3,
+    "salt_100g": 0.107
+  }
+}
@@ -0,0 +1,62 @@
+from opengoods.etl.dedup import choose_canonical, dedup_all, product_signature
+from opengoods.etl.load import _ensure_brand, ensure_source
+
+
+def test_product_signature_normalization():
+    a = product_signature("  Spring  Water ", "Acme", 500)
+    b = product_signature("spring water", "acme", 500)
+    assert a == b
+    assert product_signature("", "x", 1) is None
+
+
+def test_choose_canonical_prefers_quality():
+    members = [
+        {"id": "a", "quality_score": 0.2, "created_at": 1},
+        {"id": "b", "quality_score": 0.9, "created_at": 2},
+    ]
+    assert choose_canonical(members)["id"] == "b"
+
+
+def test_dedup_merges_duplicates(db_conn):
+    brand_id = _ensure_brand(db_conn, "DupBrand")
+
+    def mk(quality):
+        return db_conn.execute(
+            """
+            INSERT INTO product (name, brand_id, net_content_canonical, quality_score)
+            VALUES (%s, %s, %s, %s) RETURNING id
+            """,
+            ("Dup Snack", brand_id, 100, quality),
+        ).fetchone()[0]
+
+    keep = mk(0.9)
+    drop = mk(0.2)
+
+    src = ensure_source(db_conn)
+    db_conn.execute(
+        "INSERT INTO product_source (product_id, source_id, fields) VALUES (%s, %s, %s)",
+        (drop, src, ["name"]),
+    )
+
+    summary = dedup_all(db_conn)
+    assert summary == {"groups": 1, "merged": 1}
+
+    keep_status = db_conn.execute("SELECT status FROM product WHERE id = %s", (keep,)).fetchone()[0]
+    drop_status, canonical_id = db_conn.execute(
+        "SELECT status, canonical_id FROM product WHERE id = %s", (drop,)
+    ).fetchone()
+    assert keep_status == "active"
+    assert drop_status == "merged"
+    assert str(canonical_id) == str(keep)
+
+    # The merged product's source row was re-pointed to the canonical product.
+    reattached = db_conn.execute(
+        "SELECT count(*) FROM product_source WHERE product_id = %s", (keep,)
+    ).fetchone()[0]
+    assert reattached == 1
+
+    logged = db_conn.execute(
+        "SELECT count(*) FROM merge_log WHERE kept_id = %s AND merged_id = %s",
+        (keep, drop),
+    ).fetchone()[0]
+    assert logged == 1
@@ -0,0 +1,53 @@
+from pathlib import Path
+
+from opengoods.adapters.gs1 import GS1Adapter
+from opengoods.etl.supplement import apply_supplement, ensure_gs1_source
+
+MAPPING = Path(__file__).parent / "fixtures" / "gs1_mapping.json"
+GTIN = "06901234567892"
+
+
+def test_gs1_adapter_offline_lookup():
+    adapter = GS1Adapter.from_file(MAPPING)
+    rec = adapter.fetch_barcode(GTIN)
+    assert rec["brand"] == "示例品牌"
+    assert rec["net_content_value"] == 550
+    assert rec["net_content_unit"] == "ml"
+    # An entry that only has empty values yields no supplement.
+    assert adapter.fetch_barcode("00000000000000") is None
+    # Unknown barcode -> None.
+    assert adapter.fetch_barcode("99999999999999") is None
+
+
+def test_gs1_supplement_fills_only_gaps(db_conn):
+    pid = db_conn.execute(
+        "INSERT INTO product (gtin, name) VALUES (%s, %s) RETURNING id", (GTIN, "水")
+    ).fetchone()[0]
+
+    adapter = GS1Adapter.from_file(MAPPING)
+    rec = adapter.fetch_barcode(GTIN)
+    source_id = ensure_gs1_source(db_conn)
+
+    filled = apply_supplement(db_conn, rec, source_id)
+    assert {"brand", "country_of_origin", "net_content"} <= set(filled)
+
+    brand_id, country, net_value, net_unit = db_conn.execute(
+        """
+        SELECT brand_id, country_of_origin, net_content_value, net_content_unit
+        FROM product WHERE id = %s
+        """,
+        (pid,),
+    ).fetchone()
+    assert brand_id is not None
+    assert country == "China"
+    assert float(net_value) == 550.0
+    assert net_unit == "ml"
+
+    fields = db_conn.execute(
+        "SELECT fields FROM product_source WHERE product_id = %s AND source_id = %s",
+        (pid, source_id),
+    ).fetchone()[0]
+    assert "brand" in fields
+
+    # Re-applying does nothing because the gaps are now filled.
+    assert apply_supplement(db_conn, rec, source_id) == []
@@ -0,0 +1,83 @@
+"""Integration test for the DB loader.
+
+Skipped automatically when no database is reachable (e.g. local runs without
+docker, or CI jobs without a postgres service). Requires migrations applied.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from opengoods.etl.load import default_dsn, ensure_source, load_record, load_record_safe
+from opengoods.etl.transform import transform
+
+psycopg = pytest.importorskip("psycopg")
+
+FIXTURE = json.loads((Path(__file__).parent / "fixtures" / "off_product.json").read_text())
+
+
+@pytest.fixture()
+def conn():
+    try:
+        c = psycopg.connect(default_dsn(), connect_timeout=3)
+    except psycopg.OperationalError as exc:  # pragma: no cover - env dependent
+        pytest.skip(f"no database available: {exc}")
+    # ensure schema present
+    has_product = c.execute("SELECT to_regclass('public.product') IS NOT NULL").fetchone()[0]
+    if not has_product:
+        c.close()
+        pytest.skip("migrations not applied")
+    yield c
+    c.rollback()
+    c.close()
+
+
+def test_load_record_roundtrip(conn):
+    source_id = ensure_source(conn)
+    rec = transform(FIXTURE)
+    product_id = load_record(conn, rec, source_id, FIXTURE)
+
+    row = conn.execute(
+        "SELECT name, gtin, net_content_unit FROM product WHERE id = %s", (product_id,)
+    ).fetchone()
+    assert row[0] == "Nutella"
+    assert row[1] == "3017624010701"
+    assert row[2] == "g"
+
+    nutri = conn.execute(
+        "SELECT nutriments ->> 'energy_kcal' FROM food_detail WHERE product_id = %s",
+        (product_id,),
+    ).fetchone()
+    assert nutri[0] == "539.0"
+
+    prov = conn.execute(
+        "SELECT count(*) FROM product_source WHERE product_id = %s", (product_id,)
+    ).fetchone()
+    assert prov[0] >= 1
+
+    conn.rollback()  # keep the test DB clean
+
+
+def test_load_record_safe_isolates_bad_record(conn):
+    source_id = ensure_source(conn)
+
+    # Unique gtin so the good record is a fresh INSERT, not an upsert/update.
+    good = transform(FIXTURE)
+    good["gtin"] = "4006381333931"
+    assert load_record_safe(conn, good, source_id, FIXTURE) is True
+    after_good = conn.execute("SELECT count(*) FROM product").fetchone()[0]
+
+    # A record whose name violates NOT NULL must not abort the batch.
+    bad = dict(good)
+    bad["gtin"] = "5000112637922"
+    bad["name"] = None
+    assert load_record_safe(conn, bad, source_id, {}) is False
+
+    # The good record survived the bad one's rollback-to-savepoint.
+    after_bad = conn.execute("SELECT count(*) FROM product").fetchone()[0]
+    assert after_bad == after_good
+
+    conn.rollback()  # keep the test DB clean
@@ -0,0 +1,62 @@
+from datetime import UTC, datetime
+
+from opengoods.etl.merge import Candidate, merge_records, resolve_field
+
+
+def _ts(y, m, d):
+    return datetime(y, m, d, tzinfo=UTC)
+
+
+def test_resolve_field_prefers_trust_then_recency():
+    cands = [
+        Candidate(value="A", source="off", trust=0.7, fetched_at=_ts(2024, 1, 1)),
+        Candidate(value="B", source="gs1", trust=0.9, fetched_at=_ts(2023, 1, 1)),
+    ]
+    res = resolve_field(cands)
+    assert res is not None
+    assert res.value == "B"
+    assert res.source == "gs1"
+
+
+def test_resolve_field_recency_tiebreak_on_equal_trust():
+    cands = [
+        Candidate(value="old", source="a", trust=0.7, fetched_at=_ts(2023, 1, 1)),
+        Candidate(value="new", source="b", trust=0.7, fetched_at=_ts(2024, 6, 1)),
+    ]
+    assert resolve_field(cands).value == "new"
+
+
+def test_resolve_field_skips_empty():
+    cands = [
+        Candidate(value="", source="a", trust=0.99),
+        Candidate(value=None, source="b", trust=0.99),
+        Candidate(value="kept", source="c", trust=0.1),
+    ]
+    assert resolve_field(cands).value == "kept"
+    assert resolve_field([Candidate(value="", source="a")]) is None
+
+
+def test_merge_records_provenance():
+    records = [
+        {
+            "name": Candidate("Water", "off", 0.7, _ts(2024, 1, 1)),
+            "brand": Candidate("", "off", 0.7),
+        },
+        {
+            "brand": Candidate("Acme", "gs1", 0.9, _ts(2024, 2, 1)),
+            "gtin": Candidate("123", "gs1", 0.9),
+        },
+    ]
+    merged = merge_records(records)
+    assert merged.values["name"] == "Water"
+    assert merged.values["brand"] == "Acme"
+    assert merged.values["gtin"] == "123"
+    assert merged.provenance["brand"] == "gs1"
+    assert merged.provenance["name"] == "off"
+
+
+def test_merge_records_accepts_bare_values():
+    merged = merge_records([{"x": 1}, {"x": 2}])
+    # both bare -> trust tie, no timestamps -> first max() wins deterministically
+    assert merged.values["x"] in (1, 2)
+    assert merged.provenance["x"] == "unknown"
@@ -0,0 +1,53 @@
+import httpx
+
+from opengoods.adapters.openfoodfacts import OpenFoodFactsAdapter, is_cn_gs1
+
+
+def _adapter(handler, **kwargs):
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    return OpenFoodFactsAdapter(client=client, min_interval=0, backoff_base=0, **kwargs)
+
+
+def test_is_cn_gs1():
+    assert is_cn_gs1("6901234567892")  # GS1 China prefix
+    assert is_cn_gs1("690")
+    assert not is_cn_gs1("3017624010701")  # France
+    assert not is_cn_gs1("5449000000996")  # Belgium
+    assert not is_cn_gs1("")
+    assert not is_cn_gs1(None)
+    assert not is_cn_gs1("69")  # too short to carry a prefix digit
+
+
+def test_fetch_by_country_passes_filter_and_paginates():
+    seen_params = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen_params.append(dict(request.url.params))
+        page = int(request.url.params.get("page", "1"))
+        if page == 1:
+            return httpx.Response(
+                200,
+                json={"products": [{"code": "6901"}, {"code": "6902"}]},
+            )
+        return httpx.Response(200, json={"products": []})
+
+    adapter = _adapter(handler)
+    out = list(adapter.fetch_by_country("china", page_size=2, max_pages=5))
+    assert [p["code"] for p in out] == ["6901", "6902"]
+    assert seen_params[0]["countries_tags_en"] == "china"
+    assert seen_params[0]["sort_by"] == "unique_scans_n"
+
+
+def test_fetch_by_country_dedupes_across_pages():
+    def handler(request: httpx.Request) -> httpx.Response:
+        page = int(request.url.params.get("page", "1"))
+        if page == 1:
+            return httpx.Response(200, json={"products": [{"code": "6901"}, {"code": "6902"}]})
+        if page == 2:
+            # OFF popularity ordering is unstable; a repeat appears on page 2
+            return httpx.Response(200, json={"products": [{"code": "6902"}, {"code": "6903"}]})
+        return httpx.Response(200, json={"products": []})
+
+    adapter = _adapter(handler)
+    out = [p["code"] for p in adapter.fetch_by_country("china", page_size=2, max_pages=5)]
+    assert out == ["6901", "6902", "6903"]
@@ -0,0 +1,44 @@
+import httpx
+
+from opengoods.adapters.openfoodfacts import OpenFoodFactsAdapter
+
+
+def _product(code, lm):
+    return {"code": code, "product_name": f"P{code}", "last_modified_t": lm}
+
+
+def _adapter(pages):
+    """Build an adapter whose search endpoint serves the given pages."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        page = int(request.url.params.get("page", "1"))
+        products = pages.get(page, [])
+        return httpx.Response(200, json={"products": products, "page": page})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    return OpenFoodFactsAdapter(client=client, min_interval=0)
+
+
+def test_incremental_yields_only_newer_and_stops_at_watermark():
+    pages = {
+        1: [_product("1", 300), _product("2", 250), _product("3", 100)],
+    }
+    adapter = _adapter(pages)
+    got = list(adapter.fetch_modified_since(200, page_size=3, max_pages=5))
+    codes = [p["code"] for p in got]
+    assert codes == ["1", "2"]  # 100 <= 200 stops iteration
+
+
+def test_incremental_paginates_until_short_page():
+    pages = {
+        1: [_product("1", 900), _product("2", 800)],
+        2: [_product("3", 700)],  # short page -> stop after
+    }
+    adapter = _adapter(pages)
+    got = list(adapter.fetch_modified_since(0, page_size=2, max_pages=5))
+    assert [p["code"] for p in got] == ["1", "2", "3"]
+
+
+def test_incremental_empty_first_page():
+    adapter = _adapter({1: []})
+    assert list(adapter.fetch_modified_since(0, page_size=10, max_pages=3)) == []
@@ -0,0 +1,59 @@
+import httpx
+import pytest
+
+from opengoods.adapters.openfoodfacts import OpenFoodFactsAdapter
+
+
+def _adapter(handler, **kwargs):
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    return OpenFoodFactsAdapter(client=client, min_interval=0, backoff_base=0, **kwargs)
+
+
+def test_retries_transient_5xx_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] < 3:
+            return httpx.Response(503)
+        return httpx.Response(200, json={"status": 1, "product": {"code": "x"}})
+
+    adapter = _adapter(handler, max_retries=4)
+    assert adapter.fetch_barcode("x") == {"code": "x"}
+    assert calls["n"] == 3  # two 503s retried, third succeeds
+
+
+def test_retries_exhausted_raises():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(503)
+
+    adapter = _adapter(handler, max_retries=2)
+    with pytest.raises(httpx.HTTPStatusError):
+        adapter.fetch_barcode("x")
+
+
+def test_non_retryable_4xx_not_retried():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(404)
+
+    adapter = _adapter(handler, max_retries=4)
+    with pytest.raises(httpx.HTTPStatusError):
+        adapter.fetch_barcode("x")
+    assert calls["n"] == 1  # 404 is not retried
+
+
+def test_retries_connection_error_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise httpx.ConnectError("boom")
+        return httpx.Response(200, json={"status": 1, "product": {"code": "y"}})
+
+    adapter = _adapter(handler, max_retries=4)
+    assert adapter.fetch_barcode("y") == {"code": "y"}
+    assert calls["n"] == 2
@@ -0,0 +1,38 @@
+from opengoods.etl.quality import (
+    COMPLETENESS_FIELDS,
+    agreement_from_sources,
+    completeness,
+    freshness_from_age,
+    score,
+)
+
+
+def test_completeness_bounds():
+    assert completeness(set()) == 0.0
+    assert completeness(set(COMPLETENESS_FIELDS)) == 1.0
+    half = set(list(COMPLETENESS_FIELDS)[: len(COMPLETENESS_FIELDS) // 2])
+    assert 0.0 < completeness(half) < 1.0
+
+
+def test_agreement_from_sources():
+    assert agreement_from_sources(0) == 0.5
+    assert agreement_from_sources(1) == 0.5
+    assert agreement_from_sources(2) == 0.8
+    assert agreement_from_sources(5) == 1.0
+
+
+def test_freshness_from_age():
+    assert freshness_from_age(None) == 0.5
+    assert freshness_from_age(1) == 1.0
+    assert freshness_from_age(100) == 0.8
+    assert freshness_from_age(300) == 0.6
+    assert freshness_from_age(700) == 0.4
+    assert freshness_from_age(5000) == 0.2
+
+
+def test_score_weighted_sum_and_bounds():
+    assert score(completeness_score=0, source_trust=0, agreement=0, freshness=0) == 0.0
+    assert score(completeness_score=1, source_trust=1, agreement=1, freshness=1) == 1.0
+    # 0.4*1 + 0.3*0.5 + 0.2*0.5 + 0.1*1 = 0.75
+    got = score(completeness_score=1.0, source_trust=0.5, agreement=0.5, freshness=1.0)
+    assert got == 0.75
@@ -0,0 +1,21 @@
+import json
+from pathlib import Path
+
+from opengoods.etl.load import ensure_source, load_record
+from opengoods.etl.quality import compute_quality
+from opengoods.etl.transform import transform
+
+FIXTURE = json.loads((Path(__file__).parent / "fixtures" / "off_product.json").read_text())
+
+
+def test_quality_score_set_on_load(db_conn):
+    source_id = ensure_source(db_conn)
+    rec = transform(FIXTURE)
+    pid = load_record(db_conn, rec, source_id, FIXTURE)
+
+    stored = float(
+        db_conn.execute("SELECT quality_score FROM product WHERE id = %s", (pid,)).fetchone()[0]
+    )
+    assert 0.0 < stored <= 1.0
+    # The persisted value matches a fresh recomputation.
+    assert abs(stored - compute_quality(db_conn, pid)) < 1e-9
@@ -0,0 +1,16 @@
+from opengoods.etl.state import get_watermark, set_watermark
+
+
+def test_watermark_roundtrip_and_monotonic(db_conn):
+    src = "test-source"
+    assert get_watermark(db_conn, src) == 0
+
+    set_watermark(db_conn, src, 100, stats={"loaded": 1})
+    assert get_watermark(db_conn, src) == 100
+
+    # A lower watermark must not rewind progress.
+    set_watermark(db_conn, src, 50)
+    assert get_watermark(db_conn, src) == 100
+
+    set_watermark(db_conn, src, 150)
+    assert get_watermark(db_conn, src) == 150
@@ -0,0 +1,78 @@
+import json
+from decimal import Decimal
+from pathlib import Path
+
+import pytest
+
+from opengoods.etl.transform import (
+    is_valid_gtin,
+    map_category,
+    parse_quantity,
+    transform,
+    transform_nutriments,
+)
+
+FIXTURE = json.loads((Path(__file__).parent / "fixtures" / "off_product.json").read_text())
+
+
+def test_is_valid_gtin():
+    assert is_valid_gtin("3017624010701")  # real EAN-13
+    assert is_valid_gtin("5449000000996")  # Coca-Cola
+    assert not is_valid_gtin("3017624010700")  # bad check digit
+    assert not is_valid_gtin("123")
+    assert not is_valid_gtin("notanumber")
+
+
+def test_parse_quantity():
+    assert parse_quantity("400 g") == (Decimal("400"), "g")
+    assert parse_quantity("1,5 L") == (Decimal("1.5"), "L")
+    assert parse_quantity("") is None
+    assert parse_quantity("family size") is None
+
+
+def test_map_category():
+    assert map_category({"product_name": "Spring Water"}) == "food.beverages.water"
+    assert map_category({"categories": "Dark chocolate"}) == "food.snacks.chocolate"
+    assert map_category({"product_name": "Mystery"}) is None
+
+
+def test_transform_nutriments_dual_energy():
+    out = transform_nutriments(FIXTURE["nutriments"])
+    assert out["energy_kj"] == 2252.0
+    assert out["energy_kcal"] == 539.0
+    assert out["fat"] == 30.9
+    assert out["salt"] == 0.107
+
+
+def test_transform_nutriments_fills_missing_energy():
+    out = transform_nutriments({"energy-kcal_100g": 100})
+    assert out["energy_kj"] == pytest.approx(418.4)
+
+
+def test_transform_full_record():
+    rec = transform(FIXTURE)
+    assert rec is not None
+    assert rec["gtin"] == "3017624010701"
+    assert rec["name"] == "Nutella"
+    assert rec["brand"] == "Ferrero"
+    assert rec["net_content_unit"] == "g"
+    assert rec["net_content_canonical"] == Decimal("400")
+    assert rec["country_of_origin"] == "France"
+    assert rec["food"]["nutri_score"] == "E"
+    assert "milk" in rec["food"]["allergens"]
+    assert rec["image_url"].endswith(".jpg")
+
+
+def test_transform_drops_unnamed():
+    assert transform({"code": "0000000000000"}) is None
+
+
+def test_transform_clamps_long_serving_size():
+    raw = {
+        "code": "3017624010701",
+        "product_name": "X",
+        "serving_size": "1 portion (30 g) / 1 portion (30 g) / extra long descriptive text here",
+    }
+    rec = transform(raw)
+    assert rec is not None
+    assert len(rec["food"]["serving_size"]) == 32
@@ -0,0 +1,21 @@
+DROP TRIGGER IF EXISTS trg_product_sync ON product;
+DROP FUNCTION IF EXISTS product_sync_tsv();
+
+DROP TABLE IF EXISTS merge_log;
+DROP TABLE IF EXISTS product_source;
+DROP TABLE IF EXISTS product_image;
+DROP TABLE IF EXISTS product_msrp;
+DROP TABLE IF EXISTS food_detail;
+DROP TABLE IF EXISTS product;
+DROP TABLE IF EXISTS attribute_definition;
+DROP TABLE IF EXISTS unit;
+DROP TABLE IF EXISTS category_schema;
+DROP TABLE IF EXISTS category;
+DROP TABLE IF EXISTS manufacturer;
+DROP TABLE IF EXISTS brand;
+DROP TABLE IF EXISTS source;
+
+DROP EXTENSION IF EXISTS ltree;
+DROP EXTENSION IF EXISTS pg_trgm;
+-- keep pgcrypto (commonly shared); drop only if you are sure:
+-- DROP EXTENSION IF EXISTS pgcrypto;
@@ -0,0 +1,182 @@
+-- OpenGoods (天工·商品标签) initial schema.
+-- Public-good product information store: facts only, no commerce.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;   -- gen_random_uuid()
+CREATE EXTENSION IF NOT EXISTS pg_trgm;     -- fuzzy name search
+CREATE EXTENSION IF NOT EXISTS ltree;       -- category subtree queries
+
+-- Data sources (Open Food Facts / USDA / GS1 ...) with trust + license.
+CREATE TABLE source (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name         TEXT NOT NULL,
+    homepage     TEXT,
+    license      TEXT,
+    trust_weight NUMERIC(3,2) NOT NULL DEFAULT 0.5,
+    notes        TEXT,
+    UNIQUE (name)
+);
+
+CREATE TABLE brand (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name            TEXT NOT NULL,
+    normalized_name TEXT NOT NULL,
+    aliases         TEXT[] NOT NULL DEFAULT '{}',
+    UNIQUE (normalized_name)
+);
+
+CREATE TABLE manufacturer (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name            TEXT NOT NULL,
+    normalized_name TEXT NOT NULL,
+    country         VARCHAR(64),
+    UNIQUE (normalized_name)
+);
+
+-- Self-built category tree, each node optionally mapped to a GS1 GPC brick.
+CREATE TABLE category (
+    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name_zh        TEXT NOT NULL,
+    name_en        TEXT,
+    parent_id      UUID REFERENCES category(id),
+    path           LTREE NOT NULL,
+    gpc_brick_code VARCHAR(10),
+    level          INT NOT NULL DEFAULT 0,
+    UNIQUE (path)
+);
+
+-- Parameter template / constraints per category.
+CREATE TABLE category_schema (
+    category_id           UUID PRIMARY KEY REFERENCES category(id) ON DELETE CASCADE,
+    required_attributes   TEXT[] NOT NULL DEFAULT '{}',
+    recommended_attributes TEXT[] NOT NULL DEFAULT '{}',
+    nutriment_basis       VARCHAR(16)
+);
+
+-- Unit dictionary: each unit maps to a canonical unit within its dimension.
+CREATE TABLE unit (
+    code                VARCHAR(16) PRIMARY KEY,
+    dimension           VARCHAR(16) NOT NULL,
+    canonical           VARCHAR(16) NOT NULL,
+    to_canonical_factor NUMERIC,
+    aliases             TEXT[] NOT NULL DEFAULT '{}',
+    display             TEXT
+);
+
+-- Parameter dictionary: standard attribute keys with default unit.
+CREATE TABLE attribute_definition (
+    key          VARCHAR(64) PRIMARY KEY,
+    label_zh     TEXT,
+    label_en     TEXT,
+    dimension    VARCHAR(16),
+    default_unit VARCHAR(16) REFERENCES unit(code),
+    aliases      TEXT[] NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE product (
+    id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    gtin                  VARCHAR(14),
+    name                  TEXT NOT NULL,
+    brand_id              UUID REFERENCES brand(id),
+    manufacturer_id       UUID REFERENCES manufacturer(id),
+    category_id           UUID REFERENCES category(id),
+    gpc_brick_code        VARCHAR(10),
+    net_content_value     NUMERIC,
+    net_content_unit      VARCHAR(16),
+    net_content_canonical NUMERIC,
+    country_of_origin     VARCHAR(64),
+    shelf_life_days       INT,
+    storage               TEXT,
+    attributes            JSONB NOT NULL DEFAULT '{}',
+    quality_score         NUMERIC(4,3) NOT NULL DEFAULT 0,
+    status                VARCHAR(16) NOT NULL DEFAULT 'active',
+    canonical_id          UUID REFERENCES product(id),
+    search_tsv            TSVECTOR,
+    created_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CONSTRAINT product_status_chk CHECK (status IN ('active','merged','deprecated')),
+    CONSTRAINT product_quality_chk CHECK (quality_score >= 0 AND quality_score <= 1)
+);
+
+CREATE TABLE food_detail (
+    product_id       UUID PRIMARY KEY REFERENCES product(id) ON DELETE CASCADE,
+    ingredients_text TEXT,
+    ingredients      JSONB,
+    allergens        TEXT[] NOT NULL DEFAULT '{}',
+    additives        TEXT[] NOT NULL DEFAULT '{}',
+    nutriments       JSONB,
+    nutrition_basis  VARCHAR(16),
+    serving_size     VARCHAR(32),
+    nutri_score      CHAR(1),
+    labels           TEXT[] NOT NULL DEFAULT '{}',
+    CONSTRAINT food_basis_chk CHECK (nutrition_basis IS NULL OR nutrition_basis IN ('per_100g','per_100ml','per_serving'))
+);
+
+-- Official manufacturer-suggested retail price snapshot (no purchase link).
+CREATE TABLE product_msrp (
+    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    product_id     UUID NOT NULL REFERENCES product(id) ON DELETE CASCADE,
+    amount         NUMERIC(12,2) NOT NULL,
+    currency       CHAR(3) NOT NULL,
+    region         VARCHAR(8) NOT NULL DEFAULT 'CN',
+    source_id      UUID REFERENCES source(id),
+    source_url     TEXT,
+    effective_date DATE,
+    note           TEXT,
+    created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE product_image (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    product_id UUID NOT NULL REFERENCES product(id) ON DELETE CASCADE,
+    url        TEXT NOT NULL,
+    kind       VARCHAR(16) NOT NULL DEFAULT 'other',
+    license    TEXT,
+    source_id  UUID REFERENCES source(id),
+    CONSTRAINT image_kind_chk CHECK (kind IN ('front','ingredients','nutrition','other'))
+);
+
+-- Field-level provenance: which source provided which fields.
+CREATE TABLE product_source (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    product_id UUID NOT NULL REFERENCES product(id) ON DELETE CASCADE,
+    source_id  UUID REFERENCES source(id),
+    url        TEXT,
+    fields     TEXT[] NOT NULL DEFAULT '{}',
+    fetched_at TIMESTAMPTZ,
+    raw        JSONB
+);
+
+CREATE TABLE merge_log (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    kept_id    UUID,
+    merged_id  UUID,
+    reason     TEXT,
+    actor      TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Indexes
+CREATE UNIQUE INDEX idx_product_gtin ON product (gtin) WHERE gtin IS NOT NULL;
+CREATE INDEX idx_product_name_trgm ON product USING gin (name gin_trgm_ops);
+CREATE INDEX idx_product_attrs ON product USING gin (attributes);
+CREATE INDEX idx_product_tsv ON product USING gin (search_tsv);
+CREATE INDEX idx_product_category ON product (category_id);
+CREATE INDEX idx_product_brand ON product (brand_id);
+CREATE INDEX idx_product_updated ON product (updated_at);
+CREATE INDEX idx_food_nutriments ON food_detail USING gin (nutriments);
+CREATE INDEX idx_category_path ON category USING gist (path);
+CREATE INDEX idx_msrp_product ON product_msrp (product_id);
+CREATE INDEX idx_psource_product ON product_source (product_id);
+
+-- Keep search_tsv and updated_at in sync.
+CREATE OR REPLACE FUNCTION product_sync_tsv() RETURNS trigger AS $$
+BEGIN
+    NEW.search_tsv := to_tsvector('simple', coalesce(NEW.name, ''));
+    NEW.updated_at := now();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_product_sync
+    BEFORE INSERT OR UPDATE ON product
+    FOR EACH ROW EXECUTE FUNCTION product_sync_tsv();
@@ -0,0 +1,2 @@
+DELETE FROM attribute_definition;
+DELETE FROM unit;
@@ -0,0 +1,29 @@
+-- Unit dictionary seed. Keep factors aligned with ingestion/opengoods/units.py.
+
+INSERT INTO unit (code, dimension, canonical, to_canonical_factor, aliases, display) VALUES
+    ('mg',   'mass',     'g',   0.001,  ARRAY['毫克'],                 'mg'),
+    ('g',    'mass',     'g',   1,      ARRAY['克','gram','grams'],    'g'),
+    ('kg',   'mass',     'g',   1000,   ARRAY['kgs','千克','公斤'],     'kg'),
+    ('ml',   'volume',   'ml',  1,      ARRAY['毫升','milliliter'],     'mL'),
+    ('cl',   'volume',   'ml',  10,     ARRAY['厘升'],                 'cL'),
+    ('l',    'volume',   'ml',  1000,   ARRAY['L','升','litre','liter'], 'L'),
+    ('kj',   'energy',   'kJ',  1,      ARRAY['kJ','千焦'],            'kJ'),
+    ('kcal', 'energy',   'kJ',  4.184,  ARRAY['千卡','大卡'],          'kcal'),
+    ('pct',  'ratio',    'pct', 1,      ARRAY['%','percent','百分比'],  '%'),
+    ('unit', 'count',    'unit',1,      ARRAY['个','件','pcs','piece'], '个'),
+    ('mm',   'length',   'mm',  1,      ARRAY['毫米'],                 'mm'),
+    ('cm',   'length',   'mm',  10,     ARRAY['厘米'],                 'cm'),
+    ('day',  'duration', 'day', 1,      ARRAY['天','日','days'],        'day')
+ON CONFLICT (code) DO NOTHING;
+
+-- A few common food attribute definitions referencing the unit dictionary.
+INSERT INTO attribute_definition (key, label_zh, label_en, dimension, default_unit, aliases) VALUES
+    ('energy',        '能量',   'Energy',        'energy', 'kj',   ARRAY['energy_kj']),
+    ('proteins',      '蛋白质', 'Proteins',      'mass',   'g',    ARRAY['protein']),
+    ('fat',           '脂肪',   'Fat',           'mass',   'g',    ARRAY['fats']),
+    ('saturated_fat', '饱和脂肪','Saturated fat','mass',   'g',    ARRAY['saturated-fat']),
+    ('carbohydrates', '碳水化合物','Carbohydrates','mass', 'g',    ARRAY['carbs']),
+    ('sugars',        '糖',     'Sugars',        'mass',   'g',    ARRAY['sugar']),
+    ('salt',          '盐',     'Salt',          'mass',   'g',    ARRAY['sodium_salt']),
+    ('net_content',   '净含量', 'Net content',   NULL,     NULL,   ARRAY['quantity'])
+ON CONFLICT (key) DO NOTHING;
@@ -0,0 +1,3 @@
+-- remove seeded categories (children first via path depth)
+DELETE FROM category_schema;
+DELETE FROM category;
@@ -0,0 +1,53 @@
+-- Seed a FOOD-focused category skeleton.
+-- Structure = GS1 GPC backbone (segment/family/class) mapped to a self-built
+-- Chinese tree. ltree labels are english slugs (ltree forbids spaces/CJK);
+-- Chinese names live in name_zh. gpc_brick_code on leaves is a representative
+-- starter value to be replaced by a full official GPC import later.
+
+-- Root segment: Food/Beverage/Tobacco (GPC segment 50000000)
+INSERT INTO category (name_zh, name_en, parent_id, path, gpc_brick_code, level)
+VALUES ('食品饮料', 'Food/Beverage', NULL, 'food', '50000000', 0);
+
+-- Families (level 1)
+INSERT INTO category (name_zh, name_en, parent_id, path, gpc_brick_code, level)
+SELECT v.name_zh, v.name_en, c.id, v.path::ltree, v.code, 1
+FROM (VALUES
+    ('饮料',     'Beverages',        'food.beverages',  '50130000'),
+    ('乳制品蛋类','Dairy/Eggs',       'food.dairy',      '50180000'),
+    ('烘焙',     'Bakery',           'food.bakery',     '50100000'),
+    ('零食',     'Snacks',           'food.snacks',     '50190000'),
+    ('粮油',     'Staples/Oils',     'food.staple',     '50160000'),
+    ('调味品',   'Condiments',       'food.condiments', '50170000')
+) AS v(name_zh, name_en, path, code)
+JOIN category c ON c.path = 'food';
+
+-- Classes / leaves (level 2) with representative GPC brick codes
+INSERT INTO category (name_zh, name_en, parent_id, path, gpc_brick_code, level)
+SELECT v.name_zh, v.name_en, c.id, v.path::ltree, v.code, 2
+FROM (VALUES
+    ('包装饮用水', 'Bottled water',   'food.beverages.water',      '10000224', 'food.beverages'),
+    ('碳酸饮料',   'Carbonated',      'food.beverages.carbonated', '10000225', 'food.beverages'),
+    ('果汁',       'Juice',           'food.beverages.juice',      '10000226', 'food.beverages'),
+    ('牛奶',       'Milk',            'food.dairy.milk',           '10000158', 'food.dairy'),
+    ('酸奶',       'Yogurt',          'food.dairy.yogurt',         '10000159', 'food.dairy'),
+    ('奶酪',       'Cheese',          'food.dairy.cheese',         '10000160', 'food.dairy'),
+    ('面包',       'Bread',           'food.bakery.bread',         '10000040', 'food.bakery'),
+    ('饼干',       'Biscuits',        'food.bakery.biscuits',      '10000041', 'food.bakery'),
+    ('薯片膨化',   'Chips/Snacks',    'food.snacks.chips',         '10000310', 'food.snacks'),
+    ('巧克力',     'Chocolate',       'food.snacks.chocolate',     '10000311', 'food.snacks'),
+    ('大米',       'Rice',            'food.staple.rice',          '10000500', 'food.staple'),
+    ('面条',       'Noodles',         'food.staple.noodles',       '10000501', 'food.staple'),
+    ('食用油',     'Cooking oil',     'food.staple.cooking_oil',   '10000502', 'food.staple'),
+    ('酱油',       'Soy sauce',       'food.condiments.soy_sauce', '10000600', 'food.condiments'),
+    ('食盐',       'Table salt',      'food.condiments.salt',      '10000601', 'food.condiments')
+) AS v(name_zh, name_en, path, code, parent_path)
+JOIN category c ON c.path = v.parent_path::ltree;
+
+-- Parameter templates: leaf food categories use per_100g/ml nutrition basis.
+INSERT INTO category_schema (category_id, required_attributes, recommended_attributes, nutriment_basis)
+SELECT id,
+       ARRAY['net_content'],
+       ARRAY['energy','proteins','fat','carbohydrates','sugars','salt'],
+       CASE WHEN path <@ 'food.beverages' THEN 'per_100ml' ELSE 'per_100g' END
+FROM category
+WHERE level = 2;
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS ingest_state;
@@ -0,0 +1,10 @@
+-- M4 ingestion management: persistent per-source incremental watermark.
+-- The updater reads/writes one row per source to resume incremental imports
+-- (e.g. Open Food Facts `last_modified_t`) and to record run statistics.
+CREATE TABLE ingest_state (
+    source          TEXT PRIMARY KEY,
+    last_modified_t BIGINT NOT NULL DEFAULT 0,
+    last_run_at     TIMESTAMPTZ,
+    cursor          TEXT,
+    stats           JSONB NOT NULL DEFAULT '{}'
+);
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
novaalphastrikeomegaz663	69a0149bbe	feat(search+docs): trigram fuzzy search, brand/country filters, developer docs CI / Python (ingestion) (pull_request) Successful in 12s Details CI / Migrations (postgres) (pull_request) Successful in 22s Details CI / Go (api) (pull_request) Successful in 47s Details Search: - migration 0009: trigram GIN index on brand.name + btree on country_of_origin - SearchProducts: typo-tolerant word_similarity matching (>=0.42) on top of ILIKE substring + barcode; new brand/country filters; rank by similarity * (0.5 + quality_score). Response gains country_of_origin, quality_score and per-result relevance score. - public search UI: brand/country filter inputs; show country in results Docs: - serve embedded OpenAPI 3 spec at GET /api/v1/openapi.json (not rate limited) - ApiDocs page: auth + rate-limit section, updated search params/response - docs/api.md developer guide Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 09:38:27 +00:00
lixu	cf255e2380	Merge pull request 'feat(api): API Key + Redis 限流 + 用量统计 (M5a)' (#7 ) from devin/1781943842-m5a-api-key-ratelimit into main CI / Python (ingestion) (push) Successful in 11s Details CI / Migrations (postgres) (push) Successful in 23s Details CI / Go (api) (push) Successful in 48s Details	2026-06-20 16:27:13 +08:00
novaalphastrikeomegaz663	2820823b36	feat(api): API keys + Redis rate limiting + usage stats CI / Python (ingestion) (pull_request) Successful in 12s Details CI / Migrations (postgres) (pull_request) Successful in 24s Details CI / Go (api) (pull_request) Successful in 53s Details Add an optional API-key layer to the public read-only API. Keys grant higher per-minute rate limits and attribute usage; anonymous callers are still allowed at a lower IP-based budget. - migration 0008_api_key: api_key table (sha256 hash only, plaintext shown once) - apikey pkg: key generation + hashing - ratelimit pkg: Redis fixed-window limiter + per-key usage counters; fails open - public API middleware: X-API-Key / Bearer auth, X-RateLimit-* headers, 429+Retry-After - admin: issue/list/revoke keys + usage view (API + UI tab) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 08:24:07 +00:00
lixu	7d7a8f1baf	Merge pull request 'feat(ingestion): harden OFF ingestion for bulk seeding' (#6 ) from devin/1781938549-ingestion-resilience into main CI / Python (ingestion) (push) Successful in 11s Details CI / Migrations (postgres) (push) Successful in 22s Details CI / Go (api) (push) Successful in 36s Details	2026-06-20 15:54:07 +08:00
lixu	e34e007f28	Merge pull request 'feat(barcode): 多条码管理（迁移 + GTIN 校验 + 后台/公开 API + 后台 UI）' (#5 ) from devin/1781934649-multi-barcode into main CI / Python (ingestion) (push) Successful in 11s Details CI / Migrations (postgres) (push) Successful in 22s Details CI / Go (api) (push) Successful in 37s Details	2026-06-20 15:53:43 +08:00
novaalphastrikeomegaz663	5b9338175e	style(api): gofmt gtin_test.go CI / Python (ingestion) (pull_request) Successful in 8s Details CI / Migrations (postgres) (pull_request) Successful in 15s Details CI / Go (api) (pull_request) Successful in 31s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 07:33:10 +00:00
novaalphastrikeomegaz663	c090bcdc9b	style(ingest): ruff format country-seed tests CI / Python (ingestion) (pull_request) Successful in 9s Details CI / Migrations (postgres) (pull_request) Successful in 13s Details CI / Go (api) (pull_request) Successful in 29s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 07:32:30 +00:00
novaalphastrikeomegaz663	2255243081	feat(ingest): country-focused seeding (collect domestic CN products) CI / Python (ingestion) (pull_request) Failing after 6s Details CI / Migrations (postgres) (pull_request) Successful in 16s Details CI / Go (api) (pull_request) Failing after 11m35s Details Add a market-focused seeding path so the catalogue can be built from domestic products rather than the English-heavy global default: - adapter.fetch_by_country(country): OFF search filtered by countries_tags_en, sorted by unique_scans_n (most-scanned first), de-duplicated across pages since OFF popularity ordering is unstable. - is_cn_gs1(code): True for GS1-China company prefixes (690-699), i.e. genuinely domestic items vs. imports merely sold in China. - seed_off --country <slug> [--domestic-only] [--page-size/--max-pages]: e.g. 'seed_off --country china --domestic-only' loads only 69x barcodes. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 07:14:45 +00:00
novaalphastrikeomegaz663	98b5f1575d	feat(barcode): admin barcode CRUD endpoints + UI; show extra barcodes publicly CI / Python (ingestion) (pull_request) Successful in 10s Details CI / Go (api) (pull_request) Failing after 15s Details CI / Migrations (postgres) (pull_request) Failing after 11m35s Details Wire the multi-barcode store layer to HTTP and the operator console: - adminhandler: add POST /products/{id}/barcodes, DELETE /products/{id}/barcodes/{barcodeID}, and POST .../primary. A barcode owned by another product returns 409 with the conflicting product (gtin/product_id/product_name); an invalid GTIN returns 400. - admin-frontend: BarcodesCard on the product detail page lists all barcodes (primary starred), adds with type/pack-level/region, sets primary, and deletes; audit labels for the new actions. - public-frontend: product detail surfaces non-primary barcodes so a case/region code resolves and is visible to consumers. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 07:06:07 +00:00
novaalphastrikeomegaz663	044c870df7	feat(ingestion): harden OFF ingestion for bulk seeding CI / Go (api) (pull_request) Failing after 22s Details CI / Python (ingestion) (pull_request) Successful in 14s Details CI / Migrations (postgres) (pull_request) Failing after 18s Details - Add retry/backoff (429 + 5xx, Retry-After aware) to the OFF adapter so transient API errors no longer abort a run. - Clamp bounded text fields (serving_size, net_content_unit, country_of_origin) to their column widths in transform; long OFF values previously raised StringDataRightTruncation and rolled back the batch. - Load each record inside a savepoint (load_record_safe) so one malformed source record is skipped instead of aborting the whole import; jobs now report an errored count. - Tests for retry behaviour, serving_size clamping, and per-record isolation. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 06:55:56 +00:00
oyaegeli98668	1d5f775d33	feat(barcode): 多条码管理（后端+迁移+GTIN校验）WIP CI / Go (api) (pull_request) Failing after 18s Details CI / Python (ingestion) (pull_request) Successful in 7s Details CI / Migrations (postgres) (pull_request) Failing after 22s Details - 迁移 0007: 新增 product_barcode 表（一品多码），回填旧 product.gtin 为主码，全局唯一索引保证「一码一品」，每品至多一个主码 - internal/gtin: GS1 GTIN-8/12/13/14 校验（校验位 + 拒收店内码/变量重量码/优惠券码） - 公开只读 API: 任一条码命中商品、详情返回 barcodes、搜索匹配条码 - adminstore: 商品详情含 barcodes；新增 AddBarcode/DeleteBarcode/SetPrimaryBarcode，一码命中其他商品返回 ConflictError 供后台去重待办（按用户要求暂停）: 后台 handler 路由、投稿/审核多条码、前后端 UI Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 05:54:18 +00:00
lixu	88d5766e8e	Merge pull request 'feat(admin): 运营后台（登录/查看/编辑补全）+ 写入API + 审计留痕' (#4 ) from devin/1781923221-admin-console into main CI / Go (api) (push) Failing after 19s Details CI / Python (ingestion) (push) Successful in 8s Details CI / Migrations (postgres) (push) Failing after 16s Details	2026-06-20 13:42:09 +08:00
oyaegeli98668	5bfb2d3a5f	chore: 站名改为「天工商品档案公共仓」（公开站 + 后台标题/页头/页脚/API 文案） CI / Go (api) (pull_request) Failing after 15s Details CI / Python (ingestion) (pull_request) Successful in 7s Details CI / Migrations (postgres) (pull_request) Failing after 19s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 05:37:23 +00:00
oyaegeli98668	8909ddcb69	chore(public): 页脚添加 ICP 备案号鲁ICP备2025185218号-6 CI / Go (api) (pull_request) Failing after 20s Details CI / Python (ingestion) (pull_request) Successful in 8s Details CI / Migrations (postgres) (pull_request) Failing after 16s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 05:33:58 +00:00
oyaegeli98668	2d95052bd9	feat(public): 首页新增 API 调用说明页（只读端点/参数/示例/免责声明） CI / Python (ingestion) (pull_request) Successful in 6s Details CI / Go (api) (pull_request) Failing after 17s Details CI / Migrations (postgres) (pull_request) Failing after 20s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 05:26:53 +00:00
oyaegeli98668	c9a4404052	feat: 公开首页(搜索+商品详情) + 好心人投稿 + 后台审核收纳 CI / Go (api) (pull_request) Failing after 20s Details CI / Python (ingestion) (pull_request) Successful in 8s Details CI / Migrations (postgres) (pull_request) Failing after 17s Details - 公开前端 SPA（根路径 /）：首页大搜索框、检索结果、只读商品详情、贡献档案表单 - 公开写入端点 POST /api/public/submissions（无需登录，基础频率限流），投稿进入 submission 待审核队列，不直接写 product - 迁移 0006：submission 投稿表 + community 来源(trust=0.50) - 后台审核队列：列表(待审核/已通过/已驳回) → 查看投稿 → 通过(创建/补全商品 + 记 source=community + 字段级溯源 + 审计 + 重算质量分) / 驳回(记原因) - 公开只读 api 服务内嵌公开 SPA；Dockerfile.prod 增加 node 构建阶段 + 内嵌 dist Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 05:11:07 +00:00
oyaegeli98668	bad771e172	build(admin): npm 走 npmmirror 镜像以适配部署环境网络 CI / Go (api) (pull_request) Failing after 19s Details CI / Python (ingestion) (pull_request) Successful in 7s Details CI / Migrations (postgres) (pull_request) Failing after 21s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 02:54:32 +00:00
oyaegeli98668	d90a539e6b	feat(admin): 运营后台（登录/查看/审核编辑/补全）+ 写入API + 审计留痕 CI / Go (api) (pull_request) Failing after 18s Details CI / Python (ingestion) (pull_request) Successful in 7s Details CI / Migrations (postgres) (pull_request) Failing after 18s Details Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 02:53:30 +00:00
lixu	c272b2c5d7	Merge pull request 'chore(deploy): 生产 docker compose 部署配置' (#3 ) from devin/1781922421-prod-deploy into main CI / Go (api) (push) Failing after 20s Details CI / Python (ingestion) (push) Successful in 6s Details CI / Migrations (postgres) (push) Failing after 19s Details	2026-06-20 10:32:22 +08:00
oyaegeli98668	6777461268	chore(deploy): 生产 docker compose + scratch Dockerfile + 部署文档 CI / Go (api) (pull_request) Failing after 41s Details CI / Python (ingestion) (pull_request) Successful in 43s Details CI / Migrations (postgres) (pull_request) Failing after 17s Details - docker-compose.prod.yml：仅 api 绑 127.0.0.1:8120，DB/redis/minio 不暴露，restart=unless-stopped，凭据走 .env - api/Dockerfile.prod：runtime 改用 scratch + 拷贝 ca-certs（gcr.io/distroless 不可达环境），Go 模块走 goproxy.cn - .env.example / docs/deploy.md Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-20 02:27:09 +00:00
lixu	e3e5c7979c	ci: 修复 Gitea Actions 数据库连接（用服务名 postgres） (#2 ) CI / Go (api) (push) Successful in 6s Details CI / Python (ingestion) (push) Successful in 6s Details CI / Migrations (postgres) (push) Successful in 16s Details	2026-06-19 17:47:41 +08:00
rosemariejebbjtxbfp	19b7c43f37	ci: connect to postgres via service hostname for Gitea Actions CI / Go (api) (pull_request) Successful in 30s Details CI / Python (ingestion) (pull_request) Successful in 7s Details CI / Migrations (postgres) (pull_request) Successful in 16s Details Gitea Actions runs jobs inside a container, so a service container is reachable by its service name (postgres), not localhost; localhost:5432 yields connection refused. Also drop the unnecessary 5432:5432 host port mapping that caused 'port already allocated' collisions. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-19 08:54:18 +00:00
lixu	57537c880d	M4: ingestion management (#1 ) CI / Go (api) (push) Failing after 14s Details CI / Migrations (postgres) (push) Failing after 33s Details CI / Python (ingestion) (push) Failing after 13m10s Details Incremental OFF + GS1 supplement + dedup/conflict + quality scoring + scheduler	2026-06-08 17:40:26 +08:00
John Doe	a35bcd6647	M4: ingestion management (incremental, GS1 supplement, dedup/conflict, quality, scheduler) CI / Go (api) (pull_request) Has been cancelled Details CI / Python (ingestion) (pull_request) Has been cancelled Details CI / Migrations (postgres) (pull_request) Has been cancelled Details - OFF incremental fetch via search API + persistent watermark (ingest_state, migration 0004) - GS1 barcode supplement adapter (offline mapping + GS1-style API) filling only gaps with field-level provenance - Non-GTIN dedup with canonical selection + merge_log; field-level conflict resolution (source trust > recency) - Quality scoring (0.4 completeness + 0.3 source trust + 0.2 multi-source + 0.1 freshness) wired into load/merge - Jobs: update_off, dedup, schedule; docs/ingestion-management.md - 19 new tests (pure + DB-integration), ruff clean Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-08 09:27:42 +00:00
lixu	e750501b44	feat(M3): 只读 API 端点实现 CI / Go (api) (push) Has been cancelled Details CI / Python (ingestion) (push) Has been cancelled Details CI / Migrations (postgres) (push) Has been cancelled Details - store: pgx 只读数据访问层(productByGTIN/ByID/search/nutriments/msrp/brands/categories/source) - handler: 真实查询替换 501 占位, 统一分页 + 错误信封, MSRP 带免责声明无购买入口 - main: pgxpool 连接池接线 - search: 名称模糊 + 分类子树过滤(ltree <@) - 测试: healthz/pageParams 单测 + DB-backed handler 集成测试(无库自动跳过) - CI: Go job 增加 postgres service + migrate up, 实跑 DB 测试 - 依赖: pgx v5.7.2 (固定到兼容 go1.23 的版本) - 本地实跑: 8 个端点对真实 OFF 数据返回正确(barcode/search/nutriments/msrp/brands/categories/source/404) Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-08 07:14:18 +00:00
lixu	766a573989	feat(M2): Open Food Facts 采集导入 ETL - adapters/openfoodfacts.py: OFF API 适配器(限速+User-Agent) + JSONL/.gz dump 读取 - etl/transform.py: 纯函数转换(GTIN 校验/净含量解析+归一/营养 per_100g 双能量/过敏原添加剂清洗/关键词分类映射) - etl/load.py: psycopg upsert(product/food_detail/product_image) + product_source 字段级溯源 - jobs/seed_off.py: CLI(--barcodes API / --dump 文件 / --limit) - 测试: 13 个离线 transform 单测(fixture) + 可跳过的 DB 集成测试 - 依赖: 增加 psycopg[binary] - 实跑: 从 OFF API 拉 5 个真实条码入本地 postgres 验证通过 - docs/etl-openfoodfacts.md: 流程/运行/字段映射 Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-08 07:01:04 +00:00
lixu	b0b816b0ee	feat(M1): 数据模型迁移 + GS1 GPC 食品分类 + 单位字典 - migrations/0001_init: 全部核心表(product/food_detail/product_msrp/product_source/brand/manufacturer/category/category_schema/unit/attribute_definition/product_image/merge_log) + 索引(gtin唯一/name trigram/JSONB GIN/category ltree/tsvector) + tsvector/updated_at 触发器 - 0002_seed_units: 单位字典(与 units.py 一致, 含中文别名) + 常用营养参数定义 - 0003_seed_categories: 食品品类骨架(GS1 GPC 映射 + 自建中文树, ltree) + 品类参数模板(营养基准 per_100g/ml) - CI 增加 migrations job: 用 postgres service 跑 migrate up + down 验证可逆 - 本地实跑 up/down/re-up 全部通过 Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>	2026-06-08 06:32:16 +00:00