AI-3.4-02 18 类标准化商品体系

摘要

本条目对应 PRD FR-3.4-02「18 类标准化商品体系」。PRD 验收要点为：「建档规范覆盖全部 18 类并发布；新品类准入经规范评审（含薬機法适用性确认）」。现状判定为部分实现：类目树（六大类十八子类）、三语四层翻译闭环、Attribute 系统、发布审核骨架全部在位；而「标准化建档规范层」为零实现（负证据：规范相关关键词全仓检索 0 命中，category_standard 实体不存在）。

技术方案采用两段式结构：技术方案段（attribute 九项映射定义 + category_standard 新模块 + publish 准入校验 + vendor 表单消费 + RK-12 改名重译钩子）无门控、立即可开工；规范发布段（18 类规范内容定稿与 published 发布、新品类准入流程启用）受业务前置 B-c3 门控——「18 类」语义同构核对与薬機法适用性确认归商品团队 + 法务，技术侧仅提供字段位与流程卡控。

挂载方案经三候选对比定稿为 attribute 绑定分类（结构化可校验项）+ 新建本地模块 category_standard（文档型规范 + 版本/评审载体）组合：九项建档维度天然二分——可枚举、可校验、需参与筛选与准入强制的走 attribute（复用上游机制，零上游改动）；长文档、需版本化发布与评审留痕的走 category_standard。

关键概念

方案设计

总体架构与两段式门控

九项建档维度映射（字段级）

category_standard 新本地模块

模块 backend/src/modules/category-standard/（models/services/index），表 category_standard。挂载通道三候选对比结论：① metadata 自由 KV 否决为主通道（无 schema/类型/校验/版本/留痕，无法承载 required 准入强制，保留作杂项扩展位）；② attribute 绑定分类采纳（结构化 + is_required 准入强制 + is_filterable 前台筛选 + 字段增删零 migration）；③ category_standard 新模块采纳（文档型规范 + 版本化 + 评审留痕，与类目解耦可先建）。组合使「18 类覆盖」可拆解为「attribute 模板齐备 + 18 条规范 published」双验收位。

publish 准入执行点

插入位：publish-vendor-product.ts:130 的 publishVendorProductWorkflow step 链首（既有 validateProductForPublishStep 之前并列新增 assertCategoryStandardComplianceStep，保持既有校验函数零改动、职责单一）：

assertCategoryStandardComplianceStep({ product_id })
  ① 查商品所属类目（product.product_categories → handle）
  ② 查该 handle 的 published category_standard（status=published 最新 version）
     └ 不存在 → 按 flag 阶段行为：阶段1 logger.warn 留痕放行；阶段2 抛
        AppError(PRODUCT_CATEGORY_STANDARD_MISSING, "category has no published standard")
  ③ 查该类目绑定的 is_required=true attribute（经上游 attribute 模块 product_categories 绑定）
     对照 product.attribute_values 逐一核对
     └ 缺失 → 阶段1 warn；阶段2 抛
        AppError(PRODUCT_REQUIRED_ATTRIBUTE_MISSING, "required attributes missing: [names]")

• 守卫全部在 step 内（红线）；错误码在 backend/src/errors/error-codes.ts ErrorCode 枚举扩展两项，沿用 PRODUCT_NO_SHIPPING_PROFILE 等既有命名范式；
• 灰度开关：featureFlags 新增 category_standard_gate（默认 false=阶段1 warn；沿用「阶段1 warn → 阶段2 强制」两阶段灰度范式）；
• 现状行为兼容：flag 默认关 ⇒ 上线即回现状（无规范/无 attribute 校验），已售商家零感知。

RK-12：分类改名重译钩子（category-updated）

现状仅创建 hook（category-created-translation.ts:25-36），改名后译文陈旧（RK-12 medium：4×2）。两候选取舍：

选定候选 A 的配套三点：

1. seed 侧同步：CATEGORY_I18N 字典（seed-category-translations.ts:26 起，24 handle × 3 语）为事实源——分类改名必须同步改 seed 字典并重放 seed（写入逻辑先删后写幂等）；同步步骤 runbook 化（改类目名 → 改 CATEGORY_I18N → pnpm db:seed → 重译自动入队）；
2. admin 手工编辑闭环保留：category-detail.tsx:69-74 TranslationSection 不动——重译产出会覆盖译文，admin 可在重译完成后再次手工修正（人工最终确认权保留）；
3. feature flag：category_retranslate_on_update（默认 false 灰度）——hook 内 flag 关闭时直接 return，回滚 = 关 flag。

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

数据模型 · API · Workflow

数据模型：category_standard 表

索引：UNIQUE(category_handle, version)；INDEX(status)（published 查询热点）；INDEX(category_handle)。migration 走 medusa db:generate。

API 契约

AI 能力接入点

本条无直接 LLM 调用。与 translation client 通路的关系为间接复用（经 translation-job 队列，管道契约引用不重复设计）：

• RK-12 重译链路：categoriesUpdated hook → 幂等 enqueue → retry worker（并发信号量/指数退避/MAX 5 既有）→ translateCategoryToLocales（源 ja-JP → zh-Hans/en-US）→ AI 调用走 backend/src/modules/translation/client.ts 唯一通路（SSRF 三层防护/60s 超时既有）；
• 降级与跳过（NFR-3.8-01）：AI 未配置时任务入队后由 retry worker markSkippedNoConfig 终态化（failed+[no-config] 前缀，logger.info 非告警）——分类改名/类目管理主流程零阻断；翻译故障时任务指数退避重试，改名单独成功；
• 范式测试点：①未配置态改名 → 任务 markSkippedNoConfig、改名本身成功；②故障态 → 任务入队退避重试、改名成功；③幂等态 → 同分类连续两次改名 → 队列无重复活跃任务；
• 未来演进注记：建档规范文档型字段（四长文）的三语化可后续经 translation 管道扩展（需扩白名单 + reference 路由），列为后续增强不阻塞本卡。

合规挂钩

前端改动面与 i18n

前端触点（逐端）

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

admin-panel（admin-panel/src/i18n/translations/{en.json, zhCN.json, ja.json}，categoryStandard.* 命名空间）：

vendor-panel（同三文件，products.categoryStandard.* 命名空间）：

三语值随实现提交，三文件同步新增；storefront 系无新增 key。

风险

前置决策点

• B-c3 「18 类」与总纲类目清单语义同构性核对 + 薬機法适用性确认（PRD 8.1 C3 / 8.2-2 / 7.5 依赖 3）——归属商品团队 + 法务；关闭标准与核对结论本卡仅引用编号，不内联臆造。
• DEC-5 量化指标基线立项定：建档规范覆盖率（=18/18 硬指标）、attribute 填报完整率等运营指标数值本卡不臆造。
• 维度 8/9 组件形态 b2b_wholesale_fit / retail_fit 采用 toggle 或 select（是/否/部分）——实现期随 admin 配置定稿。
• 后续增强 建档规范文档型字段（四长文）的三语化经 translation 管道扩展（需扩白名单 + reference 路由）——本卡不设计其实现。

实施排期与验收

子任务 DAG 与估时（技术方案段五线并行；规范发布段等 C3）

上线顺序建议：B5（RK-12，独立价值先行）→ B1+B2 → B3/B4（flag 默认关灰度）→ 观察 warn 日志盘点缺口类目 → C3 关闭后 C1 批量发布 → 阶段2 强制。

验收标准

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

L0 门禁：文档十要素齐备、关键 code anchor 可 rg 命中、既有商品发布/翻译域单测回归通过（含 publish-vendor-product/__tests__/product-listing-review.unit.spec.ts 与 translation 域 8 单测）。

迁移与回滚

附录 · 溯源

本文档生成自 docs/reports/ai-module-prd/tdd/AI-3.4-02-standardized-product-system.md（TDD 深度分级 full；PRD V1.4）。章节映射与处理方式如下：