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

Search:
- migration 0009: trigram GIN index on brand.name + btree on country_of_origin
- SearchProducts: typo-tolerant word_similarity matching (>=0.42) on top of
  ILIKE substring + barcode; new brand/country filters; rank by
  similarity * (0.5 + quality_score). Response gains country_of_origin,
  quality_score and per-result relevance score.
- public search UI: brand/country filter inputs; show country in results

Docs:
- serve embedded OpenAPI 3 spec at GET /api/v1/openapi.json (not rate limited)
- ApiDocs page: auth + rate-limit section, updated search params/response
- docs/api.md developer guide

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

public-frontend/src/api.ts

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

public-frontend/src/components/ApiDocs.tsx

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

public-frontend/src/components/Home.tsx

@@ -13,6 +13,8 @@ export default function Home({
   onApi: () => void;
 }) {
   const [q, setQ] = useState("");
+  const [brand, setBrand] = useState("");
+  const [country, setCountry] = useState("");
   const [items, setItems] = useState<ProductSummary[]>([]);
   const [total, setTotal] = useState(0);
   const [searched, setSearched] = useState(false);
@@ -24,7 +26,10 @@ export default function Home({
     setLoading(true);
     setError("");
     try {
-      const res = await api.search(q.trim(), 1, 30);
+      const res = await api.search(q.trim(), 1, 30, {
+        brand: brand.trim() || undefined,
+        country: country.trim() || undefined,
+      });
       setItems(res.items);
       setTotal(res.total);
       setSearched(true);
@@ -61,6 +66,20 @@ export default function Home({
             {loading ? "检索中…" : "检索"}
           </button>
         </form>
+        <div className="mt-3 max-w-2xl mx-auto flex flex-wrap items-center justify-center gap-2 text-sm">
+          <input
+            value={brand}
+            onChange={(e) => setBrand(e.target.value)}
+            placeholder="按品牌筛选（如 Ferrero）"
+            className="flex-1 min-w-[14rem] bg-white border rounded-lg px-3 py-2 outline-none focus:ring-2 focus:ring-emerald-300"
+          />
+          <input
+            value={country}
+            onChange={(e) => setCountry(e.target.value)}
+            placeholder="按产地筛选（如 China）"
+            className="flex-1 min-w-[14rem] bg-white border rounded-lg px-3 py-2 outline-none focus:ring-2 focus:ring-emerald-300"
+          />
+        </div>
         <button
           onClick={onApi}
           className="mt-4 inline-flex items-center gap-1.5 text-sm text-emerald-700 hover:underline"
@@ -105,7 +124,12 @@ export default function Home({
                         {p.gtin ? ` · ${p.gtin}` : ""}
                       </div>
                     </div>
-                    <span className="text-xs text-gray-400">{p.category_path || ""}</span>
+                    <span className="text-xs text-gray-400 text-right">
+                      <span className="block">{p.category_path || ""}</span>
+                      {p.country_of_origin ? (
+                        <span className="block text-gray-400">产地：{p.country_of_origin}</span>
+                      ) : null}
+                    </span>
                   </button>
                 </li>
               ))}

public-frontend/src/types.ts

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