feat(admin): 商品编辑页增加上一个/下一个导航

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

admin-frontend/src/App.tsx

@@ -5,9 +5,20 @@ 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";
+import CategoriesPage from "./components/CategoriesPage";
+import BrandsPage from "./components/BrandsPage";
+import StatsPage from "./components/StatsPage";
+import AuditLogPage from "./components/AuditLogPage";
+import { BarChart3, FolderTree, Inbox, KeyRound, LogOut, Package, ScrollText, Tag } from "lucide-react";
 
-type Tab = "products" | "submissions" | "keys";
+type Tab =
+  | "overview"
+  | "products"
+  | "submissions"
+  | "categories"
+  | "brands"
+  | "audit"
+  | "keys";
 type View = { name: "list" } | { name: "detail"; id: string };
 
 export default function App() {
@@ -17,6 +28,7 @@ export default function App() {
   const [tab, setTab] = useState<Tab>("products");
   const [pending, setPending] = useState<number | null>(null);
   const [view, setView] = useState<View>({ name: "list" });
+  const [navIds, setNavIds] = useState<string[]>([]);
 
   useEffect(() => {
     if (!authed) return;
@@ -72,6 +84,16 @@ export default function App() {
             天工商品档案公共仓 · 后台
           </div>
           <nav className="flex items-center gap-1 text-sm">
+            <button
+              onClick={() => setTab("overview")}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "overview"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <BarChart3 className="h-4 w-4" /> 数据概览
+            </button>
             <button
               onClick={() => {
                 setTab("products");
@@ -100,6 +122,39 @@ export default function App() {
                 </span>
               )}
             </button>
+            <button
+              onClick={() => {
+                setTab("categories");
+                setView({ name: "list" });
+              }}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "categories"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <FolderTree className="h-4 w-4" /> 分类管理
+            </button>
+            <button
+              onClick={() => setTab("brands")}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "brands"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <Tag className="h-4 w-4" /> 品牌管理
+            </button>
+            <button
+              onClick={() => setTab("audit")}
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                tab === "audit"
+                  ? "bg-emerald-50 text-emerald-700"
+                  : "text-gray-600 hover:bg-gray-100"
+              }`}
+            >
+              <ScrollText className="h-4 w-4" /> 操作日志
+            </button>
             <button
               onClick={() => setTab("keys")}
               className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
@@ -123,14 +178,32 @@ export default function App() {
         </div>
       </header>
       <main className="flex-1 overflow-auto p-6">
-        {tab === "keys" ? (
+        {tab === "overview" ? (
+          <StatsPage />
+        ) : tab === "audit" ? (
+          <AuditLogPage />
+        ) : tab === "keys" ? (
           <ApiKeysPage />
+        ) : tab === "categories" ? (
+          <CategoriesPage />
+        ) : tab === "brands" ? (
+          <BrandsPage />
         ) : tab === "submissions" ? (
           <SubmissionsPage onPending={setPending} />
         ) : view.name === "list" ? (
-          <ProductList onOpen={(id) => setView({ name: "detail", id })} />
+          <ProductList
+            onOpen={(id, ids) => {
+              setNavIds(ids);
+              setView({ name: "detail", id });
+            }}
+          />
         ) : (
-          <ProductDetail id={view.id} onBack={() => setView({ name: "list" })} />
+          <ProductDetail
+            id={view.id}
+            ids={navIds}
+            onNavigate={(id) => setView({ name: "detail", id })}
+            onBack={() => setView({ name: "list" })}
+          />
         )}
       </main>
     </div>

admin-frontend/src/api.ts

@@ -61,6 +61,11 @@ export const api = {
     }>(`/products?q=${encodeURIComponent(q)}&page=${page}&size=${size}`),
   getProduct: (id: string) =>
     request<import("./types").ProductDetail>(`/products/${id}`),
+  createProduct: (body: unknown) =>
+    request<import("./types").ProductDetail>("/products", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
   updateProduct: (id: string, body: unknown) =>
     request<import("./types").ProductDetail>(`/products/${id}`, {
       method: "PUT",
@@ -102,8 +107,37 @@ export const api = {
     ),
   listBrands: () =>
     request<{ items: import("./types").Brand[] }>("/brands"),
+  createBrand: (name: string) =>
+    request<import("./types").Brand>("/brands", {
+      method: "POST",
+      body: JSON.stringify({ name }),
+    }),
+  updateBrand: (id: string, name: string) =>
+    request<import("./types").Brand>(`/brands/${id}`, {
+      method: "PUT",
+      body: JSON.stringify({ name }),
+    }),
+  mergeBrands: (id: string, targetId: string) =>
+    request<import("./types").Brand>(`/brands/${id}/merge`, {
+      method: "POST",
+      body: JSON.stringify({ target_id: targetId }),
+    }),
+  deleteBrand: (id: string) =>
+    request<{ status: string }>(`/brands/${id}`, { method: "DELETE" }),
   listCategories: () =>
     request<{ items: import("./types").Category[] }>("/categories"),
+  createCategory: (body: import("./types").CategoryInput) =>
+    request<import("./types").Category>("/categories", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  updateCategory: (id: string, body: import("./types").CategoryInput) =>
+    request<import("./types").Category>(`/categories/${id}`, {
+      method: "PUT",
+      body: JSON.stringify(body),
+    }),
+  deleteCategory: (id: string) =>
+    request<{ status: string }>(`/categories/${id}`, { method: "DELETE" }),
   listSubmissions: (status: string, page: number, size: number) =>
     request<{
       items: import("./types").SubmissionRow[];
@@ -137,4 +171,22 @@ export const api = {
     ),
   revokeApiKey: (id: string) =>
     request<{ status: string }>(`/keys/${id}`, { method: "DELETE" }),
+  stats: () => request<import("./types").AdminStats>("/stats"),
+  auditLog: (page: number, size: number) =>
+    request<{
+      items: import("./types").AuditLogRow[];
+      page: number;
+      size: number;
+      total: number;
+    }>(`/audit?page=${page}&size=${size}`),
+  bulkProducts: (body: {
+    ids: string[];
+    action: "status" | "category";
+    status?: string;
+    category_id?: string | null;
+  }) =>
+    request<{ status: string; affected: number }>("/products/bulk", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
 };

admin-frontend/src/components/ApiKeysPage.tsx

@@ -44,7 +44,7 @@ export default function ApiKeysPage() {
   }
 
   return (
-    <div className="max-w-4xl">
+    <div className="mx-auto 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">

admin-frontend/src/components/AuditLogPage.tsx

@@ -0,0 +1,115 @@
+import { useEffect, useState } from "react";
+import { api, ApiError } from "../api";
+import type { AuditLogRow } from "../types";
+import { ScrollText } from "lucide-react";
+
+const ACTION_LABEL: Record<string, string> = {
+  create: "新建",
+  update: "修改",
+  delete: "删除",
+  add_image: "添加图片",
+  delete_image: "删除图片",
+  bulk_status: "批量改状态",
+  bulk_category: "批量改分类",
+};
+
+const ENTITY_LABEL: Record<string, string> = {
+  product: "商品",
+  category: "分类",
+  brand: "品牌",
+};
+
+export default function AuditLogPage() {
+  const [rows, setRows] = useState<AuditLogRow[]>([]);
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const size = 30;
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    setError("");
+    api
+      .auditLog(page, size)
+      .then((r) => {
+        setRows(r.items);
+        setTotal(r.total);
+      })
+      .catch((e) => setError(e instanceof ApiError ? e.message : "加载失败"));
+  }, [page]);
+
+  const pages = Math.max(1, Math.ceil(total / size));
+
+  return (
+    <div className="mx-auto max-w-5xl">
+      <h2 className="mb-4 flex items-center gap-2 text-lg font-semibold text-gray-800">
+        <ScrollText className="h-5 w-5 text-emerald-600" /> 操作日志
+        <span className="text-sm font-normal text-gray-400">共 {total} 条</span>
+      </h2>
+
+      {error && (
+        <div className="mb-3 rounded bg-red-50 px-4 py-2 text-sm text-red-700">{error}</div>
+      )}
+
+      <div className="overflow-hidden rounded-lg border 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-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={5} className="px-4 py-8 text-center text-gray-400">
+                  暂无记录
+                </td>
+              </tr>
+            ) : (
+              rows.map((e) => (
+                <tr key={e.id} className="hover:bg-gray-50">
+                  <td className="whitespace-nowrap px-4 py-2 text-gray-500">
+                    {new Date(e.created_at).toLocaleString()}
+                  </td>
+                  <td className="px-4 py-2 text-gray-700">{e.actor}</td>
+                  <td className="px-4 py-2 text-gray-700">
+                    {ACTION_LABEL[e.action] || e.action}
+                  </td>
+                  <td className="px-4 py-2 text-gray-600">
+                    {ENTITY_LABEL[e.entity] || e.entity}
+                  </td>
+                  <td className="px-4 py-2 text-xs text-gray-400">
+                    {e.fields.length ? e.fields.join(", ") : "—"}
+                  </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>
+  );
+}

admin-frontend/src/components/BrandsPage.tsx

@@ -0,0 +1,305 @@
+import { useEffect, useMemo, useState } from "react";
+import { api, ApiError } from "../api";
+import type { Brand } from "../types";
+import { Tag, Pencil, Plus, Trash2, GitMerge, Search } from "lucide-react";
+
+type EditState = { id: string; name: string };
+type MergeState = { source: Brand; targetId: string };
+
+export default function BrandsPage() {
+  const [rows, setRows] = useState<Brand[]>([]);
+  const [error, setError] = useState("");
+  const [query, setQuery] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [newName, setNewName] = useState("");
+  const [edit, setEdit] = useState<EditState | null>(null);
+  const [merge, setMerge] = useState<MergeState | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function load() {
+    setError("");
+    try {
+      const res = await api.listBrands();
+      setRows(res.items);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "加载失败");
+    }
+  }
+
+  useEffect(() => {
+    load();
+  }, []);
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return rows;
+    return rows.filter((b) => b.name.toLowerCase().includes(q));
+  }, [rows, query]);
+
+  function fail(e: unknown, fallback: string) {
+    setError(e instanceof ApiError ? e.message : fallback);
+  }
+
+  async function create() {
+    if (!newName.trim()) return;
+    setBusy(true);
+    setError("");
+    try {
+      await api.createBrand(newName.trim());
+      setNewName("");
+      setCreating(false);
+      await load();
+    } catch (e) {
+      fail(e, "新建失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function saveEdit() {
+    if (!edit || !edit.name.trim()) return;
+    setBusy(true);
+    setError("");
+    try {
+      await api.updateBrand(edit.id, edit.name.trim());
+      setEdit(null);
+      await load();
+    } catch (e) {
+      fail(e, "保存失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function remove(b: Brand) {
+    if (!confirm(`确认删除品牌「${b.name}」？`)) return;
+    setError("");
+    try {
+      await api.deleteBrand(b.id);
+      await load();
+    } catch (e) {
+      fail(e, "删除失败");
+    }
+  }
+
+  async function doMerge() {
+    if (!merge || !merge.targetId) return;
+    const target = rows.find((b) => b.id === merge.targetId);
+    if (
+      !confirm(
+        `将「${merge.source.name}」的 ${merge.source.product_count} 个商品并入「${target?.name}」，并删除「${merge.source.name}」？`,
+      )
+    )
+      return;
+    setBusy(true);
+    setError("");
+    try {
+      await api.mergeBrands(merge.source.id, merge.targetId);
+      setMerge(null);
+      await load();
+    } catch (e) {
+      fail(e, "合并失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="mx-auto 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">
+            <Tag className="h-5 w-5 text-emerald-600" /> 品牌管理
+          </h2>
+          <p className="text-sm text-gray-500 mt-1">
+            维护品牌名录。可重命名、删除未被引用的品牌，或将重复品牌合并到一起。
+          </p>
+        </div>
+        <button
+          onClick={() => {
+            setCreating(true);
+            setNewName("");
+          }}
+          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>
+      )}
+
+      <div className="mb-3 relative w-72">
+        <Search className="absolute left-2 top-2.5 h-4 w-4 text-gray-400" />
+        <input
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="筛选品牌名"
+          className="w-full rounded border border-gray-300 py-2 pl-8 pr-3 text-sm focus:border-emerald-500 focus:outline-none"
+        />
+      </div>
+
+      {creating && (
+        <div className="mb-4 bg-white border rounded-lg p-5">
+          <h3 className="font-medium text-gray-700 mb-3">新建品牌</h3>
+          <div className="flex items-end gap-2">
+            <label className="block flex-1">
+              <span className="text-xs text-gray-500">品牌名称 *</span>
+              <input
+                autoFocus
+                className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+                value={newName}
+                onChange={(e) => setNewName(e.target.value)}
+                onKeyDown={(e) => e.key === "Enter" && create()}
+                placeholder="例如：可口可乐"
+              />
+            </label>
+            <button
+              onClick={create}
+              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={() => setCreating(false)}
+              className="px-4 py-2 rounded border text-sm text-gray-600"
+            >
+              取消
+            </button>
+          </div>
+        </div>
+      )}
+
+      {merge && (
+        <div className="mb-4 bg-white border rounded-lg p-5">
+          <h3 className="font-medium text-gray-700 mb-3 flex items-center gap-1.5">
+            <GitMerge className="h-4 w-4 text-emerald-600" /> 合并品牌
+          </h3>
+          <p className="text-sm text-gray-500 mb-3">
+            把「{merge.source.name}」（{merge.source.product_count} 个商品）合并到下面选择的品牌，源品牌将被删除。
+          </p>
+          <div className="flex items-end gap-2">
+            <label className="block flex-1">
+              <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={merge.targetId}
+                onChange={(e) => setMerge({ ...merge, targetId: e.target.value })}
+              >
+                <option value="">（请选择目标品牌）</option>
+                {rows
+                  .filter((b) => b.id !== merge.source.id)
+                  .map((b) => (
+                    <option key={b.id} value={b.id}>
+                      {b.name}（{b.product_count}）
+                    </option>
+                  ))}
+              </select>
+            </label>
+            <button
+              onClick={doMerge}
+              disabled={busy || !merge.targetId}
+              className="px-4 py-2 rounded bg-emerald-600 text-white text-sm hover:bg-emerald-700 disabled:opacity-60"
+            >
+              合并
+            </button>
+            <button
+              onClick={() => setMerge(null)}
+              className="px-4 py-2 rounded border text-sm text-gray-600"
+            >
+              取消
+            </button>
+          </div>
+        </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>
+            </tr>
+          </thead>
+          <tbody className="divide-y">
+            {filtered.length === 0 ? (
+              <tr>
+                <td colSpan={3} className="px-4 py-8 text-center text-gray-400">
+                  {rows.length === 0 ? "暂无品牌" : "无匹配品牌"}
+                </td>
+              </tr>
+            ) : (
+              filtered.map((b) => (
+                <tr key={b.id} className="hover:bg-gray-50">
+                  <td className="px-4 py-2 text-gray-800">
+                    {edit && edit.id === b.id ? (
+                      <input
+                        autoFocus
+                        className="border rounded px-2 py-1 text-sm w-64"
+                        value={edit.name}
+                        onChange={(e) => setEdit({ ...edit, name: e.target.value })}
+                        onKeyDown={(e) => {
+                          if (e.key === "Enter") saveEdit();
+                          if (e.key === "Escape") setEdit(null);
+                        }}
+                      />
+                    ) : (
+                      <span className="font-medium">{b.name}</span>
+                    )}
+                  </td>
+                  <td className="px-4 py-2 text-gray-600">{b.product_count}</td>
+                  <td className="px-4 py-2 text-right whitespace-nowrap">
+                    {edit && edit.id === b.id ? (
+                      <>
+                        <button
+                          onClick={saveEdit}
+                          disabled={busy}
+                          className="text-emerald-600 hover:text-emerald-700 text-xs mr-3"
+                        >
+                          保存
+                        </button>
+                        <button
+                          onClick={() => setEdit(null)}
+                          className="text-gray-400 hover:text-gray-600 text-xs"
+                        >
+                          取消
+                        </button>
+                      </>
+                    ) : (
+                      <>
+                        <button
+                          onClick={() => setEdit({ id: b.id, name: b.name })}
+                          className="text-gray-400 hover:text-emerald-600 mr-3"
+                          title="重命名"
+                        >
+                          <Pencil className="h-4 w-4" />
+                        </button>
+                        <button
+                          onClick={() => setMerge({ source: b, targetId: "" })}
+                          className="text-gray-400 hover:text-emerald-600 mr-3"
+                          title="合并到其它品牌"
+                        >
+                          <GitMerge className="h-4 w-4" />
+                        </button>
+                        <button
+                          onClick={() => remove(b)}
+                          className="text-gray-400 hover:text-red-600"
+                          title="删除"
+                        >
+                          <Trash2 className="h-4 w-4" />
+                        </button>
+                      </>
+                    )}
+                  </td>
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

admin-frontend/src/components/CategoriesPage.tsx

@@ -0,0 +1,311 @@
+import { useEffect, useMemo, useState } from "react";
+import { api, ApiError } from "../api";
+import type { Category, CategoryInput } from "../types";
+import { FolderTree, Pencil, Plus, Trash2 } from "lucide-react";
+
+type FormState = {
+  mode: "create" | "edit";
+  id?: string;
+  name_zh: string;
+  name_en: string;
+  slug: string;
+  parent_id: string; // "" = top level
+  gpc_brick_code: string;
+};
+
+function emptyForm(parentId = ""): FormState {
+  return {
+    mode: "create",
+    name_zh: "",
+    name_en: "",
+    slug: "",
+    parent_id: parentId,
+    gpc_brick_code: "",
+  };
+}
+
+export default function CategoriesPage() {
+  const [rows, setRows] = useState<Category[]>([]);
+  const [error, setError] = useState("");
+  const [form, setForm] = useState<FormState | null>(null);
+
+  async function load() {
+    setError("");
+    try {
+      const res = await api.listCategories();
+      setRows(res.items);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "加载失败");
+    }
+  }
+
+  useEffect(() => {
+    load();
+  }, []);
+
+  async function remove(c: Category) {
+    if (!confirm(`确认删除分类「${c.name_zh}」(${c.path})？`)) return;
+    setError("");
+    try {
+      await api.deleteCategory(c.id);
+      await load();
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "删除失败");
+    }
+  }
+
+  return (
+    <div className="mx-auto max-w-5xl">
+      <div className="flex items-center justify-between mb-4">
+        <div>
+          <h2 className="text-lg font-semibold text-gray-800 flex items-center gap-2">
+            <FolderTree className="h-5 w-5 text-emerald-600" /> 分类管理
+          </h2>
+          <p className="text-sm text-gray-500 mt-1">
+            维护商品分类树。英文标识(slug)用于分类路径，新建后不可修改；可重命名、移动层级、删除空分类。
+          </p>
+        </div>
+        <button
+          onClick={() => setForm(emptyForm())}
+          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>
+      )}
+
+      {form && (
+        <CategoryForm
+          form={form}
+          categories={rows}
+          onClose={() => setForm(null)}
+          onSaved={() => {
+            setForm(null);
+            load();
+          }}
+          onError={setError}
+        />
+      )}
+
+      <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">GPC</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={5} className="px-4 py-8 text-center text-gray-400">
+                  暂无分类
+                </td>
+              </tr>
+            ) : (
+              rows.map((c) => (
+                <tr key={c.id} className="hover:bg-gray-50">
+                  <td className="px-4 py-2 text-gray-800">
+                    <span style={{ paddingLeft: `${c.level * 18}px` }} className="inline-flex items-center gap-2">
+                      {c.level > 0 && <span className="text-gray-300">└</span>}
+                      <span className="font-medium">{c.name_zh}</span>
+                      {c.name_en && <span className="text-xs text-gray-400">{c.name_en}</span>}
+                    </span>
+                  </td>
+                  <td className="px-4 py-2 text-gray-500">
+                    <code className="text-xs">{c.path}</code>
+                  </td>
+                  <td className="px-4 py-2 text-gray-500 text-xs">{c.gpc_brick_code || "—"}</td>
+                  <td className="px-4 py-2 text-gray-600">{c.product_count}</td>
+                  <td className="px-4 py-2 text-right whitespace-nowrap">
+                    <button
+                      onClick={() => setForm(emptyForm(c.id))}
+                      className="text-gray-400 hover:text-emerald-600 mr-3"
+                      title="新增子分类"
+                    >
+                      <Plus className="h-4 w-4" />
+                    </button>
+                    <button
+                      onClick={() =>
+                        setForm({
+                          mode: "edit",
+                          id: c.id,
+                          name_zh: c.name_zh,
+                          name_en: c.name_en ?? "",
+                          slug: c.path,
+                          parent_id: c.parent_id ?? "",
+                          gpc_brick_code: c.gpc_brick_code ?? "",
+                        })
+                      }
+                      className="text-gray-400 hover:text-emerald-600 mr-3"
+                      title="编辑"
+                    >
+                      <Pencil className="h-4 w-4" />
+                    </button>
+                    <button
+                      onClick={() => remove(c)}
+                      className="text-gray-400 hover:text-red-600"
+                      title="删除"
+                    >
+                      <Trash2 className="h-4 w-4" />
+                    </button>
+                  </td>
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}
+
+function CategoryForm({
+  form,
+  categories,
+  onClose,
+  onSaved,
+  onError,
+}: {
+  form: FormState;
+  categories: Category[];
+  onClose: () => void;
+  onSaved: () => void;
+  onError: (msg: string) => void;
+}) {
+  const [state, setState] = useState<FormState>(form);
+  const [busy, setBusy] = useState(false);
+
+  // When editing, the node itself and its descendants are not valid parents.
+  const parentOptions = useMemo(() => {
+    if (state.mode === "create") return categories;
+    const self = categories.find((c) => c.id === state.id);
+    if (!self) return categories;
+    return categories.filter(
+      (c) => c.id !== self.id && !c.path.startsWith(self.path + "."),
+    );
+  }, [categories, state.mode, state.id]);
+
+  function set<K extends keyof FormState>(key: K, value: FormState[K]) {
+    setState((s) => ({ ...s, [key]: value }));
+  }
+
+  async function submit() {
+    if (!state.name_zh.trim()) {
+      onError("分类名称不能为空");
+      return;
+    }
+    setBusy(true);
+    onError("");
+    const body: CategoryInput = {
+      name_zh: state.name_zh.trim(),
+      name_en: state.name_en.trim() || null,
+      parent_id: state.parent_id || null,
+      gpc_brick_code: state.gpc_brick_code.trim() || null,
+    };
+    if (state.mode === "create") body.slug = state.slug.trim() || null;
+    try {
+      if (state.mode === "create") {
+        await api.createCategory(body);
+      } else if (state.id) {
+        await api.updateCategory(state.id, body);
+      }
+      onSaved();
+    } catch (e) {
+      onError(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">
+        {state.mode === "create" ? "新建分类" : "编辑分类"}
+      </h3>
+      <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={state.name_zh}
+            onChange={(e) => set("name_zh", e.target.value)}
+            placeholder="例如：饮料"
+          />
+        </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={state.name_en}
+            onChange={(e) => set("name_en", e.target.value)}
+            placeholder="Beverages"
+          />
+        </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={state.parent_id}
+            onChange={(e) => set("parent_id", e.target.value)}
+          >
+            <option value="">（顶级分类）</option>
+            {parentOptions.map((c) => (
+              <option key={c.id} value={c.id}>
+                {"\u00A0".repeat(c.level * 2)}
+                {c.name_zh} ({c.path})
+              </option>
+            ))}
+          </select>
+        </label>
+        {state.mode === "create" ? (
+          <label className="block">
+            <span className="text-xs text-gray-500">英文标识 slug（可选，留空自动生成）</span>
+            <input
+              className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+              value={state.slug}
+              onChange={(e) => set("slug", e.target.value)}
+              placeholder="beverages"
+            />
+          </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 bg-gray-50 text-gray-400"
+              value={state.slug}
+              disabled
+            />
+          </label>
+        )}
+        <label className="block">
+          <span className="text-xs text-gray-500">GPC Brick 编码（可选）</span>
+          <input
+            className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+            value={state.gpc_brick_code}
+            onChange={(e) => set("gpc_brick_code", e.target.value)}
+            placeholder="10000224"
+          />
+        </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>
+  );
+}

admin-frontend/src/components/ProductDetail.tsx

@@ -9,6 +9,8 @@ import {
 } from "../types";
 import {
   ArrowLeft,
+  ChevronLeft,
+  ChevronRight,
   Plus,
   Save,
   Trash2,
@@ -88,10 +90,18 @@ const inputCls =
 export default function ProductDetail({
   id,
   onBack,
+  ids = [],
+  onNavigate,
 }: {
   id: string;
   onBack: () => void;
+  ids?: string[];
+  onNavigate?: (id: string) => void;
 }) {
+  const navIndex = ids.indexOf(id);
+  const prevId = navIndex > 0 ? ids[navIndex - 1] : null;
+  const nextId =
+    navIndex >= 0 && navIndex < ids.length - 1 ? ids[navIndex + 1] : null;
   const [d, setD] = useState<Detail | null>(null);
   const [brands, setBrands] = useState<Brand[]>([]);
   const [categories, setCategories] = useState<Category[]>([]);
@@ -226,12 +236,35 @@ export default function ProductDetail({
   return (
     <div className="mx-auto max-w-5xl space-y-5">
       <div className="flex items-center justify-between">
-        <button
+        <div className="flex items-center gap-2">
-          onClick={onBack}
+          <button
-          className="flex items-center gap-1 text-sm text-gray-600 hover:text-gray-900"
+            onClick={onBack}
-        >
+            className="flex items-center gap-1 text-sm text-gray-600 hover:text-gray-900"
-          <ArrowLeft className="h-4 w-4" /> 返回列表
+          >
-        </button>
+            <ArrowLeft className="h-4 w-4" /> 返回列表
+          </button>
+          {ids.length > 1 && navIndex >= 0 && (
+            <div className="ml-2 flex items-center gap-1 text-sm">
+              <button
+                onClick={() => prevId && onNavigate?.(prevId)}
+                disabled={!prevId}
+                className="flex items-center gap-1 rounded border border-gray-300 px-2 py-1 text-gray-600 hover:bg-gray-50 disabled:opacity-40"
+              >
+                <ChevronLeft className="h-4 w-4" /> 上一个
+              </button>
+              <span className="text-xs text-gray-400">
+                {navIndex + 1} / {ids.length}
+              </span>
+              <button
+                onClick={() => nextId && onNavigate?.(nextId)}
+                disabled={!nextId}
+                className="flex items-center gap-1 rounded border border-gray-300 px-2 py-1 text-gray-600 hover:bg-gray-50 disabled:opacity-40"
+              >
+                下一个 <ChevronRight className="h-4 w-4" />
+              </button>
+            </div>
+          )}
+        </div>
         <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>}

admin-frontend/src/components/ProductList.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react";
-import { api } from "../api";
+import { api, ApiError } from "../api";
-import { FIELD_LABELS, ProductRow } from "../types";
+import { Brand, Category, FIELD_LABELS, ProductRow } from "../types";
-import { Search, AlertCircle } from "lucide-react";
+import { Search, AlertCircle, Plus } from "lucide-react";
 
 const STATUS_LABEL: Record<string, string> = {
   active: "在用",
@@ -27,18 +27,25 @@ function QualityBadge({ score }: { score: number }) {
 export default function ProductList({
   onOpen,
 }: {
-  onOpen: (id: string) => void;
+  onOpen: (id: string, ids: string[]) => void;
 }) {
   const [q, setQ] = useState("");
   const [input, setInput] = useState("");
   const [page, setPage] = useState(1);
-  const [size] = useState(20);
+  const [size, setSize] = useState(20);
+  const [jump, setJump] = useState("");
   const [rows, setRows] = useState<ProductRow[]>([]);
   const [total, setTotal] = useState(0);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [categories, setCategories] = useState<Category[]>([]);
+  const [bulkStatus, setBulkStatus] = useState("");
+  const [bulkCategory, setBulkCategory] = useState("");
+  const [bulkBusy, setBulkBusy] = useState(false);
 
-  useEffect(() => {
+  function reload() {
     setLoading(true);
     setError("");
     api
@@ -49,8 +56,72 @@ export default function ProductList({
       })
       .catch((e) => setError(e.message))
       .finally(() => setLoading(false));
+  }
+
+  useEffect(() => {
+    setSelected(new Set());
+    reload();
   }, [q, page, size]);
 
+  useEffect(() => {
+    api.listCategories().then((r) => setCategories(r.items)).catch(() => {});
+  }, []);
+
+  function toggle(id: string) {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }
+
+  function toggleAll() {
+    setSelected((prev) =>
+      prev.size === rows.length ? new Set() : new Set(rows.map((r) => r.id)),
+    );
+  }
+
+  async function applyBulkStatus() {
+    if (!bulkStatus || selected.size === 0) return;
+    setBulkBusy(true);
+    setError("");
+    try {
+      await api.bulkProducts({
+        ids: [...selected],
+        action: "status",
+        status: bulkStatus,
+      });
+      setSelected(new Set());
+      setBulkStatus("");
+      reload();
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "批量操作失败");
+    } finally {
+      setBulkBusy(false);
+    }
+  }
+
+  async function applyBulkCategory() {
+    if (selected.size === 0) return;
+    setBulkBusy(true);
+    setError("");
+    try {
+      await api.bulkProducts({
+        ids: [...selected],
+        action: "category",
+        category_id: bulkCategory || null,
+      });
+      setSelected(new Set());
+      setBulkCategory("");
+      reload();
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "批量操作失败");
+    } finally {
+      setBulkBusy(false);
+    }
+  }
+
   const pages = Math.max(1, Math.ceil(total / size));
 
   return (
@@ -79,19 +150,101 @@ export default function ProductList({
           <button className="rounded bg-emerald-600 px-3 py-2 text-sm text-white hover:bg-emerald-700">
             搜索
           </button>
+          <button
+            type="button"
+            onClick={() => setCreating(true)}
+            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>
         </form>
       </div>
 
+      {creating && (
+        <CreateProductModal
+          onClose={() => setCreating(false)}
+          onCreated={(id) => {
+            setCreating(false);
+            onOpen(id, [id]);
+          }}
+        />
+      )}
+
       {error && (
         <div className="mb-3 rounded bg-red-50 px-3 py-2 text-sm text-red-600">
           {error}
         </div>
       )}
 
+      {selected.size > 0 && (
+        <div className="mb-3 flex flex-wrap items-center gap-3 rounded-lg border border-emerald-200 bg-emerald-50 px-4 py-3 text-sm">
+          <span className="font-medium text-emerald-800">
+            已选 {selected.size} 项
+          </span>
+          <div className="flex items-center gap-1.5">
+            <span className="text-gray-500">改状态</span>
+            <select
+              value={bulkStatus}
+              onChange={(e) => setBulkStatus(e.target.value)}
+              className="rounded border border-gray-300 bg-white px-2 py-1"
+            >
+              <option value="">选择</option>
+              <option value="active">在用</option>
+              <option value="deprecated">已停用</option>
+              <option value="merged">已合并</option>
+            </select>
+            <button
+              onClick={applyBulkStatus}
+              disabled={bulkBusy || !bulkStatus}
+              className="rounded bg-emerald-600 px-3 py-1 text-white hover:bg-emerald-700 disabled:opacity-50"
+            >
+              应用
+            </button>
+          </div>
+          <div className="flex items-center gap-1.5">
+            <span className="text-gray-500">改分类</span>
+            <select
+              value={bulkCategory}
+              onChange={(e) => setBulkCategory(e.target.value)}
+              className="rounded border border-gray-300 bg-white px-2 py-1"
+            >
+              <option value="">（未分类）</option>
+              {categories.map((c) => (
+                <option key={c.id} value={c.id}>
+                  {"\u00A0".repeat(c.level * 2)}
+                  {c.name_zh}
+                </option>
+              ))}
+            </select>
+            <button
+              onClick={applyBulkCategory}
+              disabled={bulkBusy}
+              className="rounded bg-emerald-600 px-3 py-1 text-white hover:bg-emerald-700 disabled:opacity-50"
+            >
+              应用
+            </button>
+          </div>
+          <button
+            onClick={() => setSelected(new Set())}
+            className="text-gray-500 hover:text-gray-700"
+          >
+            取消选择
+          </button>
+        </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="w-10 px-4 py-3">
+                <input
+                  type="checkbox"
+                  checked={rows.length > 0 && selected.size === rows.length}
+                  onChange={toggleAll}
+                  aria-label="全选"
+                />
+              </th>
               <th className="px-4 py-3">名称</th>
               <th className="px-4 py-3">品牌</th>
               <th className="px-4 py-3">条码</th>
@@ -104,13 +257,13 @@ export default function ProductList({
           <tbody className="divide-y divide-gray-100">
             {loading ? (
               <tr>
-                <td colSpan={7} className="px-4 py-8 text-center text-gray-400">
+                <td colSpan={8} 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 colSpan={8} className="px-4 py-8 text-center text-gray-400">
                   暂无数据
                 </td>
               </tr>
@@ -118,9 +271,22 @@ export default function ProductList({
               rows.map((r) => (
                 <tr
                   key={r.id}
-                  onClick={() => onOpen(r.id)}
+                  onClick={() => onOpen(r.id, rows.map((x) => x.id))}
-                  className="cursor-pointer hover:bg-emerald-50/50"
+                  className={`cursor-pointer hover:bg-emerald-50/50 ${
+                    selected.has(r.id) ? "bg-emerald-50/60" : ""
+                  }`}
                 >
+                  <td
+                    className="px-4 py-3"
+                    onClick={(e) => e.stopPropagation()}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={selected.has(r.id)}
+                      onChange={() => toggle(r.id)}
+                      aria-label="选择"
+                    />
+                  </td>
                   <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">
@@ -154,7 +320,25 @@ export default function ProductList({
         </table>
       </div>
 
-      <div className="mt-4 flex items-center justify-end gap-2 text-sm text-gray-600">
+      <div className="mt-4 flex flex-wrap items-center justify-end gap-2 text-sm text-gray-600">
+        <div className="mr-auto flex items-center gap-1">
+          <span>每页</span>
+          <select
+            value={size}
+            onChange={(e) => {
+              setSize(Number(e.target.value));
+              setPage(1);
+            }}
+            className="rounded border border-gray-300 px-2 py-1"
+          >
+            {[20, 50, 100].map((n) => (
+              <option key={n} value={n}>
+                {n}
+              </option>
+            ))}
+          </select>
+          <span>条 · 共 {total} 条</span>
+        </div>
         <button
           disabled={page <= 1}
           onClick={() => setPage((p) => p - 1)}
@@ -172,6 +356,159 @@ export default function ProductList({
         >
           下一页
         </button>
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            const n = Number(jump);
+            if (Number.isFinite(n) && n >= 1) {
+              setPage(Math.min(Math.max(1, Math.trunc(n)), pages));
+              setJump("");
+            }
+          }}
+          className="flex items-center gap-1"
+        >
+          <span>跳至</span>
+          <input
+            value={jump}
+            onChange={(e) => setJump(e.target.value.replace(/[^0-9]/g, ""))}
+            placeholder={String(page)}
+            className="w-14 rounded border border-gray-300 px-2 py-1 text-center"
+            aria-label="跳转页码"
+          />
+          <button
+            type="submit"
+            className="rounded border border-gray-300 px-3 py-1 hover:bg-gray-50"
+          >
+            前往
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+}
+
+function CreateProductModal({
+  onClose,
+  onCreated,
+}: {
+  onClose: () => void;
+  onCreated: (id: string) => void;
+}) {
+  const [name, setName] = useState("");
+  const [gtin, setGtin] = useState("");
+  const [brand, setBrand] = useState("");
+  const [categoryId, setCategoryId] = useState("");
+  const [brands, setBrands] = useState<Brand[]>([]);
+  const [categories, setCategories] = useState<Category[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    api.listBrands().then((r) => setBrands(r.items)).catch(() => {});
+    api.listCategories().then((r) => setCategories(r.items)).catch(() => {});
+  }, []);
+
+  async function submit() {
+    if (!name.trim()) {
+      setError("名称不能为空");
+      return;
+    }
+    setBusy(true);
+    setError("");
+    try {
+      const created = await api.createProduct({
+        name: name.trim(),
+        gtin: gtin.trim() || null,
+        brand_name: brand.trim() || null,
+        category_id: categoryId || null,
+        status: "active",
+      });
+      onCreated(created.id);
+    } catch (e) {
+      setError(e instanceof ApiError ? e.message : "新建失败");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="fixed inset-0 z-20 flex items-center justify-center bg-black/30">
+      <div className="w-full max-w-md rounded-lg bg-white p-6 shadow-lg">
+        <h3 className="mb-4 text-base font-semibold text-gray-800">新建商品</h3>
+        {error && (
+          <div className="mb-3 rounded bg-red-50 px-3 py-2 text-sm text-red-600">
+            {error}
+          </div>
+        )}
+        <div className="space-y-3">
+          <label className="block">
+            <span className="text-xs text-gray-500">名称 *</span>
+            <input
+              autoFocus
+              className="mt-1 w-full rounded border border-gray-300 px-3 py-2 text-sm"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              placeholder="商品名称"
+            />
+          </label>
+          <label className="block">
+            <span className="text-xs text-gray-500">条码 (GTIN，可选)</span>
+            <input
+              className="mt-1 w-full rounded border border-gray-300 px-3 py-2 text-sm"
+              value={gtin}
+              onChange={(e) => setGtin(e.target.value)}
+              placeholder="8/12/13/14 位"
+            />
+          </label>
+          <label className="block">
+            <span className="text-xs text-gray-500">品牌（不存在将自动创建，可选）</span>
+            <input
+              list="create-brand-list"
+              className="mt-1 w-full rounded border border-gray-300 px-3 py-2 text-sm"
+              value={brand}
+              onChange={(e) => setBrand(e.target.value)}
+            />
+            <datalist id="create-brand-list">
+              {brands.map((b) => (
+                <option key={b.id} value={b.name} />
+              ))}
+            </datalist>
+          </label>
+          <label className="block">
+            <span className="text-xs text-gray-500">品类（可选）</span>
+            <select
+              className="mt-1 w-full rounded border border-gray-300 bg-white px-3 py-2 text-sm"
+              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>
+          </label>
+        </div>
+        <p className="mt-3 text-xs text-gray-400">
+          创建后将进入详情页，可继续补全营养、图片、多条码等信息。
+        </p>
+        <div className="mt-4 flex justify-end gap-2">
+          <button
+            onClick={onClose}
+            className="rounded border px-4 py-2 text-sm text-gray-600"
+          >
+            取消
+          </button>
+          <button
+            onClick={submit}
+            disabled={busy}
+            className="rounded bg-emerald-600 px-4 py-2 text-sm text-white hover:bg-emerald-700 disabled:opacity-60"
+          >
+            {busy ? "创建中…" : "创建并编辑"}
+          </button>
+        </div>
       </div>
     </div>
   );

admin-frontend/src/components/StatsPage.tsx

@@ -0,0 +1,125 @@
+import { useEffect, useState } from "react";
+import { api, ApiError } from "../api";
+import type { AdminStats } from "../types";
+import { BarChart3, Package, CheckCircle2, Tag, FolderTree, Inbox } from "lucide-react";
+
+const STATUS_LABEL: Record<string, string> = {
+  active: "在用",
+  merged: "已合并",
+  deprecated: "已停用",
+};
+
+function Card({
+  icon,
+  label,
+  value,
+  hint,
+}: {
+  icon: React.ReactNode;
+  label: string;
+  value: string | number;
+  hint?: string;
+}) {
+  return (
+    <div className="rounded-lg border bg-white p-5">
+      <div className="flex items-center gap-2 text-sm text-gray-500">
+        {icon}
+        {label}
+      </div>
+      <div className="mt-2 text-2xl font-semibold text-gray-800">{value}</div>
+      {hint && <div className="mt-1 text-xs text-gray-400">{hint}</div>}
+    </div>
+  );
+}
+
+export default function StatsPage() {
+  const [stats, setStats] = useState<AdminStats | null>(null);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    api
+      .stats()
+      .then(setStats)
+      .catch((e) => setError(e instanceof ApiError ? e.message : "加载失败"));
+  }, []);
+
+  return (
+    <div className="mx-auto max-w-5xl">
+      <h2 className="mb-4 flex items-center gap-2 text-lg font-semibold text-gray-800">
+        <BarChart3 className="h-5 w-5 text-emerald-600" /> 数据概览
+      </h2>
+
+      {error && (
+        <div className="mb-3 rounded bg-red-50 px-4 py-2 text-sm text-red-700">{error}</div>
+      )}
+
+      {!stats ? (
+        <div className="text-sm text-gray-400">加载中…</div>
+      ) : (
+        <>
+          <div className="grid grid-cols-2 gap-4 md:grid-cols-3">
+            <Card
+              icon={<Package className="h-4 w-4" />}
+              label="商品总数"
+              value={stats.products.toLocaleString()}
+            />
+            <Card
+              icon={<CheckCircle2 className="h-4 w-4 text-emerald-600" />}
+              label="合格档案"
+              value={stats.qualified.toLocaleString()}
+              hint={`质量分 ≥ ${stats.min_score} 且在用`}
+            />
+            <Card
+              icon={<BarChart3 className="h-4 w-4" />}
+              label="平均质量分"
+              value={Math.round(stats.avg_quality * 100)}
+              hint="满分 100"
+            />
+            <Card
+              icon={<Tag className="h-4 w-4" />}
+              label="品牌数"
+              value={stats.brands.toLocaleString()}
+            />
+            <Card
+              icon={<FolderTree className="h-4 w-4" />}
+              label="分类数"
+              value={stats.categories.toLocaleString()}
+            />
+            <Card
+              icon={<Inbox className="h-4 w-4" />}
+              label="待审核投稿"
+              value={stats.pending_submissions.toLocaleString()}
+            />
+          </div>
+
+          <div className="mt-6 rounded-lg border bg-white p-5">
+            <h3 className="mb-3 text-sm font-medium text-gray-700">按状态分布</h3>
+            <div className="space-y-2">
+              {Object.keys(stats.by_status).length === 0 ? (
+                <div className="text-sm text-gray-400">暂无数据</div>
+              ) : (
+                Object.entries(stats.by_status).map(([st, n]) => {
+                  const pct = stats.products > 0 ? (n / stats.products) * 100 : 0;
+                  return (
+                    <div key={st} className="flex items-center gap-3 text-sm">
+                      <span className="w-16 text-gray-600">
+                        {STATUS_LABEL[st] || st}
+                      </span>
+                      <div className="h-3 flex-1 overflow-hidden rounded bg-gray-100">
+                        <div
+                          className="h-full bg-emerald-500"
+                          style={{ width: `${pct}%` }}
+                        />
+                      </div>
+                      <span className="w-12 text-right text-gray-500">{n}</span>
+                    </div>
+                  );
+                })
+              )}
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

admin-frontend/src/components/SubmissionsPage.tsx

@@ -56,7 +56,7 @@ export default function SubmissionsPage({ onPending }: { onPending?: (n: number)
   }
 
   return (
-    <div>
+    <div className="mx-auto max-w-5xl">
       <div className="flex items-center gap-2 mb-4">
         {STATUS_TABS.map((t) => (
           <button
@@ -193,7 +193,7 @@ function SubmissionView({ id, onBack }: { id: string; onBack: () => void }) {
   const nutri = Object.entries(p.nutriments || {});
 
   return (
-    <div className="max-w-3xl">
+    <div className="mx-auto 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>

admin-frontend/src/types.ts

@@ -66,6 +66,7 @@ export interface ProductDetail {
 export interface Brand {
   id: string;
   name: string;
+  product_count: number;
 }
 
 export interface Category {
@@ -74,6 +75,17 @@ export interface Category {
   name_en: string | null;
   path: string;
   level: number;
+  parent_id: string | null;
+  gpc_brick_code: string | null;
+  product_count: number;
+}
+
+export interface CategoryInput {
+  name_zh: string;
+  name_en?: string | null;
+  slug?: string | null;
+  parent_id?: string | null;
+  gpc_brick_code?: string | null;
 }
 
 export interface AuditEntry {
@@ -84,6 +96,27 @@ export interface AuditEntry {
   created_at: string;
 }
 
+export interface AuditLogRow {
+  id: string;
+  actor: string;
+  action: string;
+  entity: string;
+  entity_id: string | null;
+  fields: string[];
+  created_at: string;
+}
+
+export interface AdminStats {
+  products: number;
+  qualified: number;
+  min_score: number;
+  by_status: Record<string, number>;
+  brands: number;
+  categories: number;
+  pending_submissions: number;
+  avg_quality: number;
+}
+
 export interface SubmissionRow {
   id: string;
   gtin: string | null;

api/internal/adminhandler/handler.go

@@ -64,7 +64,11 @@ func (h *Handler) Router() http.Handler {
 		r.Group(func(r chi.Router) {
 			r.Use(h.authn.Middleware)
 			r.Get("/api/me", h.Me)
+			r.Get("/api/stats", h.Stats)
+			r.Get("/api/audit", h.ListAllAudit)
 			r.Get("/api/products", h.ListProducts)
+			r.Post("/api/products", h.CreateProduct)
+			r.Post("/api/products/bulk", h.BulkProducts)
 			r.Get("/api/products/{id}", h.GetProduct)
 			r.Put("/api/products/{id}", h.UpdateProduct)
 			r.Get("/api/products/{id}/audit", h.ListAudit)
@@ -76,7 +80,14 @@ func (h *Handler) Router() http.Handler {
 			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.Post("/api/brands", h.CreateBrand)
+			r.Put("/api/brands/{id}", h.UpdateBrand)
+			r.Post("/api/brands/{id}/merge", h.MergeBrands)
+			r.Delete("/api/brands/{id}", h.DeleteBrand)
 			r.Get("/api/categories", h.ListCategories)
+			r.Post("/api/categories", h.CreateCategory)
+			r.Put("/api/categories/{id}", h.UpdateCategory)
+			r.Delete("/api/categories/{id}", h.DeleteCategory)
 
 			r.Get("/api/submissions", h.ListSubmissions)
 			r.Get("/api/submissions/{id}", h.GetSubmission)
@@ -172,6 +183,99 @@ func (h *Handler) GetProduct(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, d)
 }
 
+// CreateProduct adds a new product with core fields; the rest is filled in via
+// the detail editor.
+func (h *Handler) CreateProduct(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.CreateProduct(r.Context(), auth.UserFrom(r.Context()), in)
+	if errors.Is(err, adminstore.ErrDuplicateGTIN) {
+		writeError(w, http.StatusConflict, "duplicate_gtin", "该条码(GTIN)已被其它商品使用")
+		return
+	}
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, d)
+}
+
+// Stats returns the dashboard overview counters.
+func (h *Handler) Stats(w http.ResponseWriter, r *http.Request) {
+	st, err := h.store.Stats(r.Context())
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, st)
+}
+
+// ListAllAudit returns a page of the global operations audit log.
+func (h *Handler) ListAllAudit(w http.ResponseWriter, r *http.Request) {
+	page, size := pageParams(r)
+	items, total, err := h.store.ListAllAudit(r.Context(), 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,
+	})
+}
+
+type bulkInput struct {
+	IDs        []string `json:"ids"`
+	Action     string   `json:"action"`
+	Status     string   `json:"status"`
+	CategoryID *string  `json:"category_id"`
+}
+
+// BulkProducts applies a status or category change to many products at once.
+func (h *Handler) BulkProducts(w http.ResponseWriter, r *http.Request) {
+	var in bulkInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if len(in.IDs) == 0 {
+		writeError(w, http.StatusBadRequest, "bad_request", "未选择任何商品")
+		return
+	}
+	actor := auth.UserFrom(r.Context())
+	var (
+		affected int
+		err      error
+	)
+	switch in.Action {
+	case "status":
+		affected, err = h.store.BulkSetStatus(r.Context(), actor, in.IDs, in.Status)
+	case "category":
+		affected, err = h.store.BulkSetCategory(r.Context(), actor, in.IDs, in.CategoryID)
+	default:
+		writeError(w, http.StatusBadRequest, "bad_request", "未知的批量操作")
+		return
+	}
+	switch {
+	case errors.Is(err, adminstore.ErrInvalidStatus):
+		writeError(w, http.StatusBadRequest, "invalid_status", "无效的状态值")
+		return
+	case errors.Is(err, adminstore.ErrInvalidParent):
+		writeError(w, http.StatusBadRequest, "invalid_parent", "目标分类无效")
+		return
+	case errors.Is(err, adminstore.ErrNoTargets):
+		writeError(w, http.StatusBadRequest, "bad_request", "未选择任何商品")
+		return
+	}
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"status": "ok", "affected": affected})
+}
+
 // UpdateProduct applies an edit.
 func (h *Handler) UpdateProduct(w http.ResponseWriter, r *http.Request) {
 	var in adminstore.ProductInput
@@ -328,6 +432,164 @@ func (h *Handler) ListCategories(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// CreateCategory adds a category node.
+func (h *Handler) CreateCategory(w http.ResponseWriter, r *http.Request) {
+	var in adminstore.CategoryInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if strings.TrimSpace(in.NameZH) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "分类名称不能为空")
+		return
+	}
+	c, err := h.store.CreateCategory(r.Context(), auth.UserFrom(r.Context()), in)
+	if h.handleCategoryErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, c)
+}
+
+// UpdateCategory renames and/or moves a category node.
+func (h *Handler) UpdateCategory(w http.ResponseWriter, r *http.Request) {
+	var in adminstore.CategoryInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if strings.TrimSpace(in.NameZH) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "分类名称不能为空")
+		return
+	}
+	c, err := h.store.UpdateCategory(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), in)
+	if h.handleCategoryErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, c)
+}
+
+// DeleteCategory removes a leaf category that no product uses.
+func (h *Handler) DeleteCategory(w http.ResponseWriter, r *http.Request) {
+	err := h.store.DeleteCategory(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()))
+	if h.handleCategoryErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+// handleCategoryErr maps category-specific errors to client statuses, falling
+// back to handleErr otherwise.
+func (h *Handler) handleCategoryErr(w http.ResponseWriter, err error) bool {
+	if err == nil {
+		return false
+	}
+	switch {
+	case errors.Is(err, adminstore.ErrDuplicatePath):
+		writeError(w, http.StatusConflict, "duplicate_path", "该分类路径已存在，请换一个英文标识(slug)")
+		return true
+	case errors.Is(err, adminstore.ErrCategoryHasChildren):
+		writeError(w, http.StatusConflict, "has_children", "该分类存在子分类，请先删除或移动其子分类")
+		return true
+	case errors.Is(err, adminstore.ErrCategoryInUse):
+		writeError(w, http.StatusConflict, "in_use", "仍有商品归属于该分类，请先改归其它分类")
+		return true
+	case errors.Is(err, adminstore.ErrInvalidParent):
+		writeError(w, http.StatusBadRequest, "invalid_parent", "上级分类无效（不存在或不能移动到自身/子级下）")
+		return true
+	}
+	return h.handleErr(w, err)
+}
+
+type brandInput struct {
+	Name string `json:"name"`
+}
+
+type brandMergeInput struct {
+	TargetID string `json:"target_id"`
+}
+
+// CreateBrand adds a brand.
+func (h *Handler) CreateBrand(w http.ResponseWriter, r *http.Request) {
+	var in brandInput
+	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
+	}
+	b, err := h.store.CreateBrand(r.Context(), auth.UserFrom(r.Context()), in.Name)
+	if h.handleBrandErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, b)
+}
+
+// UpdateBrand renames a brand.
+func (h *Handler) UpdateBrand(w http.ResponseWriter, r *http.Request) {
+	var in brandInput
+	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
+	}
+	b, err := h.store.UpdateBrand(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()), in.Name)
+	if h.handleBrandErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, b)
+}
+
+// MergeBrands folds one brand's products into another, then deletes the source.
+func (h *Handler) MergeBrands(w http.ResponseWriter, r *http.Request) {
+	var in brandMergeInput
+	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
+		writeError(w, http.StatusBadRequest, "bad_request", "invalid body")
+		return
+	}
+	if strings.TrimSpace(in.TargetID) == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "请选择合并目标品牌")
+		return
+	}
+	b, err := h.store.MergeBrands(r.Context(), chi.URLParam(r, "id"), in.TargetID, auth.UserFrom(r.Context()))
+	if h.handleBrandErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, b)
+}
+
+// DeleteBrand removes a brand no product references.
+func (h *Handler) DeleteBrand(w http.ResponseWriter, r *http.Request) {
+	err := h.store.DeleteBrand(r.Context(), chi.URLParam(r, "id"), auth.UserFrom(r.Context()))
+	if h.handleBrandErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+// handleBrandErr maps brand-specific errors to client statuses.
+func (h *Handler) handleBrandErr(w http.ResponseWriter, err error) bool {
+	if err == nil {
+		return false
+	}
+	switch {
+	case errors.Is(err, adminstore.ErrDuplicateBrand):
+		writeError(w, http.StatusConflict, "duplicate_brand", "该品牌名称已存在")
+		return true
+	case errors.Is(err, adminstore.ErrBrandInUse):
+		writeError(w, http.StatusConflict, "in_use", "仍有商品使用该品牌，请先改用其它品牌或合并")
+		return true
+	case errors.Is(err, adminstore.ErrInvalidMerge):
+		writeError(w, http.StatusBadRequest, "invalid_merge", "合并目标无效（不存在或与源品牌相同）")
+		return true
+	}
+	return h.handleErr(w, err)
+}
+
 // ---------- submissions ----------
 
 // CreateSubmission accepts an anonymous public contribution into the queue.

api/internal/adminstore/brand.go

@@ -0,0 +1,154 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// Brand-management errors, mapped to client statuses by the handler.
+var (
+	// ErrDuplicateBrand is returned when a brand name already exists.
+	ErrDuplicateBrand = errors.New("duplicate brand name")
+	// ErrBrandInUse blocks deleting a brand still referenced by products.
+	ErrBrandInUse = errors.New("brand in use")
+	// ErrInvalidMerge is returned when a merge target is missing or equal to
+	// the source.
+	ErrInvalidMerge = errors.New("invalid merge target")
+)
+
+// CreateBrand inserts a new brand. Names are unique by normalized form.
+func (s *Store) CreateBrand(ctx context.Context, actor, name string) (*Brand, error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return nil, errors.New("name required")
+	}
+	var b Brand
+	err := s.pool.QueryRow(ctx,
+		`INSERT INTO brand (name, normalized_name) VALUES ($1, $2) RETURNING id, name, 0`,
+		name, normBrand(name)).Scan(&b.ID, &b.Name, &b.ProductCount)
+	if isUniqueViolation(err) {
+		return nil, ErrDuplicateBrand
+	}
+	if err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "create", "brand", &b.ID, []string{"name"}, nil, b)
+	return &b, nil
+}
+
+// UpdateBrand renames a brand, keeping the normalized name in sync.
+func (s *Store) UpdateBrand(ctx context.Context, id, actor, name string) (*Brand, error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return nil, errors.New("name required")
+	}
+	ct, err := s.pool.Exec(ctx,
+		"UPDATE brand SET name = $1, normalized_name = $2 WHERE id = $3",
+		name, normBrand(name), id)
+	if isUniqueViolation(err) {
+		return nil, ErrDuplicateBrand
+	}
+	if err != nil {
+		return nil, err
+	}
+	if ct.RowsAffected() == 0 {
+		return nil, ErrNotFound
+	}
+	out, err := s.getBrand(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "update", "brand", &id, []string{"name"}, nil, out)
+	return out, nil
+}
+
+// MergeBrands reassigns every product of src to dst, then deletes src. Useful
+// for collapsing duplicate brands (e.g. "可口可乐" and "Coca-Cola").
+func (s *Store) MergeBrands(ctx context.Context, srcID, dstID, actor string) (*Brand, error) {
+	if srcID == dstID {
+		return nil, ErrInvalidMerge
+	}
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var dstName string
+	err = tx.QueryRow(ctx, "SELECT name FROM brand WHERE id = $1", dstID).Scan(&dstName)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrInvalidMerge
+	}
+	if err != nil {
+		return nil, err
+	}
+	var srcName string
+	err = tx.QueryRow(ctx, "SELECT name FROM brand WHERE id = $1", srcID).Scan(&srcName)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	if _, err := tx.Exec(ctx, "UPDATE product SET brand_id = $1 WHERE brand_id = $2", dstID, srcID); err != nil {
+		return nil, err
+	}
+	if _, err := tx.Exec(ctx, "DELETE FROM brand WHERE id = $1", srcID); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+
+	out, err := s.getBrand(ctx, dstID)
+	if err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "merge", "brand", &srcID, []string{"name"},
+		map[string]string{"name": srcName},
+		map[string]string{"merged_into": dstName, "merged_into_id": dstID})
+	return out, nil
+}
+
+// DeleteBrand removes a brand not referenced by any product.
+func (s *Store) DeleteBrand(ctx context.Context, id, actor string) error {
+	before, err := s.getBrand(ctx, id)
+	if err != nil {
+		return err
+	}
+	if before.ProductCount > 0 {
+		return fmt.Errorf("%w: %d products", ErrBrandInUse, before.ProductCount)
+	}
+	ct, err := s.pool.Exec(ctx, "DELETE FROM brand WHERE id = $1", id)
+	if err != nil {
+		if isForeignKeyViolation(err) {
+			return ErrBrandInUse
+		}
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+	_ = s.writeAudit(ctx, actor, "delete", "brand", &id, []string{"name"}, before, nil)
+	return nil
+}
+
+func (s *Store) getBrand(ctx context.Context, id string) (*Brand, error) {
+	var b Brand
+	err := s.pool.QueryRow(ctx, `
+SELECT b.id, b.name,
+       (SELECT count(*) FROM product p WHERE p.brand_id = b.id)
+FROM brand b WHERE b.id = $1`, id).Scan(&b.ID, &b.Name, &b.ProductCount)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &b, nil
+}

api/internal/adminstore/brand_test.go

@@ -0,0 +1,78 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestBrandLifecycle(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	a, err := s.CreateBrand(ctx, "tester", "品牌A "+randomHex(4))
+	if err != nil {
+		t.Fatalf("create A: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM brand WHERE id = $1", a.ID) })
+
+	b, err := s.CreateBrand(ctx, "tester", "品牌B "+randomHex(4))
+	if err != nil {
+		t.Fatalf("create B: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM brand WHERE id = $1", b.ID) })
+
+	// Duplicate (normalized) name must be rejected.
+	if _, err := s.CreateBrand(ctx, "tester", "  "+a.Name+"  "); !errors.Is(err, ErrDuplicateBrand) {
+		t.Fatalf("expected ErrDuplicateBrand, got %v", err)
+	}
+
+	// Rename.
+	renamed, err := s.UpdateBrand(ctx, a.ID, "tester", "品牌A改名")
+	if err != nil {
+		t.Fatalf("rename: %v", err)
+	}
+	if renamed.Name != "品牌A改名" {
+		t.Fatalf("rename not applied: %q", renamed.Name)
+	}
+
+	// Attach a product to brand A so deletion is blocked and merge moves it.
+	var prodID string
+	err = s.pool.QueryRow(ctx,
+		"INSERT INTO product (name, brand_id, status) VALUES ($1,$2,'active') RETURNING id",
+		"测试商品 "+randomHex(4), a.ID).Scan(&prodID)
+	if err != nil {
+		t.Fatalf("insert product: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM product WHERE id = $1", prodID) })
+
+	// Deleting an in-use brand must fail.
+	if err := s.DeleteBrand(ctx, a.ID, "tester"); !errors.Is(err, ErrBrandInUse) {
+		t.Fatalf("expected ErrBrandInUse, got %v", err)
+	}
+
+	// Merge A into B: product reassigned, A deleted.
+	merged, err := s.MergeBrands(ctx, a.ID, b.ID, "tester")
+	if err != nil {
+		t.Fatalf("merge: %v", err)
+	}
+	if merged.ID != b.ID || merged.ProductCount < 1 {
+		t.Fatalf("merge result wrong: %+v", merged)
+	}
+	if _, err := s.getBrand(ctx, a.ID); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("source brand should be gone, got %v", err)
+	}
+
+	// Self-merge is invalid.
+	if _, err := s.MergeBrands(ctx, b.ID, b.ID, "tester"); !errors.Is(err, ErrInvalidMerge) {
+		t.Fatalf("expected ErrInvalidMerge, got %v", err)
+	}
+
+	// After moving the product away from B, B can be deleted.
+	if _, err := s.pool.Exec(ctx, "DELETE FROM product WHERE id = $1", prodID); err != nil {
+		t.Fatalf("cleanup product: %v", err)
+	}
+	if err := s.DeleteBrand(ctx, b.ID, "tester"); err != nil {
+		t.Fatalf("delete unused brand: %v", err)
+	}
+}

api/internal/adminstore/bulk.go

@@ -0,0 +1,80 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+)
+
+// Bulk-operation errors.
+var (
+	// ErrNoTargets is returned when a bulk request selects no products.
+	ErrNoTargets = errors.New("no products selected")
+	// ErrInvalidStatus is returned for an unknown product status value.
+	ErrInvalidStatus = errors.New("invalid status")
+)
+
+var validStatus = map[string]bool{"active": true, "merged": true, "deprecated": true}
+
+// BulkSetStatus updates the status of every selected product in one statement.
+func (s *Store) BulkSetStatus(ctx context.Context, actor string, ids []string, status string) (int, error) {
+	if len(ids) == 0 {
+		return 0, ErrNoTargets
+	}
+	if !validStatus[status] {
+		return 0, ErrInvalidStatus
+	}
+	ct, err := s.pool.Exec(ctx,
+		"UPDATE product SET status = $1 WHERE id = ANY($2)", status, ids)
+	if err != nil {
+		return 0, err
+	}
+	n := int(ct.RowsAffected())
+	_ = s.writeAudit(ctx, actor, "bulk_status", "product", nil,
+		[]string{"status"}, map[string]any{"ids": ids}, map[string]any{"status": status})
+	return n, nil
+}
+
+// BulkSetCategory reassigns the category of every selected product, syncing the
+// GPC brick code and recomputing quality for each one.
+func (s *Store) BulkSetCategory(ctx context.Context, actor string, ids []string, categoryID *string) (int, error) {
+	if len(ids) == 0 {
+		return 0, ErrNoTargets
+	}
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return 0, err
+	}
+	defer tx.Rollback(ctx)
+
+	var gpc *string
+	if categoryID != nil && *categoryID != "" {
+		if err := tx.QueryRow(ctx, "SELECT gpc_brick_code FROM category WHERE id = $1", *categoryID).Scan(&gpc); err != nil {
+			return 0, ErrInvalidParent
+		}
+	} else {
+		categoryID = nil
+	}
+
+	ct, err := tx.Exec(ctx,
+		"UPDATE product SET category_id = $1, gpc_brick_code = $2 WHERE id = ANY($3)",
+		categoryID, gpc, ids)
+	if err != nil {
+		return 0, err
+	}
+	for _, id := range ids {
+		if _, err := s.recomputeQualityTx(ctx, tx, id); err != nil {
+			return 0, err
+		}
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return 0, err
+	}
+	n := int(ct.RowsAffected())
+	cat := ""
+	if categoryID != nil {
+		cat = *categoryID
+	}
+	_ = s.writeAudit(ctx, actor, "bulk_category", "product", nil,
+		[]string{"category"}, map[string]any{"ids": ids}, map[string]any{"category_id": cat})
+	return n, nil
+}

api/internal/adminstore/category.go

@@ -0,0 +1,297 @@
+package adminstore
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// randomHex returns n random lowercase hex characters for fallback ltree slugs.
+func randomHex(n int) string {
+	b := make([]byte, (n+1)/2)
+	if _, err := rand.Read(b); err != nil {
+		return "x"
+	}
+	return hex.EncodeToString(b)[:n]
+}
+
+// Category-management errors, mapped to client statuses by the handler.
+var (
+	// ErrDuplicatePath is returned when a category path already exists.
+	ErrDuplicatePath = errors.New("duplicate category path")
+	// ErrCategoryHasChildren blocks deleting a node that still has children.
+	ErrCategoryHasChildren = errors.New("category has children")
+	// ErrCategoryInUse blocks deleting a node still referenced by products.
+	ErrCategoryInUse = errors.New("category in use")
+	// ErrInvalidParent is returned for a missing parent or an illegal move
+	// (onto itself or one of its own descendants).
+	ErrInvalidParent = errors.New("invalid parent category")
+)
+
+// CategoryInput is the payload accepted when creating or editing a category.
+// Slug is the ltree label (ASCII); when empty it is derived from NameEN, then
+// from a random suffix, since ltree labels cannot contain CJK or spaces.
+type CategoryInput struct {
+	NameZH       string  `json:"name_zh"`
+	NameEN       *string `json:"name_en"`
+	Slug         *string `json:"slug"`
+	ParentID     *string `json:"parent_id"`
+	GPCBrickCode *string `json:"gpc_brick_code"`
+}
+
+var slugInvalid = regexp.MustCompile(`[^a-z0-9_]+`)
+
+// slugify converts a string into a valid ltree label ([a-z0-9_]).
+func slugify(s string) string {
+	s = strings.ToLower(strings.TrimSpace(s))
+	s = slugInvalid.ReplaceAllString(s, "_")
+	s = strings.Trim(s, "_")
+	for strings.Contains(s, "__") {
+		s = strings.ReplaceAll(s, "__", "_")
+	}
+	return s
+}
+
+// resolveSlug picks an ltree label from the explicit slug, then NameEN, then a
+// random fallback so a Chinese-only category still gets a valid path label.
+func resolveSlug(in CategoryInput) string {
+	if in.Slug != nil {
+		if s := slugify(*in.Slug); s != "" {
+			return s
+		}
+	}
+	if in.NameEN != nil {
+		if s := slugify(*in.NameEN); s != "" {
+			return s
+		}
+	}
+	return "cat_" + randomHex(6)
+}
+
+func trimPtr(p *string) *string {
+	if p == nil {
+		return nil
+	}
+	t := strings.TrimSpace(*p)
+	if t == "" {
+		return nil
+	}
+	return &t
+}
+
+// CreateCategory inserts a new category node. With no parent it becomes a root
+// (level 0); otherwise its path is parentPath.slug and level is parentLevel+1.
+func (s *Store) CreateCategory(ctx context.Context, actor string, in CategoryInput) (*Category, error) {
+	name := strings.TrimSpace(in.NameZH)
+	if name == "" {
+		return nil, errors.New("name_zh required")
+	}
+
+	parentPath := ""
+	parentLevel := -1
+	var parentID *string
+	if pid := trimPtr(in.ParentID); pid != nil {
+		var path string
+		var level int
+		err := s.pool.QueryRow(ctx, "SELECT path::text, level FROM category WHERE id = $1", *pid).Scan(&path, &level)
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrInvalidParent
+		}
+		if err != nil {
+			return nil, err
+		}
+		parentPath, parentLevel, parentID = path, level, pid
+	}
+
+	slug := resolveSlug(in)
+	path := slug
+	if parentPath != "" {
+		path = parentPath + "." + slug
+	}
+	level := parentLevel + 1
+
+	var c Category
+	err := s.pool.QueryRow(ctx, `
+INSERT INTO category (name_zh, name_en, parent_id, path, gpc_brick_code, level)
+VALUES ($1, $2, $3, $4::ltree, $5, $6)
+RETURNING id, name_zh, name_en, path::text, level, parent_id::text, gpc_brick_code, 0`,
+		name, trimPtr(in.NameEN), parentID, path, trimPtr(in.GPCBrickCode), level).
+		Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level, &c.ParentID, &c.GPCBrickCode, &c.ProductCount)
+	if isUniqueViolation(err) {
+		return nil, ErrDuplicatePath
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	_ = s.writeAudit(ctx, actor, "create", "category", &c.ID, []string{"name_zh", "path"}, nil, c)
+	return &c, nil
+}
+
+// UpdateCategory renames a node and/or moves it under a new parent. Moving
+// rewrites the path of the node and every descendant via ltree, keeping level
+// in sync. Moving a node onto itself or a descendant is rejected.
+func (s *Store) UpdateCategory(ctx context.Context, id, actor string, in CategoryInput) (*Category, error) {
+	name := strings.TrimSpace(in.NameZH)
+	if name == "" {
+		return nil, errors.New("name_zh required")
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var oldPath string
+	var oldLevel int
+	var oldParent *string
+	err = tx.QueryRow(ctx, "SELECT path::text, level, parent_id::text FROM category WHERE id = $1", id).
+		Scan(&oldPath, &oldLevel, &oldParent)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	if _, err := tx.Exec(ctx,
+		"UPDATE category SET name_zh = $1, name_en = $2, gpc_brick_code = $3 WHERE id = $4",
+		name, trimPtr(in.NameEN), trimPtr(in.GPCBrickCode), id); err != nil {
+		return nil, err
+	}
+
+	newParent := trimPtr(in.ParentID)
+	if !strEq(newParent, oldParent) {
+		if err := s.moveCategoryTx(ctx, tx, id, oldPath, newParent); err != nil {
+			return nil, err
+		}
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+
+	out, err := s.getCategory(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	_ = s.writeAudit(ctx, actor, "update", "category", &id, []string{"name_zh", "name_en", "gpc_brick_code", "parent_id"}, nil, out)
+	return out, nil
+}
+
+// moveCategoryTx re-parents a subtree. The node's slug (last path label) is
+// preserved; only its ancestor prefix and level change.
+func (s *Store) moveCategoryTx(ctx context.Context, tx pgx.Tx, id, oldPath string, newParent *string) error {
+	slug := oldPath
+	if i := strings.LastIndex(oldPath, "."); i >= 0 {
+		slug = oldPath[i+1:]
+	}
+
+	newBase := slug
+	if newParent != nil {
+		var parentPath string
+		err := tx.QueryRow(ctx, "SELECT path::text FROM category WHERE id = $1", *newParent).Scan(&parentPath)
+		if errors.Is(err, pgx.ErrNoRows) {
+			return ErrInvalidParent
+		}
+		if err != nil {
+			return err
+		}
+		// Disallow moving a node under itself or one of its descendants.
+		if parentPath == oldPath || strings.HasPrefix(parentPath, oldPath+".") {
+			return ErrInvalidParent
+		}
+		newBase = parentPath + "." + slug
+	}
+
+	// Rewrite the node and all descendants in one statement; level tracks depth.
+	_, err := tx.Exec(ctx, `
+UPDATE category
+SET path  = ($1::ltree || subpath(path, nlevel($2::ltree) - 1)),
+    level = nlevel($1::ltree) + (nlevel(path) - nlevel($2::ltree)) - 1
+WHERE path = $2::ltree OR path <@ $2::ltree`, newBase, oldPath)
+	if isUniqueViolation(err) {
+		return ErrDuplicatePath
+	}
+	if err != nil {
+		return err
+	}
+
+	_, err = tx.Exec(ctx, "UPDATE category SET parent_id = $1 WHERE id = $2", newParent, id)
+	return err
+}
+
+// DeleteCategory removes a leaf node not referenced by any product. Nodes with
+// children or in-use nodes are rejected with a specific error.
+func (s *Store) DeleteCategory(ctx context.Context, id, actor string) error {
+	before, err := s.getCategory(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	var children int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM category WHERE parent_id = $1", id).Scan(&children); err != nil {
+		return err
+	}
+	if children > 0 {
+		return ErrCategoryHasChildren
+	}
+
+	var products int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM product WHERE category_id = $1", id).Scan(&products); err != nil {
+		return err
+	}
+	if products > 0 {
+		return fmt.Errorf("%w: %d products", ErrCategoryInUse, products)
+	}
+
+	ct, err := s.pool.Exec(ctx, "DELETE FROM category WHERE id = $1", id)
+	if err != nil {
+		// A concurrent product assignment can still trip the FK.
+		if isForeignKeyViolation(err) {
+			return ErrCategoryInUse
+		}
+		return err
+	}
+	if ct.RowsAffected() == 0 {
+		return ErrNotFound
+	}
+
+	_ = s.writeAudit(ctx, actor, "delete", "category", &id, []string{"path"}, before, nil)
+	return nil
+}
+
+func (s *Store) getCategory(ctx context.Context, id string) (*Category, error) {
+	var c Category
+	err := s.pool.QueryRow(ctx, `
+SELECT c.id, c.name_zh, c.name_en, c.path::text, c.level, c.parent_id::text,
+       c.gpc_brick_code,
+       (SELECT count(*) FROM product p WHERE p.category_id = c.id)
+FROM category c WHERE c.id = $1`, id).
+		Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level, &c.ParentID, &c.GPCBrickCode, &c.ProductCount)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &c, nil
+}
+
+func isUniqueViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	return errors.As(err, &pgErr) && pgErr.Code == "23505"
+}
+
+func isForeignKeyViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	return errors.As(err, &pgErr) && pgErr.Code == "23503"
+}

api/internal/adminstore/category_test.go

@@ -0,0 +1,130 @@
+package adminstore
+
+import (
+	"context"
+	"errors"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// newTestStore connects to the test database, skipping when it is unreachable
+// or migrations have not been applied.
+func newTestStore(t *testing.T) *Store {
+	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.category') IS NOT NULL").Scan(&hasTable); err != nil || !hasTable {
+		pool.Close()
+		t.Skip("migrations not applied (category missing)")
+	}
+	t.Cleanup(pool.Close)
+	return New(pool)
+}
+
+func ptr(s string) *string { return &s }
+
+func TestCategoryLifecycle(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	root, err := s.CreateCategory(ctx, "tester", CategoryInput{
+		NameZH: "测试根", Slug: ptr("test_root_" + randomHex(6)),
+	})
+	if err != nil {
+		t.Fatalf("create root: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM category WHERE path <@ $1::ltree", root.Path) })
+
+	if root.Level != 0 || root.ParentID != nil {
+		t.Fatalf("root level/parent wrong: level=%d parent=%v", root.Level, root.ParentID)
+	}
+
+	child, err := s.CreateCategory(ctx, "tester", CategoryInput{
+		NameZH: "测试子", NameEN: ptr("Test Child"), ParentID: &root.ID,
+	})
+	if err != nil {
+		t.Fatalf("create child: %v", err)
+	}
+	if child.Level != 1 || child.ParentID == nil || *child.ParentID != root.ID {
+		t.Fatalf("child hierarchy wrong: %+v", child)
+	}
+
+	// Deleting a node with children must fail.
+	if err := s.DeleteCategory(ctx, root.ID, "tester"); !errors.Is(err, ErrCategoryHasChildren) {
+		t.Fatalf("expected ErrCategoryHasChildren, got %v", err)
+	}
+
+	// Rename child.
+	renamed, err := s.UpdateCategory(ctx, child.ID, "tester", CategoryInput{NameZH: "测试子-改名"})
+	if err != nil {
+		t.Fatalf("rename: %v", err)
+	}
+	if renamed.NameZH != "测试子-改名" {
+		t.Fatalf("rename not applied: %q", renamed.NameZH)
+	}
+
+	// Move child to a second root, descendants' path/level should follow.
+	root2, err := s.CreateCategory(ctx, "tester", CategoryInput{
+		NameZH: "测试根2", Slug: ptr("test_root2_" + randomHex(6)),
+	})
+	if err != nil {
+		t.Fatalf("create root2: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM category WHERE path <@ $1::ltree", root2.Path) })
+
+	moved, err := s.UpdateCategory(ctx, child.ID, "tester", CategoryInput{NameZH: "测试子-改名", ParentID: &root2.ID})
+	if err != nil {
+		t.Fatalf("move: %v", err)
+	}
+	if moved.ParentID == nil || *moved.ParentID != root2.ID {
+		t.Fatalf("move parent wrong: %+v", moved)
+	}
+	if moved.Level != 1 {
+		t.Fatalf("moved level wrong: %d", moved.Level)
+	}
+
+	// Moving a node under itself must be rejected.
+	if _, err := s.UpdateCategory(ctx, root2.ID, "tester", CategoryInput{NameZH: "测试根2", ParentID: &child.ID}); !errors.Is(err, ErrInvalidParent) {
+		t.Fatalf("expected ErrInvalidParent for self-move, got %v", err)
+	}
+
+	// Duplicate path on create must be rejected.
+	if _, err := s.CreateCategory(ctx, "tester", CategoryInput{NameZH: "dup", Slug: ptr(root.Path)}); !errors.Is(err, ErrDuplicatePath) {
+		t.Fatalf("expected ErrDuplicatePath, got %v", err)
+	}
+
+	// Now the leaf can be deleted.
+	if err := s.DeleteCategory(ctx, child.ID, "tester"); err != nil {
+		t.Fatalf("delete leaf: %v", err)
+	}
+}
+
+func TestSlugify(t *testing.T) {
+	cases := map[string]string{
+		"Cooking Oil":  "cooking_oil",
+		"  Hello--Wld": "hello_wld",
+		"食品":           "",
+		"a__b":         "a_b",
+	}
+	for in, want := range cases {
+		if got := slugify(in); got != want {
+			t.Errorf("slugify(%q) = %q, want %q", in, got, want)
+		}
+	}
+}

api/internal/adminstore/stats.go

@@ -0,0 +1,61 @@
+package adminstore
+
+import "context"
+
+// QualifiedMinScore is the quality_score threshold at or above which a product
+// counts as "qualified" (合格) in admin and public stats.
+const QualifiedMinScore = 0.6
+
+// AdminStats summarizes the catalog for the admin overview dashboard.
+type AdminStats struct {
+	Products   int            `json:"products"`
+	Qualified  int            `json:"qualified"`
+	MinScore   float64        `json:"min_score"`
+	ByStatus   map[string]int `json:"by_status"`
+	Brands     int            `json:"brands"`
+	Categories int            `json:"categories"`
+	Pending    int            `json:"pending_submissions"`
+	AvgQuality float64        `json:"avg_quality"`
+}
+
+// Stats gathers the dashboard counters in a handful of aggregate queries.
+func (s *Store) Stats(ctx context.Context) (*AdminStats, error) {
+	out := &AdminStats{MinScore: QualifiedMinScore, ByStatus: map[string]int{}}
+
+	if err := s.pool.QueryRow(ctx, `
+SELECT count(*),
+       count(*) FILTER (WHERE quality_score >= $1 AND status = 'active'),
+       COALESCE(avg(quality_score), 0)
+FROM product`, QualifiedMinScore).Scan(&out.Products, &out.Qualified, &out.AvgQuality); err != nil {
+		return nil, err
+	}
+
+	rows, err := s.pool.Query(ctx, "SELECT status, count(*) FROM product GROUP BY status")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var st string
+		var n int
+		if err := rows.Scan(&st, &n); err != nil {
+			return nil, err
+		}
+		out.ByStatus[st] = n
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM brand").Scan(&out.Brands); err != nil {
+		return nil, err
+	}
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM category").Scan(&out.Categories); err != nil {
+		return nil, err
+	}
+	if err := s.pool.QueryRow(ctx,
+		"SELECT count(*) FROM submission WHERE status = 'pending'").Scan(&out.Pending); err != nil {
+		return nil, err
+	}
+	return out, nil
+}

api/internal/adminstore/stats_bulk_test.go

@@ -0,0 +1,71 @@
+package adminstore
+
+import (
+	"context"
+	"testing"
+)
+
+func TestStatsAndBulk(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	base, err := s.Stats(ctx)
+	if err != nil {
+		t.Fatalf("stats: %v", err)
+	}
+
+	var p1, p2 string
+	if err := s.pool.QueryRow(ctx,
+		"INSERT INTO product (name, status) VALUES ($1,'active') RETURNING id",
+		"批量测试1 "+randomHex(4)).Scan(&p1); err != nil {
+		t.Fatalf("insert p1: %v", err)
+	}
+	if err := s.pool.QueryRow(ctx,
+		"INSERT INTO product (name, status) VALUES ($1,'active') RETURNING id",
+		"批量测试2 "+randomHex(4)).Scan(&p2); err != nil {
+		t.Fatalf("insert p2: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM product WHERE id = ANY($1)", []string{p1, p2}) })
+
+	after, err := s.Stats(ctx)
+	if err != nil {
+		t.Fatalf("stats after: %v", err)
+	}
+	if after.Products != base.Products+2 {
+		t.Fatalf("product count: got %d want %d", after.Products, base.Products+2)
+	}
+
+	// Bulk set status to deprecated.
+	n, err := s.BulkSetStatus(ctx, "tester", []string{p1, p2}, "deprecated")
+	if err != nil || n != 2 {
+		t.Fatalf("bulk status: n=%d err=%v", n, err)
+	}
+	var deprecated int
+	if err := s.pool.QueryRow(ctx,
+		"SELECT count(*) FROM product WHERE id = ANY($1) AND status='deprecated'",
+		[]string{p1, p2}).Scan(&deprecated); err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if deprecated != 2 {
+		t.Fatalf("expected 2 deprecated, got %d", deprecated)
+	}
+
+	// Invalid status rejected.
+	if _, err := s.BulkSetStatus(ctx, "tester", []string{p1}, "nope"); err != ErrInvalidStatus {
+		t.Fatalf("expected ErrInvalidStatus, got %v", err)
+	}
+
+	// Empty selection rejected.
+	if _, err := s.BulkSetStatus(ctx, "tester", nil, "active"); err != ErrNoTargets {
+		t.Fatalf("expected ErrNoTargets, got %v", err)
+	}
+
+	// Global audit log should contain the bulk_status entry.
+	rows, total, err := s.ListAllAudit(ctx, 10, 0)
+	if err != nil {
+		t.Fatalf("audit: %v", err)
+	}
+	if total == 0 || len(rows) == 0 {
+		t.Fatalf("expected audit rows, got total=%d", total)
+	}
+}

api/internal/adminstore/write.go

@@ -170,6 +170,79 @@ ON CONFLICT (product_id) DO UPDATE SET
 	return after, nil
 }
 
+// ErrDuplicateGTIN is returned when a product GTIN already exists.
+var ErrDuplicateGTIN = errors.New("duplicate gtin")
+
+// CreateProduct inserts a new product from the admin UI. Only the core fields
+// are required; the operator completes the rest in the detail editor.
+func (s *Store) CreateProduct(ctx context.Context, actor string, in ProductInput) (*ProductDetail, error) {
+	if strings.TrimSpace(in.Name) == "" {
+		return nil, errors.New("name required")
+	}
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	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
+	}
+
+	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 = "active"
+	}
+
+	var id string
+	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,$10)
+RETURNING id`,
+		in.GTIN, in.Name, brandID, in.CategoryID, gpc,
+		in.NetContentValue, in.NetContentUnit, canonical,
+		in.CountryOfOrigin, status).Scan(&id)
+	if isUniqueViolation(err) {
+		return nil, ErrDuplicateGTIN
+	}
+	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
+	}
+	_ = s.writeAudit(ctx, actor, "create", "product", &id, []string{"name"}, nil, after)
+	return after, nil
+}
+
 func strEq(a, b *string) bool {
 	if a == nil && b == nil {
 		return true
@@ -330,15 +403,21 @@ func (s *Store) DeleteMSRP(ctx context.Context, productID, msrpID, actor string)
 
 // ---------- dictionaries ----------
 
-// Brand is a brand option for the edit form.
+// Brand is a brand option for the edit form and the management view.
 type Brand struct {
-	ID   string `json:"id"`
+	ID           string `json:"id"`
-	Name string `json:"name"`
+	Name         string `json:"name"`
+	ProductCount int    `json:"product_count"`
 }
 
-// ListBrands returns all brands ordered by name.
+// ListBrands returns all brands ordered by name, with the number of products
+// referencing each one.
 func (s *Store) ListBrands(ctx context.Context) ([]Brand, error) {
-	rows, err := s.pool.Query(ctx, "SELECT id, name FROM brand ORDER BY name")
+	rows, err := s.pool.Query(ctx, `
+SELECT b.id, b.name,
+       (SELECT count(*) FROM product p WHERE p.brand_id = b.id) AS product_count
+FROM brand b
+ORDER BY b.name`)
 	if err != nil {
 		return nil, err
 	}
@@ -346,7 +425,7 @@ func (s *Store) ListBrands(ctx context.Context) ([]Brand, error) {
 	out := []Brand{}
 	for rows.Next() {
 		var b Brand
-		if err := rows.Scan(&b.ID, &b.Name); err != nil {
+		if err := rows.Scan(&b.ID, &b.Name, &b.ProductCount); err != nil {
 			return nil, err
 		}
 		out = append(out, b)
@@ -354,19 +433,27 @@ func (s *Store) ListBrands(ctx context.Context) ([]Brand, error) {
 	return out, rows.Err()
 }
 
-// Category is a category option for the edit form.
+// Category is a category option for the edit form and the management view.
 type Category struct {
-	ID     string  `json:"id"`
+	ID           string  `json:"id"`
-	NameZH string  `json:"name_zh"`
+	NameZH       string  `json:"name_zh"`
-	NameEN *string `json:"name_en"`
+	NameEN       *string `json:"name_en"`
-	Path   string  `json:"path"`
+	Path         string  `json:"path"`
-	Level  int     `json:"level"`
+	Level        int     `json:"level"`
+	ParentID     *string `json:"parent_id"`
+	GPCBrickCode *string `json:"gpc_brick_code"`
+	ProductCount int     `json:"product_count"`
 }
 
-// ListCategories returns the full category tree.
+// ListCategories returns the full category tree (path order) with the number of
+// products directly assigned to each node.
 func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
-	rows, err := s.pool.Query(ctx,
+	rows, err := s.pool.Query(ctx, `
-		"SELECT id, name_zh, name_en, path::text, level FROM category ORDER BY path")
+SELECT c.id, c.name_zh, c.name_en, c.path::text, c.level, c.parent_id::text,
+       c.gpc_brick_code,
+       (SELECT count(*) FROM product p WHERE p.category_id = c.id) AS product_count
+FROM category c
+ORDER BY c.path`)
 	if err != nil {
 		return nil, err
 	}
@@ -374,7 +461,8 @@ func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
 	out := []Category{}
 	for rows.Next() {
 		var c Category
-		if err := rows.Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level); err != nil {
+		if err := rows.Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level,
+			&c.ParentID, &c.GPCBrickCode, &c.ProductCount); err != nil {
 			return nil, err
 		}
 		out = append(out, c)
@@ -393,6 +481,44 @@ type AuditEntry struct {
 	CreatedAt string   `json:"created_at"`
 }
 
+// AuditLogRow is one global audit-log row for the operations log view.
+type AuditLogRow struct {
+	ID        string   `json:"id"`
+	Actor     string   `json:"actor"`
+	Action    string   `json:"action"`
+	Entity    string   `json:"entity"`
+	EntityID  *string  `json:"entity_id"`
+	Fields    []string `json:"fields"`
+	CreatedAt string   `json:"created_at"`
+}
+
+// ListAllAudit returns a page of the global audit log, newest first, along with
+// the total row count.
+func (s *Store) ListAllAudit(ctx context.Context, limit, offset int) ([]AuditLogRow, int, error) {
+	var total int
+	if err := s.pool.QueryRow(ctx, "SELECT count(*) FROM audit_log").Scan(&total); err != nil {
+		return nil, 0, err
+	}
+	rows, err := s.pool.Query(ctx, `
+SELECT id, actor, action, entity, entity_id::text, fields, created_at::text
+FROM audit_log
+ORDER BY created_at DESC
+LIMIT $1 OFFSET $2`, limit, offset)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+	out := []AuditLogRow{}
+	for rows.Next() {
+		var e AuditLogRow
+		if err := rows.Scan(&e.ID, &e.Actor, &e.Action, &e.Entity, &e.EntityID, &e.Fields, &e.CreatedAt); err != nil {
+			return nil, 0, err
+		}
+		out = append(out, e)
+	}
+	return out, total, rows.Err()
+}
+
 // 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, `

api/internal/handler/handler.go

@@ -5,6 +5,7 @@
 package handler
 
 import (
+	_ "embed"
 	"encoding/json"
 	"errors"
 	"io/fs"
@@ -19,9 +20,16 @@ import (
 	"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"
 
+// QualifiedMinScore is the quality_score threshold at or above which a product
+// record is considered "qualified" (合格) for public stats.
+const QualifiedMinScore = 0.6
+
 const (
 	defaultPageSize = 20
 	maxPageSize     = 100
@@ -66,17 +74,23 @@ func (h *Handler) Router() http.Handler {
 	r.Get("/healthz", h.Healthz)
 
 	r.Route("/api/"+APIVersion, func(r chi.Router) {
-		r.Use(h.rateLimit)
+		// Machine-readable spec; not rate limited so tooling can always fetch it.
-		r.Route("/products", func(r chi.Router) {
+		r.Get("/openapi.json", h.OpenAPI)
-			r.Get("/barcode/{gtin}", h.ProductByBarcode)
+
-			r.Get("/search", h.SearchProducts)
+		r.Group(func(r chi.Router) {
-			r.Get("/{id}", h.ProductByID)
+			r.Use(h.rateLimit)
-			r.Get("/{id}/nutriments", h.ProductNutriments)
+			r.Route("/products", func(r chi.Router) {
-			r.Get("/{id}/msrp", h.ProductMSRP)
+				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("/stats", h.Stats)
 		})
-		r.Get("/brands", h.ListBrands)
-		r.Get("/categories", h.ListCategories)
-		r.Get("/sources/{id}", h.SourceByID)
 	})
 
 	// Public SPA (homepage + search + contribute). API routes above take
@@ -113,6 +127,21 @@ func (h *Handler) Healthz(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
 }
 
+// Stats returns catalog totals and the count of qualified records.
+func (h *Handler) Stats(w http.ResponseWriter, r *http.Request) {
+	st, err := h.store.Stats(r.Context(), QualifiedMinScore)
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, st)
+}
+
+// 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"))
@@ -131,13 +160,19 @@ func (h *Handler) ProductByID(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, p)
 }
 
-// SearchProducts runs a fuzzy name search with optional category filter + paging.
+// 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) {
-	q := r.URL.Query().Get("q")
+	qv := r.URL.Query()
-	category := r.URL.Query().Get("category")
+	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(), q, category, size, (page-1)*size)
+	items, total, err := h.store.SearchProducts(r.Context(), filters, size, (page-1)*size)
 	if h.handleErr(w, r, err) {
 		return
 	}

api/internal/handler/handler_db_test.go

@@ -116,6 +116,101 @@ func TestSearchProducts(t *testing.T) {
 	}
 }
 
+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")

api/internal/handler/openapi.json

@@ -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 }
+        }
+      }
+    }
+  }
+}

api/internal/store/store.go

@@ -29,6 +29,24 @@ func (s *Store) Ping(ctx context.Context) error {
 	return s.pool.Ping(ctx)
 }
 
+// PublicStats summarizes the public catalog for the homepage.
+type PublicStats struct {
+	Total     int     `json:"total"`
+	Qualified int     `json:"qualified"`
+	MinScore  float64 `json:"min_score"`
+}
+
+// Stats returns active-product totals and the number of qualified records whose
+// quality_score meets minScore.
+func (s *Store) Stats(ctx context.Context, minScore float64) (PublicStats, error) {
+	st := PublicStats{MinScore: minScore}
+	err := s.pool.QueryRow(ctx, `
+SELECT count(*) FILTER (WHERE status = 'active'),
+       count(*) FILTER (WHERE status = 'active' AND quality_score >= $1)
+FROM product`, minScore).Scan(&st.Total, &st.Qualified)
+	return st, err
+}
+
 // Barcode is one GS1 trade item number attached to a product.
 type Barcode struct {
 	GTIN      string  `json:"gtin"`
@@ -82,11 +100,22 @@ func (s *Store) ProductBarcodes(ctx context.Context, productID string) ([]Barcod
 
 // ProductSummary is a lightweight row used in search/listing responses.
 type ProductSummary struct {
-	ID           string  `json:"id"`
+	ID           string   `json:"id"`
-	GTIN         *string `json:"gtin"`
+	GTIN         *string  `json:"gtin"`
-	Name         string  `json:"name"`
+	Name         string   `json:"name"`
-	Brand        *string `json:"brand"`
+	Brand        *string  `json:"brand"`
-	CategoryPath *string `json:"category_path"`
+	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 = `
@@ -148,34 +177,67 @@ func (s *Store) ProductByID(ctx context.Context, id string) (*Product, error) {
 	return p, nil
 }
 
-// SearchProducts performs a fuzzy name search with optional category subtree filter.
+// fuzzyThreshold is the minimum word_similarity for a name to be considered a
-func (s *Store) SearchProducts(ctx context.Context, q, category string, limit, offset int) ([]ProductSummary, int, error) {
+// 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'"
-	if q != "" {
+
-		args = append(args, q)
+	qIdx := 0
-		where += ` AND (p.name ILIKE '%' || $1 || '%'
+	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 '%' || $1 || '%'))`
+			           WHERE pb.product_id = p.id AND pb.gtin ILIKE '%' || ` + q + ` || '%'))`
 	}
-	if category != "" {
+	if f.Category != "" {
-		args = append(args, 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 `
 
-	countSQL := "SELECT count(*) FROM product p LEFT JOIN category c ON c.id = p.category_id " + where
 	var total int
-	if err := s.pool.QueryRow(ctx, countSQL, args...).Scan(&total); err != nil {
+	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 := `
+	listSQL := "SELECT p.id, p.gtin, p.name, b.name, c.path::text, p.country_of_origin, p.quality_score, " +
-SELECT p.id, p.gtin, p.name, b.name, c.path::text
+		scoreExpr + " AS score " + from + where +
-FROM product p
+		" ORDER BY " + orderBy +
-LEFT JOIN brand b ON b.id = p.brand_id
+		" LIMIT $" + strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
-LEFT JOIN category c ON c.id = p.category_id ` + where +
-		" ORDER BY p.name LIMIT $" + strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
 
 	rows, err := s.pool.Query(ctx, listSQL, args...)
 	if err != nil {
@@ -186,7 +248,8 @@ LEFT JOIN category c ON c.id = p.category_id ` + where +
 	out := []ProductSummary{}
 	for rows.Next() {
 		var ps ProductSummary
-		if err := rows.Scan(&ps.ID, &ps.GTIN, &ps.Name, &ps.Brand, &ps.CategoryPath); err != nil {
+		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)

docs/api.md

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

migrations/0009_search.down.sql

@@ -0,0 +1,2 @@
+DROP INDEX IF EXISTS idx_product_country;
+DROP INDEX IF EXISTS idx_brand_name_trgm;

migrations/0009_search.up.sql

@@ -0,0 +1,9 @@
+-- Search upgrade: trigram-based fuzzy matching + brand/country filters.
+-- pg_trgm and the product.name GIN index already exist (see 0001). Add a
+-- matching trigram index on brand.name so brand filtering / fuzzy brand
+-- lookups can use an index instead of a sequential scan.
+CREATE INDEX IF NOT EXISTS idx_brand_name_trgm ON brand USING gin (name gin_trgm_ops);
+
+-- country_of_origin is filtered by exact/prefix match; a plain btree index
+-- keeps that cheap as the catalog grows.
+CREATE INDEX IF NOT EXISTS idx_product_country ON product (country_of_origin);

public-frontend/src/App.tsx

@@ -1,9 +1,10 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { Boxes, Search, PlusCircle, Code2 } from "lucide-react";
 import Home from "./components/Home";
 import ProductView from "./components/ProductView";
 import Contribute from "./components/Contribute";
 import ApiDocs from "./components/ApiDocs";
+import { api } from "./api";
 
 type View =
   | { name: "home" }
@@ -13,6 +14,14 @@ type View =
 
 export default function App() {
   const [view, setView] = useState<View>({ name: "home" });
+  const [qualified, setQualified] = useState<number | null>(null);
+
+  useEffect(() => {
+    api
+      .stats()
+      .then((s) => setQualified(s.qualified))
+      .catch(() => setQualified(null));
+  }, []);
 
   return (
     <div className="min-h-full flex flex-col">
@@ -72,9 +81,17 @@ export default function App() {
       </main>
 
       <footer className="border-t bg-white">
-        <div className="max-w-5xl mx-auto px-4 py-4 text-xs text-gray-400 leading-relaxed">
+        <div className="max-w-5xl mx-auto px-4 py-4 text-xs text-gray-400 leading-relaxed text-center">
-          天工商品档案公共仓 是公益性「商品事实库」，仅收录客观商品信息（条码、品牌、品类、营养、官方建议零售价快照等），不含任何购买/交易功能。
+          {qualified != null && (
-          公众投稿须经人工审核后方可收纳。
+            <div className="mb-2 text-gray-500">
+              目前已收录
+              <span className="mx-1 font-semibold text-emerald-600">
+                {qualified.toLocaleString()}
+              </span>
+              条合格商品档案
+            </div>
+          )}
+          天工是一个公益性商品档案库。主要收录商品名称，条码，品类，配料等官方快照。不涉及任何交易行为。
           <button onClick={() => setView({ name: "api" })} className="ml-1 text-emerald-600 hover:underline">
             API 调用说明
           </button>

public-frontend/src/api.ts

@@ -25,11 +25,29 @@ export interface SearchResult {
   total: number;
 }
 
+export interface SearchFilters {
+  brand?: string;
+  country?: string;
+}
+
+export interface Stats {
+  total: number;
+  qualified: number;
+  min_score: number;
+}
+
 export const api = {
-  search: (q: string, page = 1, size = 20) =>
+  stats: () => req<Stats>(`/api/v1/stats`),
-    req<SearchResult>(
+  search: (q: string, page = 1, size = 20, filters: SearchFilters = {}) => {
-      `/api/v1/products/search?q=${encodeURIComponent(q)}&page=${page}&size=${size}`,
+    const params = new URLSearchParams({
-    ),
+      q,
+      page: String(page),
+      size: String(size),
+    });
+    if (filters.brand) params.set("brand", filters.brand);
+    if (filters.country) params.set("country", filters.country);
+    return req<SearchResult>(`/api/v1/products/search?${params.toString()}`);
+  },
   product: (id: string) => req<Product>(`/api/v1/products/${id}`),
   categories: () => req<{ items: Category[] }>(`/api/v1/categories`),
   submit: (input: SubmissionInput) =>

public-frontend/src/components/ApiDocs.tsx

@@ -117,7 +117,7 @@ export default function ApiDocs() {
             基础地址：<code className="font-mono bg-gray-100 rounded px-1.5 py-0.5">{BASE}</code>
           </div>
           <ul className="mt-2 list-disc pl-5 text-gray-600 space-y-1">
-            <li>无需 API Key / Token，直接 GET 即可。</li>
+            <li>无需 API Key / Token 即可直接 GET；带 Key 可获得更高频率上限（见下文「鉴权与限流」）。</li>
             <li>
               分页参数 <code className="font-mono">page</code>（默认 1）、
               <code className="font-mono">size</code>（默认 20，最大 100）。
@@ -131,6 +131,53 @@ export default function ApiDocs() {
         </div>
       </div>
 
+      <div className="bg-white border rounded-lg p-5">
+        <h2 className="text-lg font-semibold text-gray-800">鉴权与限流</h2>
+        <p className="mt-2 text-gray-600 text-sm leading-relaxed">
+          API 默认<strong>匿名可用</strong>：无需任何凭证即可调用，按来源 IP 计入一个较低的默认频率额度。
+          如需更高额度并让用量归属到你，可在运营方申请一枚 API Key，请求时通过请求头携带：
+        </p>
+        <div className="mt-3">
+          <Code>{`# 二选一
+curl -H "X-API-Key: og_live_xxxxxxxx" ${BASE}/products/search?q=牛奶
+curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛奶`}</Code>
+        </div>
+        <p className="mt-3 text-gray-600 text-sm leading-relaxed">
+          采用<strong>固定窗口</strong>限流（每分钟）。每个响应都会回写以下响应头，便于客户端自适应：
+        </p>
+        <table className="mt-3 w-full text-sm">
+          <thead className="text-gray-400 text-left">
+            <tr>
+              <th className="font-medium pr-4 pb-1">响应头</th>
+              <th className="font-medium pb-1">含义</th>
+            </tr>
+          </thead>
+          <tbody className="align-top">
+            <tr>
+              <td className="pr-4 py-0.5 font-mono text-gray-700">X-RateLimit-Limit</td>
+              <td className="py-0.5 text-gray-600">当前窗口允许的最大请求数</td>
+            </tr>
+            <tr>
+              <td className="pr-4 py-0.5 font-mono text-gray-700">X-RateLimit-Remaining</td>
+              <td className="py-0.5 text-gray-600">当前窗口剩余可用次数</td>
+            </tr>
+            <tr>
+              <td className="pr-4 py-0.5 font-mono text-gray-700">X-RateLimit-Reset</td>
+              <td className="py-0.5 text-gray-600">窗口重置的 Unix 时间戳（秒）</td>
+            </tr>
+            <tr>
+              <td className="pr-4 py-0.5 font-mono text-gray-700">Retry-After</td>
+              <td className="py-0.5 text-gray-600">超额时返回，建议等待的秒数</td>
+            </tr>
+          </tbody>
+        </table>
+        <p className="mt-3 text-gray-600 text-sm leading-relaxed">
+          超过额度返回 <code className="font-mono">429 Too Many Requests</code>，错误码
+          <code className="font-mono">rate_limited</code>；无效或已吊销的 Key 返回
+          <code className="font-mono">401</code>，错误码 <code className="font-mono">invalid_api_key</code>。
+        </p>
+      </div>
+
       <Endpoint
         method="GET"
         path="/healthz"
@@ -164,19 +211,24 @@ export default function ApiDocs() {
         method="GET"
         path="/api/v1/products/search"
         title="搜索商品"
-        desc="按名称模糊搜索，可按品类过滤，支持分页。"
+        desc="按名称做三元组（trigram）模糊搜索，可容忍错别字；支持品类/品牌/产地过滤；结果按相关度（名称相似度 × 数据质量分）排序。"
         params={[
-          { name: "q", desc: "关键词（名称/条码），留空返回全部" },
+          { name: "q", desc: "关键词（名称/条码），支持模糊匹配；留空则按质量分返回全部" },
-          { name: "category", desc: "品类编码过滤，如 food.beverages" },
+          { name: "category", desc: "品类编码（含子树），如 food.beverages" },
+          { name: "brand", desc: "品牌名（模糊匹配），如 Ferrero" },
+          { name: "country", desc: "产地前缀（不区分大小写），如 China" },
           { name: "page", desc: "页码，默认 1" },
           { name: "size", desc: "每页条数，默认 20，最大 100" },
         ]}
-        example={`curl "${BASE}/products/search?q=nutella&page=1&size=20"`}
+        example={`curl "${BASE}/products/search?q=nutela&country=Italy&page=1&size=20"`}
         response={`{
   "items": [
     { "id": "…", "gtin": "3017624010701",
       "name": "Nutella", "brand": "Ferrero",
-      "category_path": "food.snacks.chocolate" }
+      "category_path": "food.snacks.chocolate",
+      "country_of_origin": "Italy",
+      "quality_score": 0.81,
+      "score": 0.71 }
   ],
   "page": 1, "size": 20, "total": 1
 }`}

public-frontend/src/components/Home.tsx

@@ -38,7 +38,7 @@ export default function Home({
   return (
     <div>
       <div className="text-center py-10">
-        <h1 className="text-3xl font-bold text-gray-800">天工商品档案公共仓</h1>
+        <h1 className="text-3xl font-bold text-gray-800">天工</h1>
         <p className="mt-2 text-gray-500">
           输入商品名称或条码，检索客观、可溯源的商品资料。人人可查，人人可贡献。
         </p>
@@ -105,7 +105,12 @@ export default function Home({
                         {p.gtin ? ` · ${p.gtin}` : ""}
                       </div>
                     </div>
-                    <span className="text-xs text-gray-400">{p.category_path || ""}</span>
+                    <span className="text-xs text-gray-400 text-right">
+                      <span className="block">{p.category_path || ""}</span>
+                      {p.country_of_origin ? (
+                        <span className="block text-gray-400">产地：{p.country_of_origin}</span>
+                      ) : null}
+                    </span>
                   </button>
                 </li>
               ))}

public-frontend/src/types.ts

@@ -4,6 +4,9 @@ export interface ProductSummary {
   name: string;
   brand: string | null;
   category_path: string | null;
+  country_of_origin?: string | null;
+  quality_score?: number;
+  score?: number | null;
 }
 
 export interface Barcode {