feat(search+docs): 搜索升级（trgm 模糊 + 品牌/产地过滤 + 排序）+ 开发者文档 (M5b) #8

2026-06-20T17:39:04+08:00

lixu commented

2026-06-20 17:39:04 +08:00

Summary

M5 第二部分：搜索升级 + 开发者文档（接续已合并的 #7 API Key/限流）。

搜索：把名称搜索从纯 ILIKE 子串升级为 trigram 词级模糊（容忍错别字，如 choclate→Chocolate、nutela→Nutella），并新增品牌/产地过滤与相关度排序。匹配仍是包容式（子串 OR 模糊 OR 条码），排序按 word_similarity(q, name) * (0.5 + quality_score)——相似度主导、质量分做不归零的乘子。无 q 时按质量分返回。

WHERE p.status='active'
  AND ( name ILIKE '%q%' OR word_similarity(q, name) >= 0.42 OR barcode ILIKE '%q%' )
  [AND c.path <@ category::ltree] [AND b.name ILIKE '%brand%'] [AND country ILIKE 'country%']
ORDER BY word_similarity(q, name) * (0.5 + quality_score) DESC, quality_score DESC, name

ProductSummary 响应新增 country_of_origin、quality_score、score（相关度，提供 q 时为 0–1，否则 null）。

文档：

新增 GET /api/v1/openapi.json（内嵌 OpenAPI 3 规范，不计入限流，便于工具拉取）。
ApiDocs 页新增「鉴权与限流」一节（X-API-Key/Bearer、X-RateLimit-*、429/401），并更新搜索端点的参数/返回示例。
新增 docs/api.md 开发者指南；公开站搜索页加入品牌/产地过滤输入框并展示产地。

迁移

0009_search：brand.name 加 GIN trgm 索引、product.country_of_origin 加 btree 索引（pg_trgm 与 product.name 的 trgm 索引在 0001 已建）。

测试

本地 docker postgres+redis：迁移 up/down-all/up 可逆；go vet/gofmt/go test ./... 全过（新增 TestSearchFuzzyAndFilters、TestOpenAPISpec，依赖 Redis 的用例无 Redis 时自动 skip）。真实 HTTP 烟测：错别字命中、品牌/产地过滤、openapi.json 200 且不带限流头。两个前端 npm run build 通过。

## Summary M5 第二部分：搜索升级 + 开发者文档（接续已合并的 #7 API Key/限流）。 **搜索**：把名称搜索从纯 `ILIKE` 子串升级为 **trigram 词级模糊**（容忍错别字，如 `choclate`→`Chocolate`、`nutela`→`Nutella`），并新增**品牌/产地过滤**与**相关度排序**。匹配仍是包容式（子串 OR 模糊 OR 条码），排序按 `word_similarity(q, name) * (0.5 + quality_score)`——相似度主导、质量分做不归零的乘子。无 `q` 时按质量分返回。 ```text WHERE p.status='active' AND ( name ILIKE '%q%' OR word_similarity(q, name) >= 0.42 OR barcode ILIKE '%q%' ) [AND c.path <@ category::ltree] [AND b.name ILIKE '%brand%'] [AND country ILIKE 'country%'] ORDER BY word_similarity(q, name) * (0.5 + quality_score) DESC, quality_score DESC, name ``` `ProductSummary` 响应新增 `country_of_origin`、`quality_score`、`score`（相关度，提供 `q` 时为 0–1，否则 `null`）。 **文档**： - 新增 `GET /api/v1/openapi.json`（内嵌 OpenAPI 3 规范，**不计入限流**，便于工具拉取）。 - ApiDocs 页新增「鉴权与限流」一节（`X-API-Key`/`Bearer`、`X-RateLimit-*`、`429`/`401`），并更新搜索端点的参数/返回示例。 - 新增 `docs/api.md` 开发者指南；公开站搜索页加入品牌/产地过滤输入框并展示产地。 ## 迁移 `0009_search`：`brand.name` 加 GIN trgm 索引、`product.country_of_origin` 加 btree 索引（`pg_trgm` 与 `product.name` 的 trgm 索引在 0001 已建）。 ## 测试本地 docker postgres+redis：迁移 up/down-all/up 可逆；`go vet`/`gofmt`/`go test ./...` 全过（新增 `TestSearchFuzzyAndFilters`、`TestOpenAPISpec`，依赖 Redis 的用例无 Redis 时自动 skip）。真实 HTTP 烟测：错别字命中、品牌/产地过滤、`openapi.json` 200 且不带限流头。两个前端 `npm run build` 通过。

lixu added 1 commit 2026-06-20 17:39:05 +08:00

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

CI / Python (ingestion) (pull_request) Successful in 12s

Details

CI / Migrations (postgres) (pull_request) Successful in 22s

Details

CI / Go (api) (pull_request) Successful in 47s

Details

69a0149bbe

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>

lixu merged commit 50124af833 into main

2026-06-20 17:40:07 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: lixu/goods#8