AI-3.5-03 垂直场景商务翻译 · 实现策略 TDD

摘要

PRD V1.4 §5.4 FR-3.5-03 验收要点（原文）：「各场景译文术语一致性抽检；高风险场景接入双轨复核（FR-3.5-04）后方可启用。」 需求本体：面向报价单据、商务合同、企业资质文件、客服对话、数字员工话术、授权店铺页面、消费者咨询应答七场景提供场景化商务翻译（七场景为本卡 scenario_code 枚举的唯一合法来源，不得增删场景语义）。 现状说明关键句：当前翻译能力无场景建模——无术语库、无场景提示词集；商务合同与报关文件目前走固定模板生成、不经 AI 翻译。

代码证据坐实「规划中」：rg -i "scenario" 于 translation 模块全目录 0 业务命中（无场景实体/模板查找/路由机制）； translation_config.prompt 为仅支持 {source}/{target} 占位的单一全局字符串； fillPrompt 扩展位在位（client.ts:295-306 复核精确无漂移）。管道底座（client/加密/重试队列/双防线跳过）同 AI-3.5-02 在位。

设计归属总口径：本卡 owns ①场景实体（七场景枚举＋prompt_template＋适用 locale 对）、②per-locale/per-entity 三级 prompt 路由机制、③术语注入消费方式、④场景批次上线路由； references_only ⑤翻译管道底座（AI-3.5-02）、⑥词库实体与注入契约（AI-3.3-03——schema 为「评审候选稿」，RK-14 两域联审前不冻结）、⑦高风险双轨复核（AI-3.5-04，本卡仅标门禁位，禁止两套状态机）。

关键概念

方案设计

两段式总览（承 TDD-TEMPLATE §0 规则 4）

场景实体 translation_scenario（首切片字段级，从零新建）

新本地模块 backend/src/modules/translation-scenario/（models/services/workflows/index），表 translation_scenario：

索引与约束：INDEX(scenario_code, status)（路由热点查询）；INDEX(scenario_code, source_locale, target_locale, status)（第一级命中）；INDEX(batch, status)（批次门控扫描）。

三级 prompt 路由机制（架构级，路由失败回退默认不阻断）

• 接线位置：解析出的模板在传入 fillPrompt（client.ts:295-306）之前完成 {terms} 占位替换——fillPrompt 函数体保持不动（继续只做 {source}/{target} 替换），场景路由作为独立纯函数（resolveScenarioPrompt，新 service）在 system prompt 组装链（client.ts:464-465）上游插入；
• 回退语义：任何一级查询失败（DB 异常）→ 直接第三级全局 prompt，不阻断翻译（NFR-3.8-01）；路由命中日志（命中层级/scenario id）进可观测日志，指标名 scenario_route_hit_level 随实现纳入；
• 幂等与并发：路由为只读查询，无缓存一致性风险；首版直查库（模板量级＝场景×locale 对，千级以内），进程内 TTL 缓存标注为演进项。

术语注入消费（接入段 A——DEP-3.3-03 门控；契约引用不自建）

消费契约（引用 AI-3.3-03 §4.3①——状态：评审候选稿，RK-14 联审前不冻结，以联审稿为准）：

getTranslationTermContext({ domain, source_locale, target_locale })
  → { terms: [...], prompt_block: string | null }

• {terms} 占位替换：路由产出的模板含 {terms} 时 → 以 prompt_block 整段替换；prompt_block=null（域无词条/词库不可用/flag 关闭）→ {terms} 替换为空串（模板中该段标记自然消失，翻译照常执行）——注入失败跳过术语段（NFR-3.8-01）；
• domain 取值：场景→词库域映射常量表（如 business_contract→legal、company_qualification→tax/legal 候选，映射表随实现期与运营确认；词库六域枚举值域以联审冻结稿为准）；
• 拼接位置：{terms} 替换发生在模板层（三级路由接线上游），不触碰 client.ts:464-465 组装语义；
• 本卡不设计：词条实体/取词口径/prompt_block 格式细节——全部引用 AI-3.3-03，杜绝第二套词库语义。

场景批次上线路由（对话/非对话分批，禁止混批）

• 门禁实现：路由查询条件含批次门控谓词——batch2 场景在 C-c6-dialog 门控常量（C6_DIALOG_EVALUATION_CLOSED=false 起步）未翻转时不参与生产路由（dev/test 环境可经显式 env 覆盖用于开发验证，生产不可）；high_risk 场景在 AI-3.5-04 复核通道就绪常量未翻转时同理 fail-closed 拦截；
• 混批防护：批次为实体字段非运行时可变配置——变更 batch 字段走 Workflow 且校验「batch2→batch1 迁移禁止」（守卫在 step）；admin 界面不提供批次编辑入口（防误操作）；
• 报关单据注记：报关文件不在七场景枚举内（需求描述原文无此项），维持固定模板现状，本卡不新增；商务合同/报关固定模板不经 AI 的 PRD 口径维持（生成归业务模块，翻译入口待其接入）。

路由流程 · 执行时序 · 状态机 · 实体图

数据模型 / API / Workflow

数据模型汇总

API 契约汇总

状态机（service 层白名单，forward-only）：draft → published → deprecated → published（restore）；draft → deprecated；published 再编辑 → draft（version+1）。非法迁移抛 409。沿用 AI-3.3-03 §4.2 同构白名单，行内实现，不引入 AI-3.9-04 工具依赖。

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

新 Workflow 目录 backend/src/workflows/translation-scenario/：

upsert-translation-scenario
  steps: validate-scenario-input（七场景枚举/locale 白名单/目标语≠源语/batch 与 scenario_code 匹配校验：
           对话类 scenario_code 强制 batch2、非对话类强制 batch1——混批在录入层即拒绝）
       → upsert-scenario-record（draft 态；published 再编辑 version+1＋存 prev_snapshot）
       → emit "translation-scenario.upserted"
  补偿：upsert 失败事务回滚

transition-translation-scenario
  steps: load-scenario → assert-status-transition（白名单守卫在 step 内）
       → update-scenario-status（published/deprecated 落 reason/metadata）
       → emit "translation-scenario.transitioned"
  补偿：快照回写

delete-translation-scenario
  steps: load → soft-delete → emit（补偿：恢复 deleted_at=null）

翻译执行本体（场景路由→fillPrompt→LLM 调用→落译文→重试）完整复用 AI-3.5-02 管道 Workflow/step 链（references_only），本卡零新增执行 Workflow。

前端触点与 i18n

前端触点（逐端）

i18n 三语言 key 规划（en / zhCN / ja）

admin-panel/src/i18n/translations/{en,zhCN,ja}.json 新增命名空间 translationScenario.*（三语值随实现提交；禁止混入 translationConfig.* 既有空间）：

验收与测试

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

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

风险与降级

风险卡

降级与跳过路径（NFR-3.8-01 强制范式）——三级回退＋双防线引用

• 场景模板缺失/路由查询异常 → 第三级全局 prompt（现状行为，翻译不阻断）；
• {terms} 注入失败（prompt_block=null/词库异常/词库 flag 关闭）→ 术语段替换为空串，翻译照常；
• LLM 未配置（isAIConfigured 预检范式）→ 整段跳过——既有双防线（入口预检＋markSkippedNoConfig 兜底终态化）承 AI-3.5-02 §5.3，本卡零改动引用；
• AI 调用失败 → 既有重试队列（幂等 enqueue/指数退避/MAX 5）兜底，主业务零阻断。

跳过路径测试点（要素 8 必含）：

1. 场景模板缺失→全局 prompt 回退且译文产出正常；
2. 路由查询抛错→同①；
3. 术语注入失败→无术语段翻译成功；
4. AI 未配置→场景翻译任务 markSkippedNoConfig 终态化、主业务成功；
5. 批次门禁：batch2 场景在 C-c6-dialog 未关闭时生产路由不可见（dev 覆盖除外）；
6. 高风险门禁位：high_risk 场景在双轨通道未就绪时生产路由 fail-closed 拦截。

迁移与回滚

上线顺序建议：S1→S2→S3→S4（场景建模段，flag 关态交付＝零行为变化）→ 生产翻译接入（D-dec1/C2，承 AI-3.5-02 §4.2 步骤链）→ 批次 1 上线（flag 开启＋high_risk 门禁位验证）→ DEP-3.3-03 关闭→S5/S6 术语注入 → 批次 2 等 C-c6-dialog 关闭后上线。全卡不改动翻译管道既有语义（fillPrompt 函数体零改动）；本 TDD 为设计文档，不改任何源代码/迁移/配置。

前置决策点

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

内部依赖与下游引用方

开放数值决策

• DEC-5 术语一致性抽检合格率（基线/目标）与采样率——基线立项定，本卡仅引用编号不内联臆造数值。
• DEC-5 场景路由命中层级分布 scenario_route_hit_level 的观测口径与目标——同属 DEC-5，随实现纳入。

附录：溯源表

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