soul-yongping/开发文档/2、架构/变现模块设计.md

变现模块架构设计

1. 概述

本项目核心变现逻辑围绕“内容付费”、“私域导流”与“分销裂变”三大支柱展开。为保证系统的可扩展性与维护性，我们将这三部分功能进行模块化解耦。

2. 模块划分

2.1 支付模块 (Payment Module)

负责处理所有资金交易，支持多种支付渠道（微信支付、支付宝、Stripe等）的抽象对接。

核心接口定义 (lib/modules/payment/types.ts):

• Order: 订单数据结构，包含用户ID、金额、状态、商品项。
• PaymentProvider: 支付适配器接口，定义 createOrder 和 checkStatus 方法。

当前状态:

• 已定义基础类型接口。
• 下一步：实现 WeChatPayProvider 和 MockProvider（开发测试用）。

2.2 营销模块 (Marketing Module)

负责用户触达与转化工具的管理，如弹窗、Banner、倒计时优惠等。

核心接口定义 (lib/modules/marketing/types.ts):

• Campaign: 营销活动实体，包含触发规则 (CampaignRule) 和展示内容 (CampaignContent)。
• MarketingService: 服务接口，负责评估当前用户上下文 (UserContext) 并返回激活的活动。

应用场景:

• 阅读进度 > 30% 时触发“扫码解锁全文”弹窗。
• 首页展示限时优惠 Banner。

2.3 分销模块 (Referral Module)

负责用户裂变追踪与佣金计算，是“云阿米巴”模式的技术落地。

核心接口定义 (lib/modules/referral/types.ts):

• ReferralCode: 分销码定义。
• ReferralService: 服务接口，包含生成分销码、追踪访问 (trackVisit)、记录转化 (recordConversion)。

业务逻辑:

• 每个注册用户自动生成唯一邀请码。
• 分享链接携带 ?ref=CODE 参数。
• 转化成功后，系统异步计算佣金并记录。

3. 数据流向

1. 用户访问文章页面 -> MarketingService 检查是否触发营销规则。
2. 用户点击购买 -> PaymentModule 创建订单并调起支付。
3. 支付成功 -> PaymentModule 回调更新订单状态 -> 触发 ReferralService 结算佣金（如有推荐人）。

4. 目录结构

``` lib/ modules/ payment/ types.ts providers/ marketing/ types.ts hooks/ referral/ types.ts utils/ ```