AI-3.9-04 人工审核机制 · 实现策略 TDD

摘要

NFR-3.9-04（溯源 AI-3.9-04，Should · P1）要求建立「AI 输出 → 人工确认 → 生效」的通用把关框架，覆盖五类场景：大额交易（阈值由管理层决策，DEC-3）、非标合作协议、法律文书、财税决策、医疗相关推荐——上述场景中 AI 输出仅作参考，须经人工确认（明确确认主体、确认时点、确认留痕）后方生效；面向公众的 AI 话术、展示、推荐逻辑人工审核并定期巡检。PRD 验收要点原文：「五类场景人工确认流程上线且"未确认不生效"可验证；巡检记录完整；大额阈值决策落地（DEC-3）」。

现状判定部分实现（与 PRD 附录 A 一致）：①审核底座已建成——业务资格/订单审批/协议审核均有完整人工闭环与留痕（四套状态机）；②AI 产出物把关未建——ai_review 全库检索 0 命中，把关框架尚未延伸至 AI 产出域。本 TDD 全部设计作用于②，不改动①的既有审核流。核心交付：以 channel-qualification 六态 forward-only 状态机为唯一复用母版，泛化为「迁移表工具级共享」的参数化把关框架（ai_review_record 实体 + draft→confirmed「未确认不生效」门禁 + last_transition 轨迹），框架与参数值解耦（RK-05）——大额阈值等参数由 DEC-3 落地后纯配置回填，框架零改动。

关键概念

方案设计

设计归属总览与红线声明

既有四套审核状态机盘点（逐套 file:line+状态枚举+留痕字段）

admin 审核工作台范式（复用为 AI 产出物复审界面骨架）：sellers/common/components/seller-qualification-review-actions.tsx:31-115（approve/reject 双 Drawer 动作区：channelMode 预选 :34-36、rejectionReason 状态 :37、hooks :38-41、非 PENDING 不渲染 :43-46）；seller-list/seller-status-cards.tsx（状态卡片徽标按状态着色）；h2b-buyers/[id]/page.tsx:85-86（STATUS_BADGE_COLOR[qualification.status] 模式）；approvals/approval-list + approval-detail（审批列表+详情路由范式）；cooperation-agreements/page.tsx:9-65（按状态筛选的列表页范式）。

块 A：forward-only 参数化把关框架（字段级，本卡核心）

A-1 共享把关工具（新建 backend/src/utils/ai-review-gate/ 或 policies 共享目录，纯函数）——以 qualification-state-machine.ts:26-40 为唯一复用母版泛化。三个参数（消费方各自传入，工具不强绑定任何状态集）：

assertForwardOnlyTransition({ transitions, from, to })
  → 非法迁移抛 MedusaError(UNEXPECTED_STATE, "Illegal ai review status transition: {from} -> {to}")
  （母版 :41-53 逐行为范式）

buildLastTransitionMeta({ from, to, reason, actor_id, at })
  → { [metaKey]: { from, to, reason, actor_id, at } }
  （形态对齐 affiliate StatusTransitionAuditMeta :28-34；写入由消费方 workflow step 落库）

A-2 AI 产出物默认生命周期（默认参数化示例，各消费方可覆盖）——「提交→复审→通过/驳回→撤销/重申」默认映射（ai_review_record.status 默认状态集）：

A-3 通用审核实体 ai_review_record（新本地模块 ai-review-record/，字段级）：

约束与索引：UNIQUE(artifact_type, artifact_id)（一产出物一审核行，生命周期行内演进）；INDEX(status)、INDEX(artifact_type, status)、INDEX(reviewed_by)。

块 B：五类场景挂钩表 + 巡检机制（参数 D-dec3/DEC-5 占位）

挂钩配置载体：artifact_type × 场景的映射配置（常量表起步，admin 可视化配置列演进项）；每场景的阈值/清单/资质参数一律 D-dec3/法务占位——框架设计与参数值解耦（RK-05 mitigation 原文）。

巡检机制（面向公众 AI 话术/展示/推荐逻辑——总纲 3.9⑤）：

• ai_patrol_task：id(prefix aipat) / scope（ai 话术/展示/推荐逻辑范围）/ artifact_type / sample_rule（抽样规则）/ frequency（巡检节奏=基线立项定（DEC-5）占位）/ owner；
• ai_patrol_record：id / task_id / artifact_ref / result（pass|fail|pending）/ findings / reviewer / reviewed_at / created_at；
• 完整性口径：巡检记录含「谁在何时按何规则检了何物、结论与发现问题」四要素即视为完整（PRD 验收要点「巡检记录完整」的技术口径）；数值（频次/抽样率/合格线）一律 DEC-5 占位。

块 C：消费方显式声明 + 三条边界（禁止两套状态机）

AI 能力接入点（把关层，非 AI 接入层）

本条不调用 LLM、不建 provider 通路、不设计 prompt。三段义务表述：

1. 与 translation client 通路的关系 = 旁路（把关层与通路层正交）：AI 输出（如译文批次）由 AI-3.5-02 通路（backend/src/modules/translation/client.ts）产出后，经本框架门禁（confirmed）方对外生效；本框架不触碰通路代码。关系声明：并行——通路层管「产出」，把关层管「生效」，两层经 (artifact_type, artifact_id) 弱关联衔接；
2. NFR-3.8-01 强制范式声明：「未配置/故障即跳过不阻断主业务」——本框架关闭时（flag off）AI 产出物回现状直发路径（过渡态），主业务零阻断；框架开启时门禁拦截的是「AI 产出物的对外生效」而非「主业务链路」，两者显式区分。跳过路径测试点：flag off 时产出物直发+主链路成功；
3. 降级路径：①框架故障（工具抛错异常态）→ 消费方 step 捕获后fail-closed 拒绝生效（把关层故障不得放行未审产出——本框架保护的是合规底线，不适用 fail-open）+ 告警日志；②框架关闭（flag）→ 直发过渡态（显式声明）。

合规挂钩

Workflow 与 API 契约

review 工作流（业务逻辑必须在 Workflow）——review-ai-artifact：steps 链 load-ai-review-record → assert-forward-only（A-1 工具，守卫在 step 内）→ update-ai-review-record（status+reviewed_by/reviewed_at/rejection_reason 终态必填+last_transition）→ emit ai-review.recorded；补偿=读旧值回写（快照式，非 reject-seller 式业务回滚——边界③）。

API 契约（admin scope）——路由挂载 backend/src/api/admin/ai-review-records/（Zod 校验中间件 + req.auth_context.actor_id 落库范式）；权限域=平台运营（admin scope，vendor/store 无路由——审核为平台侧职责）：

AiReviewRecordDTO（与实体字段一一对齐，deleted_at 不外露）：id / artifact_type / artifact_id / status / reviewed_by? / reviewed_at? / rejection_reason? / last_transition? / metadata? / created_at / updated_at。

• decision 路由必须经 review-ai-artifact Workflow（路由层仅做 Zod 校验 + workflow 调用，不写库）；ERR_AI_REVIEW_INVALID_TRANSITION 由 A-1 守卫 step 抛出透传（如 confirmed→draft 回退、非终态缺 reason）；
• 巡检任务创建/编辑为演进项（首期常量表配置），路由 4/5 先交付只读查询面；
• 消费方影响：AI-3.5-04 / AI-3.6-03 消费的是服务级契约（「未 confirmed 不生效」门禁+留痕范式），不消费本节 admin 路由。

迁移与回滚

seed 兼容（pnpm db:reset / db:reset:demo 不破坏）：两表均空表参与 reset（seed 不注入审核记录——审核记录是运行时事实非配置）；四套既有审核流零改动故 reset 行为不变。

上线顺序建议：F-1→F-2→F-3（框架内串行）∥ F-4/F-5 → 同波 AI-3.3-05 接线 → flag 开启（先观察单 artifact 类型灰度）→ P2 消费方接入。全卡不改动四套既有审核流与任何上游包。

前端改动面与 i18n

前端触点（逐端）

i18n 三语言 key 规划（en / zhCN / ja，仅 admin-panel）

改动面仅 admin-panel（AI 复审工作台+巡检页）：admin-panel/src/i18n/translations/en.json、zhCN.json、ja.json 同步新增，命名空间 aiReview.*。三前台/vendor i18n 无新增 key（无 UI 改动）。

验收与测试

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

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

L0 门禁：本文档十要素章节齐备、关键 code anchor 字符串可 rg 命中；实现期复跑既有回归（四套状态机既有单测：qualification-state-machine.unit.spec.ts、qualification-flow-policy.unit.spec.ts、transition-settlement-statement-status.unit.spec.ts、transition-commission-line-status.unit.spec.ts）。

风险与开放问题

已识别风险

前提与假设

开放问题

• DEC-3：大额交易人工确认阈值与非标合作场景清单的定义时点（PRD §2.5 原文——不决策的后果：高风险 AI 场景缺统一兜底标准）。
• DEC-5：巡检节奏/抽样率/合格线等数值定档（立项时）。
• X-review-agency：法律文书场景专业复核机构资质（外部资源，引用不展开）。
• 挂钩配置可视化（admin 配置面）演进时点——首期常量表起步。

前置决策点

Blocker 二分表（禁止因阻塞点否定整条 TDD）

依赖与下游消费

• 内部依赖：TASK-001（TDD-TEMPLATE 十要素骨架，已消费）+ PILOT-DECISIONS.md 决策二（共享粒度定调结论本体——其所有，本卡消费）；
• 下游消费（DEP-3.9-04）（findings blockers 原文：「审核把关框架延伸（AI-3.9-04 P1 先行）」阻塞「AI-3.5-04 复核工作流、AI-3.6-03 成交确认钩子」）：AI-3.5-04-dual-track-review.md（C 波）、AI-3.6-03-digital-employee.md（B 波）、同波 AI-3.3-05（挂接点契约）；
• 外部资源：无硬外部依赖（机构资质等场景参数为法务/业务侧输入，占位不阻塞框架）。

待决问题清单

• 前置决策 D-dec3：大额阈值数值与非标场景清单——决策落地后参数回填配置热生效（框架零改动）。
• 前置决策 DEC-5：巡检 frequency/sample_rule 数值定档——实体占位先行。
• 前置决策 flag 开启时点与灰度策略（先观察单 artifact 类型）。
• 前置决策 挂钩配置可视化（admin 配置面）演进时点。

附录：溯源对照

本文档由 docs/reports/ai-module-prd/tdd/AI-3.9-04-human-review-framework.md（文档版本 v1.0，2026-10-26）转换生成。输出章节与源章节映射如下（Preserved = 保留原文内容；Summarized = 摘要化重组；Inferred = 转换侧推断标注）：