refactor: 大规模模块拆分与重组，新增 aether-admin crate

- 新建独立 aether-admin crate 承载 admin 相关共享契约与纯辅助函数
- 拆分 ai_pipeline 下 kiro/private_envelope/conversion/planner 等大文件为子模块目录
- 重组 admin handlers 各业务域（billing/oauth/provider/system/users 等）为目录结构，移除 shared.rs/builders.rs 等反模式
- 移除 ai_pipeline runtime adapters 旧实现（claude/openai/gemini/kiro/vertex/antigravity 等），改由 provider transport 统一承载
- 移除 control_facade/execution_facade/auth_snapshot_facade 等冗余 facade 层
- 拆分 query/billing 与 query/monitoring 模块、state/runtime/payments 与 security 模块
- 扩展架构测试覆盖 admin_billing/admin_model/admin_users 等新模块
- 删除 docs/architecture/refactor-execution-plan.md 已完成的执行计划文档

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

@@ -0,0 +1,114 @@
+use super::super::shared::{
+    admin_wallet_id_from_suffix_path, admin_wallet_operator_id,
+    build_admin_wallet_not_found_response, build_admin_wallet_summary_payload,
+    build_admin_wallet_transaction_payload, build_admin_wallets_bad_request_response,
+    build_admin_wallets_data_unavailable_response, normalize_admin_wallet_balance_type,
+    normalize_admin_wallet_description, normalize_admin_wallet_non_zero_amount,
+    resolve_admin_wallet_owner_summary, AdminWalletAdjustRequest,
+    ADMIN_WALLETS_API_KEY_GIFT_ADJUST_DETAIL,
+};
+use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
+use crate::handlers::admin::shared::{attach_admin_audit_response, unix_secs_to_rfc3339};
+use crate::GatewayError;
+use axum::{
+    body::Body,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+pub(in super::super) async fn build_admin_wallet_adjust_response(
+    state: &AdminAppState<'_>,
+    request_context: &AdminRequestContext<'_>,
+    request_body: Option<&axum::body::Bytes>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some(wallet_id) = admin_wallet_id_from_suffix_path(request_context.path(), "/adjust")
+    else {
+        return Ok(build_admin_wallets_bad_request_response("wallet_id 无效"));
+    };
+    let Some(request_body) = request_body else {
+        return Ok(build_admin_wallets_bad_request_response("请求体不能为空"));
+    };
+    let payload = match serde_json::from_slice::<AdminWalletAdjustRequest>(request_body) {
+        Ok(value) => value,
+        Err(_) => return Ok(build_admin_wallets_bad_request_response("请求体格式无效")),
+    };
+    let amount_usd = match normalize_admin_wallet_non_zero_amount(payload.amount_usd, "amount_usd")
+    {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+    let balance_type = match normalize_admin_wallet_balance_type(payload.balance_type) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+    let description = match normalize_admin_wallet_description(payload.description) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+
+    let Some(existing_wallet) = state
+        .find_wallet(aether_data::repository::wallet::WalletLookupKey::WalletId(
+            &wallet_id,
+        ))
+        .await?
+    else {
+        return Ok(build_admin_wallet_not_found_response());
+    };
+    if existing_wallet.api_key_id.is_some() && balance_type == "gift" {
+        return Ok(build_admin_wallets_bad_request_response(
+            ADMIN_WALLETS_API_KEY_GIFT_ADJUST_DETAIL,
+        ));
+    }
+    let operator_id = admin_wallet_operator_id(request_context);
+    let has_postgres = state.has_postgres_pool();
+    let Some((wallet, transaction)) = state
+        .admin_adjust_wallet_balance(
+            &wallet_id,
+            amount_usd,
+            &balance_type,
+            operator_id.as_deref(),
+            description.as_deref(),
+        )
+        .await?
+    else {
+        return if has_postgres {
+            Ok(build_admin_wallet_not_found_response())
+        } else {
+            Ok(build_admin_wallets_data_unavailable_response())
+        };
+    };
+    let owner = resolve_admin_wallet_owner_summary(state, &wallet).await?;
+    let wallet_payload = build_admin_wallet_summary_payload(&wallet, &owner);
+    let transaction_payload = build_admin_wallet_transaction_payload(
+        &wallet,
+        &owner,
+        transaction.id,
+        &transaction.category,
+        &transaction.reason_code,
+        transaction.amount,
+        transaction.balance_before,
+        transaction.balance_after,
+        transaction.recharge_balance_before,
+        transaction.recharge_balance_after,
+        transaction.gift_balance_before,
+        transaction.gift_balance_after,
+        transaction.link_type.as_deref(),
+        transaction.link_id.as_deref(),
+        transaction.operator_id.as_deref(),
+        transaction.description.as_deref(),
+        unix_secs_to_rfc3339(transaction.created_at_unix_secs),
+    );
+    let response = Json(json!({
+        "wallet": wallet_payload,
+        "transaction": transaction_payload,
+    }))
+    .into_response();
+    Ok(attach_admin_audit_response(
+        response,
+        "admin_wallet_balance_adjusted",
+        "adjust_wallet_balance",
+        "wallet",
+        &wallet_id,
+    ))
+}

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

@@ -0,0 +1,116 @@
+use super::super::shared::{
+    admin_wallet_refund_ids_from_suffix_path, build_admin_wallet_not_found_response,
+    build_admin_wallet_refund_not_found_response, build_admin_wallet_refund_payload,
+    build_admin_wallets_bad_request_response, build_admin_wallets_data_unavailable_response,
+    normalize_admin_wallet_optional_text, resolve_admin_wallet_owner_summary,
+    AdminWalletRefundCompleteRequest, ADMIN_WALLETS_API_KEY_REFUND_DETAIL,
+};
+use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
+use crate::handlers::admin::shared::attach_admin_audit_response;
+use crate::GatewayError;
+use axum::{
+    body::Body,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+pub(in super::super) async fn build_admin_wallet_complete_refund_response(
+    state: &AdminAppState<'_>,
+    request_context: &AdminRequestContext<'_>,
+    request_body: Option<&axum::body::Bytes>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some((wallet_id, refund_id)) =
+        admin_wallet_refund_ids_from_suffix_path(request_context.path(), "/complete")
+    else {
+        return Ok(build_admin_wallets_bad_request_response(
+            "wallet_id 或 refund_id 无效",
+        ));
+    };
+    let Some(request_body) = request_body else {
+        return Ok(build_admin_wallets_bad_request_response("请求体不能为空"));
+    };
+    let payload = match serde_json::from_slice::<AdminWalletRefundCompleteRequest>(request_body) {
+        Ok(value) => value,
+        Err(_) => return Ok(build_admin_wallets_bad_request_response("请求体格式无效")),
+    };
+    let gateway_refund_id = match normalize_admin_wallet_optional_text(
+        payload.gateway_refund_id,
+        "gateway_refund_id",
+        128,
+    ) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+    let payout_reference = match normalize_admin_wallet_optional_text(
+        payload.payout_reference,
+        "payout_reference",
+        255,
+    ) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+    if payload
+        .payout_proof
+        .as_ref()
+        .is_some_and(|value| !value.is_object())
+    {
+        return Ok(build_admin_wallets_bad_request_response(
+            "payout_proof 必须为对象",
+        ));
+    }
+
+    let Some(wallet) = state
+        .find_wallet(aether_data::repository::wallet::WalletLookupKey::WalletId(
+            &wallet_id,
+        ))
+        .await?
+    else {
+        return Ok(build_admin_wallet_not_found_response());
+    };
+    if wallet.api_key_id.is_some() {
+        return Ok(build_admin_wallets_bad_request_response(
+            ADMIN_WALLETS_API_KEY_REFUND_DETAIL,
+        ));
+    }
+
+    let owner = resolve_admin_wallet_owner_summary(state, &wallet).await?;
+    match state
+        .admin_complete_wallet_refund(
+            &wallet_id,
+            &refund_id,
+            gateway_refund_id.as_deref(),
+            payout_reference.as_deref(),
+            payload.payout_proof,
+        )
+        .await?
+    {
+        crate::AdminWalletMutationOutcome::Applied(refund) => {
+            let response = Json(json!({
+                "refund": build_admin_wallet_refund_payload(&wallet, &owner, &refund),
+            }))
+            .into_response();
+            Ok(attach_admin_audit_response(
+                response,
+                "admin_wallet_refund_completed",
+                "complete_wallet_refund",
+                "wallet_refund",
+                &refund_id,
+            ))
+        }
+        crate::AdminWalletMutationOutcome::NotFound => {
+            Ok(build_admin_wallet_refund_not_found_response())
+        }
+        crate::AdminWalletMutationOutcome::Invalid(detail) => {
+            let detail = if detail == "refund status must be processing before completion" {
+                "只有 processing 状态的退款可以标记完成".to_string()
+            } else {
+                detail
+            };
+            Ok(build_admin_wallets_bad_request_response(detail))
+        }
+        crate::AdminWalletMutationOutcome::Unavailable => {
+            Ok(build_admin_wallets_data_unavailable_response())
+        }
+    }
+}

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

@@ -0,0 +1,111 @@
+use super::super::shared::{
+    admin_wallet_operator_id, admin_wallet_refund_ids_from_suffix_path,
+    build_admin_wallet_not_found_response, build_admin_wallet_refund_not_found_response,
+    build_admin_wallet_refund_payload, build_admin_wallet_summary_payload,
+    build_admin_wallet_transaction_payload, build_admin_wallets_bad_request_response,
+    build_admin_wallets_data_unavailable_response, normalize_admin_wallet_required_text,
+    resolve_admin_wallet_owner_summary, AdminWalletRefundFailRequest,
+    ADMIN_WALLETS_API_KEY_REFUND_DETAIL,
+};
+use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
+use crate::handlers::admin::shared::{attach_admin_audit_response, unix_secs_to_rfc3339};
+use crate::GatewayError;
+use axum::{
+    body::Body,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+pub(in super::super) async fn build_admin_wallet_fail_refund_response(
+    state: &AdminAppState<'_>,
+    request_context: &AdminRequestContext<'_>,
+    request_body: Option<&axum::body::Bytes>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some((wallet_id, refund_id)) =
+        admin_wallet_refund_ids_from_suffix_path(request_context.path(), "/fail")
+    else {
+        return Ok(build_admin_wallets_bad_request_response(
+            "wallet_id 或 refund_id 无效",
+        ));
+    };
+    let Some(request_body) = request_body else {
+        return Ok(build_admin_wallets_bad_request_response("请求体不能为空"));
+    };
+    let payload = match serde_json::from_slice::<AdminWalletRefundFailRequest>(request_body) {
+        Ok(value) => value,
+        Err(_) => return Ok(build_admin_wallets_bad_request_response("请求体格式无效")),
+    };
+    let reason = match normalize_admin_wallet_required_text(payload.reason, "reason", 500) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+
+    let Some(existing_wallet) = state
+        .find_wallet(aether_data::repository::wallet::WalletLookupKey::WalletId(
+            &wallet_id,
+        ))
+        .await?
+    else {
+        return Ok(build_admin_wallet_not_found_response());
+    };
+    if existing_wallet.api_key_id.is_some() {
+        return Ok(build_admin_wallets_bad_request_response(
+            ADMIN_WALLETS_API_KEY_REFUND_DETAIL,
+        ));
+    }
+
+    let operator_id = admin_wallet_operator_id(request_context);
+    match state
+        .admin_fail_wallet_refund(&wallet_id, &refund_id, &reason, operator_id.as_deref())
+        .await?
+    {
+        crate::AdminWalletMutationOutcome::Applied((wallet, refund, transaction)) => {
+            let owner = resolve_admin_wallet_owner_summary(state, &wallet).await?;
+            let response = Json(json!({
+                "wallet": build_admin_wallet_summary_payload(&wallet, &owner),
+                "refund": build_admin_wallet_refund_payload(&wallet, &owner, &refund),
+                "transaction": transaction
+                    .map(|transaction| {
+                        build_admin_wallet_transaction_payload(
+                            &wallet,
+                            &owner,
+                            transaction.id,
+                            &transaction.category,
+                            &transaction.reason_code,
+                            transaction.amount,
+                            transaction.balance_before,
+                            transaction.balance_after,
+                            transaction.recharge_balance_before,
+                            transaction.recharge_balance_after,
+                            transaction.gift_balance_before,
+                            transaction.gift_balance_after,
+                            transaction.link_type.as_deref(),
+                            transaction.link_id.as_deref(),
+                            transaction.operator_id.as_deref(),
+                            transaction.description.as_deref(),
+                            unix_secs_to_rfc3339(transaction.created_at_unix_secs),
+                        )
+                    })
+                    .unwrap_or(serde_json::Value::Null),
+            }))
+            .into_response();
+            Ok(attach_admin_audit_response(
+                response,
+                "admin_wallet_refund_failed",
+                "fail_wallet_refund",
+                "wallet_refund",
+                &refund_id,
+            ))
+        }
+        crate::AdminWalletMutationOutcome::NotFound => {
+            Ok(build_admin_wallet_refund_not_found_response())
+        }
+        crate::AdminWalletMutationOutcome::Invalid(detail) => {
+            Ok(build_admin_wallets_bad_request_response(detail))
+        }
+        crate::AdminWalletMutationOutcome::Unavailable => {
+            Ok(build_admin_wallets_data_unavailable_response())
+        }
+    }
+}

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

@@ -0,0 +1,11 @@
+mod adjust;
+mod complete_refund;
+mod fail_refund;
+mod process_refund;
+mod recharge;
+
+pub(super) use adjust::build_admin_wallet_adjust_response;
+pub(super) use complete_refund::build_admin_wallet_complete_refund_response;
+pub(super) use fail_refund::build_admin_wallet_fail_refund_response;
+pub(super) use process_refund::build_admin_wallet_process_refund_response;
+pub(super) use recharge::build_admin_wallet_recharge_response;

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

@@ -0,0 +1,94 @@
+use super::super::shared::{
+    admin_wallet_operator_id, admin_wallet_refund_ids_from_suffix_path,
+    build_admin_wallet_not_found_response, build_admin_wallet_refund_not_found_response,
+    build_admin_wallet_refund_payload, build_admin_wallet_summary_payload,
+    build_admin_wallet_transaction_payload, build_admin_wallets_bad_request_response,
+    build_admin_wallets_data_unavailable_response, resolve_admin_wallet_owner_summary,
+    ADMIN_WALLETS_API_KEY_REFUND_DETAIL,
+};
+use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
+use crate::handlers::admin::shared::{attach_admin_audit_response, unix_secs_to_rfc3339};
+use crate::GatewayError;
+use axum::{
+    body::Body,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+pub(in super::super) async fn build_admin_wallet_process_refund_response(
+    state: &AdminAppState<'_>,
+    request_context: &AdminRequestContext<'_>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some((wallet_id, refund_id)) =
+        admin_wallet_refund_ids_from_suffix_path(request_context.path(), "/process")
+    else {
+        return Ok(build_admin_wallets_bad_request_response(
+            "wallet_id 或 refund_id 无效",
+        ));
+    };
+
+    let Some(existing_wallet) = state
+        .find_wallet(aether_data::repository::wallet::WalletLookupKey::WalletId(
+            &wallet_id,
+        ))
+        .await?
+    else {
+        return Ok(build_admin_wallet_not_found_response());
+    };
+    if existing_wallet.api_key_id.is_some() {
+        return Ok(build_admin_wallets_bad_request_response(
+            ADMIN_WALLETS_API_KEY_REFUND_DETAIL,
+        ));
+    }
+
+    let operator_id = admin_wallet_operator_id(request_context);
+    match state
+        .admin_process_wallet_refund(&wallet_id, &refund_id, operator_id.as_deref())
+        .await?
+    {
+        crate::AdminWalletMutationOutcome::Applied((wallet, refund, transaction)) => {
+            let owner = resolve_admin_wallet_owner_summary(state, &wallet).await?;
+            let response = Json(json!({
+                "wallet": build_admin_wallet_summary_payload(&wallet, &owner),
+                "refund": build_admin_wallet_refund_payload(&wallet, &owner, &refund),
+                "transaction": build_admin_wallet_transaction_payload(
+                    &wallet,
+                    &owner,
+                    transaction.id,
+                    &transaction.category,
+                    &transaction.reason_code,
+                    transaction.amount,
+                    transaction.balance_before,
+                    transaction.balance_after,
+                    transaction.recharge_balance_before,
+                    transaction.recharge_balance_after,
+                    transaction.gift_balance_before,
+                    transaction.gift_balance_after,
+                    transaction.link_type.as_deref(),
+                    transaction.link_id.as_deref(),
+                    transaction.operator_id.as_deref(),
+                    transaction.description.as_deref(),
+                    unix_secs_to_rfc3339(transaction.created_at_unix_secs),
+                ),
+            }))
+            .into_response();
+            Ok(attach_admin_audit_response(
+                response,
+                "admin_wallet_refund_processed",
+                "process_wallet_refund",
+                "wallet_refund",
+                &refund_id,
+            ))
+        }
+        crate::AdminWalletMutationOutcome::NotFound => {
+            Ok(build_admin_wallet_refund_not_found_response())
+        }
+        crate::AdminWalletMutationOutcome::Invalid(detail) => {
+            Ok(build_admin_wallets_bad_request_response(detail))
+        }
+        crate::AdminWalletMutationOutcome::Unavailable => {
+            Ok(build_admin_wallets_data_unavailable_response())
+        }
+    }
+}

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

@@ -0,0 +1,104 @@
+use super::super::shared::{
+    admin_wallet_id_from_suffix_path, admin_wallet_operator_id,
+    build_admin_wallet_not_found_response, build_admin_wallet_payment_order_payload,
+    build_admin_wallet_summary_payload, build_admin_wallets_bad_request_response,
+    build_admin_wallets_data_unavailable_response, normalize_admin_wallet_description,
+    normalize_admin_wallet_payment_method, normalize_admin_wallet_positive_amount,
+    resolve_admin_wallet_owner_summary, AdminWalletRechargeRequest,
+    ADMIN_WALLETS_API_KEY_RECHARGE_DETAIL,
+};
+use crate::handlers::admin::request::{AdminAppState, AdminRequestContext};
+use crate::handlers::admin::shared::{attach_admin_audit_response, unix_secs_to_rfc3339};
+use crate::GatewayError;
+use axum::{
+    body::Body,
+    response::{IntoResponse, Response},
+    Json,
+};
+use serde_json::json;
+
+pub(in super::super) async fn build_admin_wallet_recharge_response(
+    state: &AdminAppState<'_>,
+    request_context: &AdminRequestContext<'_>,
+    request_body: Option<&axum::body::Bytes>,
+) -> Result<Response<Body>, GatewayError> {
+    let Some(wallet_id) = admin_wallet_id_from_suffix_path(request_context.path(), "/recharge")
+    else {
+        return Ok(build_admin_wallets_bad_request_response("wallet_id 无效"));
+    };
+    let Some(request_body) = request_body else {
+        return Ok(build_admin_wallets_bad_request_response("请求体不能为空"));
+    };
+    let payload = match serde_json::from_slice::<AdminWalletRechargeRequest>(request_body) {
+        Ok(value) => value,
+        Err(_) => return Ok(build_admin_wallets_bad_request_response("请求体格式无效")),
+    };
+    let amount_usd = match normalize_admin_wallet_positive_amount(payload.amount_usd, "amount_usd")
+    {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+    let payment_method = match normalize_admin_wallet_payment_method(payload.payment_method) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+    let description = match normalize_admin_wallet_description(payload.description) {
+        Ok(value) => value,
+        Err(detail) => return Ok(build_admin_wallets_bad_request_response(detail)),
+    };
+
+    let Some(existing_wallet) = state
+        .find_wallet(aether_data::repository::wallet::WalletLookupKey::WalletId(
+            &wallet_id,
+        ))
+        .await?
+    else {
+        return Ok(build_admin_wallet_not_found_response());
+    };
+    if existing_wallet.api_key_id.is_some() {
+        return Ok(build_admin_wallets_bad_request_response(
+            ADMIN_WALLETS_API_KEY_RECHARGE_DETAIL,
+        ));
+    }
+    let operator_id = admin_wallet_operator_id(request_context);
+    let has_postgres = state.has_postgres_pool();
+    let Some((wallet, payment_order)) = state
+        .admin_create_manual_wallet_recharge(
+            &wallet_id,
+            amount_usd,
+            &payment_method,
+            operator_id.as_deref(),
+            description.as_deref(),
+        )
+        .await?
+    else {
+        return if has_postgres {
+            Ok(build_admin_wallet_not_found_response())
+        } else {
+            Ok(build_admin_wallets_data_unavailable_response())
+        };
+    };
+    let owner = resolve_admin_wallet_owner_summary(state, &wallet).await?;
+    let response = Json(json!({
+        "wallet": build_admin_wallet_summary_payload(&wallet, &owner),
+        "payment_order": build_admin_wallet_payment_order_payload(
+            payment_order.id,
+            payment_order.order_no,
+            payment_order.amount_usd,
+            payment_order.payment_method,
+            payment_order.status,
+            unix_secs_to_rfc3339(payment_order.created_at_unix_secs),
+            payment_order
+                .credited_at_unix_secs
+                .and_then(unix_secs_to_rfc3339),
+        ),
+    }))
+    .into_response();
+    Ok(attach_admin_audit_response(
+        response,
+        "admin_wallet_manual_recharge_created",
+        "create_manual_wallet_recharge",
+        "wallet",
+        &wallet_id,
+    ))
+}