AI-3.5-02 动态内容 AI 翻译 · 实现策略 TDD

摘要

PRD V1.4 §5.4 FR-3.5-02 验收要点（原文）：「译文抽检合格率与失败重试成功率跟踪（基线立项定）；AI 服务接入启动与扩量严格按 C2 门槛执行（接入时点见 DEC-1）。」 需求本体：商品、商品分类等业务内容在发布后自动进行中日英三语 AI 翻译，前台按用户语言展示对应译文——商家只发一种语言，全球买家均可以母语浏览商品信息。 本条底座是三语检索（FR-3.3-02）与新零售跨语运营的底座；当前翻译范围限商品与商品分类的结构化内容（标题、描述等）。

两态口径（不得混同，承 PRD V1.4）：①底座已建成——翻译参数配置页（密钥加密存储）、失败自动重试队列、状态提示、自动化测试均在； ②AI 服务未接入——生产未配置任何 AI 服务（2026-10-21 部署权威口径，风险 C1 已更正为「已确认未接入」）。 代码层基线：平台唯一真实 AI 通路为 backend/src/modules/translation/client.ts（586 行，OpenAI 兼容客户端，SSRF 三层防护 + 60s 超时）， dev 环境已接内网 LLM（TRANSLATION_AI_BASE_URL=http://192.168.66.225:3030/v1），生产 .env.template 为占位值。 因此本 TDD 基线＝增强现有翻译管道，非从零新建。

全文以两段式组织（强制拆分）：管道增强段（P-①~⑤，无门控、零外部依赖，pilot 波立即可开工）与 服务接入段（生产接入步骤链、category 预检对齐、专属单测、抽检挂接点，DEC-1/C2 门控）。 接入顺序不可颠倒：先关 C2 合规条款（AI-3.9-01 专项条款发布）→ DEC-1 定接入时点 → DEC-2 定扩量节奏。

关键概念

方案设计

两段式总览（承两态口径的强制拆分）

设计红线（AGENTS.md）

• Workflow 承载业务逻辑——本卡全部数据变更走 Workflow/step（加密守卫在 step 内实现，路由层不改）；
• 不修改上游源码——@medusajs/translation 与 @mercurjs/* 仅经官方扩展点；本卡对 client.ts/config/job 均为本地模块内扩展，不触碰上游包；
• 后端是单一数据源——队列状态、配置、审计均以后端为准，admin 仅消费；
• 动态 SQL 参数化绑定——现有 q ILIKE 已示范参数化，本卡无新增裸 SQL。

管道增强段（无门控，立即可开工）

P-① 字段白名单参数化（缺口②）

现状：可翻译字段白名单写死在 step 工具内（collect-product-input.ts，卡内 :16-44 / 白名单判定实际 :36-60）。

• translation_config.translatable_fields：jsonb NULL。NULL＝回退内置默认集（向后兼容，存量行为零变化）；
• JSON schema（zod 校验，键白名单闭合——只允许代码已知且能回写译文的字段，防止配置进未支持字段后 AI 产出无处落）：

{
  "product": {
    "fields": ["title", "subtitle", "description"],
    "options": { "title": true },
    "option_values": { "value": true }
  },
  "product_category": { "fields": ["name", "description"] }
}

• 内置默认集（backend/src/utils/translation-field-whitelist.ts 新常量）＝现状硬编码清单的参数化等价物，保证「配置为空 → 行为与今天逐字节相同」；
• 读取链：collectProductInput(product, sourceLocale, whitelist?) 增加可选参——由 run-translate-product step 从 getEffectiveConfig() 取 translatable_fields ?? DEFAULT_TRANSLATABLE_FIELDS 传入；category 路径同理读 product_category 键；
• 前端：translation-config-form.tsx 增加白名单编辑区（字段多选＋非法键禁用），提交并入现有 POST /admin/translation-config（validators.ts zod schema 扩展，服务端二次校验键闭合）。

P-② 翻译状态查询 API ＋ banner 升级（缺口③）

新增路由：GET /admin/translations/status（新建 backend/src/api/admin/translations-status/route.ts——如与上游 @medusajs/translation 的 /admin/translations/* 路由命名冲突，回退名 GET /admin/translation-jobs/status；以任务卡指定名为准并留冲突注记）。

• 权限域：admin 侧（与 /admin/translation-config 同级，走 /admin 全局认证中间件；query 校验用 validateAndTransformQuery）；
• 聚合来源：translation_job 模块（本地模块，:157 注册 isQueryable: true）——不改上游 @medusajs/translation。

{
  "queue": {
    "pending": 0,             // status='pending' 计数
    "processing": 0,          // status='processing'
    "done": 0,                // status='done'（近 7 天窗口，query 参数 window_days 默认 7）
    "failed": 0,              // status='failed'（达 MAX_TRANSLATION_RETRY=5 上限）
    "retry_due_now": 0,       // pending 且 next_retry_at <= now()
    "oldest_pending_at": null // 最老 pending 的 created_at（积压时长感知）
  },
  "by_reference": {
    "product":          { "pending": 0, "processing": 0, "failed": 0 },
    "product_category": { "pending": 0, "processing": 0, "failed": 0 }
  },
  "failure_top_errors": [     // 近窗口 last_error 聚合 top 5（截断展示）
    { "last_error": "AI translation config not set", "count": 12 }
  ],
  "retry_success_rate": null, // done/(done+failed) 窗口内；样本不足为 null——映射「失败重试成功率跟踪」
  "ai_config": {
    "configured": true,       // 复用 isAIConfigured 语义（utils/translation-config.ts:49-66）
    "encryption_enabled": true // isEncryptionConfigured()（P-③ 状态透出）
  },
  "generated_at": "2026-10-25T00:00:00Z"
}

• 错误码：401 未认证 / 403 非 admin / 400 window_days 非法（1-90）/ 500 聚合失败（读路径不写库，无事务）；
• 前端升级：translation-config-status-banner.tsx（:40-57 现状仅 isFullyConfigured 二态 Alert）升级为「配置态＋队列态」复合横幅：新增 admin-panel/src/hooks/api/translation-status.ts（React Query，60s 轮询），展示 pending/failed 计数与最老积压；AI 未配置时保持现有 not-configured 文案（横幅只是可观测性，不产生任何阻断行为）。

P-③ 加密强制 ＋ 密钥轮换（RK-02 / R-encryption-fallback 缓解，缺口⑥）

现状缺陷（两处）：

1. 明文降级无守卫：src/workflows/translation-config/steps/upsert-translation-config.ts:52-56——isEncryptionConfigured() ? encryptSecret(...) : input.api_key，生产未设 TRANSLATION_ENCRYPTION_KEY 时 api_key 明文落库（无 NODE_ENV=production 守卫）；
2. 密文无版本标记层：backend/src/utils/crypto/secret-crypto.ts——decryptSecret（:92）对无前缀旧明文透明返回（:89-95），且解密仅认单一 v1 形态——轮换密钥即存量密文全部不可解。

设计 1：生产加密守卫（两阶段灰度）

• 阶段 1（告警）：step 内检测 NODE_ENV=production && !isEncryptionConfigured() && input.api_key 非空 → logger.error 告警但仍落库（灰度观察期）；
• 阶段 2（强制）：同条件改为 Workflow step 内抛 MedusaError(Types.INVALID_DATA, "TRANSLATION_ENCRYPTION_KEY is required in production")，拒绝落库不降级——守卫在 step 内实现（AGENTS.md 红线），上游 route 无需改动；
• 灰度开关：env TRANSLATION_ENCRYPTION_REQUIRED（缺省 false＝阶段 1，置 true＝阶段 2）；
• 存量明文检测与迁移：一次性 workflow migrate-plaintext-api-keys——扫描无 enc:v1: 前缀的非空 api_key 行 → encryptSecret 回写；幂等（有前缀跳过）；dev 环境跳过。

设计 2：密钥轮换（enc:v2: 双密钥读旧写新）

• secret-crypto.ts 扩展：新前缀 enc:v2: 与 KEY_SALT_V2（派生盐换版本串，隔离 KDF 域）；resolveKey(version)——v1 读 TRANSLATION_ENCRYPTION_KEY，v2 读 TRANSLATION_ENCRYPTION_KEY_V2（未设则 v2 写操作抛错）；
• decryptSecret 按前缀路由解密密钥（enc:v2:→新钥，enc:v1:→旧钥，无前缀→明文透明返回兼容不变）；读旧写新：写路径在 V2 密钥存在时一律产出 enc:v2:——「密文无版本标记、轮换即存量不可解」由「前缀→密钥版本路由」根除；
• 轮换 workflow：rotate-translation-encryption-key（steps 链见 Workflow 设计表）。

轮换操作步骤（运维 SOP，随 TDD 交付）：

1. 配置 TRANSLATION_ENCRYPTION_KEY_V2（新钥）并重启；
2. 触发轮换 workflow：逐行读存量 enc:v1: 密文 → 用旧钥解密 → enc:v2: 重加密回写（分批＋幂等＋失败行留痕）；
3. 全量行核验为 enc:v2: 后，将新钥值挪到 TRANSLATION_ENCRYPTION_KEY、清空 _V2（或保持双变量、以 v2 为主——两形态等价，取其一并在 runbook 固化）；
4. 旧密钥仅在「回滚窗口」内保留（见迁移与回滚）。

P-④ AI 调用审计 usage 采集（闭环 NFR-3.9-03，缺口⑦）

现状：callChatCompletions（client.ts :369-400）响应的 usage（prompt_tokens/completion_tokens/total_tokens）从不读取（rg 0 命中），成功/失败调用均无留痕——PRD NFR-3.9-03 明示「AI 调用专项审计（调用量与成本统计）尚无」为待建项。

新实体 ai_call_log（新本地模块 ai-call-log，表 ai_call_log）字段级：

• 索引：(reference, reference_id)、(created_at)、(model)、(status)；migration 走 medusa db:generate；
• 采集点设计（最小侵入）：client.ts 为纯函数文件夹、已有 container 入参——在 translateWithAI 单 locale 请求完成/抛错处补 recordAiCallLog(container, entry)；落库走新 ai-call-log 模块 service；写失败仅 logger.warn，不阻断翻译主流程（C6 同构）；不修改上游 @medusajs/translation（本卡全部 AI 流量走自研 client，采集覆盖完整）。

P-⑤ 吞吐/背压指标位（RK-09 缓解，缺口⑧）

现状参数：并发信号量 3（retry-translations.ts:60-68）、轮询 cron 5min（constants.ts:13）、指数退避 2^retry_count 分钟（constants.ts:16）、重试上限 MAX 5（constants.ts:10）。验收口径必含四个指标名（数值一律「基线立项定（DEC-5）」，不臆造）：

全量商品回填积压规模估算公式（运营预案用）：积压规模 ≈ 商品数 × 语种数(=2) ÷ 日吞吐；日吞吐由第四项实测后回填——基线立项定（DEC-5）。

服务接入段（DEC-1/C2 门控，关闭后方可开工）

生产接入步骤链（每步可独立验证，顺序硬约束）：

1. C2 前置（不可跳过）：隐私政策 AI 处理专项条款发布并生效（内容与双分支归属归 AI-3.9-01/法务，本卡只挂前置）；验收＝条款线上可见＋分支归属回填（DEC-2 关联）；
2. 生产配置：backend/.env 按 .env.template:91-94 填入真实 TRANSLATION_AI_BASE_URL/API_KEY/MODEL（ALLOW_PRIVATE_HOST 必须留空——模板 :88-90 注释明示生产 SSRF 防护依赖此项，且误设时 NODE_ENV=production 双重门控拦截）；同时确认 P-③ 加密守卫已处强制态；
3. DEC-1 时点到达后灰度开闸：先分类（量小）后商品，观察 P-② 队列面板与 P-⑤ 指标；
4. DEC-2 节奏扩量：扩量速率受 C2 分支归属与吞吐基线约束；全量回填前按 P-⑤ 公式预估积压。

接入段补两个缺口（缺口④⑤收口）：

• category 触发链对齐：category-created-translation.ts hook 现直调 translateCategoryToLocales（无预检）→ 对齐 product 范式：hook 内先 isAIConfigured 预检（异常返回 true 不阻断）→ enqueue 进 translation_job（reference=product_category 已在白名单 :35-42，retry worker 的 retryCategory :278-284 已就绪）——category 路径全程 C6 不阻断建类；
• 补 run-translate-category.unit.spec.ts 专属单测：覆盖正常翻译/字段缺失跳过/AI 异常 enqueue/未配置降级四分支。

译文抽检挂接点（PRD 验收要点「译文抽检合格率」载体预留）：在翻译持久化 step 与 translation.product.updated 事件之间预留 sample-review 扩展点（采样率/合格口径基线立项定（DEC-5）；复核工作流本体归 AI-3.5-04，交叉引用不重复设计）。

管道时序 · 状态机 · 实体图

数据模型 / API / Workflow

数据模型设计汇总（字段级）

API 契约汇总

Workflow 设计（业务逻辑必须在 Workflow）

前端改动面与 i18n

前端改动面（逐端）

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

改动面仅 admin-panel：admin-panel/src/i18n/translations/en.json、zhCN.json、ja.json 三文件同步新增（三语值随实现提交；遵循现有 translationConfig.* 命名空间）：

storefront / b2b / h2b / vendor i18n 无新增 key（无 UI 改动）。

验收与测试

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

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

风险与降级

风险卡

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

执行时序与分支见图 2。降级链路四条（转写自源 §5.3）：

• 防线一（入口预检）：isAIConfigured（utils/translation-config.ts:49-66）——未配置（base_url/api_key/model 任一缺）→ 跳过 enqueue，主流程零感知；探测自身异常 → catch 返回 true（:63-65）→ 回退 enqueue 路径（C6 永不阻断）；
• 防线二（兜底终态化）：retry worker 内再探测（:205-215）——未配置 → markSkippedNoConfig(job.id, SKIP_NO_CONFIG_REASON) 终态化（failed＋no-config 前缀，logger.info 非告警——预期行为非告警）；
• AI 调用失败：enqueue 幂等重试（指数退避 2^n 分钟，MAX 5，:243-248 达上限告警）；
• storefront：译文缺失 → 原语言 fallback（C6 预期降级，collections/[handle]/page.tsx:42-44 同范式）。

NFR-3.8-01 范式测试点（必列，映射 PRD 验收要点「故障演练」）：

1. 未配置态：建商品/建分类 → 主流程成功、translation_job 0 新增或立即 markSkippedNoConfig；
2. 故障态：mock AI 5xx/超时 → 主流程成功、任务进重试队列、指数退避生效；
3. 探测异常态：mock getEffectiveConfig 抛错 → isAIConfigured 返回 true → enqueue 兜底（不静默丢）；
4. 重试耗尽：MAX 5 后 failed＋告警日志（:243-248 断言）。

迁移与回滚

pnpm db:reset / db:reset:demo 兼容：两 migration 均可空库重放；translatable_fields NULL→默认集回退使 seed 流程行为不变；ai_call_log 空表不参与 seed（seed 留空惯例一致）。

上线顺序（管道段内部建议序）：P-③ 加密守卫最先（告警期先行积累观察）→ P-①②④ 并行 → P-⑤ 收口 → 接入段等 DEC-1/C2。全卡无源代码以外的仓库改动；本 TDD 为设计文档，不改任何源码/迁移/配置。

前置决策点

Blocker 二分表（阻塞什么 / 可并行做什么——禁止因阻塞点否定整条 TDD）

内部依赖与下游消费

• 内部依赖：无（本条为打样条目，无上游 TDD）；
• 下游消费：AI-3.3-02（三语检索以本管道译文为索引输入）、AI-3.5-03（场景翻译复用本管道＋fillPrompt 扩展位）、AI-3.5-04（复核工作流挂本卡抽检点）、AI-3.9-03（P-④ 为其 P0 商用化动作「补 AI 调用专项审计（与翻译扩展同批）」的实现载体）。

开放数值决策

• DEC-5 失败重试成功率与译文抽检合格率的口径基线与目标数值——基线立项定，本卡仅引用编号不内联臆造数值（外部决策点引用规范）。
• DEC-5 吞吐/背压四指标（积压深度/端到端时延/重试成功率/理论吞吐）的目标数值与抽检采样率——同属 DEC-5，随实现纳入。

附录：溯源表

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