AI-3.3-04 查询理解与结构化检索 · 实现策略 TDD

摘要

PRD V1.4 §5.2 FR-3.3-04 验收要点：「抽样查询解析准确率（基线与目标立项定）；解析结果可人工纠正并回流。」 现状判定为规划中（从零新建解析层）——q 自由文本仅做「原样 ILIKE 三列匹配」（backend/src/api/store/products/route.ts:258-272）， 无任何意图识别/实体抽取/条件转化步骤，即 PRD「搜索请求原样透传」的代码形态； 主体结构化原料仅有 seller-profile 两块字段；主体可检索性为零（store 侧公司 API 仅注册创建，公开侧仅单商家详情）。

本卡 owns ①查询解析层架构（自然语言→结构化检索条件：主体五维+产品参数六维 schema）、②解析结果人工纠正回流机制、③主体检索 API 形态； references_only 词库实体与消费 API（AI-3.3-03 owns，其 schema 现为评审候选稿）、检索链路/索引 schema（AI-3.3-02 owns，本卡承接不重设计检索底座）、 全域主体收录范围（X-subject-scope 业务定义前置，分阶段落地）。 采用两段式分段：解析层架构段无门控立即可开工；词库归一化接入段以 DEP-3.3-03 门控（RK-14 联审冻结 + AI-3.3-03 消费 API 交付后方可开工）。 LLM 调用复用直调 translation client 既有通路（零新增审计面）；解析失败降级为原关键词检索，零阻断。

关键概念

方案设计

承接声明置顶（R-search-100-cap，本卡验收有效性的先决条件）

查询解析服务架构（架构级）

落点位：解析产物经 AI-3.3-02 §4.4 预留的 query_expansion 注入位进入查询构造——本卡 owns 解析与条件生成，expandQuery 签名与注入格式对齐其冻结稿（命中词集合 OR 链、全参数化），不重写其 A1 查询构造。

解析输出 schema parsed_query（首切片字段级，本卡核心交付）

{
  "intent": "product_search | entity_search | mixed | unknown",
  "subject": {                        // 企业主体维度（PRD 五项，逐字对齐）
    "types": [],                      // 类型：枚举值域对齐 SELLER_BUSINESS_TYPES 值域 + X-subject-scope 扩展位
    "business_scopes": [],            // 经营范围：自由文本短语数组（首版不做受控枚举）
    "regions": [],                    // 属地：国家/地区码或文本（首版文本，受控码表随主体档案字段级定义）
    "capabilities": [],               // 服务能力：值域对齐 seller-profile capabilities 数组值域
    "credentials": []                 // 信用资质：文本短语（资质档案字段级随 X-subject-scope）
  },
  "product": {                        // 产品参数维度（PRD 六项，逐字对齐）
    "categories": [],                 // 品类：值域对齐既有类目树（seed 类目门类口径）
    "functions": [],                  // 功能：自由文本短语数组
    "scenarios": [],                  // 场景：文本短语数组
    "audiences": [],                  // 客群：文本短语数组
    "price_range": { "min": null, "max": null, "currency": "JPY" },  // 数值化，currency 按 locale 缺省
    "delivery_modes": []              // 交付模式：文本短语数组
  },
  "normalized_terms": [],             // 归一化检索词集合（注入 expandQuery 的命中词集；接入段经词库归一化）
  "confidence": null,                 // 规则层=启发式分级（low/mid/high）；LLM 层=模型自评 0-1；null=未评估
  "source": "rule | llm | merged",
  "fallback": false                   // true=解析失败，查询链路按原关键词检索（结构化条件全空）
}

解析结果人工纠正回流机制（架构级）

记录落库（新本地模块 backend/src/modules/query-parse-log/，表 query_parse_log，架构级字段组）：

回流消费（架构级，两条通道）：

1. 词库补词回流：纠正前后的词差异（normalized_terms 差集）经 admin 列表导出为词库生产候选输入——引用 AI-3.3-03 的 admin 词条生产通道（其管理界面 CRUD），不新建词库写入 API；该通道受其 schema 评审候选稿 状态约束（RK-14 联审后生效）；
2. 解析规则回流：高频纠正模式（如价格正则漏检、品类字典缺词）转化为规则层字典/正则的迭代输入——工程运营通道（issue/字典 PR），非运行时自动学习（显式声明不做在线自学习，避免不可审计的行为漂移）。

Workflow（数据变更走 Workflow）：correct-query-parse-log——steps：load-parse-log → validate-correction（corrected_query 结构校验）→ update-correction（corrected_query/by/at 落值）→ emit query-parse.corrected；补偿=快照回写。纠正不自动改变当次查询结果（当次已发生），只影响后续解析质量——「纠正后生效」的把关语义引用 NFR-3.9-04 框架（ai_review_record.artifact_type 开放枚举可扩展 query_parse_correction，本卡仅预留引用）。

主体检索 API 形态（架构级）

现状缺口：公开侧无主体列表/搜索 API（/store/companies 仅 POST、/store/seller/[handle] 仅详情）；新建 API 不破坏既有契约。

全域主体收录分阶段路线（架构级声明，不预设业务结论）：第一期=seller/company 主体（既有数据模型）；第二期起=协会/机构/高校等主体类型——每类主体的数据模型、公开字段、收录审核流随 X-subject-scope 业务定义分阶段立项，本卡仅在 GET /store/entities/search 响应结构预留 entity_type 字段位（首期恒 seller），不做多态主体建模。

解析准确率评估载体（架构级，数值 DEC-5）：①标注用例集 backend/src/modules/query-parse/__fixtures__/golden-set.json（覆盖 product 六维+subject 五维各≥N 条，N=DEC-5）；②比对口径=维度级命中+intent 命中，准确率=维度命中加权（权重 DEC-5）；③线上 query_parse_log 按抽样率抽取人工复核（抽样率 DEC-5），复核结论回流纠正通道——「离线用例集（回归）+线上抽样（运营）」双载体。

子任务 DAG 与排期

所属波次 p2-b（B 波——wave_verdict 结论④「AI-3.3-04 依赖 A 波词库」，B 波内部顺序自洽）。交叉引用：AI-3.3-03（A 波上游，评审候选稿）；AI-3.3-02（p1 检索链路上游）；AI-3.5-02（通路与审计）；同波 AI-3.5-03 与 AI-3.6-03 无设计耦合（不同域、零文件冲突）。

数据模型 / API / Workflow

数据模型：query_parse_log（纠正回流载体）

API 契约汇总

Workflow 设计汇总

AI 能力接入点：与 translation client 通路的关系 = 复用直调

• 配置源：解析调用沿用 translation-config DB 优先配置（getEffectiveConfig()），不新建配置实体——解析与翻译共用 provider；若实现期需独立解析模型，扩展位=translation_config 新列或 key 维度扩展（该表多行化属 AI-3.5-03/AI-3.6-03 同一批配置扩展协调项，本卡仅声明依赖不先行实施）；
• 预检：解析层 LLM 启用前置=isAIConfigured 探测（backend/src/utils/translation-config.ts:49-66 范式）；未配置→恒走规则层（fallback 行为与今天等价）；
• prompt 设计与扩展位：解析指令模板常量置于解析模块内（工程资产非运营配置），输出约束=严格 JSON+维度枚举内联说明；JSON 容错提取复用 client.ts 既有解析范式；fillPrompt（client.ts:295-306）为翻译域 prompt 组装位，本卡不改其函数体——解析 prompt 独立组装，仅共用底层 HTTP 调用（与 AI-3.5-03 的场景路由扩展互不干扰：两条 prompt 链正交）。

前端改动面与 i18n

i18n：admin-panel/src/i18n/translations/{en,zhCN,ja}.json 新增命名空间 queryParse.*（queryParse.title / queryParse.filter.fallbackOnly / queryParse.correct.title / queryParse.correct.saved / queryParse.field.intent|confidence|source）；storefront 侧解析摘要 chips key（search.parseSummary.*）三端 messages {en,ja,zh-Hans}.json 预留——三语值随实现提交，禁止混入既有命名空间。

验收与测试

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

测试策略（分层）与量化占位

量化指标占位口径：解析准确率（基线/目标）、LLM 超时预算、线上抽样率、golden-set 规模、解析时延 p95_parse_latency（数据源：解析层耗时日志）＝基线立项定（DEC-5）。

风险与降级

风险卡

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

合规挂钩

迁移与回滚

上线顺序建议：Q1→Q2→Q5（解析链）∥ Q4（主体 API）∥ Q3（纠正回流）→ flag 开启灰度（先规则层观察，再开 LLM 层）→ Q6 等词库冻结后接入。全卡不改动既有检索/公司/商家 API 契约。

前置决策点

Blocker 二分表（architectural 级硬要求：要素 7 强制完整）

内部依赖与下游引用方

开放数值决策

• DEC-5 解析准确率基线/目标、LLM 超时预算、线上抽样率、golden-set 规模——基线立项定，本卡仅引用编号不臆造数值。
• 后续切片 subject 五维受控值域与主体档案字段映射——随 X-subject-scope 业务定义冻结；首切片只冻结 schema 结构与 product 六维解析口径。

附录：溯源表

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