AI-3.2-04 智能工具试用期与付费开通

摘要

本条目对应 PRD FR-3.2-04「智能工具试用期与付费开通」。PRD 验收要点为：「四类工具“试用—到期—付费开通”全流程可配置；条款经法务复核；误导性缔约表示检查通过」。现状判定：机制从零建，但四块付费原语全部在位（最短路径成立）——复式账本、customer group 定价门控、Stripe 收款通路、定时 job 范式均已存在；subscription/entitlement/trial 实体零命中。

方案采用两层边界：机制层先行（tool_entitlement 实体 + 试用计时到期 job + customer group 解锁付费墙 + ledger entry_type 入账扩展——无外部依赖，A 波可开工）；工具适配器随后（各工具本体挂接 entitlement 检查点，随 X-tool-bodies 绑定排期）。首切片商业形态 =「一次性开通收款 + 时间窗 entitlement」（用量计量/自动续费/发票流程不在首切片）。条款法务复核（D-dec5）= 上线前置非设计前置，本卡只定义检查点不做法务结论。

关键概念

方案设计

两层边界总览

tool_entitlement 实体（字段级首切片）

新本地模块 backend/src/modules/tool-entitlement/（models/services/index），表 tool_entitlement：

索引与约束：UNIQUE(tool_code, customer_id)（同主体同工具一条 entitlement 行，生命周期行内演进）；INDEX(status)、INDEX(trial_ends_at, status)（到期扫描热点）、INDEX(customer_id)、INDEX(seller_id)。

试用期计时与到期 job

新 job backend/src/jobs/reconcile-tool-entitlement-expiry.ts（复用 30min cron 扫描范式，为 jobs 目录第 16 个定时 job，范式零学习成本）：

• config = { name: "reconcile-tool-entitlement-expiry", schedule: "*/30 * * * *" }（对齐 reconcile-h2b-deposit-timeout 范式：30 分钟扫描粒度——试用期以天为单位，30min 足够）；
• 扫描：status='trial' AND trial_ends_at <= now() 批量（BATCH_LIMIT 50 同范式）→ 逐行触发 expire-tool-entitlement Workflow；
• 幂等：job 可重入（状态机守卫保证重复触发不重复迁移——已 expired 行不再命中扫描条件）；逐行 skipped/transitioned 计数日志（范式原文对齐）；
• 到期联动：状态迁移 trial→expired + emit 通知事件（tool-entitlement.expired）——通知渠道沿平台既有通知基建消费，事件负载仅含 entitlement id/tool_code/customer_id（最小化）。

customer group 解锁付费墙（pricing 原生，禁止自建第二套）

开通链路（付费成功 → 解锁）：

• 禁止自建第二套价格门控（任务卡强制）：工具访问权判定 =「entitlement 状态 + customer group 成员资格」两事实源的组合，价格呈现完全交给 Medusa pricing；
• 取消/到期联动：expired/cancelled 时 Workflow step remove-customer-group（移出解锁组，pricing 即时回落默认价）；
• 分层声明：工具本体（如数字员工会话）的业务级访问检查走适配器契约（checkEntitlement），与 pricing 解锁分层——pricing 管「价格呈现」，entitlement 管「功能开关」。

付费入账走 ledger（spec 硬约束三连）

owner 维度：工具订阅为平台收入——FINANCE_OWNER_TYPES.platform + platform_revenue 账户，不新增 owner 类型。

工具适配器段接口契约（references_only）

机制层对外暴露的唯一接入契约（首个消费方 AI-3.6-03 立项时以此为准，本卡不设计各工具内部计费细节）：

// 内部 service（backend/src/modules/tool-entitlement/service.ts）
checkEntitlement({ tool_code, customer_id }) →
  { entitled: boolean, status: "trial"|"active"|"expired"|"cancelled"|null,
    trial_ends_at: string|null }

• 工具本体在每个功能入口（会话发起/选品生成/报价生成）调用一次；entitled=false 时工具前端呈现付费引导（引导页 UI 归各工具 TDD）；
• 契约稳定性承诺：机制层交付后该签名冻结；扩展仅限返回体追加字段（向后兼容）；
• 定价档位/试用期默认时长/续费形态 = DEC-4/DEC-5 占位，机制层全部参数化承载，不内联数值。

四类工具映射归属表

Workflow · API · 合规

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

新 Workflow 目录 backend/src/workflows/tool-entitlement/：

start-tool-trial（开通试用：admin 授予或自助入口）
  steps: validate-tool-code（枚举校验） → upsert-tool-entitlement（trial 态，trial_ends_at=now+时长）
       → assign-customer-group（试用组，如需试用级定价） → emit "tool-entitlement.trial-started"
  补偿：删除 entitlement 行/移出组（事务内）

grant-tool-entitlement（付费开通）
  steps: load-tool-entitlement → assert-transition（trial/expired→active 白名单守卫）
       → mark-entitled（entitled_at） → assign-customer-group（解锁组）
       → record-ledger-entry（tool_subscription，amount_minor，idempotency_key=收款 id 派生）
       → emit "tool-entitlement.granted"
  补偿：ledger 冲正（reversal_of_entry_id 关联冲正分录，非删除——append-only）+移出组

expire-tool-entitlement（到期，由 reconcile job 触发）
  steps: load → assert-transition（trial→expired） → mark-expired → remove-customer-group
       → emit "tool-entitlement.expired"
  补偿：快照回写

cancel-tool-entitlement（取消）
  steps: load → assert-transition（trial/active→cancelled） → mark-cancelled → remove-customer-group
       → emit（补偿：快照回写）

API 契约（机制层管理面）

错误码：404（不存在）/ 409（非法状态迁移）/ 400（validator）。store 端只读自查、无越权面（仅本人 customer_id）。

AI 能力接入点

本条为商业机制：无 LLM 调用声明——试用期计时/开通订单/付费墙/账本入账全程零 AI/LLM 调用，与 translation client 通路无调用关系。能力边界防越界声明：四类工具各自的 AI 接入点（对话引擎 LLM 通路、选品推荐模型等）归各工具本体 TDD——本卡只管「工具的商业开关」，不管「工具的智能本体」。降级方向差异：entitlement 查询失败（DB 异常）时 checkEntitlement 返回 entitled=false + 显式 error 态（宁可拒绝服务不可误放行——AI 故障跳过增强、付费门控故障不放行）。

合规挂钩

前端改动面与 i18n

前端触点（逐端）

i18n 三语言 key 规划（en / zh-Hans / ja）

风险

前置决策点

• D-dec4 试用期时长 / 付费档位金额（minor unit）/ 试点工具选择——决策归属 DEC-4；机制层参数化承载，不内联数值。
• D-dec5 条款生效（法务复核）/ 消契法适用性结论 / 验收数值（试用→付费转化率目标等）——上线前置非设计前置；转化率指标名 tool_trial_conversion_rate（数据源：entitlement 状态迁移事件聚合）随实现纳入。
• X-tool-bodies 四类工具本体绑定排期未定——适配器层挂接随其立项；首个绑定工具 = AI-3.6-03（B 波）。
• tool_trial 枚举值 ledger entry_type 的 tool_trial（0 额试用 marker）是否产生分录——随联审定，若试用不产生分录则仅用 tool_subscription 值。

实施排期与验收

子任务 DAG 与估时（机制层）

验收标准

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

迁移与回滚

附录 · 溯源

本文档生成自 docs/reports/ai-module-prd/tdd/AI-3.2-04-tool-trial-and-paywall.md（TDD 深度分级 architectural；PRD V1.4）。章节映射与处理方式如下：