AI-3.3-05 供需智能撮合 · 实现策略 TDD

摘要

PRD V1.4 §5.2 FR-3.3-05 验收要点：「撮合推荐经人工确认后分发；撮合商机有效率跟踪（基线立项定）。」 现状判定为部分实现——平台已具备三种人工/规则驱动的供需对接形态：B2B 询价报价（quote 五态状态机）、 集采（八态状态机+自动成团判定）、采购需求参考（demand_basis 只读脱敏快照）； 但「撮合」的业务语义已具备、智能引擎为零——推荐/匹配评分/智能分发全库 0 业务命中（仅 3 处法务文案误报）。

本卡交付规则级撮合（需求→结构化条件→候选供方评分→人工确认分发）：确定性规则+加权评分（评分维度可解释、人工可确认）， 算法撮合（推荐模型/用户画像/学习型评分）显式划出范围为演进项（衔接 AI-3.4-03 与 AI-3.3-04）； 把关状态机本体归人工审核框架条目（AI-3.9-04）所有，本卡只定义挂接点（禁止两套状态机声明）。 P1 全部能力为确定性规则引擎，零 AI/LLM 调用；撮合失败永远存在人工出路（quote/集采直达）。

关键概念

方案设计

设计红线声明与两段式总览

输入段：需求结构化条件（字段级）

载体：matching_recommendation.demand_snapshot JSONB（快照冻结范式沿用 demand_basis「建单时冻结、不回写」）。字段级清单（每字段给来源与类型）：

结构化条件校验：backend/src/api/store/matching-recommendations/validators.ts（zod schema，键闭合）；P1 无 LLM 解析——结构化条件由买家表单/采购需求页结构化提交；自然语言→结构化的 LLM 解析为 AI-3.3-04 接口位。

匹配段：候选供方评分（维度×权重结构，数值 DEC-5）

权重表结构（数值基线立项定（DEC-5），本卡只冻结结构与键名）：

// 配置载体：matching config（以下为 schema 非数值）
{
  "weights": { "category_hit": <DEC-5>, "qualification": <DEC-5>,
               "fulfillment": <DEC-5>, "responsiveness": <DEC-5> },  // 归一化校验 Σ=1
  "candidate": { "top_n": <DEC-5>, "category_hard_filter": true,
                 "min_score": <DEC-5> }
}

• 评分确定性：同输入同输出（纯函数 scoreCandidates(demand, candidates, weights) → scored[]，无随机/无时变因子进评分式——数据快照在生成时冻结）；单测断言确定性（验收 A4）；
• 候选集裁剪：品类硬过滤（D1=0 直接剔除，category_hard_filter:true 默认开）→ 评分排序 → top-N 截取（N 数值 DEC-5）→ 低于 min_score 剔除；
• 无候选出口：裁剪后空集 → 推荐记录落 status=empty_result（不报错不阻断，走降级提示）。

输出段：人工确认分发（挂钩 NFR-3.9-04）

把关状态机挂接点（本体归人工审核框架条目 AI-3.9-04 所有——禁止两套状态机声明）：

• 本体所有者：AI-3.9-04（同波并行卡）——把关框架的通用状态集语义、forward-only 迁移校验工具（qualification-state-machine.ts:29-39 REVIEW_TRANSITIONS 表驱动范式为共享工具来源）、五类场景枚举均归其所有；
• 本卡仅定义挂接点（三件）：①门禁语义挂接——draft→confirmed 迁移即「未确认不生效」门禁实例化，draft 态推荐对供方完全不可见；迁移合法性校验调用共享校验器（其交付前由本卡 step 内局部白名单兜底：仅允许 draft→confirmed/rejected、confirmed→distributed，交接时替换为共享工具调用）；②确认动作挂接——POST /admin/matching-recommendations/:id/confirm 写 status/reviewed_by/reviewed_at（或 rejected+rejection_reason）；③分发动作挂接——POST /admin/matching-recommendations/:id/distribute 仅 confirmed 态可调（step 内守卫），向候选供方推送询价/商机。

分发=复用既有询价链路：分发 step 供方侧动作落点为向供方发起询价请求（复用 create-request-for-quote 链路语义）；无 cart 直发变体为本卡对 quote 链路的唯一扩展点，不修改既有 workflow 本体。

配置载体（DEC-3 占位）：权重与阈值配置落新表 matching_config（单行 key="default"，字段 weights jsonb / candidate jsonb / confirmation_threshold jsonb——threshold 结构 {large_amount_minor?, scenarios[]} 数值与场景枚举标注 D-dec3，缺省 null=门禁退化为「全部推荐需人工确认」（保守默认，合规安全向））；读侧 getEffectiveMatchingConfig()（DB 优先+代码默认回退，translation-config service 同构范式）。

既有三形态语义沿用不重设计 + quote 缺陷补字段

子任务 DAG 与排期

所属波次 p1（与 AI-3.9-04 同波并行，挂接点契约对齐；与 AI-3.3-02 同域不同链路，无资源冲突）。交叉引用：AI-3.9-04（P1 同波，把关框架本体）；AI-3.3-04 / AI-3.4-03（P2 演进承接）；AI-3.2-02（资质数据上游）。

数据模型 / API / Workflow

新实体 matching_recommendation（字段级）

索引：(status)、(demand_owner_type, demand_owner_id)、(created_at)。留痕三件套对齐 seller-profile 范式；reviewed_by=req.auth_context.actor_id 落库范式（findings AI-3.9-04 锚点 review-channel-qualification.ts:43-46 同构）。

API 契约汇总

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

AI 能力接入点：规则级无 LLM 调用声明 + 演进接口位

本卡 P1 全部能力（结构化条件校验/评分/确认分发）为确定性规则引擎，零 AI/LLM 调用——与 translation client 通路无调用关系。PRD「智能匹配」的「智能」在 P1 兑现为规则级结构化撮合（评分维度可解释、人工可确认）。

前端改动面与 i18n

验收与测试

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

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

L0 门禁：本文档十要素章节齐备、关键 code anchor 字符串可 rg 命中、quote/集采既有单测可回归（backend/src/workflows/group-procurement/__tests__ 目录存在，实现期确认覆盖面并复跑；quote workflow 测试同规则）。

量化指标占位口径：撮合商机有效率（基线/目标）、top-N 候选数、评分权重四值——全部基线立项定（DEC-5）；大额阈值与非标场景清单——D-dec3（管理层决策，配置占位）。

风险与降级

风险卡

降级设计（撮合失败/无候选不阻断主流程，NFR-3.8-01 范式）

合规挂钩

迁移与回滚

pnpm db:reset / db:reset:demo 兼容声明：两 migration 均可空库重放；matching_recommendation/matching_config 空表不参与 seed（seed 留空惯例一致）；quote.seller_id 为 NULL 时全链路行为与现状逐字节等价。

上线顺序建议：M1-M4 后端先行（flag=false 影子运行：workflow 可单测/integration 验证但入口不开）→ M5 前端+flag=true 灰度开管理员侧 → DEC-3 回填阈值 → 全量开放。

前置决策点

Blocker 二分表（阻塞什么 / 可并行做什么）

内部依赖与下游消费

开放数值决策

• DEC-5 撮合商机有效率（基线/目标）、top-N 候选数、评分权重四值——基线立项定，本卡仅引用编号不臆造数值。
• DEC-3 大额交易人工确认阈值与非标合作场景清单——管理层决策，配置占位；缺省 null=保守全确认（合规安全向）。

附录：溯源表

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