feat(payments): 增加兑换码与支付适配框架 (#299)

* feat(payments): 增加兑换码与支付适配框架

* fix(ci): 对齐 Rust 1.95 lint 与格式要求

* fix(payments): harden redeem code wallet credits

---------

Co-authored-by: fawney19 <elky0401@gmail.com>

apps/aether-gateway/src/handlers/public/support/payment.rs

@@ -2,6 +2,8 @@ use axum::{body::Body, http, response::Response};
 
 pub(super) use super::{build_auth_error_response, AppState, GatewayPublicRequestContext};
 
+#[path = "payment/gateway.rs"]
+pub(super) mod payment_gateway;
 #[path = "payment/postgres.rs"]
 mod payment_postgres;
 #[path = "payment/route.rs"]

apps/aether-gateway/src/handlers/public/support/payment/gateway.rs

@@ -0,0 +1,192 @@
+use chrono::{DateTime, Utc};
+use serde_json::json;
+
+use super::payment_shared::{
+    normalize_payment_callback_request, payment_callback_signature_matches,
+    NormalizedPaymentCallbackRequest, PaymentCallbackRequest,
+};
+
+pub(crate) struct CreateCheckoutSessionInput {
+    pub(crate) order_no: String,
+    pub(crate) amount_usd: f64,
+    pub(crate) expires_at: DateTime<Utc>,
+}
+
+pub(crate) struct CreateCheckoutSessionOutput {
+    pub(crate) gateway_order_id: String,
+    pub(crate) gateway_response: serde_json::Value,
+}
+
+pub(crate) struct VerifyCallbackInput<'a> {
+    pub(crate) secret: &'a str,
+    pub(crate) signature: &'a str,
+    pub(crate) payload: PaymentCallbackRequest,
+}
+
+pub(crate) struct VerifyCallbackOutcome {
+    pub(crate) normalized_payload: NormalizedPaymentCallbackRequest,
+    pub(crate) signature_valid: bool,
+}
+
+pub(crate) trait PaymentGatewayAdapter: Sync {
+    fn payment_method(&self) -> &'static str;
+
+    fn create_checkout_session(
+        &self,
+        input: &CreateCheckoutSessionInput,
+    ) -> Result<CreateCheckoutSessionOutput, String>;
+
+    fn verify_callback(
+        &self,
+        input: VerifyCallbackInput<'_>,
+    ) -> Result<VerifyCallbackOutcome, String> {
+        let normalized_payload = normalize_payment_callback_request(input.payload)
+            .map_err(|detail: &'static str| detail.to_string())?;
+        let signature_valid = payment_callback_signature_matches(
+            &normalized_payload.payload,
+            input.signature,
+            input.secret,
+        )?;
+        Ok(VerifyCallbackOutcome {
+            normalized_payload,
+            signature_valid,
+        })
+    }
+}
+
+pub(crate) struct PaymentGatewayRegistry;
+
+impl PaymentGatewayRegistry {
+    pub(crate) fn get(payment_method: &str) -> Option<&'static dyn PaymentGatewayAdapter> {
+        match payment_method.trim().to_ascii_lowercase().as_str() {
+            "alipay" => Some(&ALIPAY_ADAPTER),
+            "wechat" => Some(&WECHAT_ADAPTER),
+            "manual" => Some(&MANUAL_ADAPTER),
+            _ => None,
+        }
+    }
+}
+
+struct AlipayAdapter;
+struct WechatAdapter;
+struct ManualAdapter;
+
+static ALIPAY_ADAPTER: AlipayAdapter = AlipayAdapter;
+static WECHAT_ADAPTER: WechatAdapter = WechatAdapter;
+static MANUAL_ADAPTER: ManualAdapter = ManualAdapter;
+
+impl PaymentGatewayAdapter for AlipayAdapter {
+    fn payment_method(&self) -> &'static str {
+        "alipay"
+    }
+
+    fn create_checkout_session(
+        &self,
+        input: &CreateCheckoutSessionInput,
+    ) -> Result<CreateCheckoutSessionOutput, String> {
+        let expires_at = input.expires_at.to_rfc3339();
+        let gateway_order_id = format!("ali_{}", input.order_no);
+        Ok(CreateCheckoutSessionOutput {
+            gateway_order_id: gateway_order_id.clone(),
+            gateway_response: json!({
+                "gateway": self.payment_method(),
+                "display_name": "支付宝",
+                "gateway_order_id": gateway_order_id,
+                "payment_url": format!("/pay/mock/alipay/{}", input.order_no),
+                "qr_code": format!("mock://alipay/{}", input.order_no),
+                "expires_at": expires_at,
+                "amount_usd": input.amount_usd,
+            }),
+        })
+    }
+}
+
+impl PaymentGatewayAdapter for WechatAdapter {
+    fn payment_method(&self) -> &'static str {
+        "wechat"
+    }
+
+    fn create_checkout_session(
+        &self,
+        input: &CreateCheckoutSessionInput,
+    ) -> Result<CreateCheckoutSessionOutput, String> {
+        let expires_at = input.expires_at.to_rfc3339();
+        let gateway_order_id = format!("wx_{}", input.order_no);
+        Ok(CreateCheckoutSessionOutput {
+            gateway_order_id: gateway_order_id.clone(),
+            gateway_response: json!({
+                "gateway": self.payment_method(),
+                "display_name": "微信支付",
+                "gateway_order_id": gateway_order_id,
+                "payment_url": format!("/pay/mock/wechat/{}", input.order_no),
+                "qr_code": format!("mock://wechat/{}", input.order_no),
+                "expires_at": expires_at,
+                "amount_usd": input.amount_usd,
+            }),
+        })
+    }
+}
+
+impl PaymentGatewayAdapter for ManualAdapter {
+    fn payment_method(&self) -> &'static str {
+        "manual"
+    }
+
+    fn create_checkout_session(
+        &self,
+        input: &CreateCheckoutSessionInput,
+    ) -> Result<CreateCheckoutSessionOutput, String> {
+        let expires_at = input.expires_at.to_rfc3339();
+        let gateway_order_id = format!("manual_{}", input.order_no);
+        Ok(CreateCheckoutSessionOutput {
+            gateway_order_id: gateway_order_id.clone(),
+            gateway_response: json!({
+                "gateway": self.payment_method(),
+                "display_name": "人工打款",
+                "gateway_order_id": gateway_order_id,
+                "payment_url": serde_json::Value::Null,
+                "qr_code": serde_json::Value::Null,
+                "instructions": "请线下确认到账后由管理员处理",
+                "expires_at": expires_at,
+                "amount_usd": input.amount_usd,
+            }),
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{CreateCheckoutSessionInput, PaymentGatewayRegistry};
+    use chrono::Utc;
+
+    #[test]
+    fn registry_resolves_builtin_mock_adapters() {
+        assert!(PaymentGatewayRegistry::get("alipay").is_some());
+        assert!(PaymentGatewayRegistry::get("wechat").is_some());
+        assert!(PaymentGatewayRegistry::get("manual").is_some());
+        assert!(PaymentGatewayRegistry::get("unknown").is_none());
+    }
+
+    #[test]
+    fn builtin_mock_checkout_payloads_keep_existing_frontend_keys() {
+        let adapter = PaymentGatewayRegistry::get("wechat").expect("adapter should exist");
+        let checkout = adapter
+            .create_checkout_session(&CreateCheckoutSessionInput {
+                order_no: "po_test".to_string(),
+                amount_usd: 12.5,
+                expires_at: Utc::now(),
+            })
+            .expect("checkout should build");
+        let payload = checkout
+            .gateway_response
+            .as_object()
+            .expect("gateway response should be object");
+
+        for key in ["gateway_order_id", "payment_url", "qr_code", "expires_at"] {
+            assert!(
+                payload.contains_key(key),
+                "mock checkout payload should contain {key}"
+            );
+        }
+    }
+}

apps/aether-gateway/src/handlers/public/support/payment/route.rs

@@ -1,8 +1,8 @@
 use axum::{body::Body, http, response::Response};
 
+use super::payment_gateway::{PaymentGatewayRegistry, VerifyCallbackInput};
 use super::payment_shared::{
-    normalize_payment_callback_request, payment_callback_payment_method_from_path,
-    payment_callback_secret, payment_callback_signature_matches, PaymentCallbackRequest,
+    payment_callback_payment_method_from_path, payment_callback_secret, PaymentCallbackRequest,
     PAYMENT_CALLBACK_SIGNATURE_HEADER, PAYMENT_CALLBACK_TOKEN_HEADER,
 };
 use super::{
@@ -72,16 +72,6 @@ pub(super) async fn maybe_build_local_payment_callback_route_response(
             ));
         }
     };
-    let payload = match normalize_payment_callback_request(raw_payload) {
-        Ok(value) => value,
-        Err(detail) => {
-            return Some(build_auth_error_response(
-                http::StatusCode::BAD_REQUEST,
-                detail,
-                false,
-            ));
-        }
-    };
     let Some(payment_method) =
         payment_callback_payment_method_from_path(&request_context.request_path)
     else {
@@ -91,17 +81,28 @@ pub(super) async fn maybe_build_local_payment_callback_route_response(
             false,
         ));
     };
-    let signature_valid =
-        match payment_callback_signature_matches(&payload.payload, &signature, &secret) {
-            Ok(value) => value,
-            Err(err) => {
-                return Some(build_auth_error_response(
-                    http::StatusCode::INTERNAL_SERVER_ERROR,
-                    err,
-                    false,
-                ));
-            }
-        };
+    let Some(adapter) = PaymentGatewayRegistry::get(&payment_method) else {
+        return Some(build_auth_error_response(
+            http::StatusCode::BAD_REQUEST,
+            "unsupported payment_method",
+            false,
+        ));
+    };
+    let verified = match adapter.verify_callback(VerifyCallbackInput {
+        secret: &secret,
+        signature: &signature,
+        payload: raw_payload,
+    }) {
+        Ok(value) => value,
+        Err(err) => {
+            let status = if err == "输入验证失败" {
+                http::StatusCode::BAD_REQUEST
+            } else {
+                http::StatusCode::INTERNAL_SERVER_ERROR
+            };
+            return Some(build_auth_error_response(status, err, false));
+        }
+    };
 
     if state.postgres_pool().is_some() {
         return Some(
@@ -109,8 +110,8 @@ pub(super) async fn maybe_build_local_payment_callback_route_response(
                 state,
                 &payment_method,
                 request_context,
-                &payload,
-                signature_valid,
+                &verified.normalized_payload,
+                verified.signature_valid,
             )
             .await,
         );
@@ -122,8 +123,8 @@ pub(super) async fn maybe_build_local_payment_callback_route_response(
             super::payment_test_support::handle_payment_callback_with_test_store(
                 &payment_method,
                 request_context,
-                &payload,
-                signature_valid,
+                &verified.normalized_payload,
+                verified.signature_valid,
             )
             .await,
         );

apps/aether-gateway/src/handlers/public/support/payment/shared.rs

@@ -10,33 +10,33 @@ pub(super) const PAYMENT_CALLBACK_TOKEN_HEADER: &str = "x-payment-callback-token
 pub(super) const PAYMENT_CALLBACK_SIGNATURE_HEADER: &str = "x-payment-callback-signature";
 
 #[derive(Debug, Deserialize)]
-pub(super) struct PaymentCallbackRequest {
-    pub(super) callback_key: String,
+pub(crate) struct PaymentCallbackRequest {
+    pub(crate) callback_key: String,
     #[serde(default)]
-    pub(super) order_no: Option<String>,
+    pub(crate) order_no: Option<String>,
     #[serde(default)]
-    pub(super) gateway_order_id: Option<String>,
-    pub(super) amount_usd: f64,
+    pub(crate) gateway_order_id: Option<String>,
+    pub(crate) amount_usd: f64,
     #[serde(default)]
-    pub(super) pay_amount: Option<f64>,
+    pub(crate) pay_amount: Option<f64>,
     #[serde(default)]
-    pub(super) pay_currency: Option<String>,
+    pub(crate) pay_currency: Option<String>,
     #[serde(default)]
-    pub(super) exchange_rate: Option<f64>,
+    pub(crate) exchange_rate: Option<f64>,
     #[serde(default)]
-    pub(super) payload: Option<serde_json::Map<String, serde_json::Value>>,
+    pub(crate) payload: Option<serde_json::Map<String, serde_json::Value>>,
 }
 
 #[derive(Debug, Clone)]
-pub(super) struct NormalizedPaymentCallbackRequest {
-    pub(super) callback_key: String,
-    pub(super) order_no: Option<String>,
-    pub(super) gateway_order_id: Option<String>,
-    pub(super) amount_usd: f64,
-    pub(super) pay_amount: Option<f64>,
-    pub(super) pay_currency: Option<String>,
-    pub(super) exchange_rate: Option<f64>,
-    pub(super) payload: serde_json::Value,
+pub(crate) struct NormalizedPaymentCallbackRequest {
+    pub(crate) callback_key: String,
+    pub(crate) order_no: Option<String>,
+    pub(crate) gateway_order_id: Option<String>,
+    pub(crate) amount_usd: f64,
+    pub(crate) pay_amount: Option<f64>,
+    pub(crate) pay_currency: Option<String>,
+    pub(crate) exchange_rate: Option<f64>,
+    pub(crate) payload: serde_json::Value,
 }
 
 pub(super) fn payment_callback_secret() -> Option<String> {

apps/aether-gateway/src/handlers/public/support/wallet.rs

@@ -23,6 +23,8 @@ mod flow;
 mod reads;
 #[path = "wallet/recharge.rs"]
 mod recharge;
+#[path = "wallet/redeem.rs"]
+mod redeem;
 #[path = "wallet/refunds.rs"]
 mod refunds;
 use self::flow::handle_wallet_flow;
@@ -39,6 +41,7 @@ use self::recharge::{
 pub(crate) use self::recharge::{
     sanitize_wallet_gateway_response, wallet_payment_order_payload_from_row,
 };
+use self::redeem::handle_wallet_redeem;
 use self::refunds::{
     handle_wallet_create_refund, handle_wallet_refund_detail, handle_wallet_refunds_list,
     wallet_refund_detail_path_matches,
@@ -153,6 +156,12 @@ pub(super) async fn maybe_build_local_wallet_response(
         );
     }
 
+    if decision.route_kind.as_deref() == Some("redeem")
+        && request_context.request_path == "/api/wallet/redeem"
+    {
+        return Some(handle_wallet_redeem(state, request_context, headers, request_body).await);
+    }
+
     if decision.route_kind.as_deref() == Some("list_recharge_orders")
         && request_context.request_path == "/api/wallet/recharge"
     {

apps/aether-gateway/src/handlers/public/support/wallet/recharge.rs

@@ -1,3 +1,6 @@
+use super::super::support_payment::payment_gateway::{
+    CreateCheckoutSessionInput, PaymentGatewayRegistry,
+};
 use super::{
     build_auth_error_response, build_auth_json_response, build_wallet_payload,
     build_wallet_recharge_storage_unavailable_response, http, parse_wallet_limit,
@@ -75,60 +78,6 @@ fn wallet_build_order_no(now: chrono::DateTime<chrono::Utc>) -> String {
     )
 }
 
-fn wallet_checkout_payload(
-    payment_method: &str,
-    order_no: &str,
-    expires_at: chrono::DateTime<chrono::Utc>,
-) -> Result<(String, serde_json::Value), String> {
-    let expires_at = expires_at.to_rfc3339();
-    match payment_method {
-        "alipay" => {
-            let gateway_order_id = format!("ali_{order_no}");
-            Ok((
-                gateway_order_id.clone(),
-                json!({
-                    "gateway": "alipay",
-                    "display_name": "支付宝",
-                    "gateway_order_id": gateway_order_id,
-                    "payment_url": format!("/pay/mock/alipay/{order_no}"),
-                    "qr_code": format!("mock://alipay/{order_no}"),
-                    "expires_at": expires_at,
-                }),
-            ))
-        }
-        "wechat" => {
-            let gateway_order_id = format!("wx_{order_no}");
-            Ok((
-                gateway_order_id.clone(),
-                json!({
-                    "gateway": "wechat",
-                    "display_name": "微信支付",
-                    "gateway_order_id": gateway_order_id,
-                    "payment_url": format!("/pay/mock/wechat/{order_no}"),
-                    "qr_code": format!("mock://wechat/{order_no}"),
-                    "expires_at": expires_at,
-                }),
-            ))
-        }
-        "manual" => {
-            let gateway_order_id = format!("manual_{order_no}");
-            Ok((
-                gateway_order_id.clone(),
-                json!({
-                    "gateway": "manual",
-                    "display_name": "人工打款",
-                    "gateway_order_id": gateway_order_id,
-                    "payment_url": serde_json::Value::Null,
-                    "qr_code": serde_json::Value::Null,
-                    "instructions": "请线下确认到账后由管理员处理",
-                    "expires_at": expires_at,
-                }),
-            ))
-        }
-        _ => Err(format!("unsupported payment_method: {payment_method}")),
-    }
-}
-
 fn wallet_order_id_from_path(request_path: &str) -> Option<String> {
     let trimmed = request_path.trim_end_matches('/');
     let order_id = trimmed.strip_prefix("/api/wallet/recharge/")?.trim();
@@ -357,17 +306,23 @@ pub(super) async fn handle_wallet_create_recharge(
             let order_id = Uuid::new_v4().to_string();
             let order_no = wallet_build_order_no(now);
             let expires_at = now + chrono::Duration::minutes(30);
-            let (gateway_order_id, gateway_response) =
-                match wallet_checkout_payload(&payload.payment_method, &order_no, expires_at) {
-                    Ok(value) => value,
-                    Err(detail) => {
-                        return build_auth_error_response(
-                            http::StatusCode::BAD_REQUEST,
-                            detail,
-                            false,
-                        );
-                    }
-                };
+            let Some(adapter) = PaymentGatewayRegistry::get(&payload.payment_method) else {
+                return build_auth_error_response(
+                    http::StatusCode::BAD_REQUEST,
+                    format!("unsupported payment_method: {}", payload.payment_method),
+                    false,
+                );
+            };
+            let checkout = match adapter.create_checkout_session(&CreateCheckoutSessionInput {
+                order_no: order_no.clone(),
+                amount_usd: payload.amount_usd,
+                expires_at,
+            }) {
+                Ok(value) => value,
+                Err(detail) => {
+                    return build_auth_error_response(http::StatusCode::BAD_REQUEST, detail, false);
+                }
+            };
             let order_payload = build_wallet_payment_order_payload(
                 order_id,
                 order_no,
@@ -380,8 +335,8 @@ pub(super) async fn handle_wallet_create_recharge(
                 0.0,
                 0.0,
                 payload.payment_method,
-                Some(gateway_order_id),
-                Some(gateway_response.clone()),
+                Some(checkout.gateway_order_id.clone()),
+                Some(checkout.gateway_response.clone()),
                 "pending".to_string(),
                 Some(now.to_rfc3339()),
                 None,
@@ -393,7 +348,7 @@ pub(super) async fn handle_wallet_create_recharge(
                 http::StatusCode::OK,
                 json!({
                     "order": order_payload,
-                    "payment_instructions": sanitize_wallet_gateway_response(Some(gateway_response)),
+                    "payment_instructions": sanitize_wallet_gateway_response(Some(checkout.gateway_response)),
                 }),
                 None,
             );
@@ -405,13 +360,23 @@ pub(super) async fn handle_wallet_create_recharge(
     let now = Utc::now();
     let order_no = wallet_build_order_no(now);
     let expires_at = now + chrono::Duration::minutes(30);
-    let (gateway_order_id, gateway_response) =
-        match wallet_checkout_payload(&payload.payment_method, &order_no, expires_at) {
-            Ok(value) => value,
-            Err(detail) => {
-                return build_auth_error_response(http::StatusCode::BAD_REQUEST, detail, false);
-            }
-        };
+    let Some(adapter) = PaymentGatewayRegistry::get(&payload.payment_method) else {
+        return build_auth_error_response(
+            http::StatusCode::BAD_REQUEST,
+            format!("unsupported payment_method: {}", payload.payment_method),
+            false,
+        );
+    };
+    let checkout = match adapter.create_checkout_session(&CreateCheckoutSessionInput {
+        order_no: order_no.clone(),
+        amount_usd: payload.amount_usd,
+        expires_at,
+    }) {
+        Ok(value) => value,
+        Err(detail) => {
+            return build_auth_error_response(http::StatusCode::BAD_REQUEST, detail, false);
+        }
+    };
     let outcome = match state
         .create_wallet_recharge_order(
             aether_data::repository::wallet::CreateWalletRechargeOrderInput {
@@ -422,8 +387,8 @@ pub(super) async fn handle_wallet_create_recharge(
                 pay_currency: payload.pay_currency.clone(),
                 exchange_rate: payload.exchange_rate,
                 payment_method: payload.payment_method.clone(),
-                gateway_order_id,
-                gateway_response: gateway_response.clone(),
+                gateway_order_id: checkout.gateway_order_id,
+                gateway_response: checkout.gateway_response.clone(),
                 order_no,
                 expires_at_unix_secs: expires_at.timestamp().max(0) as u64,
             },
@@ -456,7 +421,7 @@ pub(super) async fn handle_wallet_create_recharge(
         http::StatusCode::OK,
         json!({
             "order": order_payload,
-            "payment_instructions": sanitize_wallet_gateway_response(Some(gateway_response)),
+            "payment_instructions": sanitize_wallet_gateway_response(Some(checkout.gateway_response)),
         }),
         None,
     )

apps/aether-gateway/src/handlers/public/support/wallet/redeem.rs

@@ -0,0 +1,136 @@
+use super::{
+    build_auth_error_response, build_auth_json_response, build_auth_wallet_summary_payload, http,
+    resolve_authenticated_local_user, sanitize_wallet_gateway_response, unix_secs_to_rfc3339,
+    wallet_normalize_optional_string_field, AppState, Body, GatewayPublicRequestContext, Response,
+};
+use chrono::Utc;
+use serde::Deserialize;
+use serde_json::json;
+use uuid::Uuid;
+
+#[derive(Debug, Deserialize)]
+struct WalletRedeemRequest {
+    code: String,
+}
+
+fn wallet_build_redeem_order_no(now: chrono::DateTime<chrono::Utc>) -> String {
+    format!(
+        "po_{}_{}",
+        now.format("%Y%m%d%H%M%S%6f"),
+        &Uuid::new_v4().simple().to_string()[..12]
+    )
+}
+
+fn build_wallet_payment_order_payload(
+    record: &aether_data::repository::wallet::StoredAdminPaymentOrder,
+) -> serde_json::Value {
+    json!({
+        "id": record.id,
+        "order_no": record.order_no,
+        "wallet_id": record.wallet_id,
+        "user_id": record.user_id,
+        "amount_usd": record.amount_usd,
+        "pay_amount": record.pay_amount,
+        "pay_currency": record.pay_currency,
+        "exchange_rate": record.exchange_rate,
+        "refunded_amount_usd": record.refunded_amount_usd,
+        "refundable_amount_usd": record.refundable_amount_usd,
+        "payment_method": record.payment_method,
+        "gateway_order_id": record.gateway_order_id,
+        "gateway_response": sanitize_wallet_gateway_response(record.gateway_response.clone()),
+        "status": record.status,
+        "created_at": unix_secs_to_rfc3339(record.created_at_unix_ms),
+        "paid_at": record.paid_at_unix_secs.and_then(unix_secs_to_rfc3339),
+        "credited_at": record.credited_at_unix_secs.and_then(unix_secs_to_rfc3339),
+        "expires_at": record.expires_at_unix_secs.and_then(unix_secs_to_rfc3339),
+    })
+}
+
+pub(super) async fn handle_wallet_redeem(
+    state: &AppState,
+    request_context: &GatewayPublicRequestContext,
+    headers: &http::HeaderMap,
+    request_body: Option<&axum::body::Bytes>,
+) -> Response<Body> {
+    let auth = match resolve_authenticated_local_user(state, request_context, headers).await {
+        Ok(value) => value,
+        Err(response) => return response,
+    };
+    let Some(request_body) = request_body else {
+        return build_auth_error_response(http::StatusCode::BAD_REQUEST, "缺少请求体", false);
+    };
+    let payload = match serde_json::from_slice::<WalletRedeemRequest>(request_body) {
+        Ok(value) => value,
+        Err(_) => {
+            return build_auth_error_response(http::StatusCode::BAD_REQUEST, "输入验证失败", false)
+        }
+    };
+    let code = match wallet_normalize_optional_string_field(Some(payload.code), 128) {
+        Ok(Some(value)) => value,
+        _ => {
+            return build_auth_error_response(http::StatusCode::BAD_REQUEST, "输入验证失败", false)
+        }
+    };
+
+    let outcome = match state
+        .redeem_wallet_code(aether_data::repository::wallet::RedeemWalletCodeInput {
+            code,
+            user_id: auth.user.id.clone(),
+            order_no: wallet_build_redeem_order_no(Utc::now()),
+        })
+        .await
+    {
+        Ok(Some(value)) => value,
+        Ok(None) => {
+            return build_auth_error_response(
+                http::StatusCode::SERVICE_UNAVAILABLE,
+                "钱包兑换后端暂不可用",
+                false,
+            );
+        }
+        Err(err) => {
+            return build_auth_error_response(
+                http::StatusCode::INTERNAL_SERVER_ERROR,
+                format!("wallet redeem failed: {err:?}"),
+                false,
+            );
+        }
+    };
+
+    match outcome {
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::Redeemed {
+            wallet,
+            order,
+            amount_usd,
+            batch_name,
+        } => build_auth_json_response(
+            http::StatusCode::OK,
+            json!({
+                "order": build_wallet_payment_order_payload(&order),
+                "wallet": build_auth_wallet_summary_payload(Some(&wallet)),
+                "amount_usd": amount_usd,
+                "batch_name": batch_name,
+            }),
+            None,
+        ),
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::InvalidCode => {
+            build_auth_error_response(http::StatusCode::BAD_REQUEST, "兑换码格式无效", false)
+        }
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::CodeNotFound => {
+            build_auth_error_response(http::StatusCode::NOT_FOUND, "兑换码不存在", false)
+        }
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::CodeDisabled
+        | aether_data::repository::wallet::RedeemWalletCodeOutcome::BatchDisabled => {
+            build_auth_error_response(http::StatusCode::BAD_REQUEST, "兑换码已停用", false)
+        }
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::CodeExpired => {
+            build_auth_error_response(http::StatusCode::BAD_REQUEST, "兑换码已过期", false)
+        }
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::CodeRedeemed => {
+            build_auth_error_response(http::StatusCode::BAD_REQUEST, "兑换码已被使用", false)
+        }
+        aether_data::repository::wallet::RedeemWalletCodeOutcome::WalletInactive => {
+            build_auth_error_response(http::StatusCode::BAD_REQUEST, "wallet is not active", false)
+        }
+    }
+}