sub2api/docs/PAYMENT_FRONTEND_MIGRATION_PLAN.md

支付系统前端迁移计划

将 sub2apipay (Next.js/React) 的支付功能原生集成到 sub2api (Vue3) 前端中

分支: feature/payment (基于 upstream Wei-Shaw/sub2api:main)

---

一、迁移概述

1.1 现状

当前 sub2api 通过 iframe 嵌入外部 URL 的方式提供充值/订阅功能：

• 管理员在 系统设置 → General tab 中配置 purchase_subscription_url
• 用户侧边栏出现"充值/订阅"菜单项（受 purchase_subscription_enabled 控制）
• 点击后在 PurchaseSubscriptionView.vue 中以 iframe 加载外部页面
• 外部页面（sub2apipay）通过 URL 参数接收 user_id, token, theme, lang

现有关键文件：

文件	作用
src/components/layout/AppSidebar.vue	侧边栏菜单定义（~700行）
src/views/user/PurchaseSubscriptionView.vue	iframe 嵌入页（~159行���
src/views/admin/SettingsView.vue	管理后台设置页（~2500行）
src/stores/app.ts	公共设置存储（含 purchase_subscription_enabled）
src/stores/adminSettings.ts	管理设置存储
src/router/index.ts	路由定义
src/i18n/locales/en.ts / zh.ts	国际化文本
src/utils/embedded-url.ts	iframe URL 构建工具

1.2 目标

将 sub2apipay 的所有前端功能原生实现为 Vue3 组件，集成到 sub2api 项目中：

• 消除 iframe — 所有支付、订单页面变为原生 Vue 组件
• 消除外部依赖 — 不再需要独立部署 sub2apipay
• 直接调用后端 API — 替代 HTTP 跨域调用
• 统一认证 — 复用 sub2api 的 JWT 认证，无需 URL 传 token
• 统一 UI — 使用 sub2api 现有的 TailwindCSS 设计系统和组件库

---

二、菜单结构变更

2.1 管理员侧边栏 (adminNavItems)

当前菜单（upstream main）：

仪表盘          /admin/dashboard
运维监控        /admin/ops           (ops_monitoring_enabled 控制)
用户管理        /admin/users
分组管理        /admin/groups
渠道管理        /admin/channels
订阅管理        /admin/subscriptions
账号管理        /admin/accounts
公告管理        /admin/announcements
代理管理        /admin/proxies
充值码管理      /admin/redeem
推广码管理      /admin/promo-codes
用量统计        /admin/usage
系统设置        /admin/settings
[自定义菜单]

迁移后菜单：

仪表盘          /admin/dashboard
运维监控        /admin/ops           (ops_monitoring_enabled 控制)
用户管理        /admin/users
分组管理        /admin/groups
渠道管理        /admin/channels
订阅管理        /admin/subscriptions
账号管理        /admin/accounts
公告管理        /admin/announcements
代理管理        /admin/proxies
充值码管理      /admin/redeem
推广码管理      /admin/promo-codes
+ 订单管理      /admin/orders         ← 新增（payment_enabled 控制可见性）
用量统计        /admin/usage
系统设置        /admin/settings
[自定义菜单]

新增"订单管理"菜单及子菜单：

"订单管理"作为一级菜单项，点击后页面内部提供 tab 导航：

子菜单	路由	说明
订单概览	/admin/orders	订单统计仪表盘（日收入、支付方式分布、排行榜）
订单列表	/admin/orders/list	订单搜索/筛选/详情/退款操作
渠道管理	/admin/orders/channels	支付渠道定义（展示名称、倍率、描述）
订阅套餐	/admin/orders/plans	订阅计划管理（价格、有效期、分组绑定）

可见性规则: 仅当系统设置中"充值/订阅功能"开启时，"订单管理"菜单才可见。

2.2 用户侧边栏 (userNavItems)

当前菜单：

仪表盘          /dashboard
API密钥         /keys
用量统计        /usage
我的订阅        /subscriptions
[Sora]          /sora                (sora_client_enabled 控制)
[充值/订阅]     /purchase            (purchase_subscription_enabled 控制, iframe)
兑换码          /redeem
个人设置        /profile
[自定义菜单]

迁移后菜单：

仪表盘          /dashboard
API密钥         /keys
用量统计        /usage
我的订阅        /subscriptions
[Sora]          /sora                (sora_client_enabled 控制)
- [充值/订阅]   /purchase            ← 替换: 不再是 iframe
+ 充值/订阅     /purchase            ← 原生 Vue 页面（payment_enabled 控制）
+ 我的订单      /orders              ← 新增（payment_enabled 控制）
兑换码          /redeem
个人设置        /profile
[自定义菜单]

变更要点：

1. /purchase 路由保持不变，但组件从 iframe 替换为原生 PaymentView.vue
2. 新增 /orders 路由 — "我的订单"页面
3. 菜单可见性条件从 purchase_subscription_enabled 变更为 payment_enabled
4. 移除 purchase_subscription_url 设置项

2.3 管理员"我的账户"区域 (personalNavItems)

与 userNavItems 保持一致的变更：增加"我的订单"，替换"充值/订阅"为原生页面。

---

三、系统设置变更

3.1 Settings Tab 变更

当前 tabs：

general | security | users | gateway | email | backup | data

迁移后 tabs：

general | security | users | gateway | payment | email | backup | data

新增 payment tab，在 gateway 之后、email 之前。

3.2 payment Tab 内容

此 tab 替代原 general tab 中的"充值/订阅页面"配置区块。

配置项设计：

┌─────────────────────────────────────────────────────────┐
│  充值/订阅功能                                            │
│  ─────────────────────────────────────                   │
│  启用充值/订阅        [Toggle]                            │
│  说明: 开启后用户可通过在线支付充值余额或购买订阅。           │
│        同时"订单管理"菜单将对管理员可见。                    │
│                                                          │
│  (以下配置仅在功能启用后显示)                               │
│                                                          │
│  ┌─ 基本设置 ──────────────────────────────────────────┐ │
│  │ 最低充值金额      [___] 元                           │ │
│  │ 最高充值金额      [___] 元                           │ │
│  │ 每日充值限额      [___] 元                           │ │
│  │ 最大待支付订单数  [___]                               │ │
│  │ 订单超时时间      [___] 分钟                          │ │
│  │ 禁用余额支付      [Toggle]                           │ │
│  └──────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌─ 支付服务商 ────────────────────────────────────────┐ │
│  │ 启用的支付方式    [☑ 支付宝] [☑ 微信支付] [☑ Stripe] │ │
│  │                                                      │ │
│  │ 服务商实例管理    [管理实例 →]                         │ │
│  │ (跳转到服务商实例配置子页面)                           │ │
│  └──────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌─ 显示设置 ──────────────────────────────────────────┐ │
│  │ 帮助图片 URL     [___]                               │ │
│  │ 帮助文字         [___]                               │ │
│  └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

3.3 从 general Tab 移除的内容

原 general tab 中的以下配置区块将移除：

• "Recharge / Subscription Page" 整个 card

3.4 旧版兼容：自定义页面迁移

对于已使用 purchase_subscription_url 配置外部支付页面的用户：

• 数据库迁移脚本检查 purchase_subscription_url 是否有值
• 若有值，自动创建一个"自定义菜单页面" (custom_menu_item)，保留原 URL
• 确保旧版用户升级后，原来的外部支付页面仍可通过自定义菜单访问
• purchase_subscription_enabled 和 purchase_subscription_url 设置项保留但标记 deprecated

---

四、路由变更

4.1 新增路由

路由	组件	权限	说明
/purchase	PaymentView.vue	requiresAuth	替换原 iframe 页面
/orders	UserOrdersView.vue	requiresAuth	用户订单列表
/admin/orders	AdminOrdersView.vue	requiresAdmin	订单概览（默认 tab）
/admin/orders/list	同上组件内 tab	requiresAdmin	订单列表
/admin/orders/channels	同上组件内 tab	requiresAdmin	渠道管理
/admin/orders/plans	同上组件内 tab	requiresAdmin	订阅套餐管理
/admin/orders/providers	AdminProvidersView.vue	requiresAdmin	服务商实例管理

4.2 路由 meta

所有支付相关路由需要 meta 字段：

meta: {
  requiresAuth: true,
  requiresPayment: true,  // 新增: 需要 payment_enabled
}

路由守卫检查：若 requiresPayment && !payment_enabled，重定向到 dashboard。

---

五、新增 Vue 组件清单

5.1 用户侧页面

5.1.1 PaymentView.vue — 充值/订阅主页面

替换: PurchaseSubscriptionView.vue（iframe）

来源: sub2apipay PaymentForm.tsx + PurchaseFlow.tsx + TopUpModal.tsx

功能:

• 金额输入（自定义 + 快捷按钮）
• 支付方式选择（动态展示）
• 手续费实时计算
• 余额支付开关
• 订阅套餐选购（卡片 + 确认弹窗）
• 创建订单后跳转支付流程

子组件: PaymentMethodSelector.vue, AmountInput.vue, FeeDisplay.vue, SubscriptionPlanCard.vue, SubscriptionConfirmModal.vue

API: GET /api/v1/payment/config, GET /api/v1/payment/plans, POST /api/v1/payment/orders

5.1.2 PaymentQRCodeView.vue — 二维码支付页

来源: sub2apipay PaymentQRCode.tsx

功能: 二维码显示、倒计时、轮询状态（3s）、支付成功自动跳转

子组件: QRCodeDisplay.vue, CountdownTimer.vue

API: GET /api/v1/payment/orders/:id

5.1.3 StripePaymentView.vue — Stripe 支付页

来源: sub2apipay stripe-popup/page.tsx

功能: Stripe Payment Element 集成，使用 clientSecret 完成支付

依赖: @stripe/stripe-js

5.1.4 PaymentResultView.vue — 支付结果页

功能: 成功/失败状态展示、订单摘要、跳转按钮

5.1.5 UserOrdersView.vue — 我的订单

来源: sub2apipay OrderTable.tsx + MobileOrderList.tsx + OrderFilterBar.tsx

功能: 订单列表（分页、状态筛选、日期范围）、取消/退款操作

子组件: OrderStatusBadge.vue, OrderFilterBar.vue

API: GET /api/v1/payment/orders/my, POST .../cancel, POST .../refund-request

5.2 管理员侧页面

5.2.1 AdminOrdersView.vue — 订单管理（tab 容器）

页面内 tab 导航：订单概览 | 订单列表 | 渠道管理 | 订阅套餐

订单概览 tab:

• 统计卡片（今日/总收入、订单数、均价）
• 每日收入趋势图（Chart.js）
• 支付方式分布饼图
• 充值排行榜

子组件: OrderStatsCards.vue, DailyRevenueChart.vue, PaymentMethodChart.vue, TopUsersLeaderboard.vue

API: GET /api/v1/admin/payment/dashboard

5.2.2 订单列表 tab

来源: sub2apipay admin/orders/page.tsx + admin/OrderTable.tsx + admin/OrderDetail.tsx + admin/RefundDialog.tsx

功能: 全量订单搜索/筛选、详情面板、管理操作（取消/重试/退款）

子组件: AdminOrderTable.vue, AdminOrderDetail.vue, AdminRefundDialog.vue, AdminOrderSearchBar.vue

API: GET/POST .../admin/payment/orders, .../cancel, .../retry, .../refund

5.2.3 渠道管理 tab

来源: sub2apipay admin/channels/page.tsx + ChannelCard.tsx

功能: 渠道 CRUD（名称、关联 Group、费率、描述、启/禁用）

API: GET/POST/PUT/DELETE /api/v1/admin/payment/channels

5.2.4 订阅套餐 tab

来源: sub2apipay admin/subscriptions/page.tsx

功能: 套餐 CRUD（名称、价格、有效期、分组绑定、上架状态）

API: GET/POST/PUT/DELETE /api/v1/admin/payment/plans

5.2.5 AdminProvidersView.vue — 服务商实例管理

来源: sub2apipay admin/payment-config/page.tsx（1479 行，最大单组件）

功能: 服务商实例 CRUD，动态配置表单（EasyPay/Alipay/Wxpay/Stripe），限额配置，退款开关

路由: /admin/orders/providers（从系统设置 payment tab "管理实例"按钮跳转）

子组件: ProviderInstanceForm.vue, ProviderInstanceCard.vue

API: GET/POST/PUT/DELETE /api/v1/admin/payment/providers

5.3 共享组件

组件	用途
PaymentMethodSelector.vue	支付方式选择
AmountInput.vue	金额输入（含快捷按钮）
FeeDisplay.vue	手续费展示
QRCodeDisplay.vue	二维码渲染
CountdownTimer.vue	倒计时
OrderStatusBadge.vue	订单状态标签
OrderFilterBar.vue	订单筛选栏
SubscriptionPlanCard.vue	套餐卡片
SubscriptionConfirmModal.vue	套餐确认弹窗

---

六、Store 变更

6.1 appStore 变更

publicSettings 字段变更:

// deprecated:
purchase_subscription_enabled: boolean
purchase_subscription_url: string

// 新增:
payment_enabled: boolean  // 充值/订阅功能总开关

6.2 新增 paymentStore

// src/stores/payment.ts
defineStore('payment', () => {
  const config = ref<PaymentConfig | null>(null)
  const currentOrder = ref<Order | null>(null)
  const plans = ref<SubscriptionPlan[]>([])
  
  async function fetchConfig(): Promise<PaymentConfig>
  async function fetchPlans(): Promise<SubscriptionPlan[]>
  async function createOrder(params): Promise<Order>
  async function pollOrderStatus(orderId: string): Promise<OrderStatus>
})

6.3 adminSettingsStore 变更

新增: paymentEnabled — 控制管理侧"订单管理"菜单可见性。

---

七、API 模块新增

7.1 用户 API (src/api/payment.ts)

export const paymentAPI = {
  getConfig(): Promise<PaymentConfig>
  getPlans(): Promise<SubscriptionPlan[]>
  createOrder(params): Promise<CreateOrderResult>
  getOrder(orderId): Promise<Order>
  getMyOrders(params): Promise<PaginatedResult<Order>>
  cancelOrder(orderId): Promise<void>
  requestRefund(orderId, reason): Promise<void>
  getLimits(): Promise<MethodLimits>
}

7.2 管理 API (src/api/admin/payment.ts)

export const adminPaymentAPI = {
  // 仪表盘
  getDashboard(days?): Promise<DashboardStats>
  // 订单
  getOrders(params): Promise<PaginatedResult<Order>>
  getOrder(orderId): Promise<OrderDetail>
  cancelOrder(orderId): Promise<void>
  retryRecharge(orderId): Promise<void>
  refundOrder(orderId, params): Promise<RefundResult>
  // 渠道
  getChannels(): Promise<Channel[]>
  createChannel(data): Promise<Channel>
  updateChannel(id, data): Promise<Channel>
  deleteChannel(id): Promise<void>
  // 订阅套餐
  getPlans(): Promise<SubscriptionPlan[]>
  createPlan(data): Promise<SubscriptionPlan>
  updatePlan(id, data): Promise<SubscriptionPlan>
  deletePlan(id): Promise<void>
  // 服务商实例
  getProviders(): Promise<ProviderInstance[]>
  createProvider(data): Promise<ProviderInstance>
  updateProvider(id, data): Promise<ProviderInstance>
  deleteProvider(id): Promise<void>
}

---

八、i18n 变更

8.1 新增 payment 命名空间

payment: {
  // 充值页面
  title: '充值/订阅',  // 'Recharge / Subscription'
  amountLabel: '充值金额',
  quickAmounts: '快捷金额',
  customAmount: '自定义金额',
  paymentMethod: '支付方式',
  fee: '手续费',
  actualPay: '实付金额',
  createOrder: '确认支付',
  
  methods: {
    alipay: '支付宝',
    wxpay: '微信支付',
    stripe: 'Stripe',
    alipay_direct: '支付宝（直连）',
    wxpay_direct: '微信支付（直连）',
  },
  
  status: {
    pending: '待支付',
    paid: '已支付',
    recharging: '充值中',
    completed: '已完成',
    expired: '已过期',
    cancelled: '已取消',
    failed: '失败',
    refund_requested: '退款申请中',
    refunding: '退款中',
    refunded: '已退款',
    partially_refunded: '部分退款',
    refund_failed: '退款失败',
  },
  
  qr: {
    scanToPay: '请扫码支付',
    expiresIn: '剩余支付时间',
    expired: '订单已过期',
  },
  
  orders: {
    title: '我的订单',
    empty: '暂无订单',
    orderId: '订单号',
    amount: '金额',
    payAmount: '实付',
    status: '状态',
    paymentMethod: '支付方式',
    createdAt: '创建时间',
    cancel: '取消订单',
    requestRefund: '申请退款',
  },
  
  result: {
    success: '支付成功',
    failed: '支付失败',
    backToRecharge: '返回充值',
    viewOrders: '查看订单',
  },
}

8.2 修改的 i18n 键

nav: {
  myOrders: '我的订单',           // 'My Orders'
  orderManagement: '订单管理',     // 'Order Management'
}

admin.settings.tabs: {
  payment: '充值/订阅',            // 'Recharge / Subscription'
}

admin.settings.payment: {
  title: '充值/订阅功能',
  description: '配置在线支付充值和订阅购买功能',
  enabled: '启用充值/订阅',
  enabledHint: '开启后用户可通过在线支付充值余额或购买订阅',
  minAmount: '最低充值金额',
  maxAmount: '最高充值金额',
  dailyLimit: '每日充值限额',
  maxPendingOrders: '最大待支付订单数',
  orderTimeout: '订单超时时间（分钟）',
  balancePaymentDisabled: '禁用余额支付',
  enabledPaymentTypes: '启用的支付方式',
  manageProviders: '管理服务商实例',
  helpImageUrl: '帮助图片 URL',
  helpText: '帮助文字',
}

8.3 Deprecated i18n 键

保留但不再使用：admin.settings.purchase.*, purchase.*

---

九、文件变更清单

9.1 修改的现有文件

文件	变更
src/components/layout/AppSidebar.vue	新增菜单项，条件改为 payment_enabled
src/router/index.ts	新增路由，修改 /purchase 组件
src/views/admin/SettingsView.vue	新增 payment tab，移除旧 purchase 配置
src/stores/app.ts	publicSettings 新增 payment_enabled
src/stores/adminSettings.ts	新增 paymentEnabled
src/stores/index.ts	导出新 store
src/i18n/locales/en.ts	新增 payment 命名空间
src/i18n/locales/zh.ts	新增 payment 命名空间
src/api/index.ts	导出新 API 模块
src/types/index.ts	新增 payment 类型

9.2 新增文件

视图 (10 个):

• src/views/user/PaymentView.vue
• src/views/user/PaymentQRCodeView.vue
• src/views/user/StripePaymentView.vue
• src/views/user/PaymentResultView.vue
• src/views/user/UserOrdersView.vue
• src/views/admin/orders/AdminOrdersView.vue
• src/views/admin/orders/AdminOrderListView.vue
• src/views/admin/orders/AdminOrderChannelsView.vue
• src/views/admin/orders/AdminOrderPlansView.vue
• src/views/admin/orders/AdminProvidersView.vue

组件 (19 个):

• src/components/payment/PaymentMethodSelector.vue
• src/components/payment/AmountInput.vue
• src/components/payment/FeeDisplay.vue
• src/components/payment/QRCodeDisplay.vue
• src/components/payment/CountdownTimer.vue
• src/components/payment/OrderStatusBadge.vue
• src/components/payment/OrderFilterBar.vue
• src/components/payment/SubscriptionPlanCard.vue
• src/components/payment/SubscriptionConfirmModal.vue
• src/components/admin/payment/OrderStatsCards.vue
• src/components/admin/payment/DailyRevenueChart.vue
• src/components/admin/payment/PaymentMethodChart.vue
• src/components/admin/payment/TopUsersLeaderboard.vue
• src/components/admin/payment/AdminOrderTable.vue
• src/components/admin/payment/AdminOrderDetail.vue
• src/components/admin/payment/AdminRefundDialog.vue
• src/components/admin/payment/AdminOrderSearchBar.vue
• src/components/admin/payment/ProviderInstanceForm.vue
• src/components/admin/payment/ProviderInstanceCard.vue

API / Store / Types (4 个):

• src/api/payment.ts
• src/api/admin/payment.ts
• src/stores/payment.ts
• src/types/payment.ts

9.3 删除的文件

文件	说明
src/views/user/PurchaseSubscriptionView.vue	替换为 PaymentView.vue
src/utils/embedded-url.ts	不再需要 iframe URL 构建

9.4 新增依赖

包	用途
@stripe/stripe-js	Stripe Payment Element
qrcode	二维码渲染（已有此依赖）

---

十、后端 Setting 表新增键（前端消费）

Key	类型	默认值	说明
payment_enabled	bool	false	总开关
payment_min_amount	number	1	最低充值额
payment_max_amount	number	10000	最高充值额
payment_daily_limit	number	50000	日限额
payment_max_pending_orders	number	3	最大待支付数
payment_order_timeout_minutes	number	30	订单超时
payment_balance_disabled	bool	false	禁用余额支付
payment_enabled_types	string	""	支付方式（逗号分隔）
payment_help_image_url	string	""	帮助图片
payment_help_text	string	""	帮助文字

---

十一、实施顺序

Phase 1: 基础设施

1. TypeScript 类型定义 (types/payment.ts)
2. API 模块 (api/payment.ts, api/admin/payment.ts)
3. Store (stores/payment.ts)
4. 修改 stores/app.ts + stores/adminSettings.ts
5. 修改 router/index.ts — 新增路由
6. 修改 AppSidebar.vue — 新增菜单项
7. 新增 i18n 文本

Phase 2: 用户侧页面

1. PaymentView.vue + 子组件
2. PaymentQRCodeView.vue + QR 组件
3. StripePaymentView.vue
4. PaymentResultView.vue
5. UserOrdersView.vue + 订单组件

Phase 3: 管理侧页面

1. AdminOrdersView.vue（tab 容器 + 订单概览）
2. 订单列表 tab + 表格/详情/退款
3. 渠道管理 tab
4. 订阅套餐 tab
5. AdminProvidersView.vue（最复杂）

Phase 4: 系统设置集成

1. SettingsView.vue — 新增 payment tab
2. 移除 general tab 旧 purchase 配置
3. 旧版兼容迁移逻辑

---

附录 A: sub2apipay → sub2api 组件映射

sub2apipay (React)	行数	sub2api (Vue3)	说明
PaymentForm.tsx	~400	PaymentView.vue + 子组件	拆分为细粒度组件
PaymentQRCode.tsx	~300	PaymentQRCodeView.vue
PurchaseFlow.tsx	~350	融入 PaymentView.vue
SubscriptionConfirm.tsx	~200	SubscriptionConfirmModal.vue
SubscriptionPlanCard.tsx	~150	SubscriptionPlanCard.vue
TopUpModal.tsx	~300	融入 PaymentView.vue
OrderTable.tsx	~250	复用 sub2api DataTable
MobileOrderList.tsx	~200	响应式设计融入 View
OrderFilterBar.tsx	~150	OrderFilterBar.vue
OrderStatus.tsx	~100	OrderStatusBadge.vue
admin/DashboardStats.tsx	~150	OrderStatsCards.vue
admin/DailyChart.tsx	~200	DailyRevenueChart.vue
admin/PaymentMethodChart.tsx	~150	PaymentMethodChart.vue
admin/Leaderboard.tsx	~150	TopUsersLeaderboard.vue
admin/OrderTable.tsx	~300	AdminOrderTable.vue
admin/OrderDetail.tsx	~250	AdminOrderDetail.vue
admin/RefundDialog.tsx	~200	AdminRefundDialog.vue
admin/payment-config (page.tsx)	~1479	拆分为 View + Form + Card

附录 B: 关键设计决策

B.1 为什么不保留 iframe

维度	iframe	原生集成
用户体验	两套 UI，主题同步延迟	统一 UI
认证	URL 传 token，泄露风险	JWT 自动携带
部署	需独立部署 + 域名	单一部署
维护	两个项目两套技术栈	一个项目
性能	iframe 加载开销	无额外开销
CSP	X-Frame-Options 兼容问题	无此问题

B.2 "订单管理"作为一级菜单

• 订单是高频管理操作，需快速访问
• 包含 4 个子功能，信息密度高
• 遵循 sub2api 现有模式：业务操作独立菜单

B.3 payment_enabled 总开关

• 所有支付菜单和路由受此开关控制
• 关闭时：侧边栏不显示、路由守卫重定向、后端 API 同步校验
• 零配置时不影响不使用支付功能的用户