摘要
本条目对应 PRD FR-3.4-03「AI 智能选品推荐」。PRD 验收要点为:「推荐上线前经人工评估或对照实验验证有效性(口径立项定);选品采纳率跟踪」。现状判定为从零建(零实现)——选品/推荐/scoring 全仓检索命中均为 UI 文案误报,唯一相关能力是 pinned 置顶(人工运营干预的默认排序语义)。
承 RK-13 降级承诺:数据前提(AI-3.4-02 建档规范 + 真实商品数据量)不具备,本卡仅做架构级 TDD——管线形态(复制 translation-job 范式四要素)/ 特征源五清单 / 接口形态 / 冷启动策略四块;字段级设计显式推迟至 AI-3.4-02 建档规范落地后(DEP-3.4-02),不承诺字段级完整度。分期路线为「规则兜底 → 特征管线 → 模型化」三期,本卡不定模型。
本卡仅做架构级 TDD:管线形态 / 特征源清单 / 冷启动策略 / 人工评估口径框架。字段级/模型设计/数值全部推迟或 DEC-5 占位;真实数据积累尚早坐实(主 seed 链不建商品——seed.ts:29 留空注释,demo 链仅 11 商品)。
关键概念
方案设计(架构级——本节不承诺字段级)
架构总览与红线
| 红线(AGENTS.md §0.1) | 本卡落位 |
|---|---|
| Workflow 承载业务逻辑 | 特征计算/推荐结果落库(如有)必须走 Workflow step(沿用 translation-job 的 enqueue+worker 范式,本质即 job→workflow 链);评估/采纳事件写入走 Workflow |
| 不修改上游源码 | 订单/商品/quote/集采全部经 Medusa query/module API 只读消费 |
| 后端单一数据源 | 推荐结果与采纳归因以后端为准,三前台仅消费 |
| 参数化 SQL | 特征聚合查询(订单销量等)全部参数化绑定(沿 products route q 分支正面范式) |
数据管线形态(复制 translation-job 范式)
选品特征计算管线复制 translation-job 四要素(translation-job.ts:48-68 已复核锚点),不改其本体、新建平行模块 selection-pipeline(命名避让,挂 feature flag 独立开关):
| 范式要素 | translation-job 现状(复核锚点) | 选品管线对应设计 |
|---|---|---|
| 唯一消费者 | status 状态机 pending/processing/done/failed(:48 default pending) | selection_feature_job 同构状态机;每商品一条特征计算 job,行内演进 |
| 原子占位/幂等 | claimed_at 两步法 list+update(:55 + 注释 :49-54「worker 并发/重入不重复消费」) | 同构 claimed_at;特征重算 job 以 (product_id, trigger) 幂等去重 |
| 背压 | 并发信号量 3 + 指数退避 2^n 分钟(retry_count :57 / next_retry_at :61) | 同构信号量(P2 数据量下无需更大并发);重算失败指数退避 |
| 调度 | 5min cron(retry-translations job) | 特征刷新 cron(夜间低峰批扫起步;频率参数化,数值 DEC-5) |
触发面(架构级声明):商品发布/更新(subscriber 触发重算)、订单成交(热销特征刷新)、建档规范字段变更(AI-3.4-02 attribute 更新联动——其 RK-12 分类改名重译钩子同构思路)。触发实现细节 = 字段级推迟项。
特征源五清单(逐项数据现状与缺口)
| # | 特征源(PRD 原文五项) | 数据现状(复核锚点) | 缺口 | 门控/依赖 |
|---|---|---|---|---|
| ① | 行业属性 | seller-profile business_type(:23-25)/ capabilities(:26-27);商品侧行业字段缺——AI-3.4-02 attribute industry_applicability 落地前无商品级行业属性 | 商品级行业标签 | DEP-3.4-02 |
| ② | 企业需求 | quote/集采/demand_basis 结构化数据在(demand-basis.ts:11-14 脱敏快照范式可复用) | 需求 → 特征向量的聚合口径未定义 | 撮合设计归 AI-3.3-05(引用不展开) |
| ③ | 用户画像 | 零实现(customer 无画像字段) | 画像特征全体 | C-c6-profile(C6① 评估)——评估通过前该特征源不得启用 |
| ④ | 区域市场特征 | region / sales channel 结构在 | 市场级聚合(区域×品类热度)视图无 | 无外部门控,随管线期实现 |
| ⑤ | 热销数据 | 订单数据在 | 订单 → 商品销量/动销聚合管线无 | 无外部门控,随管线期实现;聚合口径(时窗/去重)字段级推迟 |
冷启动期仅可用 ① seller 侧属性 + ④ 渠道结构 + ② 集采/询价稀疏信号——①的商品级缺口未补前,冷启动规则实质以「类目 + 渠道 + pinned 运营」为主。
推荐接口形态(架构级契约,字段级推迟)
两决策场景、单一推荐服务(selection-recommendation 模块,规划名):
// 契约级签名(字段级推迟——入参/出参对象结构随特征源固化后定稿)
getSelectionRecommendations({ scenario, context }) → { items: [...], meta }
scenario = "b2b_procurement" | "new_retail_listing"
context(示意,非冻结):行业/客群/区域/价格带/需求快照引用
- B2B 集采选品:输入企业需求上下文(可引用 demand-basis 脱敏快照),输出候选商品组合(供采购决策参考,非自动成交——大额交易人工确认归 NFR-3.9-04 场景1,经 AI-3.3-05 撮合链路时由其挂钩,本卡不重复设计);
- 新零售上架:输入店铺渠道/客群画像(画像源受 C6 门控),输出上架选品建议(建议非自动上架——上架仍走既有 publish 审核流);
- 消费 AI-3.4-02 建档字段为特征输入(
industry_applicability/target_customer_segment/price_range_bandattribute 与 category_standard 规范字段)——声明为特征输入引用,字段定义归其卡所有(design_ownership references_only); - 采纳率跟踪埋点契约:
selection_recommendation_shown/selection_recommendation_adopted双事件(payload 含 scenario/推荐批次 id/item id/位置),归因窗口与统计口径 = DEC-5;事件落库实现 = 字段级推迟项。
冷启动策略(架构级)
无行为数据期(当前即此状态)的推荐兜底:
- 规则层:类目/渠道/区域静态规则(如「某区域渠道优先呈现其历史成交类目」——无历史时回全类目默认集);规则集以配置承载(admin 可调,架构级声明不落字段);
- 编辑精选层:运营人工圈选的推荐位——直接复用 pinned metadata 置顶(已复核的唯一人工干预点)作为冷启动排序起点与编辑精选载体(pinned 语义扩展「运营精选 = 冷启动推荐」,不新增实体);
- 数据积累过渡判据:真实商品量与订单量的量化阈值 = DEC-5——量化前不启动模型化分期,冷启动规则层持续兜底。
分期路线(架构级承诺边界)
| 分期 | 内容 | 前置 | 本卡承诺边界 |
|---|---|---|---|
| ① 规则兜底期(当前态声明) | pinned 置顶 + 默认排序 + 规则层冷启动 | 无 | 已存在(pinned);规则层随管线期落地 |
| ② 特征管线期 | 管线 + 特征源①④⑤启用 + 接口字段级定稿 + 评估框架落地 | DEP-3.4-02 + X-data-volume 部分缓解(真实数据开始积累) | 架构已定,字段级 TDD 增量随 DEP-3.4-02 解除后立项 |
| ③ 模型化期 | 排序模型/组合优化(形态不定——协同过滤/内容向量/LLM rerank 均为候选项) | X-data-volume 解除 + ② 期采纳率数据回流 | 本卡不定模型;仅约束:任何模型期输出仍走降级范式与合规挂钩 |
数据模型 · API · 合规
数据现状与从零建项
| 类别 | 项 |
|---|---|
| 已存在可复用 | translation-job 队列范式四要素(管线骨架母版);pinned 置顶排序(冷启动起点 + 降级目标);seller-profile 结构化属性;quote/集采/demand_basis 结构化数据;region/sales channel 维度 |
| 需扩展 | 订单 → 商品销量聚合(订单数据在、聚合视图无);attribute 系统行业字段(AI-3.4-02 落地后消费,本卡引用) |
| 从零新建 | 选品特征计算管线 job;推荐服务与接口;人工评估/对照实验框架;采纳率跟踪;冷启动规则集 |
AI 能力接入点
分期①②(规则兜底/特征管线)零 LLM 调用——推荐计算为规则 + 统计聚合,与 translation client 通路无调用关系。分期③(模型化期)预声明:若引入 LLM(如生成选品理由/rerank),与 translation client 通路的关系 = 「抽公共」评估(选品为独立业务域,长期与翻译共用同一 OpenAI 兼容配置易耦合——抽取公共 provider 层届时立项评估;不默认直接复用 translation client 本体,防止翻译域配置变更传导至选品域)——该声明为分期③的前置约束,非本期设计。
降级与跳过路径(NFR-3.8-01 强制范式)
| 故障场景 | 行为 |
|---|---|
| 推荐服务不可用/超时/未配置 | 降级为默认排序 + pinned 置顶(既有语义,零额外建设)——范式句:「未配置/故障即跳过不阻断主业务」 |
| 特征管线 job 失败 | 指数退避重试;达上限 failed 终态 + 告警——推荐继续以陈旧特征或冷启动规则运行,不阻断 |
| C6 画像评估未通过 | 特征源③硬禁用,推荐仅用其余特征源——合规门控即降级开关 |
跳过路径测试点(必含):①推荐服务异常 → 响应回退默认排序集(与现状 pinned 语义逐字节等价断言);②特征 job failed → 推荐仍可用(陈旧特征标记 + 冷启动规则);③画像源禁用 → 输出不含画像特征且不报错。
合规挂钩
| NFR / 评估项 | 影响判定 | 本卡动作 |
|---|---|---|
| C6①(画像与个性化推荐 APPI 影响评估) | PRD §8.1 C6① 原文并列点名 FR-3.4-03/FR-3.7-02:「用户画像与个性化推荐…涉及个人关联信息利用规则」 | 特征源③(用户画像)硬门控:评估清单由合规侧出具并通过前,画像特征不得接入管线;本卡不预设定评估结论 |
| NFR-3.9-04(面向公众 AI 推荐巡检) | PRD 原文「面向公众的 AI 话术、展示、推荐逻辑人工审核并定期巡检」——推荐结果属面向公众 AI 输出 | 挂 AI-3.9-04 巡检机制(ai_patrol_task/ai_patrol_record:scope=推荐逻辑,artifact_type 开放枚举可扩展 selection_recommendation);分期③模型化输出上线前按其把关框架评估——引用其框架,不重复设计 |
| NFR-3.9-03(审计) | 推荐生成/采纳事件留痕 | 双事件埋点即审计数据面;聚合口径随字段级定稿 |
| NFR-3.9-01(APPI 数据最小化) | 需求侧特征引用 demand_basis 脱敏快照范式(无 PII,既有口径) | 特征聚合沿用脱敏范式;不做个体级画像(C6 通过前根本无此数据) |
| B-c3 / C3(18 类同构核对) | 选品库范围核对的业务前置 | 要素 7 二分声明——本卡技术架构不受阻 |
外部决策点引用规范:数据量阈值/评估口径/采纳率目标/巡检频次全部 DEC-5 占位;画像评估 = C-c6-profile;不内联臆造。
风险
前置决策点
- DEC-5 数据量启动阈值 / 评估合格线 / 采纳率基线与目标 / 特征刷新频率 / 对照实验样本量——全部基线立项定;数据量本体先经 DB 侧量化(findings 开放问题①)再立阈值。
- C-c6-profile 画像与个性化推荐的 APPI 影响评估——评估清单由合规侧出具;通过前特征源③硬禁用(本卡不预设定评估结论)。
- B-c3 选品库范围固化(推荐候选域边界)——18 类清单核对结论回填配置。
- 分期③模型形态 协同过滤 / 内容向量 / LLM rerank 均为候选项——本卡不定模型,X-data-volume 解除后另行立项。
上游:AI-3.4-02(建档规范字段 = 特征输入,引用其九维度表;其 C3 前置传导 = 本卡 B-c3;字段级设计推迟至其落地);AI-3.3-05(需求侧数据形态参考:quote/集采/demand_basis;撮合人工确认挂钩归其卡)。同波:AI-3.2-04(无设计耦合——其映射归属表已声明智能选品 = 本卡,商业化挂接随本卡字段级期)。下游:AI-3.7-02(画像同源约束,同受 C6① 门控;对话式推荐远期形态不在本卡)。
实施排期与验收
波次与分期映射(p2-a)
| 分期 | 波次/时点 | 前置 |
|---|---|---|
| ① 规则兜底(现状) | 已存在(pinned) | 无 |
| ② 特征管线(架构本卡 + 字段级增量) | 字段级随 AI-3.4-02 建档规范落地后推进;模块骨架可在 p2 执行期以空特征源先行 | DEP-3.4-02 |
| ③ 模型化 | X-data-volume 解除后另行立项 | 数据量 DEC-5 阈值 |
子任务 DAG(架构级交付):本卡即架构交付物;可先行项 = 管线模块骨架(空转链路)/ 冷启动规则配置面 / 评估框架文档化——均标注「字段级推迟,随 DEP-3.4-02 解除推进」。
验收标准(架构级承诺边界)
| # | 验收标准 | 映射 |
|---|---|---|
| A1 | 架构方案齐备:管线形态(复制 translation-job 四要素)/ 特征源五清单(含现状与缺口逐项)/ 接口形态(两场景)/ 冷启动策略四块完整成文且相互一致 | 要素 4 |
| A2 | 人工评估口径框架(PRD 要点①):双轨框架成文——①人工评估:业务专家对 Top-N 推荐列表盲评(有效性分级量表,量表刻度 = DEC-5);②对照实验:推荐排序 vs 默认+pinned 排序分流对比(分流机制与显著性判据 = DEC-5);上线前执行为分期②验收前置 | PRD 要点① |
| A3 | 采纳率跟踪框架(PRD 要点②):shown/adopted 双事件契约成文,采纳率指标名 selection_adoption_rate(数据源:事件聚合);基线与目标 = 基线立项定(DEC-5) | PRD 要点② |
| A4 | 冷启动有效性:零行为数据期,推荐入口输出 = pinned 置顶 + 规则层结果(与现状默认排序语义等价或更优,无空结果面) | 冷启动 / 降级 |
| A5 | 降级路径(AI/管线不可用零阻断):推荐服务异常 → 默认排序+pinned(逐字节等价断言);特征 job failed → 陈旧特征标记继续服务;画像源禁用 → 无画像特征输出 | NFR-3.8-01 |
| A6 | 合规门控生效:C-c6-profile 未通过前,管线配置中画像特征源处于禁用态且不可开启(配置面守卫) | 特征源 / 合规 |
| A7 | L0 门禁:本文档十要素齐备 + 关键锚点可 rg(translation-job / seed.ts / products route pinned / DEP-3.4-02 / X-data-volume / B-c3 / 冷启动 / 特征源 / 人工评估 / DEC-5 / AI-3.4-02-standardized-product-system.md) | 模板 |
| A8 | 分期路线与推迟声明:字段级/模型设计显式标注推迟(DEP-3.4-02 解除后立项),无虚假完整度承诺 | depth_baseline / RK-13 缓解 |
测试策略(架构级承诺边界)
本卡交付时无实现可测——测试设计为分期②实施时的用例框架(声明防止验收空转):
| 层 | 分期②用例框架(本卡定义形态,实现期填充) |
|---|---|
| 单测(管线) | 特征 job 状态机/幂等/指数退避(对齐 translation-job 既有测试形态——其 8 个单测文件含 retry-translations 等可作范式参照);特征源门控(画像禁用断言) |
| 单测(降级) | A5 三测试点(异常回退/陈旧特征/画像禁用) |
| integration(接口) | 两场景契约形状断言(字段级定稿后);事件埋点 payload 断言 |
| 评估执行 | A2 双轨框架的执行手册(人工评估流程/对照实验配置)——口径数值 DEC-5 回填后生效 |
| 既有回归 | products route 既有单测复跑(pinned 语义为降级目标,回归守卫其不被破坏) |
迁移与回滚
| 变更 | 迁移 / 回滚路径 |
|---|---|
| 推荐能力整体 | feature flag 关闭 → 入口回默认排序 + pinned(与现状等价);无数据残留面 |
| 特征管线 job | job 独立开关关闭 + 代码回退;特征快照表随 migration down(新表无纠缠) |
| 事件埋点 | 事件写入开关关闭即停采;已采事件保留(append-only,归因统计可独立废弃) |
| 规则/精选配置 | admin 配置回滚即生效(配置化承载的意义) |
| migration / seed | 架构阶段零 migration;分期② schema(selection_feature_job/特征快照表)经 medusa db:generate selection-pipeline 生成;不改 pnpm db:reset / db:reset:demo(种子不含选品数据,空配置 = 回默认排序) |
规划 featureFlags.selection_recommendation(featureFlags 区,默认 false——管线/推荐独立开关,关闭态推荐入口整体回退默认排序);特征源级子开关(画像源默认永久禁用直至 C-c6-profile 通过——合规门控优先于 feature flag,双闸结构:flag 总闸 + 特征源合规闸,任一关闭即不启用)。上线顺序:flag 开启 → 冷启动规则 → 特征管线 → 评估通过(A2)→ 对外放量——「推荐上线前经人工评估或对照实验验证有效性」(PRD 验收要点原文)即放量门禁,顺序不可颠倒。
附录 · 溯源
本文档生成自 docs/reports/ai-module-prd/tdd/AI-3.4-03-ai-product-selection.md(TDD 深度分级 conceptual;PRD V1.4)。章节映射与处理方式如下:
| 本文档章节 | 源章节 | 处理 |
|---|---|---|
| 摘要 | 元数据表 + 降级承诺声明 + §1.3 判定 | Summarized |
| 关键概念 | §2.1 / §4 / §6 术语 | Summarized |
| 架构总览与红线 | §4.0 | Preserved |
| 图 1 架构总览 / 图 2 job 状态机 / 图 3 降级时序 | §4.0 / §4.1 / §5.2 | Inferred(可视化转译,节点内容对齐源文字) |
| 数据管线形态(范式四要素对照表) | §4.1 | Preserved |
| 特征源五清单 | §4.2 | Preserved |
| 推荐接口形态(契约级签名/埋点契约) | §4.3 | Preserved |
| 图 4 特征源实体关系 | §2.1③ / §4.2 | Inferred(按源盘点绘制) |
| 冷启动策略 / 分期路线 | §4.4 / §4.5 | Preserved |
| AI 能力接入点 / 降级路径 / 合规挂钩 | §5 / §6 | Preserved(条目化) |
| 风险 | §7.1 二分表 + RK-13 | Summarized |
| 前置决策点 | §7 / §6 引用规范 | Preserved |
| 实施排期与验收(波次/验收/测试/迁移回滚) | §8 / §9 / §10 | Preserved(回滚压缩为表) |
| 现状三态判定与负证据(检索式/锚点) | §1.3 / §2.1 / §2.2 | Summarized(关键锚点保留:translation-job.ts:48-68、store/products route pinned、seed.ts:29、demo 11 商品) |
源 TDD 全部锚点在其 run(run-d7006c21fca3)以 rg/sed 逐条复核,漂移双写共 2 处(seed.ts 路径与注释行、products route pinned 锚点),内容实质均验证成立。本文档保留关键锚点;规范性要求以源 TDD 为准。