@umacloud/knowledge 1.0.1

package/backend/01-standards/payment-integration.md

@@ -0,0 +1,80 @@
+---
+id: payment-integration
+title: 支付集成标准（商业级必读 · 涉及真金白银）
+domain: backend
+category: 01-standards
+difficulty: advanced
+tags: [支付, payment, stripe, 微信支付, 支付宝, webhook, 幂等, idempotency, 对账, reconciliation, 退款, pci, 商业级]
+quality_score: 96
+last_updated: 2026-06-19
+---
+
+# 支付集成标准（商业级必读 · 涉及真金白银）
+
+> 支付是**最不能出错**的模块——重复扣款、漏发货、状态不一致都是真实资金损失与纠纷。AI 常把支付写得很危险（无幂等、信任前端金额、不处理 webhook）。本标准是硬性要求。
+
+## 1. 黄金铁律
+
+- **金额与订单状态以服务端为准**，绝不信任前端传来的金额/价格——用订单 id 在后端重新计算应付金额。
+- **最终支付状态以支付网关的异步通知（webhook）为准**，不要只凭前端"支付成功"回调就发货。
+- 一切涉钱写操作**幂等 + 事务 + 状态机**，防重复。
+- 用网关官方 SDK，不要自己拼签名/调裸接口。
+
+## 2. 标准下单支付流程
+
+```
+1. 前端下单 → 后端按订单重算金额、创建 order(pending) + payment_intent(created)
+2. 后端调网关创建支付单(用我方订单号做幂等键)，返回 client_secret/支付参数
+3. 前端用参数完成支付(跳转/SDK)
+4. 网关 webhook 异步通知后端"已支付" ← 这是状态变更的唯一可信源
+5. 后端验签 webhook → 幂等更新 order(paid) → 触发发货/开通(事务内)
+6. 前端轮询/回调查订单状态展示结果(不据此改库)
+```
+
+## 3. 幂等（防重复扣款/重复发货）
+
+- 创建支付用**我方订单号作幂等键**传给网关（同一订单不会重复扣款）。
+- webhook 处理幂等：用网关事件 id 去重，同一事件处理一次（记录已处理事件表）。
+- 状态机只允许合法跃迁（pending→paid→shipped；paid 不可回 pending），重复通知不重复发货。
+
+## 4. Webhook（异步通知）—— 支付状态的唯一可信源
+
+- **必须验签**：校验网关签名/证书，拒绝伪造通知。
+- 验签后**幂等**处理；处理成功才回 200，失败回非 2xx 让网关重试。
+- webhook 处理要快/可重入；耗时操作异步化，避免超时导致网关重试风暴。
+- 不要假设 webhook 只来一次、按序来——要能处理重复与乱序。
+- 同时提供**主动查询**网关订单状态作兜底（webhook 丢失时对账补偿）。
+
+## 5. 退款与对账
+
+- 退款同样幂等 + 状态机（已退不可再退）；记录退款单与原因。
+- **定时对账**：拉网关账单与本地订单比对，发现金额/状态不一致告警人工介入。
+- 完整的**支付流水/审计**：每次状态变更、每个 webhook、每次退款都留痕可追溯。
+
+## 6. 安全与合规
+
+- **不自己存储银行卡号/CVV**（PCI 红线）；用网关托管的支付页/Element/SDK，卡信息不经过你的服务器。
+- 支付密钥/webhook secret 走环境变量，绝不进代码/前端/日志。
+- 金额用整数最小单位（分）+ 币种，**绝不用 float**。
+- 全程 HTTPS；webhook 端点校验来源。
+
+## 7. 反模式（出现即不合格）
+
+- 信任前端传的金额/价格；据前端回调就发货。
+- 无幂等：重复点击/重复 webhook 导致重复扣款或重复发货。
+- 不验签 webhook（可被伪造刷单）；webhook 处理慢/不可重入。
+- 用 float 存金额；自己存卡号；密钥硬编码。
+- 无对账、无退款状态机、无支付流水审计。
+- 自己手搓网关签名而非用官方 SDK。
+
+## 8. 最低交付 checklist
+
+- [ ] 金额/状态以服务端为准，按订单重算，不信前端。
+- [ ] 创建支付用订单号幂等键；涉钱写操作事务+幂等+状态机。
+- [ ] webhook 验签 + 幂等(事件去重) + 失败重试语义；以 webhook 为状态可信源。
+- [ ] 主动查询兜底 + 定时对账 + 不一致告警。
+- [ ] 退款幂等+状态机；完整支付流水审计。
+- [ ] 不存卡号(PCI)、用官方 SDK/托管页；密钥走 env；金额整数；全程 HTTPS。
+
+---
+**参考**：Stripe/PayPal/微信/支付宝 官方集成文档、幂等键设计、PCI-DSS、对账与争议处理实践。

package/backend/01-standards/rate-limiting-complete.md

@@ -0,0 +1,451 @@
+---
+id: rate-limiting-complete
+title: 限流完整指南
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [backend, complete, http, limiting, rate, 分布式限流, 响应头, 多维度限流]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 限流完整指南
+
+## 概述
+
+限流 (Rate Limiting) 是保护系统免受过载和滥用的核心机制。通过限制单位时间内的请求数量，防止系统被恶意攻击或突发流量击垮。本指南覆盖令牌桶、漏桶、滑动窗口等算法以及分布式限流和降级策略。
+
+---
+
+## 限流算法
+
+### 1. 令牌桶算法 (Token Bucket)
+
+以固定速率向桶中添加令牌，请求需要获取令牌才能通过。桶满时多余令牌丢弃，允许突发流量。
+
+```python
+import time
+import threading
+
+class TokenBucket:
+    def __init__(self, rate: float, capacity: int):
+        self.rate = rate            # 每秒生成的令牌数
+        self.capacity = capacity    # 桶容量
+        self.tokens = capacity      # 当前令牌数
+        self.last_refill = time.monotonic()
+        self.lock = threading.Lock()
+
+    def allow(self, tokens: int = 1) -> bool:
+        with self.lock:
+            now = time.monotonic()
+            elapsed = now - self.last_refill
+            self.tokens = min(
+                self.capacity,
+                self.tokens + elapsed * self.rate
+            )
+            self.last_refill = now
+
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return True
+            return False
+
+# 使用
+limiter = TokenBucket(rate=100, capacity=200)  # 100 req/s，允许突发 200
+if limiter.allow():
+    process_request()
+else:
+    return_429()
+```
+
+### 2. 漏桶算法 (Leaky Bucket)
+
+请求进入桶中排队，以固定速率处理。桶满时拒绝新请求。输出速率恒定。
+
+```python
+import time
+import threading
+from collections import deque
+
+class LeakyBucket:
+    def __init__(self, rate: float, capacity: int):
+        self.rate = rate
+        self.capacity = capacity
+        self.queue: deque = deque()
+        self.last_leak = time.monotonic()
+        self.lock = threading.Lock()
+
+    def allow(self) -> bool:
+        with self.lock:
+            self._leak()
+            if len(self.queue) < self.capacity:
+                self.queue.append(time.monotonic())
+                return True
+            return False
+
+    def _leak(self):
+        now = time.monotonic()
+        elapsed = now - self.last_leak
+        leaked = int(elapsed * self.rate)
+        if leaked > 0:
+            for _ in range(min(leaked, len(self.queue))):
+                self.queue.popleft()
+            self.last_leak = now
+```
+
+### 3. 固定窗口计数器 (Fixed Window Counter)
+
+将时间分为固定窗口（如每分钟），统计窗口内的请求数。
+
+```python
+class FixedWindowCounter:
+    def __init__(self, limit: int, window_seconds: int):
+        self.limit = limit
+        self.window = window_seconds
+        self.counts: dict[str, int] = {}
+        self.lock = threading.Lock()
+
+    def allow(self, key: str) -> bool:
+        window_key = f"{key}:{int(time.time()) // self.window}"
+        with self.lock:
+            count = self.counts.get(window_key, 0)
+            if count >= self.limit:
+                return False
+            self.counts[window_key] = count + 1
+            # 清理旧窗口
+            self._cleanup()
+            return True
+
+    def _cleanup(self):
+        current_window = int(time.time()) // self.window
+        expired = [k for k in self.counts if int(k.split(":")[-1]) < current_window - 1]
+        for k in expired:
+            del self.counts[k]
+```
+
+### 4. 滑动窗口日志 (Sliding Window Log)
+
+记录每个请求的时间戳，统计滑动窗口内的请求数。精度高但内存开销大。
+
+```python
+class SlidingWindowLog:
+    def __init__(self, limit: int, window_seconds: int):
+        self.limit = limit
+        self.window = window_seconds
+        self.logs: dict[str, list[float]] = {}
+        self.lock = threading.Lock()
+
+    def allow(self, key: str) -> bool:
+        now = time.monotonic()
+        with self.lock:
+            if key not in self.logs:
+                self.logs[key] = []
+
+            # 清除过期记录
+            cutoff = now - self.window
+            self.logs[key] = [t for t in self.logs[key] if t > cutoff]
+
+            if len(self.logs[key]) >= self.limit:
+                return False
+            self.logs[key].append(now)
+            return True
+```
+
+### 5. 滑动窗口计数器 (Sliding Window Counter)
+
+结合固定窗口和滑动窗口，通过加权计算实现近似滑动窗口。
+
+```python
+class SlidingWindowCounter:
+    def __init__(self, limit: int, window_seconds: int):
+        self.limit = limit
+        self.window = window_seconds
+
+    def allow(self, key: str, redis_client) -> bool:
+        now = time.time()
+        current_window = int(now) // self.window
+        previous_window = current_window - 1
+        window_elapsed = (now % self.window) / self.window
+
+        current_count = int(redis_client.get(f"{key}:{current_window}") or 0)
+        previous_count = int(redis_client.get(f"{key}:{previous_window}") or 0)
+
+        # 加权计算
+        estimated = previous_count * (1 - window_elapsed) + current_count
+        if estimated >= self.limit:
+            return False
+
+        pipe = redis_client.pipeline()
+        pipe.incr(f"{key}:{current_window}")
+        pipe.expire(f"{key}:{current_window}", self.window * 2)
+        pipe.execute()
+        return True
+```
+
+---
+
+## 算法对比
+
+| 算法 | 突发允许 | 精度 | 内存 | 适用场景 |
+|------|----------|------|------|----------|
+| 令牌桶 | 允许 | 高 | 低 | API 网关 |
+| 漏桶 | 不允许 | 高 | 中 | 平滑流量 |
+| 固定窗口 | 边界翻倍 | 低 | 低 | 简单计数 |
+| 滑动日志 | 不允许 | 最高 | 高 | 精确限流 |
+| 滑动计数器 | 部分 | 高 | 低 | 通用推荐 |
+
+---
+
+## 分布式限流
+
+### Redis + Lua 原子操作
+
+```python
+# 滑动窗口计数器 - Redis Lua 脚本
+SLIDING_WINDOW_SCRIPT = """
+local key = KEYS[1]
+local window = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+
+-- 清除过期成员
+redis.call("ZREMRANGEBYSCORE", key, 0, now - window)
+
+-- 当前窗口内的请求数
+local count = redis.call("ZCARD", key)
+
+if count < limit then
+    -- 添加当前请求
+    redis.call("ZADD", key, now, now .. ":" .. math.random(1000000))
+    redis.call("EXPIRE", key, window)
+    return 1
+else
+    return 0
+end
+"""
+
+def rate_limit_distributed(key: str, limit: int, window: int) -> bool:
+    result = r.eval(
+        SLIDING_WINDOW_SCRIPT,
+        1,
+        f"ratelimit:{key}",
+        window,
+        limit,
+        int(time.time() * 1000),
+    )
+    return result == 1
+```
+
+### API 网关限流
+
+```yaml
+# Kong API Gateway 配置
+plugins:
+  - name: rate-limiting
+    config:
+      minute: 60                # 每分钟 60 次
+      hour: 1000                # 每小时 1000 次
+      policy: redis              # 分布式策略
+      redis_host: redis
+      redis_port: 6379
+      fault_tolerant: true       # Redis 不可用时放行
+      hide_client_headers: false
+      limit_by: consumer         # 按消费者限流
+
+# Nginx 限流
+http {
+    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
+    limit_conn_zone $binary_remote_addr zone=conn:10m;
+
+    server {
+        location /api/ {
+            limit_req zone=api burst=20 nodelay;
+            limit_conn conn 100;
+            limit_req_status 429;
+        }
+    }
+}
+```
+
+---
+
+## 多维度限流
+
+```python
+class MultiDimensionRateLimiter:
+    """多维度限流器：IP + 用户 + 接口"""
+
+    def __init__(self, redis_client):
+        self.redis = redis_client
+        self.rules = {
+            "ip": {"limit": 100, "window": 60},         # 每 IP 每分钟 100 次
+            "user": {"limit": 1000, "window": 3600},     # 每用户每小时 1000 次
+            "endpoint": {"limit": 30, "window": 60},     # 每接口每分钟 30 次
+            "login": {"limit": 5, "window": 300},        # 登录每 5 分钟 5 次
+        }
+
+    def check(self, ip: str, user_id: str | None, endpoint: str) -> tuple[bool, dict]:
+        results = {}
+
+        # IP 维度
+        results["ip"] = self._check_dimension(
+            f"ratelimit:ip:{ip}", self.rules["ip"]
+        )
+
+        # 用户维度
+        if user_id:
+            results["user"] = self._check_dimension(
+                f"ratelimit:user:{user_id}", self.rules["user"]
+            )
+
+        # 接口维度
+        key_endpoint = f"ratelimit:endpoint:{user_id or ip}:{endpoint}"
+        results["endpoint"] = self._check_dimension(
+            key_endpoint, self.rules["endpoint"]
+        )
+
+        # 敏感接口特殊限流
+        if endpoint in ("/api/login", "/api/register", "/api/reset-password"):
+            results["sensitive"] = self._check_dimension(
+                f"ratelimit:login:{ip}", self.rules["login"]
+            )
+
+        allowed = all(r["allowed"] for r in results.values())
+        return allowed, results
+
+    def _check_dimension(self, key: str, rule: dict) -> dict:
+        allowed = rate_limit_distributed(key, rule["limit"], rule["window"])
+        remaining = max(0, rule["limit"] - int(self.redis.zcard(key) or 0))
+        return {
+            "allowed": allowed,
+            "limit": rule["limit"],
+            "remaining": remaining,
+            "window": rule["window"],
+        }
+```
+
+---
+
+## HTTP 响应头
+
+```python
+# FastAPI 限流中间件
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        client_ip = request.client.host
+        user_id = getattr(request.state, "user_id", None)
+        endpoint = request.url.path
+
+        allowed, results = rate_limiter.check(client_ip, user_id, endpoint)
+
+        if not allowed:
+            return Response(
+                content=json.dumps({"error": "Rate limit exceeded"}),
+                status_code=429,
+                headers={
+                    "Retry-After": "60",
+                    "X-RateLimit-Limit": str(results.get("ip", {}).get("limit", 0)),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(int(time.time()) + 60),
+                },
+                media_type="application/json",
+            )
+
+        response = await call_next(request)
+
+        # 添加限流信息头
+        ip_info = results.get("ip", {})
+        response.headers["X-RateLimit-Limit"] = str(ip_info.get("limit", 0))
+        response.headers["X-RateLimit-Remaining"] = str(ip_info.get("remaining", 0))
+        return response
+```
+
+---
+
+## 降级策略
+
+```python
+class GracefulDegradation:
+    """优雅降级管理器"""
+
+    def __init__(self):
+        self.levels = {
+            "normal": {"cache_ttl": 300, "features": "all"},
+            "warning": {"cache_ttl": 900, "features": "core_only"},
+            "critical": {"cache_ttl": 3600, "features": "readonly"},
+            "emergency": {"cache_ttl": 7200, "features": "static"},
+        }
+        self.current_level = "normal"
+
+    def check_and_degrade(self, metrics: dict):
+        error_rate = metrics.get("error_rate", 0)
+        latency_p99 = metrics.get("latency_p99", 0)
+        cpu_usage = metrics.get("cpu_usage", 0)
+
+        if error_rate > 10 or cpu_usage > 95:
+            self.current_level = "emergency"
+        elif error_rate > 5 or latency_p99 > 5000:
+            self.current_level = "critical"
+        elif error_rate > 1 or latency_p99 > 2000:
+            self.current_level = "warning"
+        else:
+            self.current_level = "normal"
+
+    def get_config(self) -> dict:
+        return self.levels[self.current_level]
+
+    def is_feature_available(self, feature: str) -> bool:
+        available = self.levels[self.current_level]["features"]
+        if available == "all":
+            return True
+        if available == "static":
+            return feature in ("health", "status")
+        if available == "readonly":
+            return feature not in ("write", "upload", "export")
+        if available == "core_only":
+            return feature in ("auth", "read", "health")
+        return False
+```
+
+---
+
+## 监控指标
+
+| 指标 | 说明 | 告警阈值 |
+|------|------|----------|
+| 限流触发次数 | 被拒绝的请求数 | 突增 > 3x |
+| 限流命中率 | 触发限流的请求比例 | > 5% |
+| 429 响应率 | HTTP 429 响应比例 | > 1% |
+| Redis 延迟 | 限流器 Redis 延迟 | > 10ms |
+
+---
+
+## 常见反模式
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|----------|
+| 仅客户端限流 | 可被绕过 | 服务端强制限流 |
+| 全局统一限额 | 正常用户被误杀 | 按用户/IP/接口分维度 |
+| 限流后无 Retry-After | 客户端盲目重试 | 返回 429 + Retry-After |
+| Redis 不可用则拒绝所有 | 可用性下降 | fault-tolerant: 降级放行 |
+| 不区分接口敏感度 | 登录等接口被暴力攻击 | 敏感接口单独更严限流 |
+| 固定窗口边界问题 | 窗口交界处突发翻倍 | 使用滑动窗口计数器 |
+
+---
+
+## Agent Checklist
+
+- [ ] 选择合适的限流算法（推荐滑动窗口计数器或令牌桶）
+- [ ] 实现多维度限流（IP / 用户 / 接口 / 敏感操作）
+- [ ] 分布式限流使用 Redis Lua 脚本保证原子性
+- [ ] 返回标准限流响应头（X-RateLimit-Limit / Remaining / Reset）
+- [ ] HTTP 429 响应包含 Retry-After 头
+- [ ] 登录/注册/重置密码等接口单独设置更严格限额
+- [ ] Redis 不可用时有降级策略（放行或本地限流）
+- [ ] 限流规则可动态调整（配置中心/环境变量）
+- [ ] 接入监控告警（限流触发率 / 429 响应率）
+- [ ] API 网关层和应用层都实施限流
+- [ ] 白名单机制（内部服务/健康检查绕过限流）
+- [ ] 定期回顾限流阈值，根据实际流量调整

package/backend/01-standards/realtime-and-websocket.md

@@ -0,0 +1,65 @@
+---
+id: realtime-and-websocket
+title: 实时通信与 WebSocket 标准（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: advanced
+tags: [实时, realtime, websocket, sse, 长连接, 重连, 心跳, 鉴权, 扩展, presence, 推送, 商业级]
+quality_score: 93
+last_updated: 2026-06-19
+---
+
+# 实时通信与 WebSocket 标准（商业级必读）
+
+> 聊天、协作、通知、实时看板需要实时通信。长连接的鉴权、重连、扩展是常见坑。本标准给出商业级要点。
+
+## 1. 选型
+
+- **单向服务端推**（通知、行情、进度）→ 优先 **SSE**（基于 HTTP，简单、自动重连、走代理友好）。
+- **双向低延迟**（聊天、协作、游戏）→ **WebSocket**。
+- 别为"偶尔刷新"上 WebSocket；轮询/SSE 更省。
+- 用成熟库（Socket.IO / ws / SignalR / Phoenix Channels / centrifugo），别手搓协议。
+
+## 2. 鉴权与安全
+
+- **连接建立时鉴权**（握手带 token，校验后才允许）；不要建立后才补鉴权。
+- token 过期处理：长连期间 token 过期要能续期或断开重连。
+- **每条消息/订阅做授权**：用户只能订阅/收到自己有权的频道（防越权偷听他人房间）。
+- 校验消息来源(origin)；限制消息大小/频率防滥用。
+
+## 3. 连接可靠性
+
+- **心跳/ping-pong** 检活，及时清理死连接。
+- **客户端自动重连**（指数退避）；重连后**补偿丢失消息**（用 last-event-id/序号拉增量），不要假设连接永不断。
+- 消息有序与去重：网络抖动可能乱序/重复，关键消息带序号/id 去重。
+- 背压：客户端慢时限制服务端发送速率/缓冲，防内存爆。
+
+## 4. 扩展（多实例）
+
+- WebSocket 有状态 → 多实例下连接分散在不同节点。用**共享 Pub/Sub（Redis/NATS）**广播，让一个节点的消息能推给连在别节点的用户。
+- 或用托管实时服务（Pusher/Ably/centrifugo）省去自建扩展。
+- 负载均衡支持长连接（sticky 或 L4）；优雅停机时通知客户端重连到别节点。
+
+## 5. Presence 与状态
+
+- 在线状态/正在输入等用集中存储（Redis）维护，多实例一致。
+- 用户多设备/多标签页要正确合并在线状态。
+
+## 6. 反模式（出现即不合格）
+
+- 连接不鉴权或建立后才鉴权；订阅/消息不做授权（可偷听他人）。
+- 无心跳清理死连接；客户端不自动重连；断连丢消息无补偿。
+- 多实例不用共享 Pub/Sub，消息只能推给同节点用户。
+- 无背压，慢客户端拖垮服务端；消息无序无去重。
+- 为低频更新滥用 WebSocket。
+
+## 7. 最低交付 checklist
+
+- [ ] 按需选 SSE/WebSocket/轮询；用成熟库不手搓。
+- [ ] 握手鉴权 + 每条订阅/消息授权 + origin/大小/频率限制。
+- [ ] 心跳检活 + 客户端指数退避重连 + 重连补偿(序号/last-event-id) + 去重。
+- [ ] 多实例用共享 Pub/Sub 广播；LB 支持长连接；优雅停机引导重连。
+- [ ] 背压控制；Presence 集中维护多设备一致。
+
+---
+**参考**：WebSocket/SSE 对比、Socket.IO 扩展(Redis adapter)、心跳与重连、Pub/Sub 广播、Presence 设计。

package/backend/01-standards/search-and-filtering.md

@@ -0,0 +1,64 @@
+---
+id: search-and-filtering
+title: 搜索与过滤标准（商业级必读）
+domain: backend
+category: 01-standards
+difficulty: intermediate
+tags: [搜索, search, 全文检索, full-text, 过滤, filter, 排序, 分页, 相关性, elasticsearch, 高亮, 商业级]
+quality_score: 93
+last_updated: 2026-06-19
+---
+
+# 搜索与过滤标准（商业级必读）
+
+> 内容/电商/SaaS 几乎都要搜索。做对了提升转化，做错了（`LIKE %x%` 扫全表、无分页、无相关性）既慢又难用。本标准给出分级做法。
+
+## 1. 选型分级（按数据量与需求）
+
+- **小数据 + 精确过滤**：DB 索引 + `WHERE`/范围/枚举过滤即可，别上重武器。
+- **结构化过滤 + 简单关键词**：Postgres 全文检索（`tsvector` + GIN 索引）/ MySQL FULLTEXT，够用且省运维。
+- **大规模 + 相关性/高亮/聚合/拼写纠错**：专用搜索引擎（Elasticsearch/OpenSearch/Meilisearch/Typesense）。
+- 经验法则：**别用 `LIKE '%keyword%'` 做全文搜索**（无法走索引、全表扫、慢）。
+
+## 2. 查询契约（一致的搜索 API）
+
+- 统一参数：`q`(关键词)、过滤(`status`/`category`/`price_min`...)、`sort`、分页(`cursor`/`page+limit`)。
+- 返回：结果数组 + 分页信息 + （可选）聚合/facet 计数 + 总数（大数据下总数可近似）。
+- 过滤用明确字段白名单，**参数化**（防注入），不要把用户输入直接拼进查询。
+
+## 3. 相关性与体验
+
+- 关键词命中按**相关性排序**（搜索引擎的 BM25/打分），不是简单按时间。
+- 支持：高亮命中、拼写容错/同义词（搜索引擎）、前缀/自动补全（autocomplete）。
+- 空结果给友好提示 + 建议（"试试更宽的关键词"/热门）。
+- 中文等需**分词**（IK/jieba 等），别按字符裸匹配。
+
+## 4. 性能
+
+- 搜索字段建索引（DB GIN / 引擎倒排）；过滤/排序字段有索引。
+- 强制**分页 + 上限**；深翻页用 search_after/cursor。
+- 高频/热门查询可缓存；facet 聚合注意成本。
+- 搜索与主库解耦：用搜索引擎时，通过同步（CDC/双写/定时）保持索引与数据一致，接受最终一致。
+
+## 5. 数据同步（用搜索引擎时）
+
+- 写主库后异步更新搜索索引（队列/CDC），**幂等**；删除/更新同步。
+- 重建索引有方案（别名切换零停机）；监控索引与主库的漂移。
+
+## 6. 反模式（出现即不合格）
+
+- `LIKE '%x%'` 做全文搜索、全表扫、无索引。
+- 无分页/无上限拉全量结果。
+- 过滤字段不白名单、用户输入直接拼查询（注入风险）。
+- 按时间而非相关性排关键词搜索；中文不分词裸匹配。
+- 用搜索引擎但索引与主库无同步/不一致无监控。
+
+## 7. 最低交付 checklist
+
+- [ ] 按数据量选型；不用 `LIKE '%%'` 做全文；搜索字段有索引（GIN/倒排）。
+- [ ] 统一搜索 API：q+过滤(白名单+参数化)+排序+分页(上限/cursor)。
+- [ ] 关键词按相关性排序；中文分词；高亮/补全/空结果建议。
+- [ ] 用引擎则异步幂等同步索引、零停机重建、漂移监控。
+
+---
+**参考**：Postgres 全文检索(tsvector/GIN)、Elasticsearch 相关性(BM25)、分词、search_after 深分页、CDC 索引同步。