feat(pay): 卡密兑换入口收敛到三个购买弹窗并对齐参考主题

- 移除余额卡片独立「卡密兑换」通用弹窗，兑换入口分布到充值/积分/会员三个弹窗的支付方式中 - 充值弹窗补齐卡密 logo 与仅卡密时的金额选择隐藏逻辑 - 积分购买弹窗 1:1 复刻参考主题 points-pay modal（商品档位/自定义/支付方式/立即支付），REST 改为 product+custom 契约 - 会员弹窗注入卡密渠道：视图模型透传 card_pass，前端渲染卡密盒并直兑 /pay/card-pass/redeem type=vip - 后台卡密兑换拆分为余额/积分/会员三个独立开关，VIP 段旧会员卡密组清理 - REST type 改为必填（balance/vip/credits），三类型独立闸门 - 测试重写为 card-pass-modal-redeem 契约，321 项全部通过
2026-09-18 12:25:18 +08:00
parent 74e43aaa76
commit b88eab0bfe
18 changed files with 746 additions and 472 deletions
@@ -155,9 +155,15 @@ class SchemaPayment {
 							['key' => 'pay_balance_product_custom_limit', 'label' => '自定义充值金额上限', 'type' => 'number', 'default' => 9999, 'min' => 1, 'max' => 99999, 'dependsOn' => ['key' => 'pay_balance_product_custom_s', 'value' => true]],
 						]],
 						['key' => 'pass-charge', 'title' => '卡密兑换', 'fields' => [
-							['key' => 'pay_balance_pass_charge_s', 'label' => '启用卡密兑换功能', 'type' => 'switch', 'default' => false, 'help' => '开启后用户中心余额卡片展示通用「卡密兑换」入口，支持余额 / 会员 / 积分卡密，类型按卡密自动识别'],
-							['key' => 'pay_balance_pass_charge_desc', 'label' => '卡密兑换说明', 'type' => 'textarea', 'default' => '', 'rows' => 2, 'dependsOn' => ['key' => 'pay_balance_pass_charge_s', 'value' => true], 'help' => '用户使用卡密兑换时显示的内容，建议为提醒事项、兑换协议等，支持HTML代码'],
-							['key' => 'pay_balance_pass_charge_only_password', 'label' => '单密码模式', 'type' => 'switch', 'default' => false, 'dependsOn' => ['key' => 'pay_balance_pass_charge_s', 'value' => true], 'help' => '余额卡密仅需输入密码，不需要卡号'],
+							['key' => 'pay_balance_pass_charge_s', 'label' => '启用卡密兑换余额功能', 'type' => 'switch', 'default' => false, 'help' => '开启后用户可在余额充值弹窗选择「卡密」渠道，使用卡密直接兑换余额'],
+							['key' => 'pay_balance_pass_charge_desc', 'label' => '卡密兑换余额说明', 'type' => 'textarea', 'default' => '', 'rows' => 2, 'dependsOn' => ['key' => 'pay_balance_pass_charge_s', 'value' => true], 'help' => '用户使用卡密兑换余额时显示的内容，建议为提醒事项、兑换协议等，支持HTML代码'],
+							['key' => 'pay_balance_pass_charge_only_password', 'label' => '余额卡密单密码模式', 'type' => 'switch', 'default' => false, 'dependsOn' => ['key' => 'pay_balance_pass_charge_s', 'value' => true], 'help' => '余额卡密仅需输入密码，不需要卡号'],
+							['key' => 'points_pass_exchange_s', 'label' => '启用卡密兑换积分功能', 'type' => 'switch', 'default' => false, 'help' => '开启后用户可在购买积分弹窗选择「卡密」渠道，使用卡密直接兑换积分'],
+							['key' => 'points_pass_exchange_desc', 'label' => '卡密兑换积分说明', 'type' => 'textarea', 'default' => '', 'rows' => 2, 'dependsOn' => ['key' => 'points_pass_exchange_s', 'value' => true], 'help' => '用户使用卡密兑换积分时显示的内容，建议为提醒事项、兑换协议等，支持HTML代码'],
+							['key' => 'points_pass_exchange_only_password', 'label' => '积分卡密单密码模式', 'type' => 'switch', 'default' => false, 'dependsOn' => ['key' => 'points_pass_exchange_s', 'value' => true], 'help' => '积分卡密仅需输入密码，不需要卡号'],
+							['key' => 'pay_vip_pass_charge_s', 'label' => '启用卡密兑换会员功能', 'type' => 'switch', 'default' => false, 'help' => '开启后用户可在会员购买/续费弹窗选择「卡密」渠道，使用会员卡密直接兑换会员'],
+							['key' => 'pay_vip_pass_charge_desc', 'label' => '卡密兑换会员说明', 'type' => 'textarea', 'default' => '', 'rows' => 2, 'dependsOn' => ['key' => 'pay_vip_pass_charge_s', 'value' => true], 'help' => '用户使用卡密兑换会员时显示的内容，建议为提醒事项、兑换协议等，支持HTML代码'],
+							['key' => 'pay_vip_pass_charge_only_password', 'label' => '会员卡密单密码模式', 'type' => 'switch', 'default' => true, 'dependsOn' => ['key' => 'pay_vip_pass_charge_s', 'value' => true], 'help' => '会员卡密仅需输入密码，不需要卡号'],
 						]],
 						['key' => 'points-exchange', 'title' => '余额兑换积分', 'fields' => [
 							['key' => 'pay_balance_points_exchange_s', 'label' => '启用余额兑换积分', 'type' => 'switch', 'default' => false, 'dependsOn' => ['key' => 'pay_balance_s', 'value' => true]],
@@ -241,9 +247,6 @@ class SchemaPayment {
 								]],
 							]],
 						]],
-						['key' => 'pass-charge', 'title' => '会员卡密', 'fields' => [
-							['key' => 'pay_vip_pass_charge_only_password', 'label' => '单密码模式', 'type' => 'switch', 'default' => true, 'help' => '会员卡密核销是否仅需卡密；关闭后，带卡号的会员卡必须同时输入卡号。会员/积分卡密无独立开关，统一受「余额充值 → 卡密兑换 → 启用卡密兑换功能」控制'],
-						]],
 						['key' => 'points-exchange', 'title' => '积分兑换会员', 'fields' => [
 							['key' => 'pay_vip_points_exchange_s', 'label' => '启用积分兑换', 'type' => 'switch', 'default' => false],
 							['key' => 'payment_vip_points_packages', 'label' => '兑换套餐', 'type' => 'textarea', 'default' => "1|500|30|积分月卡\n1|5000|0|积分永久", 'dependsOn' => ['key' => 'pay_vip_points_exchange_s', 'value' => true], 'help' => '每行：等级|积分|天数|标题（天数 0=永久；普通用户可开通，已有会员可续费同等级或升级更高等级）'],
@@ -64,6 +64,9 @@ trait VipServiceModal {
        }
        $points_exchange = is_array($catalog['points_exchange'] ?? null) ? $catalog['points_exchange'] : [];
        $methods = is_array($catalog['payment_methods'] ?? null) ? $catalog['payment_methods'] : [];
+        $card_pass = is_array($catalog['card_pass'] ?? null)
+            ? array_merge(['enabled' => false, 'desc' => '', 'only_password' => false], $catalog['card_pass'])
+            : ['enabled' => false, 'desc' => '', 'only_password' => false];
        $no_payment_method = $methods === [];
        $action_reasons = [
            'purchase' => $no_payment_method
@@ -124,6 +127,7 @@ trait VipServiceModal {
            ],
            'levels' => $level_view,
            'payment_methods' => $methods,
+            'card_pass' => $card_pass,
            'allowed_actions' => [
                'purchase' => $package_ids !== [] && $methods !== [],
                'renew' => $has_renew && $methods !== [],
@@ -517,30 +517,52 @@ trait VipServicePackages {
     * @return array<int, array{id:string,name:string}>
     */
    private function available_payment_methods(): array {
-        if (function_exists('aksrt_list_cash_payment_methods')) {
-            return aksrt_list_cash_payment_methods(true);
-        }
        $methods = [];
-        if (!class_exists('\AKSRT\Payment\Gateway')) {
-            return $methods;
+        if (function_exists('aksrt_list_cash_payment_methods')) {
+            $methods = aksrt_list_cash_payment_methods(true);
+        } else {
+            if (!class_exists('\AKSRT\Payment\Gateway')) {
+                return [];
+            }
+            $gw = \AKSRT\Payment\Gateway::get_instance();
+            foreach (['balance', 'alipay', 'wechatpay', 'paypal', 'stripe', 'epay_alipay', 'epay_wxpay'] as $id) {
+                $g = $gw->get_gateway($id);
+                if (!$g) {
+                    continue;
+                }
+                if (method_exists($g, 'is_configured') && !$g->is_configured()) {
+                    continue;
+                }
+                $methods[] = [
+                    'id' => $id,
+                    'name' => method_exists($g, 'get_name') ? (string) $g->get_name() : $id,
+                ];
+            }
        }
-        $gw = \AKSRT\Payment\Gateway::get_instance();
-        foreach (['balance', 'alipay', 'wechatpay', 'paypal', 'stripe', 'epay_alipay', 'epay_wxpay'] as $id) {
-            $g = $gw->get_gateway($id);
-            if (!$g) {
-                continue;
-            }
-            if (method_exists($g, 'is_configured') && !$g->is_configured()) {
-                continue;
-            }
-            $methods[] = [
-                'id' => $id,
-                'name' => method_exists($g, 'get_name') ? (string) $g->get_name() : $id,
-            ];
+
+        // 卡密兑换会员渠道（后台 会员购买 → 启用卡密兑换会员功能）：
+        // 提交走 /pay/card-pass/redeem type=vip，不创建支付订单。
+        $card_pass = $this->vip_card_pass_context();
+        if (!empty($card_pass['enabled'])) {
+            $methods[] = ['id' => 'card_pass', 'name' => __('卡密', 'aksrt')];
        }
        return $methods;
    }

+    /**
+     * 卡密兑换会员渠道上下文（ChargeCard vip 公开选项）。
+     *
+     * @return array{enabled:bool,desc:string,only_password:bool}
+     */
+    private function vip_card_pass_context(): array {
+        $empty = ['enabled' => false, 'desc' => '', 'only_password' => false];
+        if (!class_exists('\AKSRT\Payment\ChargeCard')) {
+            return $empty;
+        }
+        $opts = \AKSRT\Payment\ChargeCard::get_instance()->get_public_options();
+        return is_array($opts['vip'] ?? null) ? array_merge($empty, $opts['vip']) : $empty;
+    }
+


    private function format_cash_label(string $amount): string {
@@ -260,6 +260,7 @@ trait VipServicePurchase {
                'packages' => $points_packages,
            ],
            'payment_methods'    => $methods,
+            'card_pass'          => $this->vip_card_pass_context(),
            'vip_url'            => function_exists('aksrt_get_user_center_tab_url')
                ? aksrt_get_user_center_tab_url('credits')
                : (function_exists('aksrt_get_user_center_url') ? aksrt_get_user_center_url() : home_url('/')),
@@ -353,6 +354,10 @@ trait VipServicePurchase {
        if ($payment_method === '') {
            $payment_method = 'balance';
        }
+        // 卡密兑换会员走 /pay/card-pass/redeem（type=vip）直兑，不创建支付订单。
+        if ($payment_method === 'card_pass') {
+            return new \WP_Error('aksrt_card_pass_redeem_required', __('卡密兑换会员请直接输入卡密提交', 'aksrt'), ['status' => 400]);
+        }

        $note = wp_json_encode([
            'vip_pay' => 1,
@@ -146,6 +146,21 @@ trait BalanceServiceCharge {
 				$methods[] = is_array($m) ? $m : ['id' => $id, 'name' => $id];
 			}
 		}
+		// 卡密支付渠道：受「启用卡密兑换余额功能」开关控制（开关内部已含收款接口主开关）。
+		$pass_charge = is_array($cfg['pass_charge'] ?? null) ? $cfg['pass_charge'] : [];
+		$card_pass_on = false;
+		if (class_exists('\AKSRT\Payment\ChargeCard')) {
+			$card_opts = \AKSRT\Payment\ChargeCard::get_instance()->get_public_options();
+			$card_pass_on = !empty($card_opts['balance']['enabled']);
+			$pass_charge = [
+				'balance' => is_array($card_opts['balance'] ?? null) ? $card_opts['balance'] : $pass_charge,
+				'credits' => is_array($card_opts['credits'] ?? null) ? $card_opts['credits'] : [],
+				'vip'     => is_array($card_opts['vip'] ?? null) ? $card_opts['vip'] : [],
+			];
+		}
+		if ($card_pass_on) {
+			$methods[] = ['id' => 'card_pass', 'name' => __('卡密', 'aksrt')];
+		}
 		return [
 			'enabled'       => !empty($cfg['enabled']),
 			'desc'          => (string) ($cfg['desc'] ?? ''),
@@ -160,7 +175,7 @@ trait BalanceServiceCharge {
 				'service_charge' => (int) ($cfg['transfer']['service_charge'] ?? 0),
 				'desc'           => (string) ($cfg['transfer']['desc'] ?? ''),
 			],
-			'pass_charge'   => is_array($cfg['pass_charge'] ?? null) ? $cfg['pass_charge'] : [],
+			'pass_charge'   => $pass_charge,
 		];
 	}

@@ -206,6 +221,48 @@ trait BalanceServiceCharge {



+	/**
+	 * 积分商品行解析（"积分|支付|标签"，参考主题 pay_points_product 同款结构）。
+	 *
+	 * @return array<int,array{key:string,points:int,pay_price:string,title:string,tag:string}>
+	 */
+	public function parse_points_packages(string $raw): array {
+		$out = [];
+		$lines = preg_split('/\r\n|\r|\n/', $raw) ?: [];
+		$i = 0;
+		foreach ($lines as $line) {
+			$line = trim((string) $line);
+			if ($line === '') {
+				continue;
+			}
+			$parts = array_map('trim', explode('|', $line));
+			if (count($parts) < 2) {
+				continue;
+			}
+			$points = (int) $parts[0];
+			try {
+				$pay = \AKSRT\Ledger\AssetAmount::balance((string) $parts[1]);
+			} catch (\InvalidArgumentException $e) {
+				continue;
+			}
+			if ($points <= 0 || $pay->minor() <= 0) {
+				continue;
+			}
+			$title = $parts[2] ?? '';
+			$out[] = [
+				'key'       => (string) $i,
+				'points'    => $points,
+				'pay_price' => $pay->decimal(),
+				'title'     => $title !== '' ? $title : sprintf(__('购买 %d 积分', 'aksrt'), $points),
+				'tag'       => $title,
+			];
+			$i++;
+		}
+		return $out;
+	}
+
+
+
 	/**
 	 * @return array<string,mixed>|\WP_Error
 	 */
@@ -68,7 +68,10 @@ trait BalanceServiceRest {
 				'methods'             => \WP_REST_Server::CREATABLE,
 				'callback'            => [$this, 'rest_exchange_balance_for_points'],
 				'permission_callback' => [$this, 'check_asset_rest'],
-				'args' => ['amount' => ['type' => 'string', 'required' => true, 'pattern' => '^(0|[1-9]\\d*)(?:\\.\\d{1,2})?$']],
+				'args' => [
+					'product' => ['type' => 'string', 'default' => 'custom', 'maxLength' => 30],
+					'custom' => ['type' => 'string', 'default' => '0', 'pattern' => '^\d{1,9}$'],
+				],
 			],
 		]);

@@ -311,7 +314,10 @@ trait BalanceServiceRest {


 	/**
-	 * Exchange integer cash-wallet balance for points.
+	 * Buy points with cash-wallet balance (积分购买弹窗 · 余额支付).
+	 *
+	 * Body: { product: 'custom'|<package_key>, custom?: <points int> }
+	 * 自定义按汇率折算支付金额；商品按配置销售金额支付（参考主题同款语义）。
 	 */
 	public function rest_exchange_balance_for_points(\WP_REST_Request $request) {
 		if (!$this->balance_feature_enabled()) {
@@ -329,32 +335,54 @@ trait BalanceServiceRest {
 		if (!is_array($params)) {
 			$params = $request->get_params();
 		}
-		$raw_amount = $params['amount'] ?? '';
-		try {
-			$amount = \AKSRT\Ledger\AssetAmount::balance(is_string($raw_amount) ? $raw_amount : '');
-		} catch (\InvalidArgumentException $e) {
-			return new \WP_Error('aksrt_exchange_amount', __('兑换余额格式无效', 'aksrt'), ['status' => 400]);
-		}
-		if ($amount->minor() <= 0) {
-			return new \WP_Error('aksrt_exchange_amount', __('兑换余额必须大于零', 'aksrt'), ['status' => 400]);
-		}
 		$rate = max(1, (int) ($exchange['rate'] ?? 100));
 		$daily_max = max(1, (int) ($exchange['daily_max_points'] ?? 100000));
-		$scaled = $this->multiply_non_negative($amount->minor(), $rate);
-		if (is_wp_error($scaled)) {
-			return $scaled;
+		$product_key = sanitize_key((string) ($params['product'] ?? 'custom'));
+		$points = 0;
+		$pay_minor = 0;
+		$product_title = '';
+		if ($product_key !== '' && $product_key !== 'custom') {
+			$found = null;
+			foreach ($this->parse_points_packages((string) ($exchange['products_raw'] ?? '')) as $pkg) {
+				if ((string) ($pkg['key'] ?? '') === $product_key) {
+					$found = $pkg;
+					break;
+				}
+			}
+			if (!$found) {
+				return new \WP_Error('aksrt_exchange_product', __('积分商品无效', 'aksrt'), ['status' => 400]);
+			}
+			$points = (int) $found['points'];
+			try {
+				$pay_minor = \AKSRT\Ledger\AssetAmount::balance((string) $found['pay_price'])->minor();
+			} catch (\InvalidArgumentException $e) {
+				$pay_minor = 0;
+			}
+			$product_title = (string) $found['title'];
+		} else {
+			$product_key = 'custom';
+			$points = absint((string) ($params['custom'] ?? '0'));
+			$min_points = max(1, (int) ($exchange['min_points'] ?? 100));
+			if ($points <= 0) {
+				return new \WP_Error('aksrt_exchange_amount', __('请输入需购买的积分数额', 'aksrt'), ['status' => 400]);
+			}
+			if ($points < $min_points) {
+				return new \WP_Error('aksrt_exchange_min', sprintf(__('最低购买%d积分', 'aksrt'), $min_points), ['status' => 400]);
+			}
+			// 自定义按汇率折算支付金额（参考主题语义：积分 * 100 / 汇率 后四舍五入）。
+			// 纯整数实现：intdiv(2a + b, 2b) 等价于 a / b 四舍五入，避免浮点。
+			$pay_minor = intdiv($points * 200 + $rate, $rate * 2);
+			$product_title = sprintf(__('购买 %d 积分', 'aksrt'), $points);
 		}
-		if ($scaled % 100 !== 0) {
-			return new \WP_Error('aksrt_exchange_precision', __('该金额无法兑换为整数积分', 'aksrt'), ['status' => 400]);
+		if ($points <= 0) {
+			return new \WP_Error('aksrt_exchange_product', __('积分商品无效', 'aksrt'), ['status' => 400]);
+		}
+		if ($pay_minor <= 0) {
+			return new \WP_Error('aksrt_exchange_precision', __('支付金额无效', 'aksrt'), ['status' => 400]);
 		}
-		$points = intdiv($scaled, 100);
 		if ($points > $daily_max) {
 			return new \WP_Error('aksrt_exchange_daily_limit', sprintf(__('今日购买积分上限为 %d', 'aksrt'), $daily_max), ['status' => 400]);
 		}
-		$min_points = max(1, (int) ($exchange['min_points'] ?? 100));
-		if ($points < $min_points) {
-			return new \WP_Error('aksrt_exchange_min', sprintf(__('单笔至少购买 %d 积分', 'aksrt'), $min_points), ['status' => 400]);
-		}
 		$user_id = get_current_user_id();
 		$operation_key = \AKSRT\Ledger\OperationKey::from_request($request, 'points-exchange', $user_id);
 		if (is_wp_error($operation_key)) {
@@ -376,10 +404,12 @@ trait BalanceServiceRest {
 		if (!class_exists('\\AKSRT\\Payment\\OrderRepository')) {
 			return new \WP_Error('aksrt_order_unavailable', __('订单服务不可用', 'aksrt'), ['status' => 500]);
 		}
+		$pay_decimal = \AKSRT\Ledger\AssetAmount::decimal_from_minor($pay_minor);
 		$note = wp_json_encode([
 			'points_exchange' => 1,
 			'points' => $points,
-			'product_title' => sprintf(__('购买 %d 积分', 'aksrt'), $points),
+			'product' => $product_key,
+			'product_title' => $product_title,
 		], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
 		$repo = \AKSRT\Payment\OrderRepository::get_instance();
 		$existing_order = $repo->get_by_request_key($operation_key);
@@ -389,11 +419,11 @@ trait BalanceServiceRest {
 			$existing_meta = is_array($existing_meta) ? $existing_meta : [];
 			if ((int) ($existing_order['user_id'] ?? 0) !== $user_id
 				|| sanitize_key((string) ($existing_order['product_type'] ?? '')) !== \AKSRT\Core\DomainModel::ORDER_PRODUCT_POINTS
-				|| (int) ($existing_order['product_id'] ?? 0) !== 0
-				|| (string) ($existing_order['amount'] ?? '') !== $amount->decimal()
+				|| (string) ($existing_order['amount'] ?? '') !== $pay_decimal
 				|| sanitize_key((string) ($existing_order['currency'] ?? '')) !== 'cny'
 				|| sanitize_key((string) ($existing_order['payment_method'] ?? '')) !== 'balance'
 				|| (int) ($existing_meta['points'] ?? 0) !== $points
+				|| (string) ($existing_meta['product'] ?? '') !== $product_key
 			) {
 				return new \WP_Error('aksrt_ledger_idempotency_conflict', __('相同操作标识已用于其他积分购买请求', 'aksrt'), ['status' => 409]);
 			}
@@ -404,7 +434,7 @@ trait BalanceServiceRest {
 		if ($order_number === '') {
 			return new \WP_Error('aksrt_order_create_failed', __('积分订单创建失败', 'aksrt'), ['status' => 500]);
 		}
-		$business_mutation = static function (int $transaction_id) use ($is_new_order, $repo, $user_id, $amount, $points, $operation_key, $order_number, $note) {
+		$business_mutation = static function (int $transaction_id) use ($is_new_order, $repo, $user_id, $pay_decimal, $points, $operation_key, $order_number, $note) {
 			if (!$is_new_order) {
 				return true;
 			}
@@ -413,7 +443,7 @@ trait BalanceServiceRest {
 				'user_id' => $user_id,
 				'product_type' => \AKSRT\Core\DomainModel::ORDER_PRODUCT_POINTS,
 				'product_id' => 0,
-				'amount' => $amount->decimal(),
+				'amount' => $pay_decimal,
 				'currency' => 'CNY',
 				'status' => \AKSRT\Payment\Order::STATUS_PAID,
 				'payment_method' => 'balance',
@@ -426,19 +456,19 @@ trait BalanceServiceRest {
 				return new \WP_Error('aksrt_order_create_failed', __('积分订单创建失败', 'aksrt'), ['status' => 500]);
 			}
 			if (class_exists('\\AKSRT\\Payment\\CommissionLedger')) {
-				return \AKSRT\Payment\CommissionLedger::get_instance()->record_points_exchange($user_id, $amount->decimal(), $points, $operation_key, $order_number);
+				return \AKSRT\Payment\CommissionLedger::get_instance()->record_points_exchange($user_id, $pay_decimal, $points, $operation_key, $order_number);
 			}
 			return true;
 		};
 		$result = \AKSRT\Ledger\LedgerService::get_instance()->exchange(
 			$user_id,
-			$amount->minor(),
+			$pay_minor,
 			$points,
 			$operation_key,
 			'points_exchange',
 			['type' => 'order', 'key' => $order_number],
-			sprintf(__('余额兑换 %d 积分', 'aksrt'), $points),
-			['rate' => $rate],
+			sprintf(__('余额购买 %d 积分', 'aksrt'), $points),
+			['rate' => $rate, 'product' => $product_key],
 			$guard,
 			$business_mutation
 		);
@@ -446,7 +476,7 @@ trait BalanceServiceRest {
 			return $result;
 		}
 		return rest_ensure_response(['success' => true, 'data' => [
-			'message' => sprintf(__('兑换成功，获得 %d 积分', 'aksrt'), $points),
+			'message' => sprintf(__('购买成功，获得 %d 积分', 'aksrt'), $points),
 			'transaction_id' => $result->transaction_id,
 			'replayed' => $result->replayed,
 			'wallet_balance' => \AKSRT\Ledger\AssetAmount::from_minor(\AKSRT\Ledger\AssetType::BALANCE, $result->balance($user_id, \AKSRT\Ledger\AssetType::BALANCE))->decimal(),
@@ -464,12 +494,4 @@ trait BalanceServiceRest {
 		return (intdiv($amount, 100) * $rate) + intdiv(($amount % 100) * $rate, 100);
 	}

-	/** @return int|\WP_Error */
-	private function multiply_non_negative(int $left, int $right) {
-		if ($left < 0 || $right < 0 || ($right > 0 && $left > intdiv(PHP_INT_MAX, $right))) {
-			return new \WP_Error('aksrt_ledger_overflow', __('资产金额超出可用范围', 'aksrt'), ['status' => 400]);
-		}
-		return $left * $right;
-	}
-
 }
@@ -49,7 +49,7 @@ class ChargeCard {
 			'args' => [
 				'password' => ['type' => 'string', 'required' => true, 'minLength' => 1, 'maxLength' => 80, 'sanitize_callback' => 'sanitize_text_field'],
 				'card' => ['type' => 'string', 'default' => '', 'maxLength' => 60, 'sanitize_callback' => 'sanitize_text_field'],
-				'type' => ['type' => 'string', 'default' => '', 'enum' => ['', self::TYPE_BALANCE, self::TYPE_VIP, self::TYPE_CREDITS]],
+				'type' => ['type' => 'string', 'required' => true, 'enum' => [self::TYPE_BALANCE, self::TYPE_VIP, self::TYPE_CREDITS]],
 			],
        ]);
    }
@@ -91,9 +91,10 @@ class ChargeCard {
        }
 		$password = sanitize_text_field((string) ($params['password'] ?? ''));
        $card     = sanitize_text_field((string) ($params['card'] ?? ''));
+        // 弹窗各带类型（余额充值 / 积分购买 / 会员购买），不再自动识别。
        $type     = sanitize_key((string) ($params['type'] ?? ''));
-        if ($type !== '' && !in_array($type, [self::TYPE_BALANCE, self::TYPE_VIP, self::TYPE_CREDITS], true)) {
-            $type = '';
+        if (!in_array($type, [self::TYPE_BALANCE, self::TYPE_VIP, self::TYPE_CREDITS], true)) {
+            return new \WP_Error('aksrt_card_type', __('卡密兑换类型无效', 'aksrt'), ['status' => 400]);
        }

 		$operation_key = \AKSRT\Ledger\OperationKey::from_request($request, 'card-redeem', get_current_user_id());
@@ -114,9 +115,11 @@ class ChargeCard {
    /**
     * 前台卡密兑换开关视图。
     *
-     * 唯一类型闸门：balance.enabled =「启用卡密兑换功能」总开关
-     * （后台 余额充值 → 卡密兑换），并与收款接口 card_pass 主开关共同生效；
-     * 会员/积分卡密不再有独立开关。积分卡额外要求积分系统可用（系统级依赖）。
+     * 三个独立类型闸门（后台 余额充值 → 卡密兑换）：
+     * 「启用卡密兑换余额功能」「启用卡密兑换积分功能」「启用卡密兑换会员功能」，
+     * 并共同受收款接口 card_pass 主开关（任一开关开启即生效）约束；
+     * 积分卡额外要求积分系统可用（系统级依赖）。
+     * 各类型仅在自身开启时进入对应购买弹窗的支付方式。
     *
     * @return array<string,mixed>
     */
@@ -125,38 +128,33 @@ class ChargeCard {
        $channel_on = !class_exists('\AKSRT\Settings\PaymentRuntime')
            || \AKSRT\Settings\PaymentRuntime::is_gateway_enabled('card_pass');

-        $master_on = false;
-        $balance   = ['enabled' => false, 'desc' => '', 'only_password' => true];
-        $vip_only_password = true;
-        $credits_on = false;
+        $types = [
+            'balance' => ['enabled' => false, 'desc' => '', 'only_password' => false],
+            'credits' => ['enabled' => false, 'desc' => '', 'only_password' => false],
+            'vip'     => ['enabled' => false, 'desc' => '', 'only_password' => true],
+        ];

        if ($channel_on && class_exists('\AKSRT\Settings\Settings')) {
            if (method_exists('\AKSRT\Settings\Settings', 'get_payment_recharge_settings')) {
                $recharge = \AKSRT\Settings\Settings::get_payment_recharge_settings();
-                $pc = is_array($recharge['pass_charge'] ?? null) ? $recharge['pass_charge'] : [];
-                $master_on = !empty($pc['enabled']);
-                $balance = [
-                    'enabled'       => $master_on,
-                    'desc'          => (string) ($pc['desc'] ?? ''),
-                    'only_password' => !isset($pc['only_password']) || !empty($pc['only_password']),
-                ];
+                $pass_charge = is_array($recharge['pass_charge'] ?? null) ? $recharge['pass_charge'] : [];
+                foreach (array_keys($types) as $type_key) {
+                    $cfg = is_array($pass_charge[$type_key] ?? null) ? $pass_charge[$type_key] : [];
+                    $types[$type_key] = [
+                        'enabled'       => !empty($cfg['enabled']),
+                        'desc'          => (string) ($cfg['desc'] ?? ''),
+                        'only_password' => !empty($cfg['only_password']),
+                    ];
+                }
            }
-            if (method_exists('\AKSRT\Settings\Settings', 'get_payment_vip_settings')) {
-                $vip_s = \AKSRT\Settings\Settings::get_payment_vip_settings();
-                $benefit = is_array($vip_s['benefit'] ?? null) ? $vip_s['benefit'] : [];
-                $vip_only_password = !isset($benefit['pass_charge_only_password']) || !empty($benefit['pass_charge_only_password']);
-            }
-            if ($master_on) {
-                // 积分卡随总开关生效，仅要求积分系统可用（系统级依赖，非独立开关）。
-                $credits_on = !method_exists('\AKSRT\Settings\Settings', 'credits_enabled') || \AKSRT\Settings\Settings::credits_enabled();
+            if ($types['credits']['enabled']) {
+                // 积分卡额外要求积分系统可用（系统级依赖，非独立开关）。
+                $types['credits']['enabled'] = !method_exists('\AKSRT\Settings\Settings', 'credits_enabled')
+                    || \AKSRT\Settings\Settings::credits_enabled();
            }
        }

-        return [
-            'balance' => $balance,
-            'vip'     => ['only_password' => $vip_only_password],
-            'credits' => ['enabled' => $credits_on],
-        ];
+        return $types;
    }

    /**
@@ -323,12 +321,7 @@ class ChargeCard {

        // only_password: if feature requires card number and empty, fail.
        $opts = $this->get_public_options();
-        $only_password = true;
-        if ($type === self::TYPE_BALANCE) {
-            $only_password = !empty($opts['balance']['only_password']);
-        } elseif ($type === self::TYPE_VIP) {
-            $only_password = !empty($opts['vip']['only_password']);
-        }
+        $only_password = !empty($opts[$type]['only_password']);
        if (!$only_password && $card === '' && (string) ($row['card'] ?? '') !== '') {
            return new \WP_Error('aksrt_card_need_no', __('请输入卡号', 'aksrt'), ['status' => 400]);
        }
@@ -819,13 +812,26 @@ class ChargeCard {
     */
    private function assert_type_enabled(string $type) {
        $opts = $this->get_public_options();
-        // 唯一类型闸门：后台「余额充值 → 卡密兑换」总开关（已含收款接口 card_pass 主开关）。
-        if (empty($opts['balance']['enabled'])) {
-            return new \WP_Error('aksrt_card_disabled', __('卡密兑换功能未开启', 'aksrt'), ['status' => 403]);
-        }
-        // 积分卡额外要求积分系统可用（系统级依赖，非独立开关）。
+        // 积分卡：积分系统不可用优先提示（get_public_options 已把它折叠进 enabled）。
        if ($type === self::TYPE_CREDITS && empty($opts['credits']['enabled'])) {
-            return new \WP_Error('aksrt_card_disabled', __('积分系统未开启，无法兑换积分卡密', 'aksrt'), ['status' => 403]);
+            $toggle_on = false;
+            if (class_exists('\AKSRT\Settings\Settings') && method_exists('\AKSRT\Settings\Settings', 'get_payment_recharge_settings')) {
+                $recharge = \AKSRT\Settings\Settings::get_payment_recharge_settings();
+                $toggle_on = !empty($recharge['pass_charge']['credits']['enabled'] ?? false);
+            }
+            return new \WP_Error('aksrt_card_disabled', $toggle_on
+                ? __('积分系统未开启，无法兑换积分卡密', 'aksrt')
+                : __('卡密兑换积分功能未开启', 'aksrt'), ['status' => 403]);
+        }
+        // 三个独立类型闸门：各类型受自己的「启用卡密兑换XX功能」开关控制
+        // （开关内部已含收款接口 card_pass 主开关判断）。
+        if (empty($opts[$type]['enabled'])) {
+            $messages = [
+                self::TYPE_BALANCE => __('卡密兑换余额功能未开启', 'aksrt'),
+                self::TYPE_CREDITS => __('卡密兑换积分功能未开启', 'aksrt'),
+                self::TYPE_VIP     => __('卡密兑换会员功能未开启', 'aksrt'),
+            ];
+            return new \WP_Error('aksrt_card_disabled', (string) ($messages[$type] ?? __('卡密兑换功能未开启', 'aksrt')), ['status' => 403]);
        }
        return true;
    }
@@ -110,9 +110,22 @@ class PaymentRuntime {
                'desc'           => sanitize_textarea_field((string) ($settings['pay_balance_transfer_desc'] ?? '')),
            ],
            'pass_charge'     => [
-                'enabled'       => !empty($settings['pay_balance_pass_charge_s']),
-                'desc'          => sanitize_textarea_field((string) ($settings['pay_balance_pass_charge_desc'] ?? '')),
-                'only_password' => !empty($settings['pay_balance_pass_charge_only_password']),
+                // 三个独立开关：各类型卡密只进入各自的购买弹窗（收款接口同款拆分）。
+                'balance' => [
+                    'enabled'       => !empty($settings['pay_balance_pass_charge_s']),
+                    'desc'          => sanitize_textarea_field((string) ($settings['pay_balance_pass_charge_desc'] ?? '')),
+                    'only_password' => !empty($settings['pay_balance_pass_charge_only_password']),
+                ],
+                'credits' => [
+                    'enabled'       => !empty($settings['points_pass_exchange_s']),
+                    'desc'          => sanitize_textarea_field((string) ($settings['points_pass_exchange_desc'] ?? '')),
+                    'only_password' => !empty($settings['points_pass_exchange_only_password']),
+                ],
+                'vip'     => [
+                    'enabled'       => !empty($settings['pay_vip_pass_charge_s']),
+                    'desc'          => sanitize_textarea_field((string) ($settings['pay_vip_pass_charge_desc'] ?? '')),
+                    'only_password' => !isset($settings['pay_vip_pass_charge_only_password']) || !empty($settings['pay_vip_pass_charge_only_password']),
+                ],
            ],
            'points_exchange' => [
                'enabled'          => !empty($settings['pay_balance_points_exchange_s']),
@@ -120,6 +133,9 @@ class PaymentRuntime {
                'min_points'       => max(1, min(10000000, (int) ($settings['pay_balance_points_exchange_min_points'] ?? 100))),
                'daily_max_points' => max(1, min(10000000, (int) ($settings['pay_balance_points_exchange_daily_max_points'] ?? 100000))),
                'desc'             => sanitize_textarea_field((string) ($settings['pay_balance_points_exchange_desc'] ?? '')),
+                'products_raw'     => is_array($settings['pay_points_product'] ?? null)
+                    ? self::format_points_product_lines($settings['pay_points_product'])
+                    : (string) ($settings['pay_points_product'] ?? ''),
            ],
        ];
    }
@@ -229,8 +245,6 @@ class PaymentRuntime {
            ],
            'benefit'       => [
                'download_limit'   => max(0, min(9999, (int) ($settings['pay_download_limit'] ?? 0))),
-                // 会员卡密无独立开关（随「启用卡密兑换功能」总开关），仅保留单密码模式。
-                'pass_charge_only_password' => !isset($settings['pay_vip_pass_charge_only_password']) || !empty($settings['pay_vip_pass_charge_only_password']),
            ],
            'renew'         => [
                'enabled'    => !isset($settings['vip_renew']) || !empty($settings['vip_renew']),
@@ -377,7 +391,10 @@ class PaymentRuntime {
        $paypal_enabled = !empty($settings['pay_paypal_sdk_s']);
        $stripe_enabled = !empty($settings['pay_stripe_sdk_s']);
        $balance_enabled = !empty($settings['pay_balance_s']);
-        $card_pass_enabled = !empty($settings['pay_balance_pass_charge_s']);
+        // 卡密收款接口随三个兑换开关任一生效（余额 / 积分 / 会员）。
+        $card_pass_enabled = !empty($settings['pay_balance_pass_charge_s'])
+            || !empty($settings['points_pass_exchange_s'])
+            || !empty($settings['pay_vip_pass_charge_s']);

        return [
            'help_text' => __('微信 / 支付宝可在官方与易支付之间选择；PayPal、Stripe 独立开关。异步回调由各网关验签。', 'aksrt'),
@@ -553,7 +570,10 @@ class PaymentRuntime {
            case 'balance':
                return !empty($settings['pay_balance_s']);
            case 'card_pass':
-                return !empty($settings['pay_balance_pass_charge_s']);
+                // 收款接口随三个兑换开关任一生效（余额 / 积分 / 会员）。
+                return !empty($settings['pay_balance_pass_charge_s'])
+                    || !empty($settings['points_pass_exchange_s'])
+                    || !empty($settings['pay_vip_pass_charge_s']);
            case 'epay':
                return $wechat === 'epay' || $alipay === 'epay';
            case 'epay_alipay':
@@ -607,4 +627,24 @@ class PaymentRuntime {
        }
        return implode("\n", $lines);
    }
+
+    /**
+     * Format points product rows (reference-theme group shape:
+     * points 积分 / pay_price 销售金额 / tag 小标签) into "积分|支付|标签" lines.
+     *
+     * @param array<int,mixed> $products
+     */
+    private static function format_points_product_lines(array $products): string {
+        $lines = [];
+        foreach ($products as $row) {
+            if (!is_array($row)) {
+                continue;
+            }
+            $points = max(0, (int) ($row['points'] ?? 0));
+            $pay_price = max(0, (float) ($row['pay_price'] ?? 0));
+            $title = trim((string) ($row['tag'] ?? ''));
+            $lines[] = $points . '|' . $pay_price . '|' . $title;
+        }
+        return implode("\n", $lines);
+    }
 }