fix: 端口占用时自动选择可用端口，不再闪退

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

admin-frontend/src/App.tsx

@@ -28,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;
@@ -190,9 +191,19 @@ export default function App() {
         ) : 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

@@ -51,14 +51,23 @@ export const api = {
       body: JSON.stringify({ username, password }),
     }),
   me: () => request<{ username: string }>("/me"),
-  listProducts: (q: string, page: number, size: number) =>
+  listProducts: (
+    q: string,
+    page: number,
+    size: number,
+    sort?: string,
+    order?: string,
+  ) =>
     request<{
       items: import("./types").ProductRow[];
       page: number;
       size: number;
       total: number;
       completeness_fields: string[];
-    }>(`/products?q=${encodeURIComponent(q)}&page=${page}&size=${size}`),
+    }>(
+      `/products?q=${encodeURIComponent(q)}&page=${page}&size=${size}` +
+        (sort ? `&sort=${sort}&order=${order || "asc"}` : ""),
+    ),
   getProduct: (id: string) =>
     request<import("./types").ProductDetail>(`/products/${id}`),
   createProduct: (body: unknown) =>
@@ -124,6 +133,10 @@ export const api = {
     }),
   deleteBrand: (id: string) =>
     request<{ status: string }>(`/brands/${id}`, { method: "DELETE" }),
+  listKindFields: (kind: string) =>
+    request<{ items: import("./types").KindField[]; kind: string }>(
+      `/kind-fields?kind=${encodeURIComponent(kind)}`,
+    ),
   listCategories: () =>
     request<{ items: import("./types").Category[] }>("/categories"),
   createCategory: (body: import("./types").CategoryInput) =>
@@ -164,6 +177,7 @@ export const api = {
     owner_email?: string;
     tier?: string;
     rate_limit_per_min?: number;
+    quota_total?: number;
   }) =>
     request<{ key: string; item: import("./types").ApiKey; warning: string }>(
       "/keys",

admin-frontend/src/components/ApiKeysPage.tsx

@@ -4,9 +4,10 @@ import type { ApiKey } from "../types";
 import { Copy, KeyRound, Plus, Trash2 } from "lucide-react";
 
 const TIERS = [
-  { key: "free", label: "免费 (free)", rate: 120 },
-  { key: "partner", label: "合作方 (partner)", rate: 600 },
-  { key: "internal", label: "内部 (internal)", rate: 6000 },
+  { key: "free", label: "免费 (free)", rate: 120, quota: 1000 },
+  { key: "registered", label: "注册用户 (registered)", rate: 300, quota: 100000 },
+  { key: "partner", label: "合作方 (partner)", rate: 600, quota: 0 },
+  { key: "internal", label: "内部 (internal)", rate: 6000, quota: 0 },
 ];
 
 function tierLabel(tier: string): string {
@@ -111,6 +112,7 @@ export default function ApiKeysPage() {
               <th className="px-4 py-2 font-medium">级别</th>
               <th className="px-4 py-2 font-medium">速率/分钟</th>
               <th className="px-4 py-2 font-medium">用量(今日/累计)</th>
+              <th className="px-4 py-2 font-medium">累计配额</th>
               <th className="px-4 py-2 font-medium">状态</th>
               <th className="px-4 py-2 font-medium"></th>
             </tr>
@@ -118,7 +120,7 @@ export default function ApiKeysPage() {
           <tbody className="divide-y">
             {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>
@@ -139,6 +141,15 @@ export default function ApiKeysPage() {
                   <td className="px-4 py-2 text-gray-600">
                     {k.usage.today} / {k.usage.total}
                   </td>
+                  <td className="px-4 py-2 text-gray-600">
+                    {k.quota_total > 0 ? (
+                      <span className={k.usage.total >= k.quota_total ? "text-red-600" : ""}>
+                        {k.usage.total.toLocaleString()} / {k.quota_total.toLocaleString()}
+                      </span>
+                    ) : (
+                      <span className="text-gray-400">不限</span>
+                    )}
+                  </td>
                   <td className="px-4 py-2">
                     {k.revoked_at ? (
                       <span className="text-xs rounded px-2 py-0.5 bg-red-50 text-red-700">
@@ -182,13 +193,17 @@ function CreateKeyForm({
   const [ownerEmail, setOwnerEmail] = useState("");
   const [tier, setTier] = useState("free");
   const [rate, setRate] = useState(120);
+  const [quota, setQuota] = useState(1000);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState("");
 
   function pickTier(t: string) {
     setTier(t);
     const def = TIERS.find((x) => x.key === t);
-    if (def) setRate(def.rate);
+    if (def) {
+      setRate(def.rate);
+      setQuota(def.quota);
+    }
   }
 
   async function submit() {
@@ -204,6 +219,7 @@ function CreateKeyForm({
         owner_email: ownerEmail.trim() || undefined,
         tier,
         rate_limit_per_min: rate,
+        quota_total: quota,
       });
       onCreated(res.key);
     } catch (e) {
@@ -260,6 +276,16 @@ function CreateKeyForm({
             onChange={(e) => setRate(Math.max(1, parseInt(e.target.value || "1", 10)))}
           />
         </label>
+        <label className="block">
+          <span className="text-xs text-gray-500">累计配额（总调用次数，0=不限）</span>
+          <input
+            type="number"
+            min={0}
+            className="w-full border rounded-md px-3 py-2 text-sm mt-1"
+            value={quota}
+            onChange={(e) => setQuota(Math.max(0, parseInt(e.target.value || "0", 10)))}
+          />
+        </label>
       </div>
       <div className="mt-4 flex gap-2">
         <button

admin-frontend/src/components/ProductDetail.tsx

@@ -5,10 +5,13 @@ import {
   Brand,
   Category,
   FIELD_LABELS,
+  KindField,
   ProductDetail as Detail,
 } from "../types";
 import {
   ArrowLeft,
+  ChevronLeft,
+  ChevronRight,
   Plus,
   Save,
   Trash2,
@@ -88,10 +91,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[]>([]);
@@ -117,6 +128,8 @@ export default function ProductDetail({
   const [basis, setBasis] = useState("");
   const [serving, setServing] = useState("");
   const [nutriScore, setNutriScore] = useState("");
+  const [kindFields, setKindFields] = useState<KindField[]>([]);
+  const [attrs, setAttrs] = useState<Record<string, string>>({});
 
   function hydrate(detail: Detail) {
     setD(detail);
@@ -139,6 +152,13 @@ export default function ProductDetail({
     setBasis(detail.nutrition_basis || "");
     setServing(detail.serving_size || "");
     setNutriScore(detail.nutri_score || "");
+    const am: Record<string, string> = {};
+    if (detail.attributes) {
+      for (const [k, v] of Object.entries(detail.attributes)) {
+        am[k] = v == null ? "" : Array.isArray(v) ? v.join(", ") : String(v);
+      }
+    }
+    setAttrs(am);
   }
 
   function reload() {
@@ -161,6 +181,41 @@ export default function ProductDetail({
 
   const missing = useMemo(() => d?.missing ?? [], [d]);
 
+  const selectedKind = useMemo(() => {
+    const c = categories.find((x) => x.id === categoryId);
+    return c?.archive_kind || d?.archive_kind || "generic";
+  }, [categories, categoryId, d]);
+
+  useEffect(() => {
+    if (selectedKind && selectedKind !== "food") {
+      api
+        .listKindFields(selectedKind)
+        .then((r) => setKindFields(r.items))
+        .catch(() => setKindFields([]));
+    } else {
+      setKindFields([]);
+    }
+  }, [selectedKind]);
+
+  const specGroups = useMemo(() => {
+    const groups: { label: string; fields: KindField[] }[] = [];
+    for (const f of kindFields) {
+      let g = groups.find((x) => x.label === f.group_label);
+      if (!g) {
+        g = { label: f.group_label, fields: [] };
+        groups.push(g);
+      }
+      g.fields.push(f);
+    }
+    return groups;
+  }, [kindFields]);
+
+  const attrLabels = useMemo(() => {
+    const m: Record<string, string> = {};
+    for (const f of kindFields) m[f.field_key] = f.label_zh;
+    return m;
+  }, [kindFields]);
+
   function parseList(s: string): string[] {
     return s
       .split(",")
@@ -177,6 +232,22 @@ export default function ProductDetail({
       const n = parseFloat(v);
       if (!Number.isNaN(n)) nm[k] = n;
     }
+    let attributes: Record<string, unknown> | undefined;
+    if (selectedKind !== "food") {
+      attributes = {};
+      for (const f of kindFields) {
+        const raw = (attrs[f.field_key] ?? "").trim();
+        if (raw === "") continue;
+        if (f.field_type === "number") {
+          const n = parseFloat(raw);
+          if (!Number.isNaN(n)) attributes[f.field_key] = n;
+        } else if (f.field_type === "list") {
+          attributes[f.field_key] = parseList(raw);
+        } else {
+          attributes[f.field_key] = raw;
+        }
+      }
+    }
     const body = {
       gtin: gtin.trim() || null,
       name: name.trim(),
@@ -194,6 +265,7 @@ export default function ProductDetail({
       nutrition_basis: basis || null,
       serving_size: serving.trim() || null,
       nutri_score: nutriScore || null,
+      ...(attributes !== undefined ? { attributes } : {}),
     };
     try {
       const updated = await api.updateProduct(id, body);
@@ -226,12 +298,35 @@ export default function ProductDetail({
   return (
     <div className="mx-auto max-w-5xl space-y-5">
       <div className="flex items-center justify-between">
-        <button
-          onClick={onBack}
-          className="flex items-center gap-1 text-sm text-gray-600 hover:text-gray-900"
-        >
-          <ArrowLeft className="h-4 w-4" /> 返回列表
-        </button>
+        <div className="flex items-center gap-2">
+          <button
+            onClick={onBack}
+            className="flex items-center gap-1 text-sm text-gray-600 hover:text-gray-900"
+          >
+            <ArrowLeft className="h-4 w-4" /> 返回列表
+          </button>
+          {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>}
@@ -251,7 +346,8 @@ export default function ProductDetail({
       {missing.length > 0 && (
         <div className="flex items-center gap-2 rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-700">
           <AlertCircle className="h-4 w-4" />
-          待补全字段：{missing.map((f) => FIELD_LABELS[f] || f).join("、")}
+          待补全字段：
+          {missing.map((f) => FIELD_LABELS[f] || attrLabels[f] || f).join("、")}
         </div>
       )}
 
@@ -338,6 +434,7 @@ export default function ProductDetail({
         </div>
       </Card>
 
+      {selectedKind === "food" && (
       <Card title="配料与营养">
         <div className="mb-4 grid grid-cols-2 gap-4">
           <Field label="配料表">
@@ -410,6 +507,75 @@ export default function ProductDetail({
           ))}
         </div>
       </Card>
+      )}
+
+      {selectedKind !== "food" && kindFields.length > 0 && (
+        <Card title="规格参数">
+          {specGroups.map((grp) => (
+            <div key={grp.label} className="mb-4 last:mb-0">
+              {grp.label && (
+                <h4 className="mb-2 text-xs font-medium text-gray-500">
+                  {grp.label}
+                </h4>
+              )}
+              <div className="grid grid-cols-3 gap-3">
+                {grp.fields.map((f) => (
+                  <Field
+                    key={f.field_key}
+                    label={f.unit ? `${f.label_zh} (${f.unit})` : f.label_zh}
+                  >
+                    {f.field_type === "select" ? (
+                      <select
+                        className={inputCls}
+                        value={attrs[f.field_key] ?? ""}
+                        onChange={(e) =>
+                          setAttrs((prev) => ({
+                            ...prev,
+                            [f.field_key]: e.target.value,
+                          }))
+                        }
+                      >
+                        <option value="">（未设置）</option>
+                        {f.options.map((o) => (
+                          <option key={o} value={o}>
+                            {o}
+                          </option>
+                        ))}
+                      </select>
+                    ) : f.field_type === "textarea" ? (
+                      <textarea
+                        className={inputCls}
+                        rows={3}
+                        value={attrs[f.field_key] ?? ""}
+                        onChange={(e) =>
+                          setAttrs((prev) => ({
+                            ...prev,
+                            [f.field_key]: e.target.value,
+                          }))
+                        }
+                      />
+                    ) : (
+                      <input
+                        className={inputCls}
+                        type={f.field_type === "number" ? "number" : "text"}
+                        step={f.field_type === "number" ? "any" : undefined}
+                        placeholder={f.placeholder ?? undefined}
+                        value={attrs[f.field_key] ?? ""}
+                        onChange={(e) =>
+                          setAttrs((prev) => ({
+                            ...prev,
+                            [f.field_key]: e.target.value,
+                          }))
+                        }
+                      />
+                    )}
+                  </Field>
+                ))}
+              </div>
+            </div>
+          ))}
+        </Card>
+      )}
 
       <BarcodesCard product={d} onChange={reload} onError={setError} />
       <ImagesCard

admin-frontend/src/components/ProductList.tsx

@@ -1,7 +1,15 @@
 import { useEffect, useState } from "react";
 import { api, ApiError } from "../api";
 import { Brand, Category, FIELD_LABELS, ProductRow } from "../types";
-import { Search, AlertCircle, Plus } from "lucide-react";
+import { Search, AlertCircle, Plus, ChevronUp, ChevronDown, ChevronsUpDown } from "lucide-react";
+
+type SortKey =
+  | "name"
+  | "brand"
+  | "gtin"
+  | "category_path"
+  | "status"
+  | "quality_score";
 
 const STATUS_LABEL: Record<string, string> = {
   active: "在用",
@@ -24,15 +32,54 @@ function QualityBadge({ score }: { score: number }) {
   );
 }
 
+function SortableTh({
+  label,
+  sortKey,
+  sort,
+  order,
+  onSort,
+}: {
+  label: string;
+  sortKey: SortKey;
+  sort: SortKey | "";
+  order: "asc" | "desc";
+  onSort: (key: SortKey) => void;
+}) {
+  const active = sort === sortKey;
+  return (
+    <th className="px-4 py-3">
+      <button
+        type="button"
+        onClick={() => onSort(sortKey)}
+        className={`flex items-center gap-1 uppercase hover:text-gray-700 ${
+          active ? "text-emerald-600" : ""
+        }`}
+      >
+        {label}
+        {!active ? (
+          <ChevronsUpDown className="h-3.5 w-3.5 text-gray-300" />
+        ) : order === "asc" ? (
+          <ChevronUp className="h-3.5 w-3.5" />
+        ) : (
+          <ChevronDown className="h-3.5 w-3.5" />
+        )}
+      </button>
+    </th>
+  );
+}
+
 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 [sort, setSort] = useState<SortKey | "">("");
+  const [order, setOrder] = useState<"asc" | "desc">("asc");
+  const [jump, setJump] = useState("");
   const [rows, setRows] = useState<ProductRow[]>([]);
   const [total, setTotal] = useState(0);
   const [loading, setLoading] = useState(false);
@@ -48,7 +95,7 @@ export default function ProductList({
     setLoading(true);
     setError("");
     api
-      .listProducts(q, page, size)
+      .listProducts(q, page, size, sort || undefined, order)
       .then((r) => {
         setRows(r.items);
         setTotal(r.total);
@@ -60,7 +107,20 @@ export default function ProductList({
   useEffect(() => {
     setSelected(new Set());
     reload();
-  }, [q, page, size]);
+  }, [q, page, size, sort, order]);
+
+  function toggleSort(key: SortKey) {
+    setPage(1);
+    if (sort !== key) {
+      setSort(key);
+      setOrder("asc");
+    } else if (order === "asc") {
+      setOrder("desc");
+    } else {
+      setSort("");
+      setOrder("asc");
+    }
+  }
 
   useEffect(() => {
     api.listCategories().then((r) => setCategories(r.items)).catch(() => {});
@@ -164,7 +224,7 @@ export default function ProductList({
           onClose={() => setCreating(false)}
           onCreated={(id) => {
             setCreating(false);
-            onOpen(id);
+            onOpen(id, [id]);
           }}
         />
       )}
@@ -244,12 +304,12 @@ export default function ProductList({
                   aria-label="全选"
                 />
               </th>
-              <th className="px-4 py-3">名称</th>
-              <th className="px-4 py-3">品牌</th>
-              <th className="px-4 py-3">条码</th>
-              <th className="px-4 py-3">品类</th>
-              <th className="px-4 py-3">状态</th>
-              <th className="px-4 py-3">质量分</th>
+              <SortableTh label="名称" sortKey="name" sort={sort} order={order} onSort={toggleSort} />
+              <SortableTh label="品牌" sortKey="brand" sort={sort} order={order} onSort={toggleSort} />
+              <SortableTh label="条码" sortKey="gtin" sort={sort} order={order} onSort={toggleSort} />
+              <SortableTh label="品类" sortKey="category_path" sort={sort} order={order} onSort={toggleSort} />
+              <SortableTh label="状态" sortKey="status" sort={sort} order={order} onSort={toggleSort} />
+              <SortableTh label="质量分" sortKey="quality_score" sort={sort} order={order} onSort={toggleSort} />
               <th className="px-4 py-3">缺失字段</th>
             </tr>
           </thead>
@@ -270,7 +330,7 @@ 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 ${
                     selected.has(r.id) ? "bg-emerald-50/60" : ""
                   }`}
@@ -319,7 +379,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)}
@@ -337,6 +415,32 @@ 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>
   );

admin-frontend/src/types.ts

@@ -44,6 +44,8 @@ export interface ProductDetail {
   brand: string | null;
   category_id: string | null;
   category_path: string | null;
+  archive_kind: string;
+  attributes: Record<string, unknown>;
   net_content_value: number | null;
   net_content_unit: string | null;
   country_of_origin: string | null;
@@ -77,9 +79,23 @@ export interface Category {
   level: number;
   parent_id: string | null;
   gpc_brick_code: string | null;
+  archive_kind: string;
   product_count: number;
 }
 
+export interface KindField {
+  kind: string;
+  field_key: string;
+  group_label: string;
+  label_zh: string;
+  field_type: string;
+  unit: string | null;
+  options: string[];
+  placeholder: string | null;
+  sort_order: number;
+  qualified: boolean;
+}
+
 export interface CategoryInput {
   name_zh: string;
   name_en?: string | null;
@@ -183,6 +199,7 @@ export interface ApiKey {
   owner_email: string | null;
   tier: string;
   rate_limit_per_min: number;
+  quota_total: number;
   revoked_at: string | null;
   created_by: string | null;
   created_at: string;

api/cmd/server/main.go

@@ -37,7 +37,8 @@ func main() {
 		log.Print("warning: Redis not configured; public API rate limiting disabled")
 	}
 	h := handler.New(store.New(pool), publicweb.Dist()).
-		WithRateLimit(limiter, cfg.AnonRateLimitPerMin)
+		WithRateLimit(limiter, cfg.AnonRateLimitPerMin).
+		WithQuotas(cfg.AnonTotalQuota, cfg.RegisteredRateLimitPerMin, cfg.RegisteredQuotaTotal)
 
 	srv := &http.Server{
 		Addr:              cfg.Addr,

api/internal/adminhandler/apikey.go

@@ -46,7 +46,7 @@ func (h *Handler) CreateAPIKey(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "bad_request", "名称不能为空")
 		return
 	}
-	if in.Tier != "" && in.Tier != "free" && in.Tier != "partner" && in.Tier != "internal" {
+	if in.Tier != "" && in.Tier != "free" && in.Tier != "registered" && in.Tier != "partner" && in.Tier != "internal" {
 		writeError(w, http.StatusBadRequest, "bad_request", "tier 取值无效")
 		return
 	}

api/internal/adminhandler/handler.go

@@ -84,6 +84,7 @@ func (h *Handler) Router() http.Handler {
 			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/kind-fields", h.ListKindFields)
 			r.Get("/api/categories", h.ListCategories)
 			r.Post("/api/categories", h.CreateCategory)
 			r.Put("/api/categories/{id}", h.UpdateCategory)
@@ -163,8 +164,10 @@ func (h *Handler) Me(w http.ResponseWriter, r *http.Request) {
 // ListProducts returns a paginated product list.
 func (h *Handler) ListProducts(w http.ResponseWriter, r *http.Request) {
 	q := r.URL.Query().Get("q")
+	sort := r.URL.Query().Get("sort")
+	order := r.URL.Query().Get("order")
 	page, size := pageParams(r)
-	items, total, err := h.store.ListProducts(r.Context(), q, size, (page-1)*size)
+	items, total, err := h.store.ListProducts(r.Context(), q, sort, order, size, (page-1)*size)
 	if h.handleErr(w, err) {
 		return
 	}
@@ -423,6 +426,20 @@ func (h *Handler) ListBrands(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"items": items})
 }
 
+// ListKindFields returns the editable spec field template for an archive kind.
+func (h *Handler) ListKindFields(w http.ResponseWriter, r *http.Request) {
+	kind := strings.TrimSpace(r.URL.Query().Get("kind"))
+	if kind == "" {
+		writeError(w, http.StatusBadRequest, "bad_request", "缺少 kind 参数")
+		return
+	}
+	items, err := h.store.ListKindFields(r.Context(), kind)
+	if h.handleErr(w, err) {
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"items": items, "kind": kind})
+}
+
 // ListCategories returns category options.
 func (h *Handler) ListCategories(w http.ResponseWriter, r *http.Request) {
 	items, err := h.store.ListCategories(r.Context())

api/internal/adminstore/adminstore.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"errors"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/jackc/pgx/v5"
@@ -50,8 +51,34 @@ type ProductRow struct {
 	UpdatedAt    string   `json:"updated_at"`
 }
 
+// productSortColumns whitelists the sortable list columns, mapping the API sort
+// key to a SQL expression. NULLs sort last regardless of direction.
+var productSortColumns = map[string]string{
+	"name":          "p.name",
+	"brand":         "b.name",
+	"gtin":          "p.gtin",
+	"category_path": "c.path",
+	"status":        "p.status",
+	"quality_score": "p.quality_score",
+	"updated_at":    "p.updated_at",
+}
+
+// productOrderBy returns a safe ORDER BY clause for the given sort key/direction,
+// falling back to the default (most recently updated first) for unknown keys.
+func productOrderBy(sort, order string) string {
+	col, ok := productSortColumns[sort]
+	if !ok {
+		return "p.updated_at DESC"
+	}
+	dir := "ASC"
+	if strings.EqualFold(order, "desc") {
+		dir = "DESC"
+	}
+	return col + " " + dir + " NULLS LAST, p.updated_at DESC"
+}
+
 // ListProducts returns a paginated, optionally name/gtin-filtered list.
-func (s *Store) ListProducts(ctx context.Context, q string, limit, offset int) ([]ProductRow, int, error) {
+func (s *Store) ListProducts(ctx context.Context, q, sort, order string, limit, offset int) ([]ProductRow, int, error) {
 	args := []any{}
 	where := "WHERE 1=1"
 	if q != "" {
@@ -64,10 +91,15 @@ func (s *Store) ListProducts(ctx context.Context, q string, limit, offset int) (
 		return nil, 0, err
 	}
 
+	qualified, err := s.kindQualifiedKeys(ctx, s.pool)
+	if err != nil {
+		return nil, 0, err
+	}
+
 	args = append(args, limit, offset)
 	sql := `
 SELECT p.id, p.gtin, p.name, b.name, c.path::text, p.status, p.quality_score,
-       p.updated_at,
+       p.updated_at, COALESCE(c.archive_kind, 'generic'), p.attributes,
        (p.brand_id IS NOT NULL) AS has_brand,
        (p.category_id IS NOT NULL) AS has_cat,
        (p.net_content_canonical IS NOT NULL) AS has_net,
@@ -79,7 +111,8 @@ FROM product p
 LEFT JOIN brand b ON b.id = p.brand_id
 LEFT JOIN category c ON c.id = p.category_id
 LEFT JOIN food_detail f ON f.product_id = p.id ` + where +
-		" ORDER BY p.updated_at DESC LIMIT $" + strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
+		" ORDER BY " + productOrderBy(sort, order) +
+		" LIMIT $" + strconv.Itoa(len(args)-1) + " OFFSET $" + strconv.Itoa(len(args))
 
 	rows, err := s.pool.Query(ctx, sql, args...)
 	if err != nil {
@@ -91,13 +124,21 @@ LEFT JOIN food_detail f ON f.product_id = p.id ` + where +
 	for rows.Next() {
 		var r ProductRow
 		var hasBrand, hasCat, hasNet, hasCountry, hasNutri, hasIng, hasImg bool
+		var kind string
+		var attributes []byte
 		var updated time.Time
 		if err := rows.Scan(&r.ID, &r.GTIN, &r.Name, &r.Brand, &r.CategoryPath, &r.Status,
-			&r.QualityScore, &updated, &hasBrand, &hasCat, &hasNet, &hasCountry,
+			&r.QualityScore, &updated, &kind, &attributes,
+			&hasBrand, &hasCat, &hasNet, &hasCountry,
 			&hasNutri, &hasIng, &hasImg); err != nil {
 			return nil, 0, err
 		}
 		r.UpdatedAt = updated.Format(time.RFC3339)
+		attrs := map[string]any{}
+		if len(attributes) > 0 {
+			_ = json.Unmarshal(attributes, &attrs)
+		}
+		qkeys := qualified[kind]
 		present := map[string]bool{
 			"name":              r.Name != "",
 			"gtin":              r.GTIN != nil && *r.GTIN != "",
@@ -109,8 +150,11 @@ LEFT JOIN food_detail f ON f.product_id = p.id ` + where +
 			"ingredients":       hasIng,
 			"image":             hasImg,
 		}
+		for _, k := range qkeys {
+			present[k] = attrPresent(attrs, k)
+		}
 		r.Missing = []string{}
-		for _, f := range CompletenessFields {
+		for _, f := range completenessKeys(kind, qkeys) {
 			if !present[f] {
 				r.Missing = append(r.Missing, f)
 			}
@@ -150,6 +194,8 @@ type ProductDetail struct {
 	Brand           *string        `json:"brand"`
 	CategoryID      *string        `json:"category_id"`
 	CategoryPath    *string        `json:"category_path"`
+	ArchiveKind     string         `json:"archive_kind"`
+	Attributes      map[string]any `json:"attributes"`
 	NetContentValue *float64       `json:"net_content_value"`
 	NetContentUnit  *string        `json:"net_content_unit"`
 	CountryOfOrigin *string        `json:"country_of_origin"`
@@ -173,9 +219,11 @@ type ProductDetail struct {
 func (s *Store) GetProduct(ctx context.Context, id string) (*ProductDetail, error) {
 	var d ProductDetail
 	var nutriments []byte
+	var attributes []byte
 	var updated time.Time
 	err := s.pool.QueryRow(ctx, `
 SELECT p.id, p.gtin, p.name, p.brand_id, b.name, p.category_id, c.path::text,
+       COALESCE(c.archive_kind, 'generic'), p.attributes,
        p.net_content_value, p.net_content_unit, p.country_of_origin, p.status,
        p.quality_score, p.updated_at,
        f.ingredients_text, f.allergens, f.additives, f.nutriments,
@@ -186,6 +234,7 @@ LEFT JOIN category c ON c.id = p.category_id
 LEFT JOIN food_detail f ON f.product_id = p.id
 WHERE p.id = $1`, id).Scan(
 		&d.ID, &d.GTIN, &d.Name, &d.BrandID, &d.Brand, &d.CategoryID, &d.CategoryPath,
+		&d.ArchiveKind, &attributes,
 		&d.NetContentValue, &d.NetContentUnit, &d.CountryOfOrigin, &d.Status,
 		&d.QualityScore, &updated,
 		&d.IngredientsText, &d.Allergens, &d.Additives, &nutriments,
@@ -198,6 +247,10 @@ WHERE p.id = $1`, id).Scan(
 		return nil, err
 	}
 	d.UpdatedAt = updated.Format(time.RFC3339)
+	d.Attributes = map[string]any{}
+	if len(attributes) > 0 {
+		_ = json.Unmarshal(attributes, &d.Attributes)
+	}
 	if len(nutriments) > 0 {
 		_ = json.Unmarshal(nutriments, &d.Nutriments)
 	}
@@ -226,11 +279,15 @@ WHERE p.id = $1`, id).Scan(
 	}
 	d.MSRP = msrps
 
-	d.Missing = missingFromDetail(&d)
+	qualified, err := s.kindQualifiedKeys(ctx, s.pool)
+	if err != nil {
+		return nil, err
+	}
+	d.Missing = missingFromDetail(&d, qualified[d.ArchiveKind])
 	return &d, nil
 }
 
-func missingFromDetail(d *ProductDetail) []string {
+func missingFromDetail(d *ProductDetail, qualifiedAttrKeys []string) []string {
 	present := map[string]bool{
 		"name":              d.Name != "",
 		"gtin":              d.GTIN != nil && *d.GTIN != "",
@@ -242,8 +299,11 @@ func missingFromDetail(d *ProductDetail) []string {
 		"ingredients":       d.IngredientsText != nil && *d.IngredientsText != "",
 		"image":             len(d.Images) > 0,
 	}
+	for _, k := range qualifiedAttrKeys {
+		present[k] = attrPresent(d.Attributes, k)
+	}
 	missing := []string{}
-	for _, f := range CompletenessFields {
+	for _, f := range completenessKeys(d.ArchiveKind, qualifiedAttrKeys) {
 		if !present[f] {
 			missing = append(missing, f)
 		}

api/internal/adminstore/apikey.go

@@ -19,6 +19,7 @@ type APIKeyRow struct {
 	OwnerEmail      *string `json:"owner_email"`
 	Tier            string  `json:"tier"`
 	RateLimitPerMin int     `json:"rate_limit_per_min"`
+	QuotaTotal      int64   `json:"quota_total"`
 	RevokedAt       *string `json:"revoked_at"`
 	CreatedBy       *string `json:"created_by"`
 	CreatedAt       string  `json:"created_at"`
@@ -30,6 +31,7 @@ type APIKeyInput struct {
 	OwnerEmail      string `json:"owner_email"`
 	Tier            string `json:"tier"`
 	RateLimitPerMin int    `json:"rate_limit_per_min"`
+	QuotaTotal      int64  `json:"quota_total"`
 }
 
 // CreateAPIKey issues a new key, returning the one-time plaintext alongside the
@@ -43,6 +45,10 @@ func (s *Store) CreateAPIKey(ctx context.Context, in APIKeyInput, createdBy stri
 	if rate <= 0 {
 		rate = 120
 	}
+	quota := in.QuotaTotal
+	if quota < 0 {
+		quota = 0
+	}
 	var owner *string
 	if e := strings.TrimSpace(in.OwnerEmail); e != "" {
 		owner = &e
@@ -56,12 +62,12 @@ func (s *Store) CreateAPIKey(ctx context.Context, in APIKeyInput, createdBy stri
 	var revoked, created *time.Time
 	var createdByOut *string
 	err = s.pool.QueryRow(ctx, `
-INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, created_by)
-VALUES ($1, $2, $3, $4, $5, $6, $7)
-RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_at, created_by, created_at`,
-		strings.TrimSpace(in.Name), prefix, hash, owner, tier, rate, createdBy,
+INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, quota_total, revoked_at, created_by, created_at`,
+		strings.TrimSpace(in.Name), prefix, hash, owner, tier, rate, quota, createdBy,
 	).Scan(&row.ID, &row.Name, &row.KeyPrefix, &row.OwnerEmail, &row.Tier,
-		&row.RateLimitPerMin, &revoked, &createdByOut, &created)
+		&row.RateLimitPerMin, &row.QuotaTotal, &revoked, &createdByOut, &created)
 	if err != nil {
 		return "", row, err
 	}
@@ -75,7 +81,7 @@ RETURNING id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_a
 // ListAPIKeys returns all keys (active first, newest first).
 func (s *Store) ListAPIKeys(ctx context.Context) ([]APIKeyRow, error) {
 	rows, err := s.pool.Query(ctx, `
-SELECT id, name, key_prefix, owner_email, tier, rate_limit_per_min, revoked_at, created_by, created_at
+SELECT id, name, key_prefix, owner_email, tier, rate_limit_per_min, quota_total, revoked_at, created_by, created_at
 FROM api_key
 ORDER BY (revoked_at IS NULL) DESC, created_at DESC`)
 	if err != nil {
@@ -87,7 +93,7 @@ ORDER BY (revoked_at IS NULL) DESC, created_at DESC`)
 		var r APIKeyRow
 		var revoked, created *time.Time
 		if err := rows.Scan(&r.ID, &r.Name, &r.KeyPrefix, &r.OwnerEmail, &r.Tier,
-			&r.RateLimitPerMin, &revoked, &r.CreatedBy, &created); err != nil {
+			&r.RateLimitPerMin, &r.QuotaTotal, &revoked, &r.CreatedBy, &created); err != nil {
 			return nil, err
 		}
 		if revoked != nil {

api/internal/adminstore/category.go

@@ -96,11 +96,12 @@ func (s *Store) CreateCategory(ctx context.Context, actor string, in CategoryInp
 
 	parentPath := ""
 	parentLevel := -1
+	kind := DefaultKind
 	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)
+		err := s.pool.QueryRow(ctx, "SELECT path::text, level, archive_kind FROM category WHERE id = $1", *pid).Scan(&path, &level, &kind)
 		if errors.Is(err, pgx.ErrNoRows) {
 			return nil, ErrInvalidParent
 		}
@@ -119,11 +120,11 @@ func (s *Store) CreateCategory(ctx context.Context, actor string, in CategoryInp
 
 	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)
+INSERT INTO category (name_zh, name_en, parent_id, path, gpc_brick_code, level, archive_kind)
+VALUES ($1, $2, $3, $4::ltree, $5, $6, $7)
+RETURNING id, name_zh, name_en, path::text, level, parent_id::text, gpc_brick_code, archive_kind, 0`,
+		name, trimPtr(in.NameEN), parentID, path, trimPtr(in.GPCBrickCode), level, kind).
+		Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level, &c.ParentID, &c.GPCBrickCode, &c.ArchiveKind, &c.ProductCount)
 	if isUniqueViolation(err) {
 		return nil, ErrDuplicatePath
 	}
@@ -273,10 +274,10 @@ 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,
+       c.gpc_brick_code, c.archive_kind,
        (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)
+		Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level, &c.ParentID, &c.GPCBrickCode, &c.ArchiveKind, &c.ProductCount)
 	if errors.Is(err, pgx.ErrNoRows) {
 		return nil, ErrNotFound
 	}

api/internal/adminstore/kind.go

@@ -0,0 +1,101 @@
+package adminstore
+
+import "context"
+
+// DefaultKind is used for products whose category has no archive kind (or no
+// category at all).
+const DefaultKind = "generic"
+
+// FoodKind keeps the mature, dedicated food_detail path; every other kind is
+// driven generically by kind_field + product.attributes.
+const FoodKind = "food"
+
+// genericBaseFields are the core completeness fields for any non-food kind.
+// Food keeps its own richer CompletenessFields list.
+var genericBaseFields = []string{"name", "gtin", "brand", "category", "image"}
+
+// KindField describes one editable spec field for an archive kind. It drives
+// both the dynamic admin form and the kind-aware completeness computation.
+type KindField struct {
+	Kind        string   `json:"kind"`
+	FieldKey    string   `json:"field_key"`
+	GroupLabel  string   `json:"group_label"`
+	LabelZH     string   `json:"label_zh"`
+	FieldType   string   `json:"field_type"`
+	Unit        *string  `json:"unit"`
+	Options     []string `json:"options"`
+	Placeholder *string  `json:"placeholder"`
+	SortOrder   int      `json:"sort_order"`
+	Qualified   bool     `json:"qualified"`
+}
+
+// ListKindFields returns the ordered field template for one archive kind.
+func (s *Store) ListKindFields(ctx context.Context, kind string) ([]KindField, error) {
+	rows, err := s.pool.Query(ctx, `
+SELECT kind, field_key, group_label, label_zh, field_type, unit, options,
+       placeholder, sort_order, qualified
+FROM kind_field WHERE kind = $1 ORDER BY sort_order, field_key`, kind)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := []KindField{}
+	for rows.Next() {
+		var f KindField
+		if err := rows.Scan(&f.Kind, &f.FieldKey, &f.GroupLabel, &f.LabelZH,
+			&f.FieldType, &f.Unit, &f.Options, &f.Placeholder, &f.SortOrder,
+			&f.Qualified); err != nil {
+			return nil, err
+		}
+		out = append(out, f)
+	}
+	return out, rows.Err()
+}
+
+// kindQualifiedKeys returns, per kind, the attribute keys that count toward the
+// completeness/qualified score. Loaded in one query so list views stay cheap.
+func (s *Store) kindQualifiedKeys(ctx context.Context, q queryer) (map[string][]string, error) {
+	rows, err := s.pool.Query(ctx,
+		"SELECT kind, field_key FROM kind_field WHERE qualified ORDER BY sort_order, field_key")
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	m := map[string][]string{}
+	for rows.Next() {
+		var kind, key string
+		if err := rows.Scan(&kind, &key); err != nil {
+			return nil, err
+		}
+		m[kind] = append(m[kind], key)
+	}
+	return m, rows.Err()
+}
+
+// completenessKeys returns the ordered list of field keys that define a full
+// archive for the given kind.
+func completenessKeys(kind string, qualifiedAttrKeys []string) []string {
+	if kind == FoodKind {
+		return CompletenessFields
+	}
+	keys := make([]string, 0, len(genericBaseFields)+len(qualifiedAttrKeys))
+	keys = append(keys, genericBaseFields...)
+	keys = append(keys, qualifiedAttrKeys...)
+	return keys
+}
+
+// attrPresent reports whether an attribute value is meaningfully filled in.
+func attrPresent(attrs map[string]any, key string) bool {
+	v, ok := attrs[key]
+	if !ok || v == nil {
+		return false
+	}
+	switch t := v.(type) {
+	case string:
+		return t != ""
+	case []any:
+		return len(t) > 0
+	default:
+		return true
+	}
+}

api/internal/adminstore/kind_test.go

@@ -0,0 +1,119 @@
+package adminstore
+
+import (
+	"context"
+	"testing"
+)
+
+// contains reports whether s holds v.
+func contains(s []string, v string) bool {
+	for _, x := range s {
+		if x == v {
+			return true
+		}
+	}
+	return false
+}
+
+// electronicsCategoryID returns the seeded electronics.phone category id,
+// skipping the test when the archive-kind migration is not applied.
+func electronicsCategoryID(t *testing.T, s *Store) string {
+	t.Helper()
+	ctx := context.Background()
+	var hasTable bool
+	if err := s.pool.QueryRow(ctx, "SELECT to_regclass('public.kind_field') IS NOT NULL").Scan(&hasTable); err != nil || !hasTable {
+		t.Skip("archive-kind migration not applied (kind_field missing)")
+	}
+	var id string
+	err := s.pool.QueryRow(ctx, "SELECT id FROM category WHERE path = 'electronics.phone'::ltree").Scan(&id)
+	if err != nil {
+		t.Skipf("electronics.phone category not seeded: %v", err)
+	}
+	return id
+}
+
+func TestListKindFieldsElectronics(t *testing.T) {
+	s := newTestStore(t)
+	electronicsCategoryID(t, s) // ensures migration applied
+	fields, err := s.ListKindFields(context.Background(), "electronics")
+	if err != nil {
+		t.Fatalf("list kind fields: %v", err)
+	}
+	if len(fields) == 0 {
+		t.Fatal("expected seeded electronics fields, got none")
+	}
+	var sawQualified bool
+	for _, f := range fields {
+		if f.FieldKey == "model_number" && f.Qualified {
+			sawQualified = true
+		}
+	}
+	if !sawQualified {
+		t.Fatal("expected model_number to be a qualified field")
+	}
+}
+
+// TestElectronicsArchiveKind verifies a non-food product uses the electronics
+// completeness rules: food fields (nutriments/ingredients) are not required,
+// and qualified spec fields drive both "missing" and the quality score.
+func TestElectronicsArchiveKind(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+	catID := electronicsCategoryID(t, s)
+
+	created, err := s.CreateProduct(ctx, "tester", ProductInput{
+		Name:       "测试手机 " + randomHex(6),
+		CategoryID: &catID,
+	})
+	if err != nil {
+		t.Fatalf("create product: %v", err)
+	}
+	t.Cleanup(func() { _, _ = s.pool.Exec(ctx, "DELETE FROM product WHERE id = $1", created.ID) })
+
+	if created.ArchiveKind != "electronics" {
+		t.Fatalf("archive_kind = %q, want electronics", created.ArchiveKind)
+	}
+	// Food-only completeness fields must not be required for electronics.
+	if contains(created.Missing, "nutriments") || contains(created.Missing, "ingredients") {
+		t.Fatalf("electronics product should not require food fields: missing=%v", created.Missing)
+	}
+	// Qualified spec fields should appear as missing while empty.
+	for _, k := range []string{"model_number", "ccc_cert", "screen_size"} {
+		if !contains(created.Missing, k) {
+			t.Fatalf("expected %q in missing, got %v", k, created.Missing)
+		}
+	}
+
+	scoreBefore := created.QualityScore
+
+	gtin := "69" + randomHex(11)
+	brand := "TestPhoneCo"
+	updated, err := s.UpdateProduct(ctx, created.ID, "tester", ProductInput{
+		Name:       created.Name,
+		GTIN:       &gtin,
+		BrandName:  &brand,
+		CategoryID: &catID,
+		Status:     "active",
+		Attributes: map[string]any{
+			"model_number": "X-100",
+			"ccc_cert":     "2024010101234567",
+			"screen_size":  "6.1",
+			"color":        "黑色",
+		},
+	})
+	if err != nil {
+		t.Fatalf("update product: %v", err)
+	}
+
+	if got := updated.Attributes["model_number"]; got != "X-100" {
+		t.Fatalf("attributes not persisted: %v", updated.Attributes)
+	}
+	for _, k := range []string{"model_number", "ccc_cert", "screen_size"} {
+		if contains(updated.Missing, k) {
+			t.Fatalf("%q should be filled, still missing: %v", k, updated.Missing)
+		}
+	}
+	if updated.QualityScore <= scoreBefore {
+		t.Fatalf("quality should rise after filling fields: before=%v after=%v", scoreBefore, updated.QualityScore)
+	}
+}

api/internal/adminstore/quality.go

@@ -2,6 +2,7 @@ package adminstore
 
 import (
 	"context"
+	"encoding/json"
 	"math"
 	"time"
 
@@ -58,35 +59,56 @@ func (s *Store) computeQuality(ctx context.Context, q queryer, productID string)
 	var netCanonical *float64
 	var ingredients *string
 	var hasNutri, hasImage bool
+	var kind string
+	var attributes []byte
 	err := q.QueryRow(ctx, `
 SELECT p.name, p.gtin, p.brand_id, p.category_id, p.net_content_canonical,
-       p.country_of_origin, f.ingredients_text,
+       p.country_of_origin, COALESCE(c.archive_kind, 'generic'), p.attributes,
+       f.ingredients_text,
        (f.nutriments IS NOT NULL AND f.nutriments::text <> '{}'),
        EXISTS (SELECT 1 FROM product_image pi WHERE pi.product_id = p.id)
-FROM product p LEFT JOIN food_detail f ON f.product_id = p.id
+FROM product p
+LEFT JOIN category c ON c.id = p.category_id
+LEFT JOIN food_detail f ON f.product_id = p.id
 WHERE p.id = $1`, productID).Scan(
 		&name, &gtin, &brandID, &categoryID, &netCanonical, &country,
-		&ingredients, &hasNutri, &hasImage)
+		&kind, &attributes, &ingredients, &hasNutri, &hasImage)
 	if err != nil {
 		return 0, err
 	}
 
+	attrs := map[string]any{}
+	if len(attributes) > 0 {
+		_ = json.Unmarshal(attributes, &attrs)
+	}
+	qualified, err := s.kindQualifiedKeys(ctx, s.pool)
+	if err != nil {
+		return 0, err
+	}
+	qkeys := qualified[kind]
+
+	known := map[string]bool{
+		"name":              name != nil && *name != "",
+		"gtin":              gtin != nil && *gtin != "",
+		"brand":             brandID != nil,
+		"category":          categoryID != nil,
+		"net_content":       netCanonical != nil,
+		"country_of_origin": country != nil && *country != "",
+		"nutriments":        hasNutri,
+		"ingredients":       ingredients != nil && *ingredients != "",
+		"image":             hasImage,
+	}
+	for _, k := range qkeys {
+		known[k] = attrPresent(attrs, k)
+	}
+	keys := completenessKeys(kind, qkeys)
 	present := 0
-	bump := func(ok bool) {
-		if ok {
+	for _, k := range keys {
+		if known[k] {
 			present++
 		}
 	}
-	bump(name != nil && *name != "")
-	bump(gtin != nil && *gtin != "")
-	bump(brandID != nil)
-	bump(categoryID != nil)
-	bump(netCanonical != nil)
-	bump(country != nil && *country != "")
-	bump(hasNutri)
-	bump(ingredients != nil && *ingredients != "")
-	bump(hasImage)
-	completeness := float64(present) / float64(len(CompletenessFields))
+	completeness := float64(present) / float64(len(keys))
 
 	var sourceCount int
 	var sourceTrust *float64

api/internal/adminstore/write.go

@@ -27,6 +27,9 @@ type ProductInput struct {
 	NutritionBasis  *string        `json:"nutrition_basis"`
 	ServingSize     *string        `json:"serving_size"`
 	NutriScore      *string        `json:"nutri_score"`
+	// Attributes carries non-food spec values (driven by kind_field) for the
+	// generic archive kinds. Nil means "leave unchanged".
+	Attributes map[string]any `json:"attributes"`
 }
 
 func normBrand(name string) string { return strings.Join(strings.Fields(strings.ToLower(name)), " ") }
@@ -86,10 +89,11 @@ func (s *Store) UpdateProduct(ctx context.Context, id, actor string, in ProductI
 		brandID = &bid
 	}
 
-	// Resolve category gpc brick code.
+	// Resolve category gpc brick code + archive kind.
 	var gpc *string
+	kind := DefaultKind
 	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) {
+		if err := tx.QueryRow(ctx, "SELECT gpc_brick_code, archive_kind FROM category WHERE id = $1", *in.CategoryID).Scan(&gpc, &kind); err != nil && !errors.Is(err, pgx.ErrNoRows) {
 			return nil, err
 		}
 	}
@@ -116,19 +120,28 @@ WHERE id=$11`,
 		return nil, err
 	}
 
-	var nutriJSON []byte
-	if in.Nutriments != nil {
-		nutriJSON, _ = json.Marshal(in.Nutriments)
+	// Non-food spec values live in product.attributes (nil means unchanged).
+	if in.Attributes != nil {
+		attrJSON, _ := json.Marshal(in.Attributes)
+		if _, err = tx.Exec(ctx, "UPDATE product SET attributes=$1 WHERE id=$2", attrJSON, id); err != nil {
+			return nil, err
+		}
 	}
-	allergens := in.Allergens
-	if allergens == nil {
-		allergens = []string{}
-	}
-	additives := in.Additives
-	if additives == nil {
-		additives = []string{}
-	}
-	_, err = tx.Exec(ctx, `
+
+	if kind == FoodKind {
+		var nutriJSON []byte
+		if in.Nutriments != nil {
+			nutriJSON, _ = json.Marshal(in.Nutriments)
+		}
+		allergens := in.Allergens
+		if allergens == nil {
+			allergens = []string{}
+		}
+		additives := in.Additives
+		if additives == nil {
+			additives = []string{}
+		}
+		_, err = tx.Exec(ctx, `
 INSERT INTO food_detail (product_id, ingredients_text, allergens, additives,
    nutriments, nutrition_basis, serving_size, nutri_score)
 VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
@@ -140,10 +153,11 @@ ON CONFLICT (product_id) DO UPDATE SET
    nutrition_basis=EXCLUDED.nutrition_basis,
    serving_size=EXCLUDED.serving_size,
    nutri_score=EXCLUDED.nutri_score`,
-		id, in.IngredientsText, allergens, additives,
-		nutriJSON, in.NutritionBasis, in.ServingSize, in.NutriScore)
-	if err != nil {
-		return nil, err
+			id, in.IngredientsText, allergens, additives,
+			nutriJSON, in.NutritionBasis, in.ServingSize, in.NutriScore)
+		if err != nil {
+			return nil, err
+		}
 	}
 
 	if _, err := s.recomputeQualityTx(ctx, tx, id); err != nil {
@@ -284,6 +298,9 @@ func diffFields(a, b *ProductDetail) []string {
 	add("nutrition_basis", strEq(a.NutritionBasis, b.NutritionBasis))
 	add("serving_size", strEq(a.ServingSize, b.ServingSize))
 	add("nutri_score", strEq(a.NutriScore, b.NutriScore))
+	aa, _ := json.Marshal(a.Attributes)
+	ab, _ := json.Marshal(b.Attributes)
+	add("attributes", string(aa) == string(ab))
 	return changed
 }
 
@@ -442,6 +459,7 @@ type Category struct {
 	Level        int     `json:"level"`
 	ParentID     *string `json:"parent_id"`
 	GPCBrickCode *string `json:"gpc_brick_code"`
+	ArchiveKind  string  `json:"archive_kind"`
 	ProductCount int     `json:"product_count"`
 }
 
@@ -450,7 +468,7 @@ type Category struct {
 func (s *Store) ListCategories(ctx context.Context) ([]Category, error) {
 	rows, err := s.pool.Query(ctx, `
 SELECT c.id, c.name_zh, c.name_en, c.path::text, c.level, c.parent_id::text,
-       c.gpc_brick_code,
+       c.gpc_brick_code, c.archive_kind,
        (SELECT count(*) FROM product p WHERE p.category_id = c.id) AS product_count
 FROM category c
 ORDER BY c.path`)
@@ -462,7 +480,7 @@ ORDER BY c.path`)
 	for rows.Next() {
 		var c Category
 		if err := rows.Scan(&c.ID, &c.NameZH, &c.NameEN, &c.Path, &c.Level,
-			&c.ParentID, &c.GPCBrickCode, &c.ProductCount); err != nil {
+			&c.ParentID, &c.GPCBrickCode, &c.ArchiveKind, &c.ProductCount); err != nil {
 			return nil, err
 		}
 		out = append(out, c)

api/internal/config/config.go

@@ -9,19 +9,25 @@ import (
 // Values are read from environment variables with sensible defaults so the
 // server can boot in a local Docker Compose setup without extra configuration.
 type Config struct {
-	Addr                string
-	DatabaseURL         string
-	RedisURL            string
-	AnonRateLimitPerMin int
+	Addr                      string
+	DatabaseURL               string
+	RedisURL                  string
+	AnonRateLimitPerMin       int
+	AnonTotalQuota            int
+	RegisteredRateLimitPerMin int
+	RegisteredQuotaTotal      int
 }
 
 // Load reads configuration from the environment.
 func Load() Config {
 	return Config{
-		Addr:                getenv("OPENGOODS_ADDR", ":8080"),
-		DatabaseURL:         getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
-		RedisURL:            getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
-		AnonRateLimitPerMin: getenvInt("OPENGOODS_ANON_RATE_LIMIT_PER_MIN", 60),
+		Addr:                      getenv("OPENGOODS_ADDR", ":8080"),
+		DatabaseURL:               getenv("OPENGOODS_DATABASE_URL", "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"),
+		RedisURL:                  getenv("OPENGOODS_REDIS_URL", "redis://localhost:6379/0"),
+		AnonRateLimitPerMin:       getenvInt("OPENGOODS_ANON_RATE_LIMIT_PER_MIN", 60),
+		AnonTotalQuota:            getenvInt("OPENGOODS_ANON_TOTAL_QUOTA", 1000),
+		RegisteredRateLimitPerMin: getenvInt("OPENGOODS_REGISTERED_RATE_LIMIT_PER_MIN", 300),
+		RegisteredQuotaTotal:      getenvInt("OPENGOODS_REGISTERED_QUOTA_TOTAL", 100000),
 	}
 }
 

api/internal/handler/account.go

@@ -0,0 +1,128 @@
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"regexp"
+	"strings"
+
+	"github.com/baicai2026-baicai/goods/api/internal/store"
+)
+
+// emailRe is a deliberately permissive sanity check; real validation is the
+// unique constraint plus the user being able to receive their own key.
+var emailRe = regexp.MustCompile(`^[^@\s]+@[^@\s]+\.[^@\s]+$`)
+
+const minPasswordLen = 8
+
+type credentials struct {
+	Email    string `json:"email"`
+	Password string `json:"password"`
+}
+
+func decodeCredentials(w http.ResponseWriter, r *http.Request) (credentials, bool) {
+	var c credentials
+	if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 4096)).Decode(&c); err != nil {
+		writeError(w, r, http.StatusBadRequest, "invalid_body", "请求格式无效")
+		return credentials{}, false
+	}
+	c.Email = strings.TrimSpace(c.Email)
+	if !emailRe.MatchString(c.Email) {
+		writeError(w, r, http.StatusBadRequest, "invalid_email", "邮箱格式无效")
+		return credentials{}, false
+	}
+	if len(c.Password) < minPasswordLen {
+		writeError(w, r, http.StatusBadRequest, "weak_password", "密码至少需要 8 位")
+		return credentials{}, false
+	}
+	return c, true
+}
+
+// keyResponse is returned whenever a fresh plaintext key is issued; the key is
+// shown exactly once and cannot be recovered afterwards.
+type keyResponse struct {
+	Email           string `json:"email"`
+	APIKey          string `json:"api_key"`
+	KeyPrefix       string `json:"key_prefix"`
+	RateLimitPerMin int    `json:"rate_limit_per_min"`
+	QuotaTotal      int64  `json:"quota_total"`
+}
+
+// Register creates an account and issues its first API key. POST {email, password}.
+func (h *Handler) Register(w http.ResponseWriter, r *http.Request) {
+	c, ok := decodeCredentials(w, r)
+	if !ok {
+		return
+	}
+	key, acct, err := h.store.RegisterUser(r.Context(), c.Email, c.Password, h.regRatePerMin, h.regQuotaTotal)
+	if errors.Is(err, store.ErrEmailTaken) {
+		writeError(w, r, http.StatusConflict, "email_taken", "该邮箱已注册，请直接登录查看或重置密钥")
+		return
+	}
+	if h.handleErr(w, r, err) {
+		return
+	}
+	writeJSON(w, http.StatusCreated, keyResponse{
+		Email:           acct.Email,
+		APIKey:          key,
+		KeyPrefix:       acct.KeyPrefix,
+		RateLimitPerMin: acct.RateLimitPerMin,
+		QuotaTotal:      acct.QuotaTotal,
+	})
+}
+
+// AccountInfo verifies credentials and returns the account's key metadata plus
+// cumulative usage. POST {email, password}. The plaintext key is not returned.
+func (h *Handler) AccountInfo(w http.ResponseWriter, r *http.Request) {
+	c, ok := decodeCredentials(w, r)
+	if !ok {
+		return
+	}
+	acct, err := h.store.Authenticate(r.Context(), c.Email, c.Password)
+	if errors.Is(err, store.ErrNotFound) {
+		writeError(w, r, http.StatusUnauthorized, "invalid_credentials", "邮箱或密码错误")
+		return
+	}
+	if h.handleErr(w, r, err) {
+		return
+	}
+	used := h.limiter.TotalUsed(r.Context(), acct.KeyID)
+	remaining := acct.QuotaTotal - used
+	if remaining < 0 {
+		remaining = 0
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"email":              acct.Email,
+		"key_prefix":         acct.KeyPrefix,
+		"rate_limit_per_min": acct.RateLimitPerMin,
+		"quota_total":        acct.QuotaTotal,
+		"quota_used":         used,
+		"quota_remaining":    remaining,
+	})
+}
+
+// RegenerateKey revokes the account's current key and issues a new one, carrying
+// over cumulative usage so the quota cannot be reset. POST {email, password}.
+func (h *Handler) RegenerateKey(w http.ResponseWriter, r *http.Request) {
+	c, ok := decodeCredentials(w, r)
+	if !ok {
+		return
+	}
+	key, acct, oldKeyID, err := h.store.RegenerateKey(r.Context(), c.Email, c.Password, h.regRatePerMin, h.regQuotaTotal)
+	if errors.Is(err, store.ErrNotFound) {
+		writeError(w, r, http.StatusUnauthorized, "invalid_credentials", "邮箱或密码错误")
+		return
+	}
+	if h.handleErr(w, r, err) {
+		return
+	}
+	h.limiter.CopyTotal(r.Context(), oldKeyID, acct.KeyID)
+	writeJSON(w, http.StatusOK, keyResponse{
+		Email:           acct.Email,
+		APIKey:          key,
+		KeyPrefix:       acct.KeyPrefix,
+		RateLimitPerMin: acct.RateLimitPerMin,
+		QuotaTotal:      acct.QuotaTotal,
+	})
+}

api/internal/handler/account_db_test.go

@@ -0,0 +1,149 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/redis/go-redis/v9"
+
+	"github.com/baicai2026-baicai/goods/api/internal/ratelimit"
+	"github.com/baicai2026-baicai/goods/api/internal/store"
+)
+
+func cleanupCounter(t *testing.T, subject string) {
+	t.Helper()
+	redisURL := os.Getenv("OPENGOODS_REDIS_URL")
+	if redisURL == "" {
+		redisURL = "redis://localhost:6379/0"
+	}
+	opt, err := redis.ParseURL(redisURL)
+	if err != nil {
+		return
+	}
+	rdb := redis.NewClient(opt)
+	defer rdb.Close()
+	rdb.Del(context.Background(), "usage:total:"+subject)
+}
+
+// newQuotaHandler builds a handler backed by the test DB and a live Redis
+// limiter, with a small anonymous quota so exhaustion is cheap to exercise.
+func newQuotaHandler(t *testing.T, anonQuota int) *Handler {
+	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 hasUser bool
+	if err := pool.QueryRow(ctx, "SELECT to_regclass('public.app_user') IS NOT NULL").Scan(&hasUser); err != nil || !hasUser {
+		pool.Close()
+		t.Skip("migrations not applied")
+	}
+	redisURL := os.Getenv("OPENGOODS_REDIS_URL")
+	if redisURL == "" {
+		redisURL = "redis://localhost:6379/0"
+	}
+	limiter := ratelimit.New(redisURL)
+	pingCtx, pingCancel := context.WithTimeout(context.Background(), time.Second)
+	defer pingCancel()
+	if err := limiter.Ping(pingCtx); err != nil {
+		pool.Close()
+		t.Skipf("redis not reachable: %v", err)
+	}
+	t.Cleanup(pool.Close)
+	return New(store.New(pool), nil).
+		WithRateLimit(limiter, 1000).
+		WithQuotas(anonQuota, 300, 100000)
+}
+
+func cleanupAccount(t *testing.T, email string) {
+	t.Helper()
+	dsn := os.Getenv("OPENGOODS_DATABASE_URL")
+	if dsn == "" {
+		dsn = "postgres://opengoods:opengoods@localhost:5432/opengoods?sslmode=disable"
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		return
+	}
+	defer pool.Close()
+	_, _ = pool.Exec(ctx, "DELETE FROM app_user WHERE lower(email)=lower($1)", email)
+	_, _ = pool.Exec(ctx, "DELETE FROM api_key WHERE owner_email=$1", email)
+}
+
+func TestAnonTotalQuotaExhausts(t *testing.T) {
+	h := newQuotaHandler(t, 3)
+	// Unique client IP so the lifetime counter starts fresh for this test; the
+	// counter never expires, so drop it afterwards to keep runs independent.
+	n := time.Now().UnixNano()
+	ip := fmt.Sprintf("203.%d.%d.%d", n/65536%256, n/256%256, n%256)
+	t.Cleanup(func() { cleanupCounter(t, "ip:"+ip) })
+	call := func() *httptest.ResponseRecorder {
+		req := httptest.NewRequest(http.MethodGet, "/api/"+APIVersion+"/stats", nil)
+		req.RemoteAddr = ip + ":12345"
+		rec := httptest.NewRecorder()
+		h.Router().ServeHTTP(rec, req)
+		return rec
+	}
+	for i := 1; i <= 3; i++ {
+		if rec := call(); rec.Code != http.StatusOK {
+			t.Fatalf("call %d should be allowed, got %d (%s)", i, rec.Code, rec.Body.String())
+		}
+	}
+	rec := call()
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("4th call should be 403 quota_exhausted, got %d (%s)", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "quota_exhausted") {
+		t.Fatalf("expected quota_exhausted error, got %s", rec.Body.String())
+	}
+}
+
+func TestRegisterIssuesHigherQuotaKey(t *testing.T) {
+	h := newQuotaHandler(t, 1000)
+	email := fmt.Sprintf("h-user-%d@example.com", time.Now().UnixNano())
+	t.Cleanup(func() { cleanupAccount(t, email) })
+
+	body := fmt.Sprintf(`{"email":%q,"password":"supersecret"}`, email)
+	req := httptest.NewRequest(http.MethodPost, "/api/"+APIVersion+"/register", strings.NewReader(body))
+	req.RemoteAddr = "198.51.100.7:9999"
+	rec := httptest.NewRecorder()
+	h.Router().ServeHTTP(rec, req)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("register status = %d (%s)", rec.Code, rec.Body.String())
+	}
+	var resp keyResponse
+	if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil {
+		t.Fatal(err)
+	}
+	if resp.APIKey == "" || resp.QuotaTotal != 100000 || resp.RateLimitPerMin != 300 {
+		t.Fatalf("unexpected register response: %+v", resp)
+	}
+
+	// A second registration with the same email conflicts.
+	req2 := httptest.NewRequest(http.MethodPost, "/api/"+APIVersion+"/register", strings.NewReader(body))
+	req2.RemoteAddr = "198.51.100.7:9999"
+	rec2 := httptest.NewRecorder()
+	h.Router().ServeHTTP(rec2, req2)
+	if rec2.Code != http.StatusConflict {
+		t.Fatalf("duplicate register status = %d (%s)", rec2.Code, rec2.Body.String())
+	}
+}

api/internal/handler/handler.go

@@ -37,20 +37,43 @@ const (
 	// defaultAnonLimit is the per-minute request budget for unauthenticated
 	// callers (identified by client IP) when none is configured.
 	defaultAnonLimit = 60
+
+	// defaultAnonTotalQuota is the lifetime number of calls an anonymous caller
+	// (by IP) may make before being asked to register for a higher quota.
+	defaultAnonTotalQuota = 1000
+
+	// defaultRegRatePerMin / defaultRegQuotaTotal are the per-minute budget and
+	// cumulative quota granted to a self-registered API key.
+	defaultRegRatePerMin = 300
+	defaultRegQuotaTotal = 100000
+
+	// registerRatePerMin caps account registration/login attempts per IP to
+	// curb abuse; these endpoints sit outside the metered quota group.
+	registerRatePerMin = 10
 )
 
 // Handler holds dependencies shared by the HTTP routes.
 type Handler struct {
-	store     *store.Store
-	spa       fs.FS
-	limiter   *ratelimit.Limiter
-	anonLimit int
+	store          *store.Store
+	spa            fs.FS
+	limiter        *ratelimit.Limiter
+	anonLimit      int
+	anonTotalQuota int64
+	regRatePerMin  int
+	regQuotaTotal  int64
 }
 
 // New constructs a Handler backed by the given store. spa may be nil (JSON-only).
 // Rate limiting is disabled until WithRateLimit is called.
 func New(s *store.Store, spa fs.FS) *Handler {
-	return &Handler{store: s, spa: spa, anonLimit: defaultAnonLimit}
+	return &Handler{
+		store:          s,
+		spa:            spa,
+		anonLimit:      defaultAnonLimit,
+		anonTotalQuota: defaultAnonTotalQuota,
+		regRatePerMin:  defaultRegRatePerMin,
+		regQuotaTotal:  defaultRegQuotaTotal,
+	}
 }
 
 // WithRateLimit attaches a Redis-backed limiter and the anonymous per-minute
@@ -64,6 +87,22 @@ func (h *Handler) WithRateLimit(l *ratelimit.Limiter, anonPerMin int) *Handler {
 	return h
 }
 
+// WithQuotas configures the cumulative free quota for anonymous callers and the
+// per-minute rate + cumulative quota self-registered keys receive. Non-positive
+// values keep the defaults.
+func (h *Handler) WithQuotas(anonTotal, regPerMin, regTotal int) *Handler {
+	if anonTotal > 0 {
+		h.anonTotalQuota = int64(anonTotal)
+	}
+	if regPerMin > 0 {
+		h.regRatePerMin = regPerMin
+	}
+	if regTotal > 0 {
+		h.regQuotaTotal = int64(regTotal)
+	}
+	return h
+}
+
 // Router builds the top-level HTTP handler with middleware and routes mounted.
 func (h *Handler) Router() http.Handler {
 	r := chi.NewRouter()
@@ -91,6 +130,16 @@ func (h *Handler) Router() http.Handler {
 			r.Get("/sources/{id}", h.SourceByID)
 			r.Get("/stats", h.Stats)
 		})
+
+		// Self-service account routes. Lightly IP-throttled to curb abuse but
+		// outside the metered quota group so a user can always register or
+		// check their key even after exhausting the free anonymous quota.
+		r.Group(func(r chi.Router) {
+			r.Use(h.registerLimit)
+			r.Post("/register", h.Register)
+			r.Post("/account", h.AccountInfo)
+			r.Post("/account/regenerate", h.RegenerateKey)
+		})
 	})
 
 	// Public SPA (homepage + search + contribute). API routes above take

api/internal/handler/middleware.go

@@ -24,8 +24,11 @@ const apiKeyIDKey ctxKey = 0
 // are set on every response; over-budget callers get 429 + Retry-After.
 func (h *Handler) rateLimit(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		id := "ip:" + clientIP(r)
+		ip := clientIP(r)
+		id := "ip:" + ip
+		subject := "ip:" + ip // cumulative-quota counter subject
 		limit := h.anonLimit
+		quota := h.anonTotalQuota
 		keyID := ""
 
 		if raw := presentedKey(r); raw != "" {
@@ -45,6 +48,8 @@ func (h *Handler) rateLimit(next http.Handler) http.Handler {
 			keyID = k.ID
 			limit = k.RateLimitPerMin
 			id = "key:" + k.ID
+			subject = k.ID
+			quota = k.QuotaTotal
 		}
 
 		res := h.limiter.Allow(r.Context(), id, limit, time.Minute)
@@ -61,8 +66,36 @@ func (h *Handler) rateLimit(next http.Handler) http.Handler {
 			return
 		}
 
+		// Attribute one call to the caller's lifetime counter, then enforce the
+		// cumulative quota (quota <= 0 means unlimited). Keys also get daily and
+		// last-used stats recorded for the admin console.
+		var used int64
 		if keyID != "" {
 			h.limiter.RecordUsage(r.Context(), keyID)
+			used = h.limiter.TotalUsed(r.Context(), keyID)
+		} else {
+			used = h.limiter.IncrTotal(r.Context(), subject)
+		}
+		if quota > 0 {
+			remaining := quota - used
+			if remaining < 0 {
+				remaining = 0
+			}
+			w.Header().Set("X-Quota-Limit", strconv.FormatInt(quota, 10))
+			w.Header().Set("X-Quota-Used", strconv.FormatInt(used, 10))
+			w.Header().Set("X-Quota-Remaining", strconv.FormatInt(remaining, 10))
+			if used > quota {
+				if keyID == "" {
+					writeError(w, r, http.StatusForbidden, "quota_exhausted",
+						"免费额度（共 "+strconv.FormatInt(quota, 10)+" 次）已用尽，请注册账号获取更高配额的 API 密钥")
+				} else {
+					writeError(w, r, http.StatusForbidden, "quota_exhausted", "API 密钥配额已用尽")
+				}
+				return
+			}
+		}
+
+		if keyID != "" {
 			next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), apiKeyIDKey, keyID)))
 			return
 		}
@@ -70,6 +103,25 @@ func (h *Handler) rateLimit(next http.Handler) http.Handler {
 	})
 }
 
+// registerLimit throttles self-service account endpoints per client IP without
+// consuming the metered free quota, so a caller can still register or recover
+// their key after exhausting the anonymous quota.
+func (h *Handler) registerLimit(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		res := h.limiter.Allow(r.Context(), "register:"+clientIP(r), h.regRatePerMin, time.Minute)
+		if !res.Allowed {
+			retry := res.ResetUnix - time.Now().Unix()
+			if retry < 1 {
+				retry = 1
+			}
+			w.Header().Set("Retry-After", strconv.FormatInt(retry, 10))
+			writeError(w, r, http.StatusTooManyRequests, "rate_limited", "操作过于频繁，请稍后再试")
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
 // presentedKey extracts an API key from the X-API-Key header or a Bearer token.
 func presentedKey(r *http.Request) string {
 	if v := strings.TrimSpace(r.Header.Get("X-API-Key")); v != "" {

api/internal/handler/openapi.json

@@ -10,7 +10,8 @@
   "tags": [
     { "name": "products" },
     { "name": "catalog" },
-    { "name": "meta" }
+    { "name": "meta" },
+    { "name": "account" }
   ],
   "security": [{ "ApiKeyHeader": [] }, { "BearerKey": [] }, {}],
   "paths": {
@@ -114,6 +115,35 @@
         "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
         "responses": { "200": { "description": "Source" }, "404": { "$ref": "#/components/responses/NotFound" } }
       }
+    },
+    "/register": {
+      "post": {
+        "tags": ["account"],
+        "summary": "Register an account and issue an API key",
+        "description": "Self-service registration; returns the plaintext API key exactly once.",
+        "security": [],
+        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 } } } } } },
+        "responses": { "201": { "description": "Account created; plaintext key returned once" }, "400": { "description": "Invalid email or weak password" }, "409": { "description": "Email already registered" } }
+      }
+    },
+    "/account": {
+      "post": {
+        "tags": ["account"],
+        "summary": "View account key metadata and cumulative quota usage",
+        "security": [],
+        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } },
+        "responses": { "200": { "description": "Account info with quota usage" }, "401": { "description": "Invalid credentials" } }
+      }
+    },
+    "/account/regenerate": {
+      "post": {
+        "tags": ["account"],
+        "summary": "Revoke the current key and issue a new one",
+        "description": "Cumulative usage carries over; returns the plaintext key exactly once.",
+        "security": [],
+        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } },
+        "responses": { "200": { "description": "New plaintext key returned once" }, "401": { "description": "Invalid credentials" } }
+      }
     }
   },
   "components": {

api/internal/ratelimit/ratelimit.go

@@ -116,6 +116,45 @@ func (l *Limiter) RecordUsage(ctx context.Context, keyID string) {
 	_, _ = pipe.Exec(ctx)
 }
 
+// IncrTotal increments the lifetime call counter for subject and returns the
+// new total. The counter never expires; it is the cumulative number of calls
+// attributed to a caller (an API key id, or "ip:<addr>" for anonymous callers).
+// Fails open returning 0 on any error so quota enforcement never takes the API
+// down.
+func (l *Limiter) IncrTotal(ctx context.Context, subject string) int64 {
+	if !l.Enabled() || subject == "" {
+		return 0
+	}
+	n, err := l.rdb.Incr(ctx, "usage:total:"+subject).Result()
+	if err != nil {
+		return 0
+	}
+	return n
+}
+
+// CopyTotal carries a lifetime counter from one subject to another, used when a
+// key is regenerated so a caller cannot reset their cumulative quota. Best
+// effort: a missing or zero source counter is a no-op.
+func (l *Limiter) CopyTotal(ctx context.Context, from, to string) {
+	if !l.Enabled() || from == "" || to == "" {
+		return
+	}
+	n, err := l.rdb.Get(ctx, "usage:total:"+from).Int64()
+	if err != nil || n == 0 {
+		return
+	}
+	l.rdb.Set(ctx, "usage:total:"+to, n, 0)
+}
+
+// TotalUsed reads the lifetime call counter for subject without incrementing.
+func (l *Limiter) TotalUsed(ctx context.Context, subject string) int64 {
+	if !l.Enabled() || subject == "" {
+		return 0
+	}
+	n, _ := l.rdb.Get(ctx, "usage:total:"+subject).Int64()
+	return n
+}
+
 // Usage reads aggregated usage for a key. Returns a zero-value stat on error.
 func (l *Limiter) Usage(ctx context.Context, keyID string) UsageStat {
 	var st UsageStat

api/internal/store/account.go

@@ -0,0 +1,169 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+)
+
+// ErrEmailTaken is returned when registering an email that already exists.
+var ErrEmailTaken = errors.New("email already registered")
+
+// Account is a self-registered public-API user and its current key metadata.
+type Account struct {
+	ID              string `json:"id"`
+	Email           string `json:"email"`
+	KeyID           string `json:"-"`
+	KeyPrefix       string `json:"key_prefix"`
+	RateLimitPerMin int    `json:"rate_limit_per_min"`
+	QuotaTotal      int64  `json:"quota_total"`
+}
+
+// bcryptDummyHash is compared against on unknown-email logins to keep timing
+// roughly constant and avoid leaking which emails are registered.
+const bcryptDummyHash = "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
+
+func isUniqueViolation(err error) bool {
+	var pgErr *pgconn.PgError
+	return errors.As(err, &pgErr) && pgErr.Code == "23505"
+}
+
+// RegisterUser creates an account plus a self-issued API key with the given
+// per-minute rate and cumulative quota, returning the plaintext key (shown
+// once). Email uniqueness is case-insensitive; ErrEmailTaken signals a dupe.
+func (s *Store) RegisterUser(ctx context.Context, email, password string, ratePerMin int, quotaTotal int64) (plaintext string, acct Account, err error) {
+	email = strings.TrimSpace(email)
+	pwHash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return "", Account{}, err
+	}
+	key, keyHash, prefix, err := apikey.Generate()
+	if err != nil {
+		return "", Account{}, err
+	}
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return "", Account{}, err
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	var keyID string
+	if err = tx.QueryRow(ctx,
+		`INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
+		 VALUES ($1,$2,$3,$4,'registered',$5,$6,'self-register') RETURNING id`,
+		"user:"+strings.ToLower(email), prefix, keyHash, email, ratePerMin, quotaTotal,
+	).Scan(&keyID); err != nil {
+		return "", Account{}, err
+	}
+
+	var userID string
+	if err = tx.QueryRow(ctx,
+		`INSERT INTO app_user (email, password_hash, api_key_id) VALUES ($1,$2,$3) RETURNING id`,
+		email, string(pwHash), keyID,
+	).Scan(&userID); err != nil {
+		if isUniqueViolation(err) {
+			return "", Account{}, ErrEmailTaken
+		}
+		return "", Account{}, err
+	}
+
+	if err = tx.Commit(ctx); err != nil {
+		return "", Account{}, err
+	}
+	return key, Account{
+		ID: userID, Email: email, KeyID: keyID, KeyPrefix: prefix,
+		RateLimitPerMin: ratePerMin, QuotaTotal: quotaTotal,
+	}, nil
+}
+
+// Authenticate verifies an email/password pair and returns the account with its
+// current (non-revoked) key metadata. Returns ErrNotFound on unknown email or
+// wrong password.
+func (s *Store) Authenticate(ctx context.Context, email, password string) (Account, error) {
+	email = strings.TrimSpace(email)
+	var (
+		userID, pwHash string
+		keyID          *string
+	)
+	err := s.pool.QueryRow(ctx,
+		`SELECT id, password_hash, api_key_id FROM app_user WHERE lower(email) = lower($1)`, email,
+	).Scan(&userID, &pwHash, &keyID)
+	if errors.Is(err, pgx.ErrNoRows) {
+		_ = bcrypt.CompareHashAndPassword([]byte(bcryptDummyHash), []byte(password))
+		return Account{}, ErrNotFound
+	}
+	if err != nil {
+		return Account{}, err
+	}
+	if err := bcrypt.CompareHashAndPassword([]byte(pwHash), []byte(password)); err != nil {
+		return Account{}, ErrNotFound
+	}
+
+	acct := Account{ID: userID, Email: email}
+	if keyID != nil {
+		acct.KeyID = *keyID
+		_ = s.pool.QueryRow(ctx,
+			`SELECT key_prefix, rate_limit_per_min, quota_total
+			 FROM api_key WHERE id = $1 AND revoked_at IS NULL`, *keyID,
+		).Scan(&acct.KeyPrefix, &acct.RateLimitPerMin, &acct.QuotaTotal)
+	}
+	return acct, nil
+}
+
+// RegenerateKey verifies credentials, revokes the account's current key, and
+// issues a fresh one with the same rate/quota, returning the plaintext key and
+// the previous key id (so cumulative usage can be carried over). Returns
+// ErrNotFound on bad credentials.
+func (s *Store) RegenerateKey(ctx context.Context, email, password string, ratePerMin int, quotaTotal int64) (plaintext string, acct Account, oldKeyID string, err error) {
+	cur, err := s.Authenticate(ctx, email, password)
+	if err != nil {
+		return "", Account{}, "", err
+	}
+	key, keyHash, prefix, err := apikey.Generate()
+	if err != nil {
+		return "", Account{}, "", err
+	}
+
+	oldKeyID = cur.KeyID
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return "", Account{}, "", err
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	if oldKeyID != "" {
+		if _, err = tx.Exec(ctx,
+			`UPDATE api_key SET revoked_at = now() WHERE id = $1`, oldKeyID); err != nil {
+			return "", Account{}, "", err
+		}
+	}
+	var newKeyID string
+	if err = tx.QueryRow(ctx,
+		`INSERT INTO api_key (name, key_prefix, key_hash, owner_email, tier, rate_limit_per_min, quota_total, created_by)
+		 VALUES ($1,$2,$3,$4,'registered',$5,$6,'self-register') RETURNING id`,
+		"user:"+strings.ToLower(cur.Email), prefix, keyHash, cur.Email, ratePerMin, quotaTotal,
+	).Scan(&newKeyID); err != nil {
+		return "", Account{}, "", err
+	}
+	if _, err = tx.Exec(ctx,
+		`UPDATE app_user SET api_key_id = $1 WHERE id = $2`, newKeyID, cur.ID); err != nil {
+		return "", Account{}, "", err
+	}
+	if err = tx.Commit(ctx); err != nil {
+		return "", Account{}, "", err
+	}
+
+	cur.KeyID = newKeyID
+	cur.KeyPrefix = prefix
+	cur.RateLimitPerMin = ratePerMin
+	cur.QuotaTotal = quotaTotal
+	return key, cur, oldKeyID, nil
+}

api/internal/store/account_test.go

@@ -0,0 +1,99 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"github.com/baicai2026-baicai/goods/api/internal/apikey"
+)
+
+func testStore(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 hasUser bool
+	if err := pool.QueryRow(ctx, "SELECT to_regclass('public.app_user') IS NOT NULL").Scan(&hasUser); err != nil || !hasUser {
+		pool.Close()
+		t.Skip("migrations not applied")
+	}
+	t.Cleanup(pool.Close)
+	return New(pool)
+}
+
+func TestRegisterAuthenticateRegenerate(t *testing.T) {
+	s := testStore(t)
+	ctx := context.Background()
+	email := fmt.Sprintf("user-%d@example.com", time.Now().UnixNano())
+
+	t.Cleanup(func() {
+		_, _ = s.pool.Exec(ctx, "DELETE FROM app_user WHERE lower(email)=lower($1)", email)
+		_, _ = s.pool.Exec(ctx, "DELETE FROM api_key WHERE owner_email=$1", email)
+	})
+
+	key, acct, err := s.RegisterUser(ctx, email, "supersecret", 300, 100000)
+	if err != nil {
+		t.Fatalf("register: %v", err)
+	}
+	if key == "" || acct.KeyPrefix == "" || acct.QuotaTotal != 100000 || acct.RateLimitPerMin != 300 {
+		t.Fatalf("unexpected account: %+v key=%q", acct, key)
+	}
+
+	// The issued key resolves via the public auth path with its quota attached.
+	k, err := s.APIKeyByHash(ctx, apikey.Hash(key))
+	if err != nil {
+		t.Fatalf("APIKeyByHash: %v", err)
+	}
+	if k.QuotaTotal != 100000 || k.RateLimitPerMin != 300 {
+		t.Fatalf("key metadata mismatch: %+v", k)
+	}
+
+	// Duplicate email is rejected.
+	if _, _, err := s.RegisterUser(ctx, email, "anotherpass", 300, 100000); !errors.Is(err, ErrEmailTaken) {
+		t.Fatalf("expected ErrEmailTaken, got %v", err)
+	}
+
+	// Wrong password fails; correct password authenticates.
+	if _, err := s.Authenticate(ctx, email, "wrong"); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("expected ErrNotFound for bad password, got %v", err)
+	}
+	got, err := s.Authenticate(ctx, email, "supersecret")
+	if err != nil {
+		t.Fatalf("authenticate: %v", err)
+	}
+	if got.KeyPrefix != acct.KeyPrefix {
+		t.Fatalf("authenticate key prefix = %q want %q", got.KeyPrefix, acct.KeyPrefix)
+	}
+
+	// Regeneration revokes the old key and issues a new one.
+	newKey, regen, oldKeyID, err := s.RegenerateKey(ctx, email, "supersecret", 300, 100000)
+	if err != nil {
+		t.Fatalf("regenerate: %v", err)
+	}
+	if newKey == key || oldKeyID != acct.KeyID || regen.KeyID == oldKeyID {
+		t.Fatalf("regenerate did not rotate key: old=%s new=%+v", oldKeyID, regen)
+	}
+	if _, err := s.APIKeyByHash(ctx, apikey.Hash(key)); !errors.Is(err, ErrNotFound) {
+		t.Fatalf("old key should be revoked, got %v", err)
+	}
+	if _, err := s.APIKeyByHash(ctx, apikey.Hash(newKey)); err != nil {
+		t.Fatalf("new key should be active: %v", err)
+	}
+}

api/internal/store/store.go

@@ -4,8 +4,10 @@ package store
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"strconv"
+	"strings"
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgxpool"
@@ -56,6 +58,15 @@ type Barcode struct {
 	IsPrimary bool    `json:"is_primary"`
 }
 
+// ProductSpec is one labeled spec line for a non-food product, rendered from
+// the product's attributes JSONB against its archive kind's field template.
+type ProductSpec struct {
+	Key   string `json:"key"`
+	Label string `json:"label"`
+	Value string `json:"value"`
+	Unit  string `json:"unit,omitempty"`
+}
+
 // Product is the full public view of a product.
 type Product struct {
 	ID              string         `json:"id"`
@@ -64,11 +75,13 @@ type Product struct {
 	Brand           *string        `json:"brand"`
 	CategoryPath    *string        `json:"category_path"`
 	GPCBrickCode    *string        `json:"gpc_brick_code"`
+	ArchiveKind     string         `json:"archive_kind"`
 	NetContentValue *float64       `json:"net_content_value"`
 	NetContentUnit  *string        `json:"net_content_unit"`
 	CountryOfOrigin *string        `json:"country_of_origin"`
 	QualityScore    float64        `json:"quality_score"`
 	Barcodes        []Barcode      `json:"barcodes"`
+	Specs           []ProductSpec  `json:"specs,omitempty"`
 	Nutriments      map[string]any `json:"nutriments,omitempty"`
 	NutritionBasis  *string        `json:"nutrition_basis,omitempty"`
 	NutriScore      *string        `json:"nutri_score,omitempty"`
@@ -120,6 +133,7 @@ type SearchFilters struct {
 
 const productSelect = `
 SELECT p.id, p.gtin, p.name, b.name, c.path::text, p.gpc_brick_code,
+       COALESCE(c.archive_kind, 'generic'), p.attributes,
        p.net_content_value, p.net_content_unit, p.country_of_origin, p.quality_score,
        f.nutriments, f.nutrition_basis, f.nutri_score, f.ingredients_text,
        f.allergens, f.additives
@@ -129,21 +143,81 @@ LEFT JOIN category c ON c.id = p.category_id
 LEFT JOIN food_detail f ON f.product_id = p.id
 `
 
-func scanProduct(row pgx.Row) (*Product, error) {
+func scanProduct(row pgx.Row) (*Product, []byte, error) {
 	var p Product
+	var attributes []byte
 	err := row.Scan(
 		&p.ID, &p.GTIN, &p.Name, &p.Brand, &p.CategoryPath, &p.GPCBrickCode,
+		&p.ArchiveKind, &attributes,
 		&p.NetContentValue, &p.NetContentUnit, &p.CountryOfOrigin, &p.QualityScore,
 		&p.Nutriments, &p.NutritionBasis, &p.NutriScore, &p.Ingredients,
 		&p.Allergens, &p.Additives,
 	)
 	if errors.Is(err, pgx.ErrNoRows) {
-		return nil, ErrNotFound
+		return nil, nil, ErrNotFound
 	}
+	if err != nil {
+		return nil, nil, err
+	}
+	return &p, attributes, nil
+}
+
+// buildSpecs renders the labeled, ordered spec list for a non-food product from
+// its attributes JSONB against its archive kind's field template.
+func (s *Store) buildSpecs(ctx context.Context, kind string, attributes []byte) ([]ProductSpec, error) {
+	if kind == "" || kind == "food" || len(attributes) == 0 {
+		return nil, nil
+	}
+	attrs := map[string]any{}
+	if err := json.Unmarshal(attributes, &attrs); err != nil || len(attrs) == 0 {
+		return nil, nil
+	}
+	rows, err := s.pool.Query(ctx,
+		"SELECT field_key, label_zh, COALESCE(unit, '') FROM kind_field WHERE kind = $1 ORDER BY sort_order, field_key", kind)
 	if err != nil {
 		return nil, err
 	}
-	return &p, nil
+	defer rows.Close()
+	specs := []ProductSpec{}
+	for rows.Next() {
+		var key, label, unit string
+		if err := rows.Scan(&key, &label, &unit); err != nil {
+			return nil, err
+		}
+		v, ok := attrs[key]
+		if !ok || v == nil {
+			continue
+		}
+		val := stringifyAttr(v)
+		if val == "" {
+			continue
+		}
+		specs = append(specs, ProductSpec{Key: key, Label: label, Value: val, Unit: unit})
+	}
+	return specs, rows.Err()
+}
+
+// stringifyAttr renders a JSON attribute value as display text.
+func stringifyAttr(v any) string {
+	switch t := v.(type) {
+	case string:
+		return t
+	case float64:
+		return strconv.FormatFloat(t, 'f', -1, 64)
+	case bool:
+		if t {
+			return "是"
+		}
+		return "否"
+	case []any:
+		parts := make([]string, 0, len(t))
+		for _, e := range t {
+			parts = append(parts, stringifyAttr(e))
+		}
+		return strings.Join(parts, "、")
+	default:
+		return ""
+	}
 }
 
 // ProductByGTIN looks up an active product by any of its barcodes.
@@ -154,26 +228,32 @@ func (s *Store) ProductByGTIN(ctx context.Context, gtin string) (*Product, error
          SELECT 1 FROM product_barcode pb
          WHERE pb.product_id = p.id AND pb.gtin = $1))
  LIMIT 1`, gtin)
-	p, err := scanProduct(row)
+	p, attrs, err := scanProduct(row)
 	if err != nil {
 		return nil, err
 	}
 	if p.Barcodes, err = s.ProductBarcodes(ctx, p.ID); err != nil {
 		return nil, err
 	}
+	if p.Specs, err = s.buildSpecs(ctx, p.ArchiveKind, attrs); err != nil {
+		return nil, err
+	}
 	return p, nil
 }
 
 // ProductByID looks up a product by its UUID.
 func (s *Store) ProductByID(ctx context.Context, id string) (*Product, error) {
 	row := s.pool.QueryRow(ctx, productSelect+" WHERE p.id = $1", id)
-	p, err := scanProduct(row)
+	p, attrs, err := scanProduct(row)
 	if err != nil {
 		return nil, err
 	}
 	if p.Barcodes, err = s.ProductBarcodes(ctx, p.ID); err != nil {
 		return nil, err
 	}
+	if p.Specs, err = s.buildSpecs(ctx, p.ArchiveKind, attrs); err != nil {
+		return nil, err
+	}
 	return p, nil
 }
 
@@ -373,6 +453,7 @@ type APIKey struct {
 	ID              string
 	Name            string
 	RateLimitPerMin int
+	QuotaTotal      int64
 }
 
 // APIKeyByHash returns the active (non-revoked) key matching a SHA-256 hash,
@@ -380,9 +461,9 @@ type APIKey struct {
 func (s *Store) APIKeyByHash(ctx context.Context, hash string) (*APIKey, error) {
 	var k APIKey
 	err := s.pool.QueryRow(ctx,
-		`SELECT id, name, rate_limit_per_min
+		`SELECT id, name, rate_limit_per_min, quota_total
 		 FROM api_key WHERE key_hash = $1 AND revoked_at IS NULL`, hash,
-	).Scan(&k.ID, &k.Name, &k.RateLimitPerMin)
+	).Scan(&k.ID, &k.Name, &k.RateLimitPerMin, &k.QuotaTotal)
 	if errors.Is(err, pgx.ErrNoRows) {
 		return nil, ErrNotFound
 	}

ingestion/opengoods/adapters/bypos.py

@@ -0,0 +1,116 @@
+"""Adapter for the bypos-collector output (central product library zc.bypos.net).
+
+The ``bypos-collector`` tool (see ``tools/bypos-collector``) queries the same
+central product library that the 云店 POS uses when adding a product by barcode,
+and writes one JSON object per line (JSONL) with these fields::
+
+    barcode name spec unit area manufacturer license
+    in_price sell_price status retmsg fetched_at source
+
+This module turns one such record into the internal product shape consumed by
+:func:`opengoods.etl.load.load_bypos_record`. It is a pure function (no DB, no
+network) so it is easy to unit-test.
+
+The central library is a Chinese retail catalogue: it provides 品名/规格/单位/
+产地/厂商/建议价 but **not** ingredients or nutrition, so no ``food`` block is
+produced.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation
+
+from opengoods.etl.transform import _clamp, is_valid_gtin, parse_quantity
+from opengoods.units import UnitError, normalize
+
+SOURCE_NAME = "bypos中心库"
+SOURCE_HOMEPAGE = "https://zc.bypos.net"
+# Vendor catalogue data; not an open-licensed dataset. Display facts only.
+SOURCE_LICENSE = "proprietary"
+SOURCE_TRUST = 0.6
+
+
+def _to_price(text: str | None) -> Decimal | None:
+    """Parse a price string to a positive Decimal, or None for empty/zero."""
+    if not text:
+        return None
+    try:
+        amount = Decimal(str(text).strip())
+    except (InvalidOperation, ValueError):
+        return None
+    if amount <= 0:
+        return None
+    return amount
+
+
+def _net_content(spec: str | None) -> tuple[Decimal | None, str | None, Decimal | None]:
+    """Best-effort parse a spec like '500mL'/'5kg' to (value, unit, canonical).
+
+    Packaging-style specs ('20支', '1X24', '盒') have no mass/volume unit and
+    yield ``(None, None, None)`` — the raw spec is kept in attributes instead.
+    """
+    parsed = parse_quantity(spec or "")
+    if not parsed:
+        return None, None, None
+    value, unit = parsed
+    try:
+        norm = normalize(value, unit)
+    except UnitError:
+        return None, None, None
+    return norm.value, norm.unit, norm.canonical_value
+
+
+def transform_bypos(rec: dict) -> dict | None:
+    """Transform one bypos-collector JSONL record into an internal product dict.
+
+    Returns ``None`` for non-hit rows or rows without a usable name.
+    """
+    if rec.get("status") != "hit":
+        return None
+    name = (rec.get("name") or "").strip()
+    if not name:
+        return None
+
+    barcode = str(rec.get("barcode") or "").strip()
+    gtin = barcode if barcode and is_valid_gtin(barcode) else None
+
+    net_value, net_unit, net_canonical = _net_content(rec.get("spec"))
+
+    spec = (rec.get("spec") or "").strip()
+    pack_unit = (rec.get("unit") or "").strip()
+    area = (rec.get("area") or "").strip()
+    manufacturer = (rec.get("manufacturer") or "").strip() or None
+    license_no = (rec.get("license") or "").strip()
+    in_price = _to_price(rec.get("in_price"))
+    sell_price = _to_price(rec.get("sell_price"))
+
+    attributes: dict[str, object] = {}
+    if spec:
+        attributes["spec"] = spec
+    if pack_unit:
+        attributes["pack_unit"] = pack_unit
+    if area:
+        attributes["origin_area"] = area
+    if license_no:
+        attributes["production_license"] = license_no
+    if in_price is not None:
+        attributes["suggested_in_price"] = float(in_price)
+    if sell_price is not None:
+        attributes["suggested_retail_price"] = float(sell_price)
+
+    # Domestic GS1-China barcodes (69x) are China-made; area is a province/city,
+    # kept separately in attributes.origin_area.
+    country = "中国" if gtin and gtin.startswith("69") else None
+
+    return {
+        "gtin": gtin,
+        "name": name,
+        "manufacturer": manufacturer,
+        "net_content_value": net_value,
+        "net_content_unit": _clamp(net_unit, 16),
+        "net_content_canonical": net_canonical,
+        "country_of_origin": country,
+        "attributes": attributes,
+        "msrp": sell_price,
+        "fetched_at": (rec.get("fetched_at") or "").strip() or None,
+    }

ingestion/opengoods/etl/load.py

@@ -14,6 +14,10 @@ from typing import Any
 import psycopg
 from psycopg.types.json import Jsonb
 
+from opengoods.adapters.bypos import SOURCE_HOMEPAGE as SOURCE_HOMEPAGE_BYPOS
+from opengoods.adapters.bypos import SOURCE_LICENSE as SOURCE_LICENSE_BYPOS
+from opengoods.adapters.bypos import SOURCE_NAME as SOURCE_NAME_BYPOS
+from opengoods.adapters.bypos import SOURCE_TRUST as SOURCE_TRUST_BYPOS
 from opengoods.adapters.openfoodfacts import OFF_LICENSE, SOURCE_NAME
 from opengoods.etl.quality import update_quality
 
@@ -73,6 +77,23 @@ def _ensure_brand(conn: psycopg.Connection, name: str | None) -> str | None:
     return row[0]
 
 
+def _ensure_manufacturer(
+    conn: psycopg.Connection, name: str | None, country: str | None = None
+) -> str | None:
+    if not name:
+        return None
+    row = conn.execute(
+        """
+        INSERT INTO manufacturer (name, normalized_name, country)
+        VALUES (%s, %s, %s)
+        ON CONFLICT (normalized_name) DO UPDATE SET name = manufacturer.name
+        RETURNING id
+        """,
+        (name, _normalize_brand(name), country),
+    ).fetchone()
+    return row[0]
+
+
 def _category_id(conn: psycopg.Connection, path: str | None) -> tuple[str | None, str | None]:
     if not path:
         return None, None
@@ -218,6 +239,140 @@ def load_record_safe(
         return False
 
 
+def ensure_bypos_source(conn: psycopg.Connection) -> str:
+    """Upsert the bypos central-library source row and return its id."""
+    return ensure_source_named(
+        conn,
+        SOURCE_NAME_BYPOS,
+        SOURCE_HOMEPAGE_BYPOS,
+        SOURCE_LICENSE_BYPOS,
+        SOURCE_TRUST_BYPOS,
+    )
+
+
+def load_bypos_record(
+    conn: psycopg.Connection, rec: dict[str, Any], source_id: str, raw: dict
+) -> str:
+    """Upsert one transformed bypos record; return the product id.
+
+    Unlike OFF records these have no ingredients/nutrition, so no ``food_detail``
+    row is written. The suggested retail price (if any) is stored as a CNY MSRP
+    snapshot, and provenance/MSRP rows are keyed by source so a re-import
+    refreshes rather than duplicates them.
+    """
+    manufacturer_id = _ensure_manufacturer(
+        conn, rec.get("manufacturer"), rec.get("country_of_origin")
+    )
+    attrs = rec.get("attributes") or {}
+    fields = ["name", "net_content", "country_of_origin"]
+    if manufacturer_id:
+        fields.append("manufacturer")
+    if attrs:
+        fields.append("attributes")
+
+    if rec.get("gtin"):
+        fields.append("gtin")
+        prod = conn.execute(
+            """
+            INSERT INTO product (gtin, name, manufacturer_id,
+                net_content_value, net_content_unit, net_content_canonical,
+                country_of_origin, attributes)
+            VALUES (%s,%s,%s,%s,%s,%s,%s,%s)
+            ON CONFLICT (gtin) WHERE gtin IS NOT NULL DO UPDATE SET
+                name = EXCLUDED.name,
+                manufacturer_id = COALESCE(EXCLUDED.manufacturer_id, product.manufacturer_id),
+                net_content_value = COALESCE(EXCLUDED.net_content_value, product.net_content_value),
+                net_content_unit = COALESCE(EXCLUDED.net_content_unit, product.net_content_unit),
+                net_content_canonical = COALESCE(
+                    EXCLUDED.net_content_canonical, product.net_content_canonical),
+                country_of_origin = COALESCE(EXCLUDED.country_of_origin, product.country_of_origin),
+                attributes = product.attributes || EXCLUDED.attributes
+            RETURNING id
+            """,
+            (
+                rec["gtin"],
+                rec["name"],
+                manufacturer_id,
+                rec.get("net_content_value"),
+                rec.get("net_content_unit"),
+                rec.get("net_content_canonical"),
+                rec.get("country_of_origin"),
+                Jsonb(attrs),
+            ),
+        ).fetchone()
+    else:
+        prod = conn.execute(
+            """
+            INSERT INTO product (name, manufacturer_id,
+                net_content_value, net_content_unit, net_content_canonical,
+                country_of_origin, attributes)
+            VALUES (%s,%s,%s,%s,%s,%s,%s)
+            RETURNING id
+            """,
+            (
+                rec["name"],
+                manufacturer_id,
+                rec.get("net_content_value"),
+                rec.get("net_content_unit"),
+                rec.get("net_content_canonical"),
+                rec.get("country_of_origin"),
+                Jsonb(attrs),
+            ),
+        ).fetchone()
+    product_id = prod[0]
+
+    # Refresh this source's MSRP snapshot (suggested retail price, CNY).
+    conn.execute(
+        "DELETE FROM product_msrp WHERE product_id = %s AND source_id = %s",
+        (product_id, source_id),
+    )
+    if rec.get("msrp") is not None:
+        conn.execute(
+            """
+            INSERT INTO product_msrp (product_id, amount, currency, region, source_id, source_url)
+            VALUES (%s,%s,'CNY','CN',%s,%s)
+            """,
+            (product_id, rec["msrp"], source_id, SOURCE_HOMEPAGE_BYPOS),
+        )
+        fields.append("msrp")
+
+    # Refresh this source's provenance row (one per source for idempotency).
+    conn.execute(
+        "DELETE FROM product_source WHERE product_id = %s AND source_id = %s",
+        (product_id, source_id),
+    )
+    conn.execute(
+        """
+        INSERT INTO product_source (product_id, source_id, url, fields, fetched_at, raw)
+        VALUES (%s,%s,%s,%s, COALESCE(%s::timestamptz, now()), %s)
+        """,
+        (
+            product_id,
+            source_id,
+            SOURCE_HOMEPAGE_BYPOS,
+            fields,
+            rec.get("fetched_at"),
+            Jsonb(_jsonable(raw)),
+        ),
+    )
+
+    update_quality(conn, product_id)
+    return product_id
+
+
+def load_bypos_record_safe(
+    conn: psycopg.Connection, rec: dict[str, Any], source_id: str, raw: dict
+) -> bool:
+    """Load one bypos record inside a savepoint (see :func:`load_record_safe`)."""
+    try:
+        with conn.transaction():
+            load_bypos_record(conn, rec, source_id, raw)
+        return True
+    except Exception as exc:  # noqa: BLE001 - per-record isolation is intentional
+        logger.warning("skipping bypos record gtin=%s: %s", rec.get("gtin"), exc)
+        return False
+
+
 def _jsonable(raw: dict) -> dict:
     """Drop values that are not JSON-serializable from a raw record."""
     try:

ingestion/opengoods/jobs/import_bypos.py

@@ -0,0 +1,77 @@
+"""Import products collected by the bypos-collector tool into OpenGoods.
+
+The ``tools/bypos-collector`` program writes one product per line (JSONL). This
+job reads such a file, transforms each ``hit`` record into the internal product
+shape, and upserts it into the database under the ``bypos中心库`` source with
+field-level provenance.
+
+Usage::
+
+    python -m opengoods.jobs.import_bypos --input products.jsonl
+    python -m opengoods.jobs.import_bypos --input products.jsonl --limit 500
+
+Re-running is safe: products are upserted by GTIN and the source's MSRP/
+provenance rows are refreshed rather than duplicated.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import sys
+from collections.abc import Iterator
+
+import psycopg
+
+from opengoods.adapters.bypos import transform_bypos
+from opengoods.etl.load import default_dsn, ensure_bypos_source, load_bypos_record_safe
+
+
+def _read_jsonl(path: str) -> Iterator[dict]:
+    opener = gzip.open if path.endswith(".gz") else open
+    with opener(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+
+def run(args: argparse.Namespace) -> int:
+    loaded = skipped = errored = 0
+    with psycopg.connect(args.dsn, autocommit=False) as conn:
+        source_id = ensure_bypos_source(conn)
+        yielded = 0
+        for raw in _read_jsonl(args.input):
+            if args.limit and yielded >= args.limit:
+                break
+            rec = transform_bypos(raw)
+            if rec is None:
+                skipped += 1
+                continue
+            yielded += 1
+            if load_bypos_record_safe(conn, rec, source_id, raw):
+                loaded += 1
+            else:
+                errored += 1
+        conn.commit()
+    print(f"loaded={loaded} skipped={skipped} errored={errored}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Import bypos-collector JSONL into OpenGoods")
+    parser.add_argument(
+        "--input", required=True, help="path to a bypos-collector JSONL (.jsonl or .jsonl.gz)"
+    )
+    parser.add_argument("--limit", type=int, default=0, help="max hit records to load (0 = all)")
+    parser.add_argument("--dsn", default=default_dsn(), help="PostgreSQL DSN")
+    return run(parser.parse_args(argv))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ingestion/tests/test_bypos.py

@@ -0,0 +1,155 @@
+"""Tests for the bypos-collector adapter/transform and DB loader.
+
+The pure-function tests run anywhere; the DB roundtrip is skipped automatically
+when no database is reachable or migrations are not applied.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+import pytest
+
+from opengoods.adapters.bypos import transform_bypos
+
+psycopg = pytest.importorskip("psycopg")
+
+# A real central-library "hit" row as emitted by the collector.
+HIT = {
+    "barcode": "6901028941068",
+    "name": "泰山合悦",
+    "spec": "20支",
+    "unit": "盒",
+    "area": "广东",
+    "manufacturer": "",
+    "license": "",
+    "in_price": "22.50",
+    "sell_price": "28.00",
+    "status": "hit",
+    "retmsg": "获取商品信息成功",
+    "fetched_at": "2026-06-24T02:08:34Z",
+    "source": "zc.bypos.net",
+}
+
+# A hit with a real mass/volume spec that should normalize to net content.
+HIT_VOLUME = {
+    "barcode": "6920459905012",
+    "name": "康师傅冰红茶490ml",
+    "spec": "490毫升",
+    "unit": "瓶",
+    "area": "浙江杭州",
+    "manufacturer": "",
+    "license": "",
+    "in_price": "2.20",
+    "sell_price": "3.00",
+    "status": "hit",
+    "fetched_at": "2026-06-24T02:08:34Z",
+    "source": "zc.bypos.net",
+}
+
+
+def test_transform_skips_non_hit():
+    assert transform_bypos({**HIT, "status": "miss", "name": ""}) is None
+    assert transform_bypos({**HIT, "status": "invalid"}) is None
+
+
+def test_transform_skips_missing_name():
+    assert transform_bypos({**HIT, "name": "  "}) is None
+
+
+def test_transform_packaging_spec_kept_raw():
+    rec = transform_bypos(HIT)
+    assert rec is not None
+    assert rec["gtin"] == "6901028941068"
+    assert rec["name"] == "泰山合悦"
+    # '20支' is a count, not mass/volume -> no net_content, raw spec retained.
+    assert rec["net_content_value"] is None
+    assert rec["net_content_unit"] is None
+    assert rec["attributes"]["spec"] == "20支"
+    assert rec["attributes"]["pack_unit"] == "盒"
+    assert rec["attributes"]["origin_area"] == "广东"
+    assert rec["attributes"]["suggested_in_price"] == 22.5
+    assert rec["attributes"]["suggested_retail_price"] == 28.0
+    assert rec["msrp"] == Decimal("28.00")
+    assert rec["country_of_origin"] == "中国"
+
+
+def test_transform_volume_spec_normalized():
+    rec = transform_bypos(HIT_VOLUME)
+    assert rec is not None
+    assert rec["net_content_value"] == Decimal("490")
+    assert rec["net_content_unit"] == "ml"
+    assert rec["net_content_canonical"] == Decimal("490")
+    assert rec["attributes"]["origin_area"] == "浙江杭州"
+
+
+def test_transform_zero_price_dropped():
+    rec = transform_bypos({**HIT, "in_price": "0.00", "sell_price": "0.00"})
+    assert rec is not None
+    assert rec["msrp"] is None
+    assert "suggested_in_price" not in rec["attributes"]
+    assert "suggested_retail_price" not in rec["attributes"]
+
+
+def test_transform_invalid_barcode_no_gtin():
+    rec = transform_bypos({**HIT, "barcode": "123"})
+    assert rec is not None
+    assert rec["gtin"] is None
+    assert rec["country_of_origin"] is None
+
+
+# --- DB roundtrip (skipped without a database) ---------------------------------
+
+
+@pytest.fixture()
+def conn():
+    from opengoods.etl.load import default_dsn
+
+    try:
+        c = psycopg.connect(default_dsn(), connect_timeout=3)
+    except psycopg.OperationalError as exc:  # pragma: no cover - env dependent
+        pytest.skip(f"no database available: {exc}")
+    has_product = c.execute("SELECT to_regclass('public.product') IS NOT NULL").fetchone()[0]
+    if not has_product:
+        c.close()
+        pytest.skip("migrations not applied")
+    yield c
+    c.rollback()
+    c.close()
+
+
+def test_load_bypos_roundtrip(conn):
+    from opengoods.etl.load import ensure_bypos_source, load_bypos_record
+
+    source_id = ensure_bypos_source(conn)
+    rec = transform_bypos(HIT_VOLUME)
+    product_id = load_bypos_record(conn, rec, source_id, HIT_VOLUME)
+
+    row = conn.execute(
+        "SELECT name, gtin, net_content_unit, country_of_origin, attributes ->> 'pack_unit' "
+        "FROM product WHERE id = %s",
+        (product_id,),
+    ).fetchone()
+    assert row[0] == "康师傅冰红茶490ml"
+    assert row[1] == "6920459905012"
+    assert row[2] == "ml"
+    assert row[3] == "中国"
+    assert row[4] == "瓶"
+
+    msrp = conn.execute(
+        "SELECT amount, currency FROM product_msrp WHERE product_id = %s AND source_id = %s",
+        (product_id, source_id),
+    ).fetchone()
+    assert msrp[0] == Decimal("3.00")
+    assert msrp[1] == "CNY"
+
+    # Re-import is idempotent: still one MSRP and one provenance row per source.
+    load_bypos_record(conn, rec, source_id, HIT_VOLUME)
+    counts = conn.execute(
+        "SELECT (SELECT count(*) FROM product_msrp WHERE product_id=%s AND source_id=%s), "
+        "(SELECT count(*) FROM product_source WHERE product_id=%s AND source_id=%s)",
+        (product_id, source_id, product_id, source_id),
+    ).fetchone()
+    assert counts == (1, 1)
+
+    conn.rollback()

migrations/0010_archive_kinds.down.sql

@@ -0,0 +1,9 @@
+-- Detach any products from the seeded 3C categories, then remove them.
+UPDATE product SET category_id = NULL
+WHERE category_id IN (SELECT id FROM category WHERE path <@ 'electronics');
+
+DELETE FROM category WHERE path <@ 'electronics';
+
+DROP TABLE IF EXISTS kind_field;
+
+ALTER TABLE category DROP COLUMN IF EXISTS archive_kind;

migrations/0010_archive_kinds.up.sql

@@ -0,0 +1,64 @@
+-- Generic, extensible "archive kind" (档案模式) framework.
+-- Instead of a dedicated detail table per domain (food/electronics/drug/...),
+-- each category belongs to an archive_kind, and a metadata table (kind_field)
+-- describes the editable spec fields for that kind. Non-food spec values live
+-- in the existing product.attributes JSONB. Adding a new domain later (drug,
+-- machinery, ...) is just: seed kind_field rows + a category subtree.
+
+ALTER TABLE category ADD COLUMN archive_kind VARCHAR(24) NOT NULL DEFAULT 'generic';
+
+-- The existing seeded tree is the food domain.
+UPDATE category SET archive_kind = 'food' WHERE path <@ 'food';
+
+-- Field template per archive kind: drives the dynamic admin form and the
+-- kind-aware completeness/qualified computation.
+CREATE TABLE kind_field (
+    kind        VARCHAR(24) NOT NULL,
+    field_key   VARCHAR(64) NOT NULL,
+    group_label TEXT NOT NULL DEFAULT '',
+    label_zh    TEXT NOT NULL,
+    field_type  VARCHAR(16) NOT NULL DEFAULT 'text',
+    unit        TEXT,
+    options     TEXT[] NOT NULL DEFAULT '{}',
+    placeholder TEXT,
+    sort_order  INT NOT NULL DEFAULT 0,
+    qualified   BOOLEAN NOT NULL DEFAULT false,
+    PRIMARY KEY (kind, field_key),
+    CONSTRAINT kind_field_type_chk CHECK (field_type IN ('text','number','textarea','select','list'))
+);
+
+-- Seed the electronics (3C) field template.
+INSERT INTO kind_field (kind, field_key, group_label, label_zh, field_type, unit, sort_order, qualified) VALUES
+('electronics','model_number',   '基础规格','型号',        'text',   NULL,  10, true),
+('electronics','ccc_cert',       '基础规格','3C认证号(CCC)','text',  NULL,  20, true),
+('electronics','color',          '基础规格','颜色',        'text',   NULL,  30, false),
+('electronics','release_year',   '基础规格','发布年份',    'number', NULL,  40, false),
+('electronics','warranty_months','基础规格','保修期',      'number', '月',  50, false),
+('electronics','dimensions',     '外形','尺寸(长x宽x高)',  'text',   'mm',  60, false),
+('electronics','weight',         '外形','重量',            'number', 'g',   70, false),
+('electronics','power',          '外形','电源/功率',       'text',   NULL,  80, false),
+('electronics','os',             '关键参数','操作系统',    'text',   NULL,  90, false),
+('electronics','cpu',            '关键参数','处理器',      'text',   NULL, 100, false),
+('electronics','ram',            '关键参数','内存',        'text',   NULL, 110, false),
+('electronics','storage',        '关键参数','存储',        'text',   NULL, 120, false),
+('electronics','screen_size',    '关键参数','屏幕尺寸',    'text',   NULL, 130, true),
+('electronics','battery',        '关键参数','电池容量',    'text',   NULL, 140, false),
+('electronics','ports',          '关键参数','接口',        'text',   NULL, 150, false);
+
+-- Seed the 3C category tree.
+INSERT INTO category (name_zh, name_en, parent_id, path, level, archive_kind)
+VALUES ('电子数码', 'Electronics', NULL, 'electronics', 0, 'electronics');
+
+INSERT INTO category (name_zh, name_en, parent_id, path, level, archive_kind)
+SELECT v.name_zh, v.name_en, c.id, v.path::ltree, 1, 'electronics'
+FROM (VALUES
+    ('手机',     'Smartphone',     'electronics.phone'),
+    ('笔记本电脑', 'Laptop',        'electronics.laptop'),
+    ('平板电脑',  'Tablet',         'electronics.tablet'),
+    ('智能手表',  'Smartwatch',     'electronics.watch'),
+    ('耳机',     'Headphone',      'electronics.headphone'),
+    ('相机',     'Camera',         'electronics.camera'),
+    ('电视',     'TV',             'electronics.tv'),
+    ('家用电器',  'Home appliance', 'electronics.appliance')
+) AS v(name_zh, name_en, path)
+JOIN category c ON c.path = 'electronics';

migrations/0011_api_quota.down.sql

@@ -0,0 +1,10 @@
+DROP TABLE IF EXISTS app_user;
+
+-- Demote any self-registered keys before restoring the narrower tier check.
+UPDATE api_key SET tier = 'free' WHERE tier = 'registered';
+
+ALTER TABLE api_key DROP CONSTRAINT IF EXISTS api_key_tier_chk;
+ALTER TABLE api_key ADD CONSTRAINT api_key_tier_chk
+    CHECK (tier IN ('free', 'partner', 'internal'));
+
+ALTER TABLE api_key DROP COLUMN IF EXISTS quota_total;

migrations/0011_api_quota.up.sql

@@ -0,0 +1,27 @@
+-- Cumulative usage quotas + self-service user registration for the public API.
+--
+-- The free anonymous tier is capped at a lifetime number of calls (enforced in
+-- Redis, keyed by client IP). To keep calling beyond the free quota a caller
+-- registers an account and self-issues an API key with a higher quota.
+-- quota_total = 0 means unlimited.
+--
+-- Registration is the one place the public server writes to PostgreSQL (it
+-- inserts an app_user and its api_key); every other public route stays
+-- read-only. Request counting still lives entirely in Redis.
+
+ALTER TABLE api_key ADD COLUMN IF NOT EXISTS quota_total BIGINT NOT NULL DEFAULT 0;
+
+ALTER TABLE api_key DROP CONSTRAINT IF EXISTS api_key_tier_chk;
+ALTER TABLE api_key ADD CONSTRAINT api_key_tier_chk
+    CHECK (tier IN ('free', 'registered', 'partner', 'internal'));
+
+CREATE TABLE IF NOT EXISTS app_user (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email         TEXT NOT NULL,
+    password_hash TEXT NOT NULL,
+    api_key_id    UUID REFERENCES api_key (id) ON DELETE SET NULL,
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Case-insensitive uniqueness so each email registers at most once.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_app_user_email ON app_user (lower(email));

public-frontend/src/App.tsx

@@ -1,16 +1,18 @@
 import { useEffect, useState } from "react";
-import { Boxes, Search, PlusCircle, Code2 } from "lucide-react";
+import { Boxes, Search, PlusCircle, Code2, KeyRound } from "lucide-react";
 import Home from "./components/Home";
 import ProductView from "./components/ProductView";
 import Contribute from "./components/Contribute";
 import ApiDocs from "./components/ApiDocs";
+import Account from "./components/Account";
 import { api } from "./api";
 
 type View =
   | { name: "home" }
   | { name: "product"; id: string }
   | { name: "contribute" }
-  | { name: "api" };
+  | { name: "api" }
+  | { name: "account" };
 
 export default function App() {
   const [view, setView] = useState<View>({ name: "home" });
@@ -59,6 +61,14 @@ export default function App() {
             >
               <Code2 className="w-4 h-4" /> API
             </button>
+            <button
+              className={`px-3 py-1.5 rounded-md flex items-center gap-1.5 ${
+                view.name === "account" ? "bg-emerald-50 text-emerald-700" : "text-gray-600 hover:bg-gray-100"
+              }`}
+              onClick={() => setView({ name: "account" })}
+            >
+              <KeyRound className="w-4 h-4" /> API 密钥
+            </button>
           </nav>
         </div>
       </header>
@@ -77,11 +87,12 @@ export default function App() {
         {view.name === "contribute" && (
           <Contribute onDone={() => setView({ name: "home" })} />
         )}
-        {view.name === "api" && <ApiDocs />}
+        {view.name === "api" && <ApiDocs onRegister={() => setView({ name: "account" })} />}
+        {view.name === "account" && <Account />}
       </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">
               目前已收录

public-frontend/src/api.ts

@@ -36,6 +36,23 @@ export interface Stats {
   min_score: number;
 }
 
+export interface KeyResponse {
+  email: string;
+  api_key: string;
+  key_prefix: string;
+  rate_limit_per_min: number;
+  quota_total: number;
+}
+
+export interface AccountInfo {
+  email: string;
+  key_prefix: string;
+  rate_limit_per_min: number;
+  quota_total: number;
+  quota_used: number;
+  quota_remaining: number;
+}
+
 export const api = {
   stats: () => req<Stats>(`/api/v1/stats`),
   search: (q: string, page = 1, size = 20, filters: SearchFilters = {}) => {
@@ -55,4 +72,19 @@ export const api = {
       method: "POST",
       body: JSON.stringify(input),
     }),
+  register: (email: string, password: string) =>
+    req<KeyResponse>(`/api/v1/register`, {
+      method: "POST",
+      body: JSON.stringify({ email, password }),
+    }),
+  account: (email: string, password: string) =>
+    req<AccountInfo>(`/api/v1/account`, {
+      method: "POST",
+      body: JSON.stringify({ email, password }),
+    }),
+  regenerate: (email: string, password: string) =>
+    req<KeyResponse>(`/api/v1/account/regenerate`, {
+      method: "POST",
+      body: JSON.stringify({ email, password }),
+    }),
 };

public-frontend/src/components/Account.tsx

@@ -0,0 +1,192 @@
+import { useState } from "react";
+import { Check, Copy, KeyRound, AlertTriangle } from "lucide-react";
+import { api, type AccountInfo, type KeyResponse } from "../api";
+
+function KeyReveal({ data }: { data: KeyResponse }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <div className="mt-4 rounded-lg border border-emerald-200 bg-emerald-50 p-4">
+      <div className="flex items-start gap-2 text-amber-700 text-sm">
+        <AlertTriangle className="w-4 h-4 mt-0.5 shrink-0" />
+        <span>请立即复制保存此密钥，它只显示这一次，无法再次查看。</span>
+      </div>
+      <div className="mt-3 flex items-center gap-2">
+        <code className="flex-1 break-all bg-white border rounded-md px-3 py-2 text-sm font-mono text-gray-800">
+          {data.api_key}
+        </code>
+        <button
+          onClick={async () => {
+            try {
+              await navigator.clipboard.writeText(data.api_key);
+              setCopied(true);
+              setTimeout(() => setCopied(false), 1200);
+            } catch {
+              /* clipboard unavailable */
+            }
+          }}
+          className="text-gray-400 hover:text-gray-600 shrink-0"
+          title="复制"
+        >
+          {copied ? <Check className="w-5 h-5 text-emerald-600" /> : <Copy className="w-5 h-5" />}
+        </button>
+      </div>
+      <div className="mt-3 text-sm text-gray-600">
+        配额：每分钟 <strong>{data.rate_limit_per_min}</strong> 次 · 累计{" "}
+        <strong>{data.quota_total.toLocaleString()}</strong> 次
+      </div>
+      <div className="mt-2 text-xs text-gray-500">
+        调用时通过请求头携带：
+        <code className="font-mono">X-API-Key: {data.api_key.slice(0, 12)}…</code>
+      </div>
+    </div>
+  );
+}
+
+export default function Account() {
+  const [mode, setMode] = useState<"register" | "manage">("register");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [issued, setIssued] = useState<KeyResponse | null>(null);
+  const [info, setInfo] = useState<AccountInfo | null>(null);
+
+  const reset = () => {
+    setError(null);
+    setIssued(null);
+    setInfo(null);
+  };
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    reset();
+    if (password.length < 8) {
+      setError("密码至少需要 8 位");
+      return;
+    }
+    setLoading(true);
+    try {
+      if (mode === "register") {
+        setIssued(await api.register(email, password));
+      } else {
+        setInfo(await api.account(email, password));
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "操作失败");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function regenerate() {
+    reset();
+    setLoading(true);
+    try {
+      setIssued(await api.regenerate(email, password));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "操作失败");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div className="max-w-xl mx-auto space-y-5">
+      <div className="bg-white border rounded-lg p-5">
+        <h1 className="flex items-center gap-2 text-2xl font-bold text-gray-800">
+          <KeyRound className="w-6 h-6 text-emerald-600" /> API 密钥
+        </h1>
+        <p className="mt-2 text-sm text-gray-600 leading-relaxed">
+          匿名调用免费，但每个来源 IP 累计共 <strong>1000</strong> 次。注册一个账号即可自助领取专属 API
+          密钥，获得更高的每分钟频率与累计调用配额。
+        </p>
+
+        <div className="mt-4 inline-flex rounded-md border bg-gray-50 p-0.5 text-sm">
+          <button
+            className={`px-4 py-1.5 rounded ${
+              mode === "register" ? "bg-white shadow-sm text-emerald-700" : "text-gray-500"
+            }`}
+            onClick={() => {
+              setMode("register");
+              reset();
+            }}
+          >
+            注册领取
+          </button>
+          <button
+            className={`px-4 py-1.5 rounded ${
+              mode === "manage" ? "bg-white shadow-sm text-emerald-700" : "text-gray-500"
+            }`}
+            onClick={() => {
+              setMode("manage");
+              reset();
+            }}
+          >
+            查看 / 重置
+          </button>
+        </div>
+
+        <form onSubmit={submit} className="mt-4 space-y-3">
+          <div>
+            <label className="block text-sm text-gray-600 mb-1">邮箱</label>
+            <input
+              type="email"
+              required
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              placeholder="you@example.com"
+              className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-500"
+            />
+          </div>
+          <div>
+            <label className="block text-sm text-gray-600 mb-1">密码（至少 8 位）</label>
+            <input
+              type="password"
+              required
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              placeholder="••••••••"
+              className="w-full border rounded-md px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-emerald-500"
+            />
+          </div>
+          {error && <div className="text-sm text-red-600">{error}</div>}
+          <button
+            type="submit"
+            disabled={loading}
+            className="w-full bg-emerald-600 text-white rounded-md py-2 text-sm font-medium hover:bg-emerald-700 disabled:opacity-50"
+          >
+            {loading ? "处理中…" : mode === "register" ? "注册并领取密钥" : "查询账号"}
+          </button>
+        </form>
+
+        {issued && <KeyReveal data={issued} />}
+
+        {info && (
+          <div className="mt-4 rounded-lg border bg-gray-50 p-4 text-sm text-gray-700 space-y-1.5">
+            <div>
+              邮箱：<span className="font-medium">{info.email}</span>
+            </div>
+            <div>
+              密钥前缀：<code className="font-mono">{info.key_prefix}…</code>
+            </div>
+            <div>
+              每分钟频率：<strong>{info.rate_limit_per_min}</strong> 次
+            </div>
+            <div>
+              累计配额：已用 <strong>{info.quota_used.toLocaleString()}</strong> /{" "}
+              {info.quota_total.toLocaleString()} 次（剩余{" "}
+              <strong className="text-emerald-600">{info.quota_remaining.toLocaleString()}</strong>）
+            </div>
+            <button
+              onClick={regenerate}
+              disabled={loading}
+              className="mt-2 text-emerald-600 hover:underline disabled:opacity-50"
+            >
+              忘记密钥？重置并生成新密钥
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

public-frontend/src/components/ApiDocs.tsx

@@ -102,7 +102,7 @@ function Endpoint({
   );
 }
 
-export default function ApiDocs() {
+export default function ApiDocs({ onRegister }: { onRegister?: () => void }) {
   return (
     <div className="space-y-5">
       <div className="bg-white border rounded-lg p-5">
@@ -117,7 +117,11 @@ 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；带 Key 可获得更高频率上限（见下文「鉴权与限流」）。</li>
+            <li>
+              无需 API Key / Token 即可直接 GET；匿名调用按来源 IP 累计共 <strong>1000</strong> 次，
+              用满后需<button onClick={onRegister} className="text-emerald-600 hover:underline">注册账号</button>
+              领取更高配额密钥（见下文「鉴权与配额」）。
+            </li>
             <li>
               分页参数 <code className="font-mono">page</code>（默认 1）、
               <code className="font-mono">size</code>（默认 20，最大 100）。
@@ -132,10 +136,13 @@ export default function ApiDocs() {
       </div>
 
       <div className="bg-white border rounded-lg p-5">
-        <h2 className="text-lg font-semibold text-gray-800">鉴权与限流</h2>
+        <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，请求时通过请求头携带：
+          API 默认<strong>匿名可用</strong>：无需任何凭证即可调用，但按来源 IP 计一个
+          <strong>累计总配额（共 1000 次）</strong>，用满后返回
+          <code className="font-mono">403</code>（错误码 <code className="font-mono">quota_exhausted</code>），
+          需<button onClick={onRegister} className="text-emerald-600 hover:underline">注册账号</button>
+          自助领取更高配额的 API Key。注册得到的密钥拥有更高的每分钟频率与累计调用配额，请求时通过请求头携带：
         </p>
         <div className="mt-3">
           <Code>{`# 二选一
@@ -143,7 +150,7 @@ 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>限流（每分钟）。每个响应都会回写以下响应头，便于客户端自适应：
+          同时采用<strong>每分钟固定窗口</strong>频率限制与<strong>累计总配额</strong>两层控制。每个响应都会回写以下响应头，便于客户端自适应：
         </p>
         <table className="mt-3 w-full text-sm">
           <thead className="text-gray-400 text-left">
@@ -169,12 +176,26 @@ curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛
               <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>
+            <tr>
+              <td className="pr-4 py-0.5 font-mono text-gray-700">X-Quota-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-Quota-Used</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-Quota-Remaining</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>。
+          每分钟超额返回 <code className="font-mono">429 Too Many Requests</code>（错误码
+          <code className="font-mono">rate_limited</code>）；累计配额用尽返回
+          <code className="font-mono">403</code>（错误码 <code className="font-mono">quota_exhausted</code>）；
+          无效或已吊销的 Key 返回 <code className="font-mono">401</code>（错误码
+          <code className="font-mono">invalid_api_key</code>）。
         </p>
       </div>
 
@@ -322,6 +343,70 @@ curl -H "Authorization: Bearer og_live_xxxxxxxx" ${BASE}/products/search?q=牛
 }`}
       />
 
+      <Endpoint
+        method="POST"
+        path="/api/v1/register"
+        title="注册账号并领取 API 密钥"
+        desc="用邮箱 + 密码（至少 8 位）注册，自助领取一枚更高配额的 API 密钥。明文密钥只在本次响应返回一次，请妥善保存。"
+        params={[
+          { name: "email", required: true, desc: "邮箱（唯一）" },
+          { name: "password", required: true, desc: "密码，至少 8 位" },
+        ]}
+        example={`curl -X POST ${BASE}/register \\
+  -H "Content-Type: application/json" \\
+  -d '{"email":"you@example.com","password":"your-password"}'`}
+        response={`{
+  "email": "you@example.com",
+  "api_key": "og_live_xxxxxxxxxxxx",
+  "key_prefix": "og_live_xxxx",
+  "rate_limit_per_min": 300,
+  "quota_total": 100000
+}`}
+      />
+
+      <Endpoint
+        method="POST"
+        path="/api/v1/account"
+        title="查看账号与配额用量"
+        desc="用邮箱 + 密码查询当前密钥前缀、频率/累计配额上限及已用量（不返回明文密钥）。"
+        params={[
+          { name: "email", required: true, desc: "注册邮箱" },
+          { name: "password", required: true, desc: "账号密码" },
+        ]}
+        example={`curl -X POST ${BASE}/account \\
+  -H "Content-Type: application/json" \\
+  -d '{"email":"you@example.com","password":"your-password"}'`}
+        response={`{
+  "email": "you@example.com",
+  "key_prefix": "og_live_xxxx",
+  "rate_limit_per_min": 300,
+  "quota_total": 100000,
+  "quota_used": 1234,
+  "quota_remaining": 98766
+}`}
+      />
+
+      <Endpoint
+        method="POST"
+        path="/api/v1/account/regenerate"
+        title="重置 API 密钥"
+        desc="吊销当前密钥并生成新密钥（累计用量会延续，不会因重置而清零）。明文新密钥只返回一次。"
+        params={[
+          { name: "email", required: true, desc: "注册邮箱" },
+          { name: "password", required: true, desc: "账号密码" },
+        ]}
+        example={`curl -X POST ${BASE}/account/regenerate \\
+  -H "Content-Type: application/json" \\
+  -d '{"email":"you@example.com","password":"your-password"}'`}
+        response={`{
+  "email": "you@example.com",
+  "api_key": "og_live_yyyyyyyyyyyy",
+  "key_prefix": "og_live_yyyy",
+  "rate_limit_per_min": 300,
+  "quota_total": 100000
+}`}
+      />
+
       <div className="text-xs text-gray-400 leading-relaxed">
         数据可能存在误差或滞后，按「现状」提供，不构成医疗/购买建议。商品资料版权归各原始来源所有，
         请遵循其许可（如 OpenFoodFacts 的 ODbL）。

public-frontend/src/components/ProductView.tsx

@@ -106,6 +106,23 @@ export default function ProductView({ id, onBack }: { id: string; onBack: () =>
         </div>
       </div>
 
+      {p.specs && p.specs.length > 0 && (
+        <div className="bg-white border rounded-lg p-5 mt-4">
+          <h2 className="font-medium text-gray-700 mb-2">规格参数</h2>
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-2 text-sm">
+            {p.specs.map((s) => (
+              <div key={s.key} className="bg-gray-50 rounded px-3 py-2">
+                <div className="text-gray-400 text-xs">{s.label}</div>
+                <div className="text-gray-800">
+                  {s.value}
+                  {s.unit ? ` ${s.unit}` : ""}
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
       {nutriEntries.length > 0 && (
         <div className="bg-white border rounded-lg p-5 mt-4">
           <h2 className="font-medium text-gray-700 mb-2">

public-frontend/src/types.ts

@@ -17,6 +17,13 @@ export interface Barcode {
   is_primary: boolean;
 }
 
+export interface ProductSpec {
+  key: string;
+  label: string;
+  value: string;
+  unit?: string;
+}
+
 export interface Product {
   id: string;
   gtin: string | null;
@@ -24,6 +31,8 @@ export interface Product {
   name: string;
   brand: string | null;
   category_path: string | null;
+  archive_kind?: string;
+  specs?: ProductSpec[] | null;
   net_content_value: number | null;
   net_content_unit: string | null;
   country_of_origin: string | null;

tools/bypos-collector/.gitignore

@@ -0,0 +1,9 @@
+# build artifacts
+bypos-collector.exe
+bypos-collector
+bypos-collector-linux
+*.exe
+# collected data / outputs
+*.jsonl
+*.csv
+*.log

tools/bypos-collector/README.md

@@ -0,0 +1,83 @@
+# bypos-collector
+
+按条码批量采集商品档案的小工具(单文件 Windows/Linux 程序,自带本地 Web 控制台)。
+数据来源是云店「新增商品」输入条码时所查的同一个中心商品库 `zc.bypos.net`。
+采集结果落地为 JSONL,供后续导入本项目(天工/goods)。
+
+> 这是一个**独立模块**(有自己的 `go.mod`),与 `api/` 主服务互不影响,
+> CI 不会编译它。放在 `tools/` 下仅作代码留存与后期迭代。
+
+## 目录
+
+| 文件 | 说明 |
+| --- | --- |
+| `main.go` | 入口:本地 HTTP 服务 + 启动浏览器 + API 路由(start/stop/stats/download/export.csv) |
+| `collect.go` | 核心:签名、EAN-13 校验位、范围/清单枚举、并发+限速、JSONL 落库、断点续采 |
+| `web/index.html` | 内嵌(`go:embed`)的控制台界面 |
+| `build.sh` | 交叉编译出 `bypos-collector.exe`(windows/amd64)与 linux 测试二进制 |
+| `使用说明.md` | 面向使用者的操作说明 |
+
+## 构建
+
+```bash
+./build.sh
+# 产物:bypos-collector.exe(发给 Windows 用户)/ bypos-collector-linux(本地测试)
+```
+
+二进制与采集产物(`*.jsonl`/`*.csv`)已在 `.gitignore` 中排除,不入库。
+
+## 接口与签名(逆向所得,后期迭代参考)
+
+云店新增商品页输入条码时,前端经服务端代理 `/prod-api/ZmSvr/httpUtil/getGet`
+转发到中心库:
+
+```
+GET http://zc.bypos.net/byGoodsService/byMessage.asmx/GetGoodsinfo
+    ?sdogid=<账号id>&regnum=1&barcode=<条码>
+    &sparm1=<md5(sdogid)>            # 常量,随账号固定
+    &sparm2=<md5(barcode + tsMs)>    # tsMs = 当前秒*1000(末尾恒为 000)
+    &sparm3=<tsMs 前 10 位 = 秒级时间戳>
+    &sparm4=&barcodetype=yunpos
+```
+
+返回 `<string>{...json...}</string>`,内层 JSON 字段:
+
+| 上游字段 | 含义 | 归一化字段 |
+| --- | --- | --- |
+| item_name | 品名 | name |
+| item_size | 规格 | spec |
+| unit_no | 单位 | unit |
+| item_area | 产地/地区 | area |
+| birth_com | 生产企业(常空) | manufacturer |
+| birth_doc | 生产许可(常空) | license |
+| inprice | 建议进价 | in_price |
+| sellprice | 建议零售价 | sell_price |
+| retcode | 1=命中,0=失败 | status(hit/miss/invalid) |
+
+`retmsg` 含「非国标条码 / 参数异常」=> invalid;含「条码不存在」=> miss。
+
+## 配置
+
+- `sdogid`：中心库账号 id（本项目所属云店账号的授权 id）。
+  优先从环境变量 `BYPOS_SDOGID` 读取，其次是命令行 `-sdogid` 参数，
+  也可以在 Web 控制台的输入框中填写。**三者都未设时启动会警告、开始采集时会报错。**
+- 网络错误自动重试（最多 3 次，指数退避 500ms/1s/2s）。
+
+## 导入 goods/天工库
+
+采集得到的 JSONL 用 ingestion 里的导入任务入库(只导入 `status=hit` 的记录,
+按 GTIN 去重 upsert,重复导入幂等):
+
+```bash
+cd ingestion
+python -m opengoods.jobs.import_bypos --input products.jsonl
+# 可选:--limit N 限制条数;--dsn 指定数据库
+```
+
+字段映射:`barcode→gtin`、`name→name`、`spec`(可解析的质量/体积如 500mL/5kg)
+`→net_content`、其余规格/单位/产地/许可/进价留存到 `attributes`、`sell_price→`
+CNY MSRP 快照。来源记为 `bypos中心库`,带字段级 provenance。
+
+## 注意
+
+批量自动查询比页面逐条更"重",上游可能对账号限频。请低速、分前缀/品类分批采集。

tools/bypos-collector/build.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Build the bypos-collector for Windows (and a Linux binary for local testing).
+set -euo pipefail
+cd "$(dirname "$0")"
+gofmt -w ./*.go
+go vet ./...
+echo "building windows/amd64 .exe ..."
+GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o bypos-collector.exe .
+echo "building linux/amd64 (for testing) ..."
+go build -o bypos-collector-linux .
+ls -la bypos-collector.exe bypos-collector-linux

tools/bypos-collector/collect.go

@@ -0,0 +1,515 @@
+package main
+
+import (
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// ---- upstream config ----
+
+const endpoint = "http://zc.bypos.net/byGoodsService/byMessage.asmx/GetGoodsinfo"
+
+// maxRetries is the number of retry attempts for transient network errors.
+const maxRetries = 3
+
+// resolveSdogID reads the account id from $BYPOS_SDOGID, falling back to the
+// explicit argument (CLI flag or Web UI input). Returns empty if neither set.
+func resolveSdogID(explicit string) string {
+	if v := os.Getenv("BYPOS_SDOGID"); v != "" {
+		return v
+	}
+	return explicit
+}
+
+var stringTagRe = regexp.MustCompile(`(?s)<string[^>]*>(.*)</string>`)
+
+// Product is the normalized record we persist (one JSON object per line).
+type Product struct {
+	Barcode      string `json:"barcode"`
+	Name         string `json:"name"`         // item_name 品名
+	Spec         string `json:"spec"`         // item_size 规格
+	Unit         string `json:"unit"`         // unit_no 单位
+	Area         string `json:"area"`         // item_area 产地/地区
+	Manufacturer string `json:"manufacturer"` // birth_com 生产企业
+	License      string `json:"license"`      // birth_doc 生产许可
+	InPrice      string `json:"in_price"`     // 建议进价
+	SellPrice    string `json:"sell_price"`   // 建议零售价
+	Status       string `json:"status"`       // hit / miss / invalid / error
+	RetMsg       string `json:"retmsg"`       // 原始返回信息
+	FetchedAt    string `json:"fetched_at"`   // RFC3339
+	Source       string `json:"source"`       // zc.bypos.net
+}
+
+// upstream raw fields
+type rawResp struct {
+	RetCode   string `json:"retcode"`
+	RetMsg    string `json:"retmsg"`
+	Barcode   string `json:"barcode"`
+	ItemName  string `json:"item_name"`
+	UnitNo    string `json:"unit_no"`
+	ItemSize  string `json:"item_size"`
+	ItemArea  string `json:"item_area"`
+	BirthCom  string `json:"birth_com"`
+	BirthDoc  string `json:"birth_doc"`
+	InPrice   string `json:"inprice"`
+	SellPrice string `json:"sellprice"`
+}
+
+func md5hex(s string) string {
+	h := md5.Sum([]byte(s))
+	return hex.EncodeToString(h[:])
+}
+
+// ean13Check computes the EAN-13 check digit for a 12-digit body.
+func ean13Check(body string) (string, bool) {
+	if len(body) != 12 {
+		return "", false
+	}
+	sum := 0
+	for i := 0; i < 12; i++ {
+		c := body[i]
+		if c < '0' || c > '9' {
+			return "", false
+		}
+		d := int(c - '0')
+		if i%2 == 0 {
+			sum += d
+		} else {
+			sum += d * 3
+		}
+	}
+	chk := (10 - (sum % 10)) % 10
+	return body + strconv.Itoa(chk), true
+}
+
+// lookupOnce performs a single HTTP request to the upstream central library.
+func (c *Collector) lookupOnce(ctx context.Context, barcode string) (*Product, error) {
+	tsMs := strconv.FormatInt(time.Now().Unix()*1000, 10) // always ends in 000
+	sparm1 := md5hex(c.sdogID)
+	sparm2 := md5hex(barcode + tsMs)
+	sparm3 := tsMs[:10]
+	q := url.Values{}
+	q.Set("sdogid", c.sdogID)
+	q.Set("regnum", "1")
+	q.Set("barcode", barcode)
+	q.Set("sparm1", sparm1)
+	q.Set("sparm2", sparm2)
+	q.Set("sparm3", sparm3)
+	q.Set("sparm4", "")
+	q.Set("barcodetype", "yunpos")
+	reqURL := endpoint + "?" + q.Encode()
+
+	req, _ := http.NewRequestWithContext(ctx, "GET", reqURL, nil)
+	req.Header.Set("User-Agent", "Mozilla/5.0")
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	b, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	inner := b
+	if m := stringTagRe.FindSubmatch(b); m != nil {
+		inner = m[1]
+	}
+	var r rawResp
+	if err := json.Unmarshal(inner, &r); err != nil {
+		return nil, fmt.Errorf("parse: %v (body=%.120s)", err, string(b))
+	}
+	p := &Product{
+		Barcode:   barcode,
+		RetMsg:    r.RetMsg,
+		FetchedAt: time.Now().Format(time.RFC3339),
+		Source:    "zc.bypos.net",
+	}
+	if r.RetCode == "1" {
+		p.Status = "hit"
+		p.Name = strings.TrimSpace(r.ItemName)
+		p.Spec = strings.TrimSpace(r.ItemSize)
+		p.Unit = strings.TrimSpace(r.UnitNo)
+		p.Area = strings.TrimSpace(r.ItemArea)
+		p.Manufacturer = strings.TrimSpace(r.BirthCom)
+		p.License = strings.TrimSpace(r.BirthDoc)
+		p.InPrice = strings.TrimSpace(r.InPrice)
+		p.SellPrice = strings.TrimSpace(r.SellPrice)
+	} else if strings.Contains(r.RetMsg, "非国标") || strings.Contains(r.RetMsg, "参数异常") {
+		p.Status = "invalid"
+	} else {
+		p.Status = "miss"
+	}
+	return p, nil
+}
+
+// lookup queries the upstream with up to maxRetries retries on transient errors.
+func (c *Collector) lookup(ctx context.Context, barcode string) (*Product, error) {
+	var lastErr error
+	for attempt := 0; attempt <= maxRetries; attempt++ {
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+		p, err := c.lookupOnce(ctx, barcode)
+		if err == nil {
+			return p, nil
+		}
+		lastErr = err
+		if attempt < maxRetries {
+			backoff := time.Duration(1<<uint(attempt)) * 500 * time.Millisecond
+			select {
+			case <-time.After(backoff):
+			case <-ctx.Done():
+				return nil, ctx.Err()
+			}
+		}
+	}
+	return nil, lastErr
+}
+
+// ---- job / collector state ----
+
+type Stats struct {
+	Running   bool   `json:"running"`
+	Total     int64  `json:"total"`
+	Done      int64  `json:"done"`
+	Hits      int64  `json:"hits"`
+	Miss      int64  `json:"miss"`
+	Invalid   int64  `json:"invalid"`
+	Errors    int64  `json:"errors"`
+	Skipped   int64  `json:"skipped"`
+	Current   string `json:"current"`
+	OutFile   string `json:"out_file"`
+	StartedAt string `json:"started_at"`
+	Message   string `json:"message"`
+}
+
+type Collector struct {
+	mu      sync.Mutex
+	client  *http.Client
+	sdogID  string
+	outPath string
+	outFile *os.File
+
+	cancel context.CancelFunc
+	wg     sync.WaitGroup
+
+	// atomic counters
+	total, done, hits, miss, invalid, errors, skipped int64
+	running                                           int32
+
+	current   atomic.Value // string
+	startedAt string
+	message   string
+
+	seen   map[string]struct{} // barcodes already in output (dedupe / resume)
+	recent []Product           // ring of last results for UI
+}
+
+func NewCollector(sdogID string) *Collector {
+	sdogID = resolveSdogID(sdogID)
+	c := &Collector{
+		client: &http.Client{Timeout: 25 * time.Second},
+		sdogID: sdogID,
+		seen:   map[string]struct{}{},
+	}
+	c.current.Store("")
+	return c
+}
+
+func (c *Collector) isRunning() bool { return atomic.LoadInt32(&c.running) == 1 }
+
+func (c *Collector) snapshot() Stats {
+	cur, _ := c.current.Load().(string)
+	c.mu.Lock()
+	msg := c.message
+	out := c.outPath
+	started := c.startedAt
+	c.mu.Unlock()
+	return Stats{
+		Running:   c.isRunning(),
+		Total:     atomic.LoadInt64(&c.total),
+		Done:      atomic.LoadInt64(&c.done),
+		Hits:      atomic.LoadInt64(&c.hits),
+		Miss:      atomic.LoadInt64(&c.miss),
+		Invalid:   atomic.LoadInt64(&c.invalid),
+		Errors:    atomic.LoadInt64(&c.errors),
+		Skipped:   atomic.LoadInt64(&c.skipped),
+		Current:   cur,
+		OutFile:   out,
+		StartedAt: started,
+		Message:   msg,
+	}
+}
+
+func (c *Collector) recentResults() []Product {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	out := make([]Product, len(c.recent))
+	copy(out, c.recent)
+	return out
+}
+
+func (c *Collector) pushRecent(p Product) {
+	c.mu.Lock()
+	c.recent = append(c.recent, p)
+	if len(c.recent) > 60 {
+		c.recent = c.recent[len(c.recent)-60:]
+	}
+	c.mu.Unlock()
+}
+
+// loadSeen reads an existing output file to build the dedupe set (for resume).
+func (c *Collector) loadSeen(path string) error {
+	c.seen = map[string]struct{}{}
+	f, err := os.Open(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	defer f.Close()
+	dec := json.NewDecoder(f)
+	for {
+		var p Product
+		if err := dec.Decode(&p); err != nil {
+			break
+		}
+		if p.Barcode != "" {
+			c.seen[p.Barcode] = struct{}{}
+		}
+	}
+	return nil
+}
+
+type JobReq struct {
+	Mode        string `json:"mode"`        // "range" | "list"
+	StartBody   string `json:"start_body"`  // 12-digit body (range mode)
+	EndBody     string `json:"end_body"`    // 12-digit body (range mode)
+	List        string `json:"list"`        // newline/space separated barcodes (list mode)
+	Concurrency int    `json:"concurrency"` // parallel requests
+	DelayMs     int    `json:"delay_ms"`    // min interval between request starts
+	LogMiss     bool   `json:"log_miss"`    // also write miss/invalid lines
+	OutFile     string `json:"out_file"`
+	SdogID      string `json:"sdog_id"`
+}
+
+func sanitizeBarcodes(s string) []string {
+	fields := regexp.MustCompile(`[^0-9]+`).Split(s, -1)
+	var out []string
+	for _, f := range fields {
+		if f != "" {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// Start launches a collection job. Returns error if validation fails or busy.
+func (c *Collector) Start(req JobReq) error {
+	if c.isRunning() {
+		return fmt.Errorf("已有任务在运行")
+	}
+	if req.Concurrency <= 0 {
+		req.Concurrency = 3
+	}
+	if req.Concurrency > 20 {
+		req.Concurrency = 20
+	}
+	if req.DelayMs < 0 {
+		req.DelayMs = 0
+	}
+	if req.OutFile == "" {
+		req.OutFile = "products.jsonl"
+	}
+	if req.SdogID != "" {
+		c.sdogID = req.SdogID
+	}
+	if c.sdogID == "" {
+		return fmt.Errorf("未指定 sdogid，请通过控制台输入框、环境变量 $BYPOS_SDOGID 或 -sdogid 参数配置")
+	}
+
+	// Build the list of barcodes to query.
+	var barcodes []string
+	switch req.Mode {
+	case "list":
+		barcodes = sanitizeBarcodes(req.List)
+		if len(barcodes) == 0 {
+			return fmt.Errorf("条码清单为空")
+		}
+	case "range":
+		start, err := strconv.ParseInt(req.StartBody, 10, 64)
+		if err != nil || len(req.StartBody) != 12 {
+			return fmt.Errorf("起始码必须是 12 位数字(不含校验位)")
+		}
+		end, err := strconv.ParseInt(req.EndBody, 10, 64)
+		if err != nil || len(req.EndBody) != 12 {
+			return fmt.Errorf("结束码必须是 12 位数字(不含校验位)")
+		}
+		if end < start {
+			return fmt.Errorf("结束码不能小于起始码")
+		}
+		if end-start+1 > 5_000_000 {
+			return fmt.Errorf("单次范围过大(>500万),请缩小区间分批采集")
+		}
+		for v := start; v <= end; v++ {
+			body := fmt.Sprintf("%012d", v)
+			full, ok := ean13Check(body)
+			if ok {
+				barcodes = append(barcodes, full)
+			}
+		}
+	default:
+		return fmt.Errorf("未知模式: %s", req.Mode)
+	}
+
+	abs, _ := filepath.Abs(req.OutFile)
+	if err := c.loadSeen(abs); err != nil {
+		return fmt.Errorf("读取已有文件失败: %v", err)
+	}
+	f, err := os.OpenFile(abs, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+	if err != nil {
+		return fmt.Errorf("打开输出文件失败: %v", err)
+	}
+	c.outFile = f
+	c.outPath = abs
+
+	// reset counters
+	atomic.StoreInt64(&c.total, int64(len(barcodes)))
+	atomic.StoreInt64(&c.done, 0)
+	atomic.StoreInt64(&c.hits, 0)
+	atomic.StoreInt64(&c.miss, 0)
+	atomic.StoreInt64(&c.invalid, 0)
+	atomic.StoreInt64(&c.errors, 0)
+	atomic.StoreInt64(&c.skipped, 0)
+	c.mu.Lock()
+	c.recent = nil
+	c.startedAt = time.Now().Format(time.RFC3339)
+	c.message = ""
+	c.mu.Unlock()
+	atomic.StoreInt32(&c.running, 1)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	c.cancel = cancel
+
+	go c.run(ctx, barcodes, req)
+	return nil
+}
+
+func (c *Collector) Stop() {
+	if c.cancel != nil {
+		c.cancel()
+	}
+}
+
+func (c *Collector) run(ctx context.Context, barcodes []string, req JobReq) {
+	defer func() {
+		atomic.StoreInt32(&c.running, 0)
+		if c.outFile != nil {
+			c.outFile.Sync()
+			c.outFile.Close()
+			c.outFile = nil
+		}
+		c.current.Store("")
+	}()
+
+	jobs := make(chan string, req.Concurrency*2)
+	var writeMu sync.Mutex
+
+	// global rate limiter: one token every DelayMs
+	var ticker *time.Ticker
+	if req.DelayMs > 0 {
+		ticker = time.NewTicker(time.Duration(req.DelayMs) * time.Millisecond)
+		defer ticker.Stop()
+	}
+
+	worker := func() {
+		defer c.wg.Done()
+		for bc := range jobs {
+			if ctx.Err() != nil {
+				return
+			}
+			if ticker != nil {
+				select {
+				case <-ticker.C:
+				case <-ctx.Done():
+					return
+				}
+			}
+			c.current.Store(bc)
+			p, err := c.lookup(ctx, bc)
+			if err != nil {
+				if ctx.Err() != nil {
+					return
+				}
+				atomic.AddInt64(&c.errors, 1)
+				atomic.AddInt64(&c.done, 1)
+				ep := Product{Barcode: bc, Status: "error", RetMsg: err.Error(), FetchedAt: time.Now().Format(time.RFC3339), Source: "zc.bypos.net"}
+				c.pushRecent(ep)
+				continue
+			}
+			switch p.Status {
+			case "hit":
+				atomic.AddInt64(&c.hits, 1)
+			case "miss":
+				atomic.AddInt64(&c.miss, 1)
+			case "invalid":
+				atomic.AddInt64(&c.invalid, 1)
+			}
+			atomic.AddInt64(&c.done, 1)
+			c.pushRecent(*p)
+			if p.Status == "hit" || req.LogMiss {
+				line, _ := json.Marshal(p)
+				writeMu.Lock()
+				c.outFile.Write(line)
+				c.outFile.Write([]byte("\n"))
+				c.seen[bc] = struct{}{}
+				writeMu.Unlock()
+			}
+		}
+	}
+
+	for i := 0; i < req.Concurrency; i++ {
+		c.wg.Add(1)
+		go worker()
+	}
+
+	for _, bc := range barcodes {
+		if ctx.Err() != nil {
+			break
+		}
+		if _, ok := c.seen[bc]; ok {
+			atomic.AddInt64(&c.skipped, 1)
+			atomic.AddInt64(&c.done, 1)
+			continue
+		}
+		select {
+		case jobs <- bc:
+		case <-ctx.Done():
+		}
+	}
+	close(jobs)
+	c.wg.Wait()
+
+	c.mu.Lock()
+	if ctx.Err() != nil {
+		c.message = "已停止"
+	} else {
+		c.message = "采集完成"
+	}
+	c.mu.Unlock()
+}

tools/bypos-collector/collect_test.go

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

tools/bypos-collector/go.mod

@@ -0,0 +1,3 @@
+module byposcollector
+
+go 1.23.4

tools/bypos-collector/main.go

@@ -0,0 +1,197 @@
+package main
+
+import (
+	"bufio"
+	"embed"
+	"encoding/csv"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"io/fs"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"runtime"
+	"time"
+)
+
+//go:embed web/*
+var webFS embed.FS
+
+var collector *Collector
+
+// waitExit keeps the console window open on Windows so the user can read errors.
+func waitExit() {
+	if runtime.GOOS == "windows" {
+		fmt.Println("\n按回车键退出...")
+		bufio.NewReader(os.Stdin).ReadBytes('\n')
+	}
+}
+
+func main() {
+	// Log to file so crashes are diagnosable even if console closes.
+	lf, lfErr := os.OpenFile("bypos-collector.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+	if lfErr == nil {
+		log.SetOutput(io.MultiWriter(os.Stderr, lf))
+		defer lf.Close()
+	}
+
+	defer func() {
+		if r := recover(); r != nil {
+			log.Printf("程序崩溃: %v", r)
+			waitExit()
+		}
+	}()
+
+	log.Println("bypos-collector 启动中...")
+
+	addr := flag.String("addr", "127.0.0.1:8765", "本地监听地址")
+	noOpen := flag.Bool("no-open", false, "不自动打开浏览器")
+	sdog := flag.String("sdogid", "", "中心库账号 id（优先读 $BYPOS_SDOGID 环境变量）")
+	flag.Parse()
+	collector = NewCollector(*sdog)
+	if collector.sdogID == "" {
+		log.Println("警告: 未配置 sdogid，请通过 $BYPOS_SDOGID 环境变量、-sdogid 参数或控制台输入框指定")
+	}
+
+	sub, err := fs.Sub(webFS, "web")
+	if err != nil {
+		log.Printf("错误: 无法加载内嵌 web 资源: %v", err)
+		waitExit()
+		return
+	}
+	mux := http.NewServeMux()
+	mux.Handle("/", http.FileServer(http.FS(sub)))
+	mux.HandleFunc("/api/start", handleStart)
+	mux.HandleFunc("/api/stop", handleStop)
+	mux.HandleFunc("/api/stats", handleStats)
+	mux.HandleFunc("/api/download", handleDownload)
+	mux.HandleFunc("/api/export.csv", handleExportCSV)
+
+	ln, err := net.Listen("tcp", *addr)
+	if err != nil {
+		log.Printf("端口 %s 被占用，自动选择可用端口...", *addr)
+		ln, err = net.Listen("tcp", "127.0.0.1:0")
+		if err != nil {
+			log.Printf("错误: 无法监听: %v", err)
+			waitExit()
+			return
+		}
+	}
+	realAddr := ln.Addr().String()
+	urlStr := "http://" + realAddr + "/"
+	fmt.Println("==============================================")
+	fmt.Println(" 中心库商品采集器  bypos-collector")
+	fmt.Println(" 控制台: " + urlStr)
+	fmt.Println(" 关闭本窗口即停止程序")
+	fmt.Println("==============================================")
+	log.Printf("监听地址: %s", realAddr)
+	if !*noOpen {
+		go openBrowser(urlStr)
+	}
+	if err := http.Serve(ln, mux); err != nil {
+		log.Printf("HTTP 服务异常退出: %v", err)
+		waitExit()
+	}
+}
+
+func openBrowser(url string) {
+	time.Sleep(600 * time.Millisecond)
+	var cmd string
+	var args []string
+	switch runtime.GOOS {
+	case "windows":
+		cmd = "rundll32"
+		args = []string{"url.dll,FileProtocolHandler", url}
+	case "darwin":
+		cmd = "open"
+		args = []string{url}
+	default:
+		cmd = "xdg-open"
+		args = []string{url}
+	}
+	_ = exec.Command(cmd, args...).Start()
+}
+
+func writeJSON(w http.ResponseWriter, code int, v interface{}) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(code)
+	json.NewEncoder(w).Encode(v)
+}
+
+func handleStart(w http.ResponseWriter, r *http.Request) {
+	if r.Method != "POST" {
+		http.Error(w, "method", 405)
+		return
+	}
+	var req JobReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSON(w, 400, map[string]string{"error": "请求格式错误"})
+		return
+	}
+	if err := collector.Start(req); err != nil {
+		writeJSON(w, 400, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, 200, map[string]string{"ok": "started"})
+}
+
+func handleStop(w http.ResponseWriter, r *http.Request) {
+	collector.Stop()
+	writeJSON(w, 200, map[string]string{"ok": "stopping"})
+}
+
+func handleStats(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, 200, map[string]interface{}{
+		"stats":  collector.snapshot(),
+		"recent": collector.recentResults(),
+	})
+}
+
+func handleDownload(w http.ResponseWriter, r *http.Request) {
+	s := collector.snapshot()
+	if s.OutFile == "" {
+		http.Error(w, "no output yet", 404)
+		return
+	}
+	f, err := os.Open(s.OutFile)
+	if err != nil {
+		http.Error(w, err.Error(), 404)
+		return
+	}
+	defer f.Close()
+	w.Header().Set("Content-Type", "application/x-ndjson; charset=utf-8")
+	w.Header().Set("Content-Disposition", "attachment; filename=products.jsonl")
+	io.Copy(w, f)
+}
+
+func handleExportCSV(w http.ResponseWriter, r *http.Request) {
+	s := collector.snapshot()
+	if s.OutFile == "" {
+		http.Error(w, "no output yet", 404)
+		return
+	}
+	f, err := os.Open(s.OutFile)
+	if err != nil {
+		http.Error(w, err.Error(), 404)
+		return
+	}
+	defer f.Close()
+	w.Header().Set("Content-Type", "text/csv; charset=utf-8")
+	w.Header().Set("Content-Disposition", "attachment; filename=products.csv")
+	w.Write([]byte{0xEF, 0xBB, 0xBF}) // UTF-8 BOM so Excel reads Chinese correctly
+	cw := csv.NewWriter(w)
+	cw.Write([]string{"barcode", "name", "spec", "unit", "area", "manufacturer", "license", "in_price", "sell_price", "status", "retmsg", "fetched_at", "source"})
+	dec := json.NewDecoder(f)
+	for {
+		var p Product
+		if err := dec.Decode(&p); err != nil {
+			break
+		}
+		cw.Write([]string{p.Barcode, p.Name, p.Spec, p.Unit, p.Area, p.Manufacturer, p.License, p.InPrice, p.SellPrice, p.Status, p.RetMsg, p.FetchedAt, p.Source})
+	}
+	cw.Flush()
+}

tools/bypos-collector/web/index.html

@@ -0,0 +1,211 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>中心库商品采集器</title>
+<style>
+  * { box-sizing: border-box; }
+  body { font-family: -apple-system, "Microsoft YaHei", Arial, sans-serif; margin: 0; background:#f4f6f9; color:#222; }
+  header { background:#1f6feb; color:#fff; padding:14px 22px; font-size:18px; font-weight:600; }
+  .wrap { max-width:1080px; margin:18px auto; padding:0 16px; }
+  .card { background:#fff; border:1px solid #e3e8ef; border-radius:10px; padding:18px 20px; margin-bottom:16px; }
+  .card h3 { margin:0 0 12px; font-size:15px; color:#1f6feb; }
+  label { display:block; font-size:13px; color:#555; margin:8px 0 4px; }
+  input[type=text], input[type=number], textarea, select {
+    width:100%; padding:8px 10px; border:1px solid #cdd5e0; border-radius:6px; font-size:14px;
+  }
+  textarea { height:90px; font-family:monospace; }
+  .row { display:flex; gap:14px; flex-wrap:wrap; }
+  .row > div { flex:1; min-width:160px; }
+  .tabs { display:flex; gap:8px; margin-bottom:12px; }
+  .tab { padding:7px 16px; border:1px solid #cdd5e0; border-radius:20px; cursor:pointer; font-size:13px; background:#fff; }
+  .tab.active { background:#1f6feb; color:#fff; border-color:#1f6feb; }
+  button.primary { background:#1f6feb; color:#fff; border:none; padding:10px 22px; border-radius:6px; font-size:14px; cursor:pointer; }
+  button.danger { background:#d1242f; color:#fff; border:none; padding:10px 22px; border-radius:6px; font-size:14px; cursor:pointer; }
+  button.ghost { background:#fff; color:#1f6feb; border:1px solid #1f6feb; padding:8px 16px; border-radius:6px; cursor:pointer; font-size:13px; }
+  button:disabled { opacity:.5; cursor:not-allowed; }
+  .stats { display:flex; gap:10px; flex-wrap:wrap; }
+  .stat { flex:1; min-width:90px; background:#f7f9fc; border:1px solid #e3e8ef; border-radius:8px; padding:10px; text-align:center; }
+  .stat .n { font-size:22px; font-weight:700; }
+  .stat .l { font-size:12px; color:#777; margin-top:2px; }
+  .bar { height:10px; background:#e3e8ef; border-radius:6px; overflow:hidden; margin:10px 0; }
+  .bar > div { height:100%; background:#2da44e; width:0%; transition:width .4s; }
+  table { width:100%; border-collapse:collapse; font-size:13px; }
+  th, td { text-align:left; padding:6px 8px; border-bottom:1px solid #eef1f5; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; max-width:180px; }
+  th { color:#888; font-weight:600; }
+  .hit { color:#2da44e; } .miss { color:#999; } .invalid { color:#d1242f; } .error { color:#bf8700; }
+  .hint { font-size:12px; color:#888; margin-top:6px; line-height:1.5; }
+  .est { font-size:13px; color:#1f6feb; margin-top:6px; }
+</style>
+</head>
+<body>
+<header>中心库商品采集器 · bypos-collector</header>
+<div class="wrap">
+
+  <div class="card">
+    <h3>① 规划采集范围</h3>
+    <div class="tabs">
+      <div class="tab active" data-mode="range" onclick="setMode('range')">按条码范围</div>
+      <div class="tab" data-mode="list" onclick="setMode('list')">按条码清单</div>
+    </div>
+
+    <div id="pane-range">
+      <div class="hint">EAN-13 国标条码共 13 位,最后一位是校验位由程序自动计算。下面填<b>前 12 位</b>(本体),程序逐个枚举并补校验位查询。常见前缀:69 开头为中国大陆。</div>
+      <label>快捷填充前缀(可选)</label>
+      <div class="row">
+        <div><input type="text" id="prefix" placeholder="如 690100,点下方按钮自动算区间"/></div>
+        <div style="flex:0"><button class="ghost" onclick="fillFromPrefix()">用前缀填充区间</button></div>
+      </div>
+      <div class="row">
+        <div>
+          <label>起始本体(12 位)</label>
+          <input type="text" id="start" value="690100000000" maxlength="12"/>
+        </div>
+        <div>
+          <label>结束本体(12 位)</label>
+          <input type="text" id="end" value="690100000999" maxlength="12"/>
+        </div>
+      </div>
+      <div class="est" id="est"></div>
+    </div>
+
+    <div id="pane-list" style="display:none">
+      <label>粘贴条码清单(每行一个,或用空格/逗号分隔)</label>
+      <textarea id="list" placeholder="6901028941068&#10;6920202888883"></textarea>
+    </div>
+  </div>
+
+  <div class="card">
+    <h3>② 采集参数</h3>
+    <div class="row">
+      <div>
+        <label>中心库账号 sdogid</label>
+        <input type="text" id="sdogid" placeholder="留空则使用环境变量或启动参数"/>
+      </div>
+      <div>
+        <label>并发数</label>
+        <input type="number" id="concurrency" value="3" min="1" max="20"/>
+      </div>
+      <div>
+        <label>每次请求间隔(毫秒)</label>
+        <input type="number" id="delay" value="300" min="0"/>
+      </div>
+      <div>
+        <label>输出文件名</label>
+        <input type="text" id="outfile" value="products.jsonl"/>
+      </div>
+    </div>
+    <label style="margin-top:12px"><input type="checkbox" id="logmiss"/> 同时记录未命中/无效条码(默认只存命中)</label>
+    <div class="hint">速度越快越容易触发上游频控。建议并发 3、间隔 300ms 起步,稳定后再调。已采过的条码会自动跳过(断点续采)。</div>
+  </div>
+
+  <div class="card">
+    <h3>③ 运行</h3>
+    <div style="margin-bottom:12px">
+      <button class="primary" id="btnStart" onclick="start()">开始采集</button>
+      <button class="danger" id="btnStop" onclick="stop()" disabled>停止</button>
+      <button class="ghost" onclick="window.open('/api/download')">下载 JSONL</button>
+      <button class="ghost" onclick="window.open('/api/export.csv')">导出 CSV(Excel)</button>
+    </div>
+    <div class="bar"><div id="prog"></div></div>
+    <div class="stats">
+      <div class="stat"><div class="n" id="s-done">0</div><div class="l">已处理</div></div>
+      <div class="stat"><div class="n" id="s-total">0</div><div class="l">总计</div></div>
+      <div class="stat"><div class="n hit" id="s-hits">0</div><div class="l">命中</div></div>
+      <div class="stat"><div class="n miss" id="s-miss">0</div><div class="l">未命中</div></div>
+      <div class="stat"><div class="n invalid" id="s-invalid">0</div><div class="l">无效</div></div>
+      <div class="stat"><div class="n error" id="s-errors">0</div><div class="l">错误</div></div>
+      <div class="stat"><div class="n" id="s-skipped">0</div><div class="l">跳过</div></div>
+    </div>
+    <div class="hint" id="msg"></div>
+  </div>
+
+  <div class="card">
+    <h3>④ 实时结果(最近 60 条)</h3>
+    <div style="max-height:340px; overflow:auto">
+      <table>
+        <thead><tr><th>条码</th><th>品名</th><th>规格</th><th>单位</th><th>产地</th><th>进价</th><th>零售价</th><th>状态</th></tr></thead>
+        <tbody id="rows"></tbody>
+      </table>
+    </div>
+  </div>
+</div>
+
+<script>
+let mode = 'range';
+function setMode(m){
+  mode = m;
+  document.querySelectorAll('.tab').forEach(t=>t.classList.toggle('active', t.dataset.mode===m));
+  document.getElementById('pane-range').style.display = m==='range'?'block':'none';
+  document.getElementById('pane-list').style.display = m==='list'?'block':'none';
+}
+function fillFromPrefix(){
+  let p = document.getElementById('prefix').value.replace(/[^0-9]/g,'');
+  if(!p){ alert('请先填前缀'); return; }
+  if(p.length>=12){ alert('前缀太长,应少于 12 位'); return; }
+  let pad = 12 - p.length;
+  document.getElementById('start').value = p + '0'.repeat(pad);
+  document.getElementById('end').value   = p + '9'.repeat(pad);
+  updateEst();
+}
+function updateEst(){
+  let s = document.getElementById('start').value.replace(/[^0-9]/g,'');
+  let e = document.getElementById('end').value.replace(/[^0-9]/g,'');
+  if(s.length===12 && e.length===12){
+    let n = (BigInt(e) - BigInt(s)) + 1n;
+    document.getElementById('est').textContent = '本次将查询约 ' + n.toString() + ' 个条码';
+  } else {
+    document.getElementById('est').textContent = '';
+  }
+}
+document.getElementById('start').addEventListener('input', updateEst);
+document.getElementById('end').addEventListener('input', updateEst);
+updateEst();
+
+async function start(){
+  let body = {
+    mode: mode,
+    start_body: document.getElementById('start').value.trim(),
+    end_body: document.getElementById('end').value.trim(),
+    list: document.getElementById('list').value,
+    sdog_id: document.getElementById('sdogid').value.trim(),
+    concurrency: parseInt(document.getElementById('concurrency').value)||3,
+    delay_ms: parseInt(document.getElementById('delay').value)||0,
+    log_miss: document.getElementById('logmiss').checked,
+    out_file: document.getElementById('outfile').value.trim()
+  };
+  let r = await fetch('/api/start', {method:'POST', headers:{'Content-Type':'application/json'}, body:JSON.stringify(body)});
+  let j = await r.json();
+  if(j.error){ alert('启动失败: ' + j.error); return; }
+}
+async function stop(){ await fetch('/api/stop', {method:'POST'}); }
+
+function esc(s){ return (s||'').replace(/[&<>]/g, c=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[c])); }
+
+async function poll(){
+  try{
+    let r = await fetch('/api/stats'); let j = await r.json();
+    let s = j.stats;
+    document.getElementById('s-done').textContent = s.done;
+    document.getElementById('s-total').textContent = s.total;
+    document.getElementById('s-hits').textContent = s.hits;
+    document.getElementById('s-miss').textContent = s.miss;
+    document.getElementById('s-invalid').textContent = s.invalid;
+    document.getElementById('s-errors').textContent = s.errors;
+    document.getElementById('s-skipped').textContent = s.skipped;
+    let pct = s.total>0 ? Math.floor(s.done*100/s.total) : 0;
+    document.getElementById('prog').style.width = pct + '%';
+    document.getElementById('msg').textContent = (s.running? ('采集中… 当前 '+s.current) : (s.message||'空闲'));
+    document.getElementById('btnStart').disabled = s.running;
+    document.getElementById('btnStop').disabled = !s.running;
+    let rows = (j.recent||[]).slice().reverse().map(p=>
+      '<tr><td>'+esc(p.barcode)+'</td><td>'+esc(p.name)+'</td><td>'+esc(p.spec)+'</td><td>'+esc(p.unit)+'</td><td>'+esc(p.area)+'</td><td>'+esc(p.in_price)+'</td><td>'+esc(p.sell_price)+'</td><td class="'+p.status+'">'+esc(p.status)+'</td></tr>'
+    ).join('');
+    document.getElementById('rows').innerHTML = rows;
+  }catch(e){}
+}
+setInterval(poll, 1000); poll();
+</script>
+</body>
+</html>

tools/bypos-collector/使用说明.md

@@ -0,0 +1,68 @@
+# 中心库商品采集器 bypos-collector 使用说明
+
+一个单文件 Windows 小程序,通过云店「新增商品」用到的同一个中心商品库
+(`zc.bypos.net`)按条码批量采集商品档案(品名/规格/单位/产地/厂商/建议进价/建议零售价),
+存到本地,供后续导入天工(goods)系统。
+
+## 一、运行
+
+1. 把 `bypos-collector.exe` 放到任意空文件夹(采集结果会生成在同一文件夹)。
+2. 双击运行。会弹出一个黑色命令行窗口(不要关它),并自动打开浏览器控制台
+   `http://127.0.0.1:8765/`。
+   - 若没自动打开,手动在浏览器输入上面这个地址。
+3. 用完直接关掉那个命令行窗口即可退出。
+
+## 二、采集
+
+控制台分四步:
+
+**① 规划采集范围** —— 两种方式二选一:
+- **按条码范围**:EAN-13 国标条码共 13 位,最后一位是校验位,程序自动算。
+  你只填**前 12 位**的起止区间。可在「快捷填充前缀」里填如 `690100`,
+  点按钮自动生成区间(`690100000000` ~ `690100999999`)。
+- **按条码清单**:直接粘贴一批条码(每行一个,或空格/逗号分隔)。
+
+**② 采集参数**:
+- 并发数(默认 3)、请求间隔(默认 300ms):**越慢越安全**,上游可能对账号限频。
+- 输出文件名(默认 `products.jsonl`)。
+- 「同时记录未命中/无效条码」:默认只存命中的;勾上会把未命中也记下来。
+
+**③ 运行**:点「开始采集」。进度、命中/未命中/错误实时显示。
+已经采过的条码会自动跳过(可随时停了再开,断点续采)。
+
+**④ 实时结果**:最近 60 条滚动显示。
+
+## 三、导出
+
+- 「下载 JSONL」:原始数据(每行一个 JSON),用于导入天工系统。
+- 「导出 CSV」:Excel 可直接打开查看。
+
+## 四、字段说明(JSONL 每行)
+
+| 字段 | 含义 |
+| --- | --- |
+| barcode | 条码(GTIN/EAN-13) |
+| name | 品名 |
+| spec | 规格 |
+| unit | 单位 |
+| area | 产地/地区 |
+| manufacturer | 生产企业(常为空) |
+| license | 生产许可(常为空) |
+| in_price | 建议进价 |
+| sell_price | 建议零售价 |
+| status | hit=命中 / miss=不存在 / invalid=非国标条码 / error=请求出错 |
+| fetched_at | 采集时间 |
+
+## 五、注意
+
+- 这是用云店账号授权去查上游中心库,**批量自动**比页面里一条条查更"重",
+  上游厂商可能对账号做频控/限额。请低速、分批("一点点采"),发现大量报错就降速。
+- 全量 69 段是个天文数字,不要无脑全跑;建议按你关心的品牌/品类前缀分批。
+
+## 六、命令行参数(可选)
+
+```
+bypos-collector.exe -addr 127.0.0.1:8765   # 改监听端口
+bypos-collector.exe -no-open               # 不自动开浏览器
+bypos-collector.exe -sdogid 137966         # 指定中心库账号 id
+```