AI-3.3-02 全域三语检索 · 实现策略 TDD

摘要

PRD V1.4 §5.2 FR-3.3-02 验收要点：「跨语查询召回质量抽检合格率（基线与目标立项定）；三语查询体验一致。」 现状判定为部分实现——后端 q 自由文本过滤已实现且参数化注入安全（backend/src/api/store/products/route.ts:258-272）， 三语译文底座（Medusa Translation Module 译文表）已启用（backend/medusa-config.ts:55-56）， 但三语跨语检索实际为零：查询链路仅搜原语言三列、索引 schema 单语、b2b/h2b 搜索输入框 disabled、 B2C「Algolia 列表」实为一次性拉取前 100 条 + 客户端过滤（R-search-100-cap 数据天花板）。

本卡 P1 为检索底座工程改造（零 AI/LLM 调用）：已定档候选 A「深化 Medusa 路径」—— q 查询以 A1 EXISTS 子查询直查译文表实现跨语命中（事务同库、零同步时延）； R-search-100-cap 以 C1 服务端分页先行修复；三端搜索链路启用与 locale 透传对齐 storefront 既有范式。 同义词注入仅预留 query_expansion 恒等占位（槽位契约归 AI-3.3-03 所有，本卡不设计术语库实体）。 范围口径承 findings key_finding：本条范围大于 PRD 原文表述——实际缺口为三端搜索链路改造 + 数据天花板修复，PRD 原文低估了前台侧缺口。

关键概念

方案设计

设计红线声明（AGENTS.md §0.1 逐条对照）

后端查询链路改造（选定分支 = 候选 A「深化 Medusa 路径」）

前置决策 F-search-backend-choice 已由 PILOT 决策一定档：已定档 选定候选 A；候选 B（启用 Algolia）不废弃，降级为 AI-3.3-04 演进重估项。以下为三候选对比（查询链路跨语化，字段级）：

A1 字段级设计（backend/src/api/store/products/route.ts q 分支 :262-271 内扩展）

输入：filters.q: string（已 trim），filters 携带 locale 上下文
构造（全部参数化绑定，? 占位符序与 bindings.push 顺序严格一致）：
  原语言条件（现状保留）：(p.title ILIKE ? OR p.description ILIKE ? OR p.subtitle ILIKE ?)
  跨语条件（新增）：
    EXISTS (
      SELECT 1 FROM translation t
      WHERE t.reference = ?                -- 'product'，取 TRANSLATION_REFERENCES.PRODUCT 常量
        AND t.reference_id = p.id
        AND t.locale_code = ANY(?)         -- 目标语集合（文本数组参数），默认三语全量
        AND t.deleted_at IS NULL
        AND (
             t.translations->>'title'       ILIKE ?
          OR t.translations->>'description' ILIKE ?
          OR t.translations->>'subtitle'    ILIKE ?
        )
    )
  LIKE 转义：沿用 :265 escapedQ（% _ \ 转义），ILIKE pattern 复用同一 likePattern 值
合并：conditions.push(`(原语言条件 OR 跨语条件)`)

三端搜索链路改造清单（无论后端分支选择，逐项字段级）

① b2b-storefront / h2b-storefront：补传 x-medusa-locale（对齐 storefront:128,197,360 范式）

• getRequestLocale 工具按端既有 locale 解析实现复用（next-intl 上下文），不新建；
• 效果：B2B/H2B 前台商品标题/描述按用户语言展示译文（Translation Module 读路径原生支持），与检索改造解耦、同批交付。

② b2b/h2b search-in-results/index.tsx：disabled 装饰框 → 真实搜索

两端 src/modules/store/components/refinement-list/search-in-results/index.tsx:13（<input :13、disabled :15）：

• 移除 disabled 与 hover:cursor-not-allowed，改为受控输入（useState + debounce ~300ms）；
• 提交/输入触发把 q 写入当前列表页 URL 查询参数（与 refinement-list 既有 refinement 状态管理同通道，挂载点不动）；
• 列表数据函数（①中 listProducts/listProductsWithSort）透传 q 给后端（配合 4.1 跨语查询）；
• i18n：复用既有三语 key（catalog.searchInProducts/catalog.searchInList/layout.searchDisabledTitle）；searchDisabledTitle 提示 key 移除引用后保留在 messages（不删 key，回滚友好）。

③ storefront AlgoliaProductsListing.tsx：废除客户端过滤，升级服务端 q + 分页

• 使用方页面（categories/page.tsx:85、categories/[category]/page.tsx:102）resolvedSearchParams.query 读取处同步映射 q；
• admin-panel / vendor-panel / influencer-panel / referrer-panel：无改动（rg 确认无搜索链路触点；algolia-product.ts 类型文件属 B 路线资产，本卡不动）。

④ locale 白名单与 reference 集合全链路复用

全量索引/分页方案（R-search-100-cap，必须先行）

选定 C1 字段级落地：

• AlgoliaProductsListing.tsx：分页状态从 URL searchParams 读取（page 或 offset，与既有 refinement 参数同管理通道）；:192 limit: "100" 改 limit: PRODUCT_LIMIT（组件级常量，默认 20——与集合页现有分页语义对齐，最终值随 UI 验收）；每页渲染调 fetch（:205-206）带 offset=(page-1)*PRODUCT_LIMIT；:308 total 取响应 count；
• 后端零改动（route.ts 现有 SQL 已支持 LIMIT/OFFSET 与 count）；
• 超 100 条可见性回归测试点（验收 A3）：构造 >100 条商品数据集，断言第 101 条商品按其译文词搜索可命中且计数 ≥101（改造前必失败、改造后通过的判据用例）。

同义词扩展槽（碰撞约束：不设计共享术语库实体）

实现顺序 DAG 与排期（分页先行，强约束）

所属波次 p1（与 AI-3.5-02 打样同域衔接：本卡消费其译文物料，非串行阻塞）。交叉引用：AI-3.5-02（译文物料上游，pilot 波）、AI-3.3-03（A 波 P2，同义词槽消费契约）、AI-3.3-04（B 波 P2，查询理解与 Algolia 重估）、AI-3.9-04（无直接挂钩）。

数据模型 / API / Workflow

数据模型汇总

API 契约汇总

Workflow 设计

AI 能力接入点：无 LLM 调用声明

本卡 P1 交付物（跨语查询/分页/链路改造）为纯工程检索能力，零 AI/LLM 调用——与 backend/src/modules/translation/client.ts 通路无调用关系，仅有数据依赖：AI-3.5-02 翻译管道（LLM 调用唯一发生点）产出三语译文行 → translation 表（同一 Postgres 库）→ EXISTS 子查询只读（事务同库零同步时延）→ GET /store/products?q=… 跨语命中。预留接口假设：语种识别/查询理解/语义转换归 AI-3.3-04（P2），其输入位即本卡查询上下文（q + x-medusa-locale + 用户会话 locale）；本卡预留的 query_expansion 注入位同时是 AI-3.3-04「解析结果→结构化检索条件」的落点位。

前端改动面与 i18n

三语值随实现提交；key 命名沿用各端既有 catalog/layout 命名空间，禁止并行新建第三套。

验收与测试

验收标准（PRD 要点 + 技术口径）

测试策略（分层）与 L0 门禁

L0 门禁：本文档十要素章节齐备、关键 code anchor 字符串可 rg 命中、backend products route 既有单测可回归（backend/src/api/store/products/__tests__/route.unit.spec.ts、h2b-visibility.unit.spec.ts——实现期复跑）。

量化指标占位口径：跨语召回抽检合格率（基线/目标）＝基线立项定（DEC-5）；检索时延指标名 p95_query_latency（数据源：route 耗时日志）随实现纳入，数值同属 DEC-5，本卡不预设。

风险与降级

Blocker 与风险卡

降级与跳过路径（NFR-3.8-01 范式）

迁移与回滚

无新增 schema migration（A1 路线零新表零加列；translation 表为上游模块既有建表）。pnpm db:reset / db:reset:demo 兼容：查询链路改造对种子数据零依赖变更——空译文库时行为与现状等价（A6），demo 种子的译文行（AI-3.5-02 管道产物）自动被跨语查询受益。

• ALGOLIA_ENABLED 既有开关沿用且维持 false（backend/.env.template:56；未选 B 路线，无索引同步管线需要开关）；
• 本卡查询改造不新增 flag（行为升级属缺陷修复+能力补齐性质；如实现期需灰度，允许以 env 只读开关 TRILINGUAL_SEARCH_ENABLED（缺省 true）包裹 EXISTS 分支——回退语义与代码回退等价，二选一，不并存两套回滚机制）；
• reindex 说明：A 路线无索引重建需求（数据即译文表，事务同库）；若未来启用 Algolia 路线，全量 reindex 步骤随届时 TDD 交付，本卡仅留演进记录。

前置决策点

前置决策置顶声明：F-search-backend-choice 已定档

• 决策本体归 PILOT 决策一所有（打样 run-64960599a217，2026-10-25），本卡消费其结论；
• 选定分支声明：候选 A「深化 Medusa 路径」——q ILIKE 检索扩展至三语译文字段 + 翻译联动（4.1 A1 EXISTS 方案）；ALGOLIA_ENABLED=false 维持默认关；本卡全部字段级设计按 A 分支冻结；
• 未选分支备选记录：候选 B（启用 Algolia 改索引 schema）不废弃——降级为 AI-3.3-04 语义检索演进时的重估项（届时先做 @mercurjs/algolia 插件源码 node_modules 二次确认）；备选资产留存：algolia-product.ts:5-31 单语 schema（三语化时加 locale/译文/synonym_expanded_query 字段）、medusa-config.ts:67-77 条件注册（启用开关现成）；
• 本决策解锁本卡字段级设计冻结（PILOT 解锁声明原文）。若未来复审改判 B 路线，4.1 A1 查询设计与 4.3 C1 分页方案仍为 B 路线的对照基线，不作废。

Blocker 二分表（阻塞什么 / 可并行做什么）

内部依赖与下游消费

开放数值决策

• DEC-5 跨语查询召回抽检合格率的基线与目标数值——基线立项定，本卡仅引用编号不内联臆造数值（外部决策点引用规范）。
• DEC-5 检索时延指标 p95_query_latency 的目标数值——同属 DEC-5，随实现纳入。

附录：溯源表

本文档由 docs/reports/ai-module-prd/tdd/AI-3.3-02-trilingual-search.md（v1.0，2026-10-26）可读化重组生成。章节映射与处理方式如下：