feat(referrals): 添加邀请返利和注册确认功能

apps/aether-gateway/src/handlers/admin/billing/payments/orders.rs

@@ -16,6 +16,7 @@ use axum::{
     Json,
 };
 use serde_json::json;
+use tracing::warn;
 
 pub(super) async fn maybe_build_local_admin_payment_orders_response(
     state: &AdminAppState<'_>,
@@ -211,6 +212,19 @@ async fn build_admin_payment_credit_order_response(
         .await?
     {
         crate::AdminWalletMutationOutcome::Applied((order, credited)) => {
+            if credited {
+                if let Err(err) = state
+                    .app()
+                    .apply_referral_rewards_for_payment_order_id(&order.id)
+                    .await
+                {
+                    warn!(
+                        error = ?err,
+                        order_id = %order.id,
+                        "failed to apply referral rewards for admin-credited payment order"
+                    );
+                }
+            }
             Ok(attach_admin_audit_response(
                 Json(json!({
                     "order": build_admin_payment_order_payload(&order),

apps/aether-gateway/src/handlers/admin/billing/wallets/mutations/complete_refund.rs

@@ -14,6 +14,7 @@ use axum::{
     Json,
 };
 use serde_json::json;
+use tracing::warn;
 
 pub(in super::super) async fn build_admin_wallet_complete_refund_response(
     state: &AdminAppState<'_>,
@@ -86,6 +87,20 @@ pub(in super::super) async fn build_admin_wallet_complete_refund_response(
         .await?
     {
         crate::AdminWalletMutationOutcome::Applied(refund) => {
+            if let Some(order_id) = refund.payment_order_id.as_deref() {
+                if let Err(err) = state
+                    .app()
+                    .reverse_referral_rewards_for_order(order_id, refund.amount_usd)
+                    .await
+                {
+                    warn!(
+                        error = ?err,
+                        order_id = %order_id,
+                        refund_id = %refund.id,
+                        "failed to reverse referral rewards for completed refund"
+                    );
+                }
+            }
             let response = Json(json!({
                 "refund": build_admin_wallet_refund_payload(&wallet, &owner, &refund),
             }))

apps/aether-gateway/src/handlers/admin/mod.rs

@@ -6,6 +6,7 @@ pub(super) mod features;
 mod model;
 pub(super) mod observability;
 pub(super) mod provider;
+mod referrals;
 mod system;
 mod users;
 

apps/aether-gateway/src/handlers/admin/referrals.rs

@@ -0,0 +1,278 @@
+use crate::data::state::{ReferralRelationshipListQuery, ReferralRewardListQuery};
+use crate::handlers::admin::request::{AdminRouteRequest, AdminRouteResult};
+use crate::handlers::admin::shared::{attach_admin_audit_response, query_param_value};
+use crate::GatewayError;
+use axum::{
+    body::Body,
+    http,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde::Deserialize;
+use serde_json::json;
+
+#[derive(Debug, Default, Deserialize)]
+struct ReferralAdminMutationRequest {
+    note: Option<String>,
+}
+
+pub(crate) async fn maybe_build_local_admin_referrals_response(
+    request: AdminRouteRequest<'_>,
+) -> AdminRouteResult {
+    let request_context = request.request_context();
+    let Some(decision) = request_context.decision() else {
+        return Ok(None);
+    };
+    if decision.route_family.as_deref() != Some("referrals_manage") {
+        return Ok(None);
+    }
+    let response = match decision.route_kind.as_deref() {
+        Some("list_referrals") => {
+            build_admin_referrals_list_response(&request.state(), &request_context).await?
+        }
+        Some("list_referral_rewards") => {
+            build_admin_referral_rewards_list_response(&request.state(), &request_context).await?
+        }
+        Some("retry_referral_reward") => {
+            build_admin_referral_reward_retry_response(
+                &request.state(),
+                &request_context,
+                request.request_body(),
+            )
+            .await?
+        }
+        Some("void_referral_reward") => {
+            build_admin_referral_reward_void_response(
+                &request.state(),
+                &request_context,
+                request.request_body(),
+            )
+            .await?
+        }
+        _ => build_admin_referrals_unavailable_response(),
+    };
+    Ok(Some(response))
+}
+
+fn admin_referrals_bad_request(detail: impl Into<String>) -> Response<Body> {
+    (
+        http::StatusCode::BAD_REQUEST,
+        Json(json!({ "detail": detail.into() })),
+    )
+        .into_response()
+}
+
+fn build_admin_referrals_unavailable_response() -> Response<Body> {
+    (
+        http::StatusCode::SERVICE_UNAVAILABLE,
+        Json(json!({ "detail": "Admin referral data unavailable" })),
+    )
+        .into_response()
+}
+
+fn parse_limit(query: Option<&str>) -> Result<usize, String> {
+    match query_param_value(query, "limit") {
+        Some(value) => value
+            .parse::<usize>()
+            .map(|value| value.clamp(1, 200))
+            .map_err(|_| "limit 必须是正整数".to_string()),
+        None => Ok(50),
+    }
+}
+
+fn parse_offset(query: Option<&str>) -> Result<usize, String> {
+    match query_param_value(query, "offset") {
+        Some(value) => value
+            .parse::<usize>()
+            .map_err(|_| "offset 必须是非负整数".to_string()),
+        None => Ok(0),
+    }
+}
+
+fn parse_optional_bool(query: Option<&str>, key: &str) -> Result<Option<bool>, String> {
+    let Some(value) = query_param_value(query, key) else {
+        return Ok(None);
+    };
+    match value.trim().to_ascii_lowercase().as_str() {
+        "true" | "1" | "yes" => Ok(Some(true)),
+        "false" | "0" | "no" => Ok(Some(false)),
+        _ => Err(format!("{key} 必须是布尔值")),
+    }
+}
+
+fn operator_id(
+    request_context: &crate::handlers::admin::request::AdminRequestContext<'_>,
+) -> Option<String> {
+    request_context
+        .decision()
+        .and_then(|decision| decision.admin_principal.as_ref())
+        .map(|principal| principal.user_id.clone())
+}
+
+fn reward_id_from_path(path: &str, suffix: &str) -> Option<String> {
+    let trimmed = path.trim_end_matches('/');
+    let rest = trimmed.strip_prefix("/api/admin/referral-rewards/")?;
+    let id = rest.strip_suffix(suffix)?.trim_end_matches('/');
+    (!id.is_empty()).then_some(id.to_string())
+}
+
+fn parse_mutation_note(body: Option<&axum::body::Bytes>) -> Result<Option<String>, String> {
+    let Some(body) = body.filter(|body| !body.is_empty()) else {
+        return Ok(None);
+    };
+    let payload = serde_json::from_slice::<ReferralAdminMutationRequest>(body)
+        .map_err(|_| "请求数据验证失败".to_string())?;
+    Ok(payload
+        .note
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty()))
+}
+
+async fn build_admin_referrals_list_response(
+    state: &crate::handlers::admin::request::AdminAppState<'_>,
+    request_context: &crate::handlers::admin::request::AdminRequestContext<'_>,
+) -> Result<Response<Body>, GatewayError> {
+    let query = request_context.query_string();
+    let limit = match parse_limit(query) {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    let offset = match parse_offset(query) {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    let first_paid = match parse_optional_bool(query, "first_paid") {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    let Some((items, total, stats)) = state
+        .app()
+        .list_admin_referral_relationships(ReferralRelationshipListQuery {
+            inviter: query_param_value(query, "inviter"),
+            invitee: query_param_value(query, "invitee"),
+            invite_code: query_param_value(query, "invite_code"),
+            first_paid,
+            limit,
+            offset,
+        })
+        .await?
+    else {
+        return Ok(build_admin_referrals_unavailable_response());
+    };
+    Ok(Json(json!({
+        "items": items,
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+        "stats": stats,
+    }))
+    .into_response())
+}
+
+async fn build_admin_referral_rewards_list_response(
+    state: &crate::handlers::admin::request::AdminAppState<'_>,
+    request_context: &crate::handlers::admin::request::AdminRequestContext<'_>,
+) -> Result<Response<Body>, GatewayError> {
+    let query = request_context.query_string();
+    let limit = match parse_limit(query) {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    let offset = match parse_offset(query) {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    let Some((items, total, stats)) = state
+        .app()
+        .list_admin_referral_rewards(ReferralRewardListQuery {
+            order_id: query_param_value(query, "order_id"),
+            reward_type: query_param_value(query, "reward_type"),
+            status: query_param_value(query, "status"),
+            limit,
+            offset,
+        })
+        .await?
+    else {
+        return Ok(build_admin_referrals_unavailable_response());
+    };
+    Ok(Json(json!({
+        "items": items,
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+        "stats": stats,
+    }))
+    .into_response())
+}
+
+async fn build_admin_referral_reward_retry_response(
+    state: &crate::handlers::admin::request::AdminAppState<'_>,
+    request_context: &crate::handlers::admin::request::AdminRequestContext<'_>,
+    request_body: Option<&axum::body::Bytes>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some(reward_id) = reward_id_from_path(request_context.path(), "/retry") else {
+        return Ok(admin_referrals_bad_request("返利记录不存在"));
+    };
+    let note = match parse_mutation_note(request_body) {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    match state
+        .app()
+        .retry_referral_reward(
+            &reward_id,
+            operator_id(request_context).as_deref(),
+            note.as_deref(),
+        )
+        .await?
+    {
+        Some(reward) => Ok(attach_admin_audit_response(
+            Json(json!({ "reward": reward })).into_response(),
+            "admin_referral_reward_retry",
+            "retry_referral_reward",
+            "referral_reward",
+            &reward_id,
+        )),
+        None => Ok((
+            http::StatusCode::NOT_FOUND,
+            Json(json!({ "detail": "Referral reward not found" })),
+        )
+            .into_response()),
+    }
+}
+
+async fn build_admin_referral_reward_void_response(
+    state: &crate::handlers::admin::request::AdminAppState<'_>,
+    request_context: &crate::handlers::admin::request::AdminRequestContext<'_>,
+    request_body: Option<&axum::body::Bytes>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some(reward_id) = reward_id_from_path(request_context.path(), "/void") else {
+        return Ok(admin_referrals_bad_request("返利记录不存在"));
+    };
+    let note = match parse_mutation_note(request_body) {
+        Ok(value) => value,
+        Err(detail) => return Ok(admin_referrals_bad_request(detail)),
+    };
+    match state
+        .app()
+        .void_referral_reward(
+            &reward_id,
+            operator_id(request_context).as_deref(),
+            note.as_deref(),
+        )
+        .await?
+    {
+        Some(reward) => Ok(attach_admin_audit_response(
+            Json(json!({ "reward": reward })).into_response(),
+            "admin_referral_reward_void",
+            "void_referral_reward",
+            "referral_reward",
+            &reward_id,
+        )),
+        None => Ok((
+            http::StatusCode::NOT_FOUND,
+            Json(json!({ "detail": "Referral reward not found" })),
+        )
+            .into_response()),
+    }
+}

apps/aether-gateway/src/handlers/admin/routes.rs

@@ -1,6 +1,6 @@
 use super::{
-    announcements, auth, billing, endpoint, features, model, observability, provider, request,
-    system, users,
+    announcements, auth, billing, endpoint, features, model, observability, provider, referrals,
+    request, system, users,
 };
 
 pub(crate) async fn maybe_build_local_admin_response(
@@ -40,6 +40,10 @@ pub(crate) async fn maybe_build_local_admin_response(
         return Ok(Some(response));
     }
 
+    if let Some(response) = referrals::maybe_build_local_admin_referrals_response(request).await? {
+        return Ok(Some(response));
+    }
+
     if let Some(response) = features::maybe_build_local_admin_features_response(request).await? {
         return Ok(Some(response));
     }

apps/aether-gateway/src/handlers/admin/users/groups.rs

@@ -14,6 +14,7 @@ use axum::{
     Json,
 };
 use serde_json::json;
+use std::collections::BTreeSet;
 
 #[derive(Debug, serde::Deserialize)]
 struct AdminUserGroupPayload {
@@ -209,14 +210,18 @@ pub(in super::super) async fn build_admin_replace_user_group_members_response(
     if state.find_user_group_by_id(&group_id).await?.is_none() {
         return Ok(not_found("用户分组不存在"));
     }
-    if read_default_user_group_id(state).await?.as_deref() == Some(group_id.as_str()) {
-        return Ok(bad_request_owned("默认用户组成员由系统维护".to_string()));
-    }
     let payload = match parse_members_payload(request_body) {
         Ok(value) => value,
         Err(detail) => return Ok(bad_request_owned(detail)),
     };
     let user_ids = normalize_ids(payload.user_ids);
+    if read_default_user_group_id(state).await?.as_deref() == Some(group_id.as_str()) {
+        if let Some(response) =
+            validate_default_group_member_replacement(state, &group_id, &user_ids).await?
+        {
+            return Ok(response);
+        }
+    }
     let known_users = state.resolve_auth_user_summaries_by_ids(&user_ids).await?;
     if known_users.len() != user_ids.len() {
         return Ok(bad_request_owned("成员包含不存在的用户".to_string()));
@@ -245,6 +250,52 @@ pub(in super::super) async fn build_admin_replace_user_group_members_response(
     ))
 }
 
+async fn validate_default_group_member_replacement(
+    state: &AdminAppState<'_>,
+    group_id: &str,
+    next_user_ids: &[String],
+) -> Result<Option<Response<Body>>, GatewayError> {
+    let next_user_ids = next_user_ids.iter().cloned().collect::<BTreeSet<String>>();
+    let removed_user_ids = state
+        .list_user_group_members(group_id)
+        .await?
+        .into_iter()
+        .filter(|member| !next_user_ids.contains(&member.user_id))
+        .map(|member| member.user_id)
+        .collect::<Vec<_>>();
+    if removed_user_ids.is_empty() {
+        return Ok(None);
+    }
+
+    let summaries = state
+        .resolve_auth_user_summaries_by_ids(&removed_user_ids)
+        .await?;
+    let users_with_other_groups = state
+        .list_user_group_memberships_by_user_ids(&removed_user_ids)
+        .await?
+        .into_iter()
+        .filter(|membership| membership.group_id != group_id)
+        .map(|membership| membership.user_id)
+        .collect::<BTreeSet<_>>();
+
+    for user_id in removed_user_ids {
+        let Some(summary) = summaries.get(&user_id) else {
+            continue;
+        };
+        if crate::roles::can_access_admin_console(&summary.role) {
+            continue;
+        }
+        if !users_with_other_groups.contains(&user_id) {
+            return Ok(Some(bad_request_owned(format!(
+                "用户 {} 移出默认组后将不属于任何用户组",
+                summary.username
+            ))));
+        }
+    }
+
+    Ok(None)
+}
+
 pub(in super::super) async fn build_admin_set_default_user_group_response(
     state: &AdminAppState<'_>,
     request_body: Option<&axum::body::Bytes>,

apps/aether-gateway/src/handlers/public/support/announcements/admin_routes.rs

@@ -32,6 +32,7 @@ struct AdminAnnouncementCreateRequest {
     kind: String,
     priority: Option<i32>,
     is_pinned: Option<bool>,
+    requires_ack: Option<bool>,
     start_time: Option<String>,
     end_time: Option<String>,
 }
@@ -45,6 +46,7 @@ struct AdminAnnouncementUpdateRequest {
     priority: Option<i32>,
     is_active: Option<bool>,
     is_pinned: Option<bool>,
+    requires_ack: Option<bool>,
     start_time: Option<String>,
     end_time: Option<String>,
 }
@@ -168,6 +170,7 @@ fn build_create_record(
         kind: payload.kind,
         priority: payload.priority.unwrap_or(0),
         is_pinned: payload.is_pinned.unwrap_or(false),
+        requires_ack: payload.requires_ack.unwrap_or(false),
         author_id: operator_id,
         start_time_unix_secs: parse_optional_rfc3339_unix_secs(
             payload.start_time.as_deref(),
@@ -194,6 +197,7 @@ fn build_update_record(
         priority: payload.priority,
         is_active: payload.is_active,
         is_pinned: payload.is_pinned,
+        requires_ack: payload.requires_ack,
         start_time_unix_secs: parse_optional_rfc3339_unix_secs(
             payload.start_time.as_deref(),
             "start_time",

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

@@ -78,6 +78,7 @@ pub(super) fn build_public_announcement_payload(
         "priority": announcement.priority,
         "is_active": announcement.is_active,
         "is_pinned": announcement.is_pinned,
+        "requires_ack": announcement.requires_ack,
         "author": {
             "id": announcement.author_id,
             "username": announcement.author_username,

apps/aether-gateway/src/handlers/public/support/announcements/user_routes.rs

@@ -13,7 +13,7 @@ use super::super::{build_unhandled_public_support_response, resolve_authenticate
 use super::announcements_shared::{
     announcements_bad_request_response, announcements_internal_detail,
     announcements_internal_error_response, announcements_not_found_response,
-    read_status_announcement_id_from_path,
+    build_public_announcement_payload, read_status_announcement_id_from_path,
 };
 
 #[derive(Debug, serde::Deserialize)]
@@ -75,6 +75,37 @@ pub(crate) async fn maybe_build_local_announcement_user_response(
             };
             Some(Json(json!({ "unread_count": unread_count })).into_response())
         }
+        Some("required_unread")
+            if request_context.request_method == http::Method::GET
+                && matches!(
+                    request_context.request_path.as_str(),
+                    "/api/announcements/users/me/required-unread"
+                        | "/api/announcements/users/me/required-unread/"
+                ) =>
+        {
+            let items = match state
+                .list_required_unread_active_announcements(&auth.user.id, now_unix_secs, 20)
+                .await
+            {
+                Ok(value) => value,
+                Err(err) => {
+                    return Some(announcements_internal_error_response(
+                        announcements_internal_detail(err),
+                    ))
+                }
+            };
+            let payload_items = items
+                .iter()
+                .map(build_public_announcement_payload)
+                .collect::<Vec<_>>();
+            Some(
+                Json(json!({
+                    "items": payload_items,
+                    "total": payload_items.len(),
+                }))
+                .into_response(),
+            )
+        }
         Some("read_all")
             if request_context.request_method == http::Method::POST
                 && matches!(

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

@@ -26,6 +26,18 @@ pub(crate) async fn build_auth_registration_settings_payload(
     let turnstile_site_key_config = state
         .read_system_config_json_value("turnstile_site_key")
         .await?;
+    let privacy_enabled_config = state
+        .read_system_config_json_value("registration_privacy_policy_enabled")
+        .await?;
+    let privacy_format_config = state
+        .read_system_config_json_value("registration_privacy_policy_format")
+        .await?;
+    let privacy_content_config = state
+        .read_system_config_json_value("registration_privacy_policy_content")
+        .await?;
+    let privacy_version_config = state
+        .read_system_config_json_value("registration_privacy_policy_version")
+        .await?;
 
     let email_configured = smtp_host
         .as_ref()
@@ -48,6 +60,15 @@ pub(crate) async fn build_auth_registration_settings_payload(
     };
     let turnstile_enabled = system_config_bool(turnstile_enabled_config.as_ref(), false);
     let turnstile_site_key = system_config_string(turnstile_site_key_config.as_ref());
+    let privacy_policy_enabled = system_config_bool(privacy_enabled_config.as_ref(), false);
+    let privacy_policy_format = match system_config_string(privacy_format_config.as_ref()) {
+        Some(value) if matches!(value.as_str(), "markdown" | "html") => value,
+        _ => "markdown".to_string(),
+    };
+    let privacy_policy_content =
+        system_config_string(privacy_content_config.as_ref()).unwrap_or_default();
+    let privacy_policy_version =
+        system_config_string(privacy_version_config.as_ref()).unwrap_or_else(|| "1".to_string());
 
     Ok(json!({
         "enable_registration": enable_registration,
@@ -57,6 +78,12 @@ pub(crate) async fn build_auth_registration_settings_payload(
         "turnstile_enabled": turnstile_enabled,
         "turnstile_site_key": turnstile_site_key,
         "turnstile_required_actions": ["send_verification_code", "register"],
+        "privacy_policy": {
+            "enabled": privacy_policy_enabled,
+            "format": privacy_policy_format,
+            "content": privacy_policy_content,
+            "version": privacy_policy_version,
+        },
     }))
 }
 

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

@@ -18,6 +18,9 @@ struct AuthRegisterRequest {
     username: String,
     password: String,
     turnstile_token: Option<String>,
+    invite_code: Option<String>,
+    privacy_policy_accepted: Option<bool>,
+    privacy_policy_version: Option<String>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -131,6 +134,26 @@ pub(crate) fn validate_auth_register_password(password: &str, policy: &str) -> R
     Ok(())
 }
 
+struct RegistrationPrivacyPolicySettings {
+    enabled: bool,
+    version: String,
+}
+
+async fn read_registration_privacy_policy_settings(
+    state: &AppState,
+) -> Result<RegistrationPrivacyPolicySettings, GatewayError> {
+    let enabled = state
+        .read_system_config_json_value("registration_privacy_policy_enabled")
+        .await?;
+    let version = state
+        .read_system_config_json_value("registration_privacy_policy_version")
+        .await?;
+    Ok(RegistrationPrivacyPolicySettings {
+        enabled: system_config_bool(enabled.as_ref(), false),
+        version: system_config_string(version.as_ref()).unwrap_or_else(|| "1".to_string()),
+    })
+}
+
 pub(crate) async fn auth_password_policy_level(state: &AppState) -> Result<String, GatewayError> {
     let config = state
         .read_system_config_json_value("password_policy_level")
@@ -388,6 +411,31 @@ pub(super) async fn handle_auth_register(
     if !enable_registration {
         return build_auth_error_response(http::StatusCode::FORBIDDEN, "系统暂不开放注册", false);
     }
+    let privacy_policy = match read_registration_privacy_policy_settings(state).await {
+        Ok(value) => value,
+        Err(err) => {
+            return build_auth_error_response(
+                http::StatusCode::INTERNAL_SERVER_ERROR,
+                format!("auth settings lookup failed: {err:?}"),
+                false,
+            );
+        }
+    };
+    if privacy_policy.enabled {
+        let accepted = payload.privacy_policy_accepted.unwrap_or(false);
+        let accepted_version = payload
+            .privacy_policy_version
+            .as_deref()
+            .map(str::trim)
+            .unwrap_or_default();
+        if !accepted || accepted_version != privacy_policy.version {
+            return build_auth_error_response(
+                http::StatusCode::BAD_REQUEST,
+                "请先阅读并同意当前版本的隐私政策",
+                false,
+            );
+        }
+    }
 
     if let Err(response) = verify_auth_turnstile(
         state,
@@ -555,6 +603,63 @@ pub(super) async fn handle_auth_register(
             false,
         );
     }
+    if privacy_policy.enabled {
+        match state
+            .record_user_privacy_policy_acceptance(&user.id, &privacy_policy.version)
+            .await
+        {
+            Ok(true) => {}
+            Ok(false) => {
+                let _ = state.delete_local_auth_user(&user.id).await;
+                return build_auth_error_response(
+                    http::StatusCode::SERVICE_UNAVAILABLE,
+                    AUTH_REGISTRATION_STORAGE_UNAVAILABLE_DETAIL,
+                    false,
+                );
+            }
+            Err(err) => {
+                let _ = state.delete_local_auth_user(&user.id).await;
+                return build_auth_error_response(
+                    http::StatusCode::INTERNAL_SERVER_ERROR,
+                    format!("auth privacy policy acceptance failed: {err:?}"),
+                    false,
+                );
+            }
+        }
+    }
+    let invite_code = payload
+        .invite_code
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+    if invite_code.is_some() {
+        let source = json!({
+            "channel": "registration",
+            "ip": cf_connecting_ip,
+            "user_agent": headers
+                .get(http::header::USER_AGENT)
+                .and_then(|value| value.to_str().ok()),
+        });
+        if let Err(err) = state
+            .bind_referral_invite_after_registration(
+                &user.id,
+                user.email_verified,
+                invite_code,
+                Some(source),
+            )
+            .await
+        {
+            let _ = state.delete_local_auth_user(&user.id).await;
+            let (status, detail) = match err {
+                GatewayError::Client { status, message } => (status, message),
+                other => (
+                    http::StatusCode::INTERNAL_SERVER_ERROR,
+                    format!("auth referral binding failed: {other:?}"),
+                ),
+            };
+            return build_auth_error_response(status, detail, false);
+        }
+    }
 
     if require_verification {
         if let Some(email) = email.as_deref() {

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

@@ -3,6 +3,7 @@ use std::collections::BTreeMap;
 use axum::{body::Body, http, response::Response};
 use md5::{Digest, Md5};
 use serde_json::json;
+use tracing::warn;
 
 use super::{payment_shared::payment_callback_payload_hash, AppState, GatewayPublicRequestContext};
 
@@ -373,9 +374,20 @@ pub(super) async fn handle_epay_notify(
 
     match outcome {
         Ok(Some(aether_data::repository::wallet::ProcessPaymentCallbackOutcome::Applied {
+            order,
+            order_id,
             ..
-        }))
-        | Ok(Some(
+        })) => {
+            if let Err(err) = state.apply_referral_rewards_for_paid_order(&order).await {
+                warn!(
+                    error = ?err,
+                    order_id = %order_id,
+                    "failed to apply referral rewards for epay callback"
+                );
+            }
+            epay_plain(http::StatusCode::OK, "success")
+        }
+        Ok(Some(
             aether_data::repository::wallet::ProcessPaymentCallbackOutcome::AlreadyCredited {
                 ..
             },

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

@@ -10,6 +10,7 @@ use super::{
     build_auth_error_response, build_payment_callback_storage_unavailable_response, AppState,
     GatewayPublicRequestContext,
 };
+use tracing::warn;
 
 pub(super) async fn handle_payment_callback_with_wallet_repository(
     state: &AppState,
@@ -109,21 +110,30 @@ pub(super) async fn handle_payment_callback_with_wallet_repository(
             order_no,
             wallet_id,
             order,
-        } => build_auth_json_response(
-            http::StatusCode::OK,
-            json!({
-                "ok": true,
-                "duplicate": duplicate,
-                "credited": true,
-                "order_id": order_id,
-                "order_no": order_no,
-                "status": order.status,
-                "wallet_id": wallet_id,
-                "payment_method": payment_method,
-                "request_path": request_context.request_path,
-            }),
-            None,
-        ),
+        } => {
+            if let Err(err) = state.apply_referral_rewards_for_paid_order(&order).await {
+                warn!(
+                    error = ?err,
+                    order_id = %order_id,
+                    "failed to apply referral rewards for credited payment order"
+                );
+            }
+            build_auth_json_response(
+                http::StatusCode::OK,
+                json!({
+                    "ok": true,
+                    "duplicate": duplicate,
+                    "credited": true,
+                    "order_id": order_id,
+                    "order_no": order_no,
+                    "status": order.status,
+                    "wallet_id": wallet_id,
+                    "payment_method": payment_method,
+                    "request_path": request_context.request_path,
+                }),
+                None,
+            )
+        }
     }
 }
 

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

@@ -31,6 +31,9 @@ use user_me_catalog::*;
 #[path = "user_me_preferences.rs"]
 mod user_me_preferences;
 use user_me_preferences::*;
+#[path = "user_me_referral.rs"]
+mod user_me_referral;
+use user_me_referral::*;
 #[path = "user_me_profile.rs"]
 mod user_me_profile;
 use user_me_profile::*;

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

@@ -0,0 +1,69 @@
+use super::{
+    build_auth_error_response, resolve_authenticated_local_user, AppState,
+    GatewayPublicRequestContext,
+};
+use axum::{
+    body::Body,
+    http,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+pub(super) async fn handle_users_me_referral_get(
+    state: &AppState,
+    request_context: &GatewayPublicRequestContext,
+    headers: &http::HeaderMap,
+) -> Response<Body> {
+    let auth = match resolve_authenticated_local_user(state, request_context, headers).await {
+        Ok(value) => value,
+        Err(response) => return response,
+    };
+    if !state.has_referral_data_backend() {
+        return build_auth_error_response(
+            http::StatusCode::SERVICE_UNAVAILABLE,
+            "邀请返利数据暂不可用",
+            false,
+        );
+    }
+    let dashboard = match state.referral_dashboard(&auth.user.id).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!("referral dashboard failed: {err:?}"),
+                false,
+            );
+        }
+    };
+    let base = headers
+        .get("origin")
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or_default();
+    let invitation_link = if base.is_empty() {
+        format!("/register?invite={}", dashboard.invite_code)
+    } else {
+        format!("{base}/register?invite={}", dashboard.invite_code)
+    };
+    Json(json!({
+        "invite_code": dashboard.invite_code,
+        "invitation_link": invitation_link,
+        "summary": {
+            "total_invites": dashboard.total_invites,
+            "effective_invites": dashboard.effective_invites,
+            "paid_reward_usd": dashboard.paid_reward_usd,
+            "pending_reward_usd": dashboard.pending_reward_usd,
+            "reversed_reward_usd": dashboard.reversed_reward_usd,
+        }
+    }))
+    .into_response()
+}

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

@@ -15,11 +15,12 @@ use super::{
     handle_users_me_management_tokens_list, handle_users_me_model_capabilities_get,
     handle_users_me_model_capabilities_put, handle_users_me_password_patch,
     handle_users_me_preferences_get, handle_users_me_preferences_put,
-    handle_users_me_providers_get, handle_users_me_sessions_get, handle_users_me_update_session,
-    handle_users_me_usage_active_get, handle_users_me_usage_get, handle_users_me_usage_heatmap_get,
-    handle_users_me_usage_interval_timeline_get, users_me_api_key_capabilities_path_matches,
-    users_me_api_key_detail_path_matches, users_me_api_key_install_sessions_path_matches,
-    users_me_api_key_providers_path_matches, users_me_management_token_detail_path_matches,
+    handle_users_me_providers_get, handle_users_me_referral_get, handle_users_me_sessions_get,
+    handle_users_me_update_session, handle_users_me_usage_active_get, handle_users_me_usage_get,
+    handle_users_me_usage_heatmap_get, handle_users_me_usage_interval_timeline_get,
+    users_me_api_key_capabilities_path_matches, users_me_api_key_detail_path_matches,
+    users_me_api_key_install_sessions_path_matches, users_me_api_key_providers_path_matches,
+    users_me_management_token_detail_path_matches,
     users_me_management_token_regenerate_path_matches,
     users_me_management_token_toggle_path_matches, users_me_management_tokens_root,
     users_me_session_detail_path_matches, AppState, GatewayPublicRequestContext,
@@ -211,6 +212,9 @@ pub(crate) async fn maybe_build_local_users_me_response(
         Some("preferences") if request_context.request_path == "/api/users/me/preferences" => {
             Some(handle_users_me_preferences_get(state, request_context, headers).await)
         }
+        Some("referral") if request_context.request_path == "/api/users/me/referral" => {
+            Some(handle_users_me_referral_get(state, request_context, headers).await)
+        }
         Some("available_models")
             if request_context.request_path == "/api/users/me/available-models" =>
         {