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/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
 }`}