@seaverse/payment-sdk 0.8.1 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 SeaVerse Payment SDK - 一站式支付解决方案，提供积分管理、支付弹窗、订阅管理和订单跟踪功能。
 
-> **最新版本**: v0.8.1 | **文档语言**: 中文优先（包含英文说明）
+> **最新版本**: v0.8.2 | **文档语言**: 中文优先（包含英文说明）
 
 ## 📦 安装
 
@@ -95,6 +95,46 @@ const modal = new GenericPackageModal({
 modal.open();
 ```
 
+## 🏗️ 架构设计
+
+### 代码重构 (v0.8.1)
+
+为了提高代码可维护性和消除重复逻辑，SDK 进行了架构重构：
+
+**核心改进**：
+- ✅ **抽象基类设计** - 创建 `BasePackageModal<TPackage, TOptions>` 抽象基类
+- ✅ **消除重复代码** - 减少 ~400 行重复代码（SDK 初始化、支付流程、事件处理）
+- ✅ **类型安全** - 使用 TypeScript 泛型确保类型安全
+- ✅ **向后兼容** - 公开 API 完全不变，现有代码无需修改
+
+**类继承结构**：
+
+```
+BasePackageModal<TPackage, TOptions>  (抽象基类)
+├── CreditPackageModal                 (积分套餐弹框)
+└── GenericPackageModal                (通用套餐弹框)
+```
+
+**BasePackageModal 提供的共享功能**：
+- SDK 初始化和状态管理
+- 支付流程处理（订单创建、支付弹框）
+- 事件监听和按钮处理
+- 工具方法（formatNumber、cleanup 等）
+
+**子类只需实现**：
+- `createModal()` - 创建和配置 PaymentModal
+- `renderContent()` - 渲染弹框内容（UI 特定逻辑）
+- `getPackages()` - 获取套餐列表
+- `getPackageDisplayName()` - 获取套餐显示名称
+- `getLoadingButtonHTML()` - 获取加载按钮 HTML
+
+这种设计确保：
+- **单一职责** - 基类负责逻辑，子类负责 UI
+- **DRY 原则** - 共享逻辑只需维护一处
+- **易于扩展** - 添加新套餐类型只需继承基类
+
+---
+
 ## 📖 核心功能模块
 
 ### ⭐️ 推荐功能（新用户优先使用）
@@ -179,6 +219,164 @@ SDK 内置以下积分套餐：
 | Pro     | 520  | $1.99 | 专业套餐 |
 | Ultra   | 1200 | $4.99 | 旗舰套餐 |
 
+---
+
+### PaymentCheckoutModal - 完整收银台流程
+
+**适用场景**：
+- ✅ 需要完整的支付收银台体验（支付方式选择 + 订单信息展示）
+- ✅ 自动创建订单并完成支付
+- ✅ 支持三种支付方式：Link Payment、Dropin Payment、BindCard Payment
+- ✅ 适合需要更多控制和自定义的场景
+
+#### 基础用法
+
+```typescript
+import { PaymentCheckoutModal, type Product, type AutoCreateOrderConfig } from '@seaverse/payment-sdk';
+
+// 定义产品信息
+const product: Product = {
+  id: 'pkg_credit_100',
+  name: '100 Credits Package',
+  price: 9.99,
+  currency: 'USD',
+  type: 'credit_package',  // 'credit_package' | 'subscription' | 'change_subscription'
+};
+
+// 创建收银台 modal
+const modal = new PaymentCheckoutModal({
+  // 产品信息
+  product: product,
+
+  // 自动创建订单配置
+  autoCreateOrder: {
+    productId: product.id,
+    purchaseType: 1,              // 1=一次性购买, 2=订阅
+    apiHost: 'https://api.example.com',
+    accountToken: 'user-token',
+    clientId: 'your-client-id',
+    countryCode: 'SG',
+  },
+
+  // 可选配置
+  accountName: 'John Doe',        // 显示在订单信息中
+  language: 'en',                 // 'en' | 'zh-CN'
+
+  // 回调函数
+  onPaymentSuccess: (payload) => {
+    console.log('支付成功！', payload);
+    // payload 包含: orderId, transactionId, 等信息
+  },
+
+  onPaymentFailed: (error) => {
+    console.error('支付失败：', error.message);
+  },
+
+  onPaymentMethodSelect: (method) => {
+    console.log('选择支付方式：', method.name);
+  },
+
+  onLinkPaymentStart: (methodName) => {
+    console.log('Link 支付开始：', methodName);
+    // 可以在这里显示 "请在新窗口完成支付" 提示
+  },
+
+  onLoading: (loading) => {
+    console.log('加载状态：', loading);
+  },
+});
+
+// 打开收银台
+modal.open();
+```
+
+#### 三种初始化模式
+
+PaymentCheckoutModal 支持三种初始化模式（三选一）：
+
+**模式 1: autoCreateOrder（推荐）**
+```typescript
+const modal = new PaymentCheckoutModal({
+  product: { id: 'pkg_1', name: 'Product', price: 9.99, currency: 'USD', type: 'credit_package' },
+  autoCreateOrder: {
+    productId: 'pkg_1',
+    purchaseType: 1,
+    apiHost: 'https://api.example.com',
+    accountToken: 'token',
+    clientId: 'client-id',
+    countryCode: 'SG',
+  },
+  onPaymentSuccess: (payload) => { /* ... */ },
+});
+```
+
+**模式 2: payment（提前创建 OrderPayment 实例）**
+```typescript
+import { OrderPayment } from '@seaverse/payment-sdk';
+
+const payment = new OrderPayment({
+  transactionId: 'txn_123',
+  apiHost: 'https://api.example.com',
+  accountToken: 'token',
+});
+
+const modal = new PaymentCheckoutModal({
+  product: { /* ... */ },
+  payment: payment,
+  paymentMethods: [...],  // 需要手动提供支付方式列表
+  onPaymentSuccess: (payload) => { /* ... */ },
+});
+```
+
+**模式 3: transactionId（延迟初始化）**
+```typescript
+const modal = new PaymentCheckoutModal({
+  product: { /* ... */ },
+  transactionId: 'txn_123',
+  paymentMethods: [...],  // 需要手动提供支付方式列表
+  onPaymentSuccess: (payload) => { /* ... */ },
+});
+```
+
+#### 配置选项说明
+
+| 选项 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `product` | `Product` | 否 | 产品信息（id, name, price, currency, type） |
+| `autoCreateOrder` | `AutoCreateOrderConfig` | 三选一 | 自动创建订单配置（推荐） |
+| `payment` | `OrderPayment` | 三选一 | 提前创建的 OrderPayment 实例 |
+| `transactionId` | `string` | 三选一 | 订单 transaction_id（延迟初始化） |
+| `paymentMethods` | `PaymentMethod[]` | 否 | 支付方式列表（autoCreateOrder 模式会自动获取） |
+| `accountName` | `string` | 否 | 用户账号名称（显示在订单信息中） |
+| `language` | `'en' \| 'zh-CN'` | 否 | 语言设置（默认 'en'） |
+| `onPaymentSuccess` | `(payload) => void` | 否 | 支付成功回调 |
+| `onPaymentFailed` | `(error) => void` | 否 | 支付失败回调 |
+| `onPaymentMethodSelect` | `(method) => void` | 否 | 选择支付方式回调 |
+| `onLinkPaymentStart` | `(methodName) => void` | 否 | Link 支付开始回调 |
+| `onLoading` | `(loading) => void` | 否 | 加载状态回调 |
+
+#### 产品类型说明
+
+| 类型 | 值 | 说明 |
+|------|------|------|
+| 信用包 | `'credit_package'` | 一次性购买积分包 |
+| 订阅 | `'subscription'` | 新订阅购买 |
+| 变更订阅 | `'change_subscription'` | 订阅升级/降级 |
+
+#### 支付方式说明
+
+PaymentCheckoutModal 支持三种支付方式：
+
+1. **Link Payment**: 跳转到外部支付页面，自动轮询订单状态
+2. **Dropin Payment**: 嵌入式支付表单，支持信用卡、PayPal 等
+3. **BindCard Payment**: 使用已保存的卡片支付（显示卡片列表）
+
+#### 完整示例
+
+查看完整示例代码：`examples/payment-sdk-demo/src/components/new-sdk/PaymentCheckoutSection.tsx`
+
+---
+
 #### 环境配置
 
 SDK 根据 `environment` 自动配置以下参数：
@@ -1002,5 +1200,27 @@ MIT License
 
 ---
 
-**更新日期**: 2026-01-31
-**SDK 版本**: v0.8.0
+**更新日期**: 2026-02-02
+**SDK 版本**: v0.8.2
+
+## 📝 更新日志
+
+### v0.8.2 (2026-02-02)
+
+**架构重构**：
+- 🏗️ 创建 `BasePackageModal` 抽象基类，消除 `CreditPackageModal` 和 `GenericPackageModal` 之间的重复代码
+- 📉 减少约 400 行重复代码（25% 代码量减少）
+- 🎯 `CreditPackageModal`: 从 1042 行减少到 515 行
+- 🎯 `GenericPackageModal`: 从 752 行减少到 340 行
+- ✅ 完全向后兼容，现有代码无需修改
+- 🔒 通过 TypeScript 泛型确保类型安全
+
+**类型系统改进**：
+- 新增 `BasePackage` 接口 - 所有套餐类型的基础接口
+- 新增 `BasePackageModalOptions<TPackage>` 接口 - 通用配置接口
+- `CreditPackage` 和 `GenericPackage` 现在继承自 `BasePackage`
+
+**开发体验提升**：
+- 更容易添加新的套餐类型（只需继承 `BasePackageModal`）
+- 修复 bug 只需在基类中修改一处
+- 更清晰的职责分离（基类处理逻辑，子类处理 UI）