AI-3.3-03 共享行业术语库 · 实现策略 TDD

摘要

PRD V1.4 §5.2 FR-3.3-03 验收要点：「术语库覆盖选定行业词表；翻译与检索两端复用生效；词库更新机制可运营。」 现状判定为从零新建（无任何词库能力）——但两域消费端注入点已明确且经代码复核： 翻译域 fillPrompt 注入位（backend/src/modules/translation/client.ts:295-306，精确成立）与 检索域查询/索引扩展槽（AI-3.3-02 §4.4）。行业词条内容生产为持续运营任务，仅定义验收口径（覆盖数值 DEC-5）， 不阻塞下游 TDD 生成与基础设施实施。

本卡交付共享术语库基础设施四件套——①术语实体（thesaurus_term）+ ②admin CRUD + ③消费 API 双契约（翻译端注入契约 / 检索端查询扩展契约）+ ④管理界面，及词库更新运营机制（生效/版本/回滚）。 RK-14 强制设计约束：实体 schema 冻结前必须经翻译域与检索域两域消费契约联合评审——评审前本卡全部字段级设计为 评审候选稿，不构成冻结。Blockers 为空，全卡可开工。

关键概念

方案设计

设计红线声明与设计归属

数据模型：thesaurus_term 实体（字段级，从零新建）

新本地模块 backend/src/modules/thesaurus/（models/services/index），表 thesaurus_term：

索引与约束：

• UNIQUE(domain, source_text, source_locale, target_locale)（同域同源词同目标语唯一；软删行经 deleted_at 部分唯一索引处理，migration 按 @medusajs/translation 表 unique index 范式写 partial index）；
• INDEX(domain, status)（消费端 published 热点查询）；INDEX(synonym_group)（组展开）；INDEX(status)。

消费 API 双契约（本卡冻结，RK-14 联审对象）

① 翻译端注入契约（翻译域消费格式——冻结稿，接线实施归 AI-3.5-03）

服务内部函数（backend/src/modules/thesaurus/service.ts 导出，无 HTTP 路由）：

getTranslationTermContext({ domain, source_locale, target_locale })
  → { terms: [{ source_text, target_text, synonyms: string[] }],
      prompt_block: string | null }   // 无 published 词条时 prompt_block = null

• 取词口径：domain = ? AND status = 'published' AND source_locale = ? AND target_locale = ?（参数化）；synonyms = 同 synonym_group 内其他 published 词条的 source_text 集合（上限截断随联审定，暂记 20）；
• prompt_block 格式（per-domain 术语约束段，评审冻结对象）：

【术语表（必须遵守，逐条按给定译法）】
- {source_text} → {target_text}
- …（每域上限条目数随联审定，暂记 50，按 updated_at DESC 截断）

• 注入位对齐：翻译请求携带 domain 上下文时，prompt_block 拼接进 system prompt（落点为 client.ts:464-465 systemPrompt 组装链尾——fillPrompt（client.ts:295-306）本身只做 {source}/{target} 替换不改其函数体；术语段作为独立段追加，避免污染 config.prompt 语义）；
• 双域联审点：prompt_block 分隔符/条目上限/是否标注禁译词，由翻译域引用方（AI-3.5-03）在本契约框架内提出、联审定稿。

② 检索端查询扩展契约（检索域消费格式——对齐 AI-3.3-02 §4.4 槽位）

expandQueryByThesaurus(q: string, locale?: string) → string[]

• 实现 AI-3.3-02 §4.4 预留的 expandQuery(q) 恒等占位的真实语义；命中规则（P1 精确匹配起步）：q 经 trim 后与 source_text/target_text/同 synonym_group 词全等命中（大小写不敏感，ILIKE 转义同 route.ts:265 范式）→ 返回 [原词, ...组内全部 published 词]（去重保序）；未命中或词库不可用 → 恒返回 [q]；
• 展开词集合注入 AI-3.3-02 §4.1 A1 查询构造：命中词集合 OR 链（其卡已声明「仍全参数化」）；
• 分词/模糊匹配/跨语查询改写属 AI-3.3-04 演进（其 §5.2 已预留该落点位），本卡不含；
• 性能注记：词表量级为运营词条数（千级以内），INDEX(domain,status) 覆盖查询；命中判断走内存集缓存（进程内 TTL ≤60s，失效即回源）标注为演进项——首版直接查库即可满足；
• 双域联审点：展开是否含 target_text 方向词（检索跨语场景）由 AI-3.3-02 维护方在联审提出——本契约默认含（一词两用口径），评审可收紧。

词库更新运营机制（生效/版本/回滚）

Workflow 设计（数据变更必须走 Workflow）

新 Workflow 目录 backend/src/workflows/thesaurus/：

upsert-thesaurus-term（创建/更新）
  steps: validate-thesaurus-input（域枚举/locale 白名单/目标语≠源语/唯一性预检）
       → upsert-thesaurus-term-record（status=draft；published 再编辑时 version+1+存 prev_snapshot）
       → emit "thesaurus-term.upserted"
  补偿：upsert 失败回滚写入（事务内，无跨模块副作用）

transition-thesaurus-term（publish/deprecate/restore）
  steps: load-thesaurus-term → assert-status-transition（状态机白名单，守卫在 step 内）
       → update-thesaurus-term-status（published/deprecated 时 reviewed_at/reviewed_by/rejection_reason 留痕）
       → emit "thesaurus-term.transitioned"
  补偿：读旧值回写（快照式）

delete-thesaurus-term（软删）
  steps: load → soft-delete → emit（补偿=恢复 deleted_at=null）

消费端（getTranslationTermContext/expandQueryByThesaurus）为只读 service，不设 Workflow。

子任务 DAG 与排期

所属波次 p2-a（A 波先行——设计归属方，wave_verdict 结论①「A 波先行判定维持」一致）。交叉引用：AI-3.3-02（检索域上游契约，p1 已交付）；AI-3.5-03（翻译域 B 波引用方）；AI-3.3-04（B 波下游）；与 AI-3.4-03 同属 p2-a 可并行，无文件/API 冲突。

数据模型 / API / Workflow

实体关系

admin CRUD API 契约（四件套②）

新 API 目录 backend/src/api/admin/thesaurus-terms/（route.ts+middlewares.ts+validators.ts，范式对齐 translation-config route 的中间件与出口处理）：

状态机（service 层白名单，forward-only 语义参照 qualification-state-machine 范式，本卡行内实现不引入 AI-3.9-04 工具依赖）：draft → published → deprecated → published（restore 行级回滚）；draft → deprecated（废弃草稿）；published 再编辑 → draft（version+1）。非法迁移抛 409。

API 契约汇总

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

共享术语库本体（实体/CRUD/消费 API/管理界面）零 LLM/AI 调用——与 backend/src/modules/translation/client.ts 通路无调用关系，是被其消费的数据源：admin 词条生产（人工运营，draft→published）→ published 集合 → thesaurus_term 表 → ①getTranslationTermContext → 术语约束段 → 翻译 LLM 调用的 prompt 上下文（LLM 调用本体仍由 translation client 承载，属 AI-3.5-03/3.5-02 通路）；②expandQueryByThesaurus → 展开词集合 → 检索查询构造（纯 SQL，零 AI）。与该通路关系 = 数据供给（prompt 上下文增强），非通路复用/并行/抽公共任一形态——本卡不改通路。

前端改动面与 i18n

i18n 三语言 key 规划（en / zh-Hans / ja）

三语值随实现提交；命名空间 thesaurus.* 独立，禁止混入 translation.* 既有空间。

验收与测试

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

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

量化指标占位口径：行业词表覆盖条数（分域）＝基线立项定（DEC-5）；词条审核抽检率＝DEC-5；消费查询 p95 时延指标名 thesaurus_lookup_p95（数据源：service 耗时日志）随实现纳入，数值同属 DEC-5。

风险与降级

风险卡

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

合规挂钩

迁移与回滚

• backend/src/modules/thesaurus/ 新模块建表经 medusa db:generate thesaurus 生成 migration（新增目录不触碰既有模块 migration 序列）；
• partial unique index（UNIQUE(domain, source_text, source_locale, target_locale) WHERE deleted_at IS NULL）按 @medusajs/translation 表 unique index 范式手写于 migration 内（medusa model DSL 表达力不足处，migration 补写，属官方支持路径）；
• seed 兼容声明：不改动 pnpm db:reset / db:reset:demo 流程——空词库下两消费函数恒等回退（A6），种子链路零依赖零破坏；demo 种子不注入词条（内容生产为运营任务，避免 seed 与运营口径混淆）。

feature flag 与开关：新增 featureFlags.thesaurus（backend/medusa-config.ts:55-56 featureFlags 区既有 translation: true 同位扩展，默认 false——词库功能独立开关）：关闭时消费函数恒等回退+admin API 返回 404（能力整体不可见）；灰度序：flag 开启→联审通过→消费链路合入；关闭态与代码回退等价，二选一不并存两套回滚机制（沿用 AI-3.3-02 §10.3 范式声明）。

前置决策点

Blocker 二分表

RK-14 设计协调（非 blocker，为设计前置流程）联审前置

内部依赖与下游引用方（阻塞/可并行二分）

开放数值决策

• DEC-5 行业词表覆盖条数（分域）/ 词条审核抽检率 / 消费查询 p95 时延目标——基线立项定，本卡仅引用编号不臆造数值。
• 联审待定 prompt_block 分隔符/条目上限（暂记 50）/ synonyms 截断上限（暂记 20）/ 展开是否含 target_text 方向词——两域联合评审定稿。

附录：溯源表

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