diff --git a/PAYMENT_DESIGN.md b/PAYMENT_DESIGN.md index ff8ece4..fc9494f 100644 --- a/PAYMENT_DESIGN.md +++ b/PAYMENT_DESIGN.md @@ -32,12 +32,16 @@ ## 3. 渠道决策(用户拍板,技术侧全兼容) -| 渠道 | 前提 | 形态 | 备注 | +**已拍板(2026-07-17):真渠道用微信支付 Native(P5.2)。** 需企业主体 + 微信商户号 +(mchid + APIv3 密钥 + 商户证书);形态 = 下单得 code_url → Web 面渲染二维码 → +用户扫码付 → 回调(APIv3 签名验签 + AES-GCM 解密)。SDK 用官方 +`github.com/wechatpay-apiv3/wechatpay-go`。其余渠道留 adapter 位,不做。 + +| 渠道 | 前提 | 形态 | 状态 | |---|---|---|---| -| **兑换码/人工核销**(P5.1 内置) | 无 | admin 生成码 → 用户在 Web 面输码入账 | 零资质立即可用;也是线下打款的核销通道 | -| 支付宝(当面付/电脑网站支付) | 企业主体 + 签约 | 二维码/跳转 | 国内首选,个体户也可签当面付 | -| 微信支付(Native) | 企业主体 + 商户号 | 二维码 | 与支付宝同形态,adapter 并列 | -| Stripe Checkout | 海外主体 | 跳转托管页 | 出海再接;回调形态同构(webhook+签名) | +| **兑换码/人工核销**(P5.1 内置) | 无 | admin 生成码 → 用户在 Web 面输码入账 | 先做,零资质跑通闭环 | +| **微信支付 Native**(P5.2) | 企业主体 + 商户号 | 二维码(code_url) | ✅ 已拍板 | +| 支付宝 / Stripe | — | — | 不做,留 adapter 位 | Adapter 接口(`internal/payment/channel.go`): ```go @@ -52,6 +56,20 @@ type Channel interface { } ``` +## 3b. 两层汇率,各管各的(用户 2026-07-17 强调:积分↔token 必须可动态调) + +``` +人民币 ──(第一层: 积分包定价 price_fen→credits_micro, admin 配包/上下架)──> 积分 +积分 ──(第二层: tokens_per_credit, admin 计费页动态调, DB 热生效 ✅已存在)──> token +``` + +- **第二层是现成的**:`SettingTokensPerCredit`(DB 优先→env→1000),admin「计费 & 用量」 + 页可改,对后续任务实时生效(P2 期 live 验证过:改 500 → 新任务 credits=tok/500)。 + 支付不碰它。 +- **第一层是本期新增**:`sundynix_credit_pack` 表,admin 可改价/加量/上下架。 +- 解耦收益:促销只动包;模型成本变了要调积分购买力只动汇率;互不牵连。 + 订单锁定的是**下单当时**的包价与积分数(写死在订单行),之后改包不影响已付订单。 + ## 4. 数据模型(新增两件) ``` @@ -96,7 +114,9 @@ Web面账单页 → GET /billing/packs → 选包 → POST /billing/orders {pack 两张表 + ledger 唯一索引 + Channel 接口 + redeem adapter + `/billing/*` 路由 (下单≥billing_admin? 不——**充值谁都该能充,挂 ≥member**;viewer 只读仍拦)+ Web 面账单页真充值 UI + admin 生成兑换码。 -- **P5.2 首个真渠道**(等拍板,推荐支付宝当面付):adapter + 回调路由 + 轮询查单。 +- **P5.2 微信支付 Native(已拍板)**:wechatpay-go adapter(Native 下单 code_url → + Web 面二维码)+ APIv3 回调验签解密 + 轮询查单。商户号/证书经 env 注入, + 未配置时渠道自动隐藏(只剩兑换码),别让半配置状态把下单路由搞出 5xx。 - **P5.3 对账与观测**:admin「支付订单」流 + 日终对账 + 掉单补偿定时器。 - **P5.4 按需**:退款流程化、发票、微信/Stripe 并列。