features: payment_analytics-multi_currency-payment_reconciliation-advanced_metrics (#239)

Author: anonfedora

.DS_Store

@@ -0,0 +1,31 @@
+-- Multi-Currency Support
+-- Creates tables for storing exchange rates and currency-related data.
+
+-- -------------------------------------------------------------------------
+-- exchange_rates
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS exchange_rates (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    from_currency   VARCHAR(3) NOT NULL,
+    to_currency     VARCHAR(3) NOT NULL,
+    rate            NUMERIC(20, 10) NOT NULL,
+    source          VARCHAR(100),
+    last_updated    TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+
+    CONSTRAINT chk_currency_code CHECK (
+        from_currency IN ('USD', 'EUR', 'GBP', 'JPY') AND
+        to_currency IN ('USD', 'EUR', 'GBP', 'JPY')
+    ),
+    CONSTRAINT chk_rate_positive CHECK (rate > 0),
+    CONSTRAINT uq_currency_pair UNIQUE (from_currency, to_currency)
+);
+
+-- -------------------------------------------------------------------------
+-- Indexes
+-- -------------------------------------------------------------------------
+CREATE INDEX IF NOT EXISTS idx_exchange_rates_currency_pair
+    ON exchange_rates(from_currency, to_currency);
+
+CREATE INDEX IF NOT EXISTS idx_exchange_rates_last_updated
+    ON exchange_rates(last_updated DESC);

backend/Cargo.lock

@@ -0,0 +1,28 @@
+-- Payment Analytics
+-- Creates tables for storing aggregated analytics data for performance.
+
+-- -------------------------------------------------------------------------
+-- payment_analytics_daily
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS payment_analytics_daily (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    merchant_id     VARCHAR(255),
+    date            DATE NOT NULL,
+    total_payments  BIGINT NOT NULL DEFAULT 0,
+    total_amount    NUMERIC(20, 10) NOT NULL DEFAULT 0,
+    successful_payments BIGINT NOT NULL DEFAULT 0,
+    failed_payments BIGINT NOT NULL DEFAULT 0,
+    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+
+    CONSTRAINT uq_merchant_date UNIQUE (merchant_id, date)
+);
+
+-- -------------------------------------------------------------------------
+-- Indexes
+-- -------------------------------------------------------------------------
+CREATE INDEX IF NOT EXISTS idx_payment_analytics_merchant_date
+    ON payment_analytics_daily(merchant_id, date DESC);
+
+CREATE INDEX IF NOT EXISTS idx_payment_analytics_date
+    ON payment_analytics_daily(date DESC);

backend/migrations/20260528000000_multi_currency.sql

@@ -0,0 +1,61 @@
+-- Payment Reconciliation
+-- Creates tables for payment reconciliation and audit logs.
+
+-- -------------------------------------------------------------------------
+-- payment_reconciliations
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS payment_reconciliations (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    payment_id          UUID,
+    external_id         VARCHAR(255),
+    source              VARCHAR(50) NOT NULL,
+    amount              BIGINT NOT NULL,
+    currency            VARCHAR(10) NOT NULL,
+    status              VARCHAR(50) NOT NULL DEFAULT 'pending',
+    discrepancy_notes   TEXT,
+    resolved_by         UUID,
+    resolved_at         TIMESTAMP WITH TIME ZONE,
+    created_at          TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at          TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+
+    CONSTRAINT chk_source CHECK (source IN ('stellar', 'bank', 'manual')),
+    CONSTRAINT chk_status CHECK (status IN ('pending', 'matched', 'mismatched', 'manual_review', 'resolved'))
+);
+
+-- -------------------------------------------------------------------------
+-- reconciliation_audit_logs
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS reconciliation_audit_logs (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    reconciliation_id   UUID NOT NULL REFERENCES payment_reconciliations(id) ON DELETE CASCADE,
+    actor_id            UUID NOT NULL,
+    action              VARCHAR(100) NOT NULL,
+    old_status          VARCHAR(50),
+    new_status          VARCHAR(50),
+    notes               TEXT,
+    created_at          TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+
+    CONSTRAINT chk_action_status CHECK (old_status IN ('pending', 'matched', 'mismatched', 'manual_review', 'resolved') OR old_status IS NULL),
+    CONSTRAINT chk_new_status CHECK (new_status IN ('pending', 'matched', 'mismatched', 'manual_review', 'resolved') OR new_status IS NULL)
+);
+
+-- -------------------------------------------------------------------------
+-- Indexes
+-- -------------------------------------------------------------------------
+CREATE INDEX IF NOT EXISTS idx_payment_reconciliations_status
+    ON payment_reconciliations(status);
+
+CREATE INDEX IF NOT EXISTS idx_payment_reconciliations_payment_id
+    ON payment_reconciliations(payment_id);
+
+CREATE INDEX IF NOT EXISTS idx_payment_reconciliations_external_id
+    ON payment_reconciliations(external_id);
+
+CREATE INDEX IF NOT EXISTS idx_payment_reconciliations_created_at
+    ON payment_reconciliations(created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_reconciliation_audit_logs_reconciliation_id
+    ON reconciliation_audit_logs(reconciliation_id);
+
+CREATE INDEX IF NOT EXISTS idx_reconciliation_audit_logs_created_at
+    ON reconciliation_audit_logs(created_at DESC);

backend/migrations/20260528000001_payment_analytics.sql

@@ -10,8 +10,13 @@ use tower_http::{cors::CorsLayer, trace::TraceLayer};
 use crate::{
     config::Config,
     http::{
-        admin, audit, auth, batches, disputes, files, health, identity, jobs, metrics as metrics_http,
-        notifications, payments, profiles, transfers, version as version_http, withdrawals,
+        admin, analytics, audit, auth, batches, currency, disputes, files, health, identity, jobs,
+        metrics as metrics_http, notifications, payments, profiles, transfers, version as version_http,
+        withdrawals,
+    },
+    http::{
+        get_reconciliation_audit_log, get_reconciliations, resolve_reconciliation,
+        run_reconciliation,
     },
     job_worker::JobWorker,
     middleware::{
@@ -132,6 +137,26 @@ pub async fn create_app(
         .route("/audit-logs/:id", get(audit::get_audit_log))
         .layer(middleware::from_fn(role_guard::admin_only()));
 
+    // -------------------- Analytics --------------------
+    let analytics_routes = Router::new()
+        .route("/analytics/payments", get(analytics::get_payment_analytics))
+        .route("/analytics/merchant/:merchant_id", get(analytics::get_merchant_performance))
+        .route("/analytics/report", post(analytics::generate_custom_report))
+        .route("/analytics/export", post(analytics::export_to_csv));
+
+    // -------------------- Reconciliation --------------------
+    let reconciliation_routes = Router::new()
+        .route("/reconciliation/run", post(run_reconciliation))
+        .route("/reconciliation", get(get_reconciliations))
+        .route("/reconciliation/:id/resolve", post(resolve_reconciliation))
+        .route("/reconciliation/:id/audit", get(get_reconciliation_audit_log));
+
+    // -------------------- Currency --------------------
+    let currency_routes = Router::new()
+        .route("/currency/convert", get(currency::convert_currency))
+        .route("/currency/rates/:from/:to", get(currency::get_exchange_rate))
+        .route("/currency/supported", get(currency::get_supported_currencies));
+
     // -------------------- Batches --------------------
     let batch_routes = Router::new()
         .route("/batches", post(batches::create_batch))
@@ -189,7 +214,10 @@ pub async fn create_app(
         .nest("/files", files_routes)
         .nest("/batches", batch_routes)
         .nest("/admin", admin_routes)
-        .nest("/audit", audit_routes);
+        .nest("/audit", audit_routes)
+        .nest("/", currency_routes)
+        .nest("/", analytics_routes)
+        .nest("/", reconciliation_routes);
 
     // v2-only protected routes (disputes)
     let v2_only_protected = Router::new()

backend/migrations/20260528000002_payment_reconciliation.sql

@@ -0,0 +1,92 @@
+use axum::{
+    extract::{Path, Query, State},
+    http::StatusCode,
+    response::IntoResponse,
+    Json,
+};
+use chrono::{DateTime, Duration, Utc};
+use serde::Deserialize;
+use std::sync::Arc;
+
+use crate::models::Payment;
+use crate::service::{
+    CustomReportRequest, MerchantPerformance, PaymentAnalytics, ServiceContainer,
+};
+
+#[derive(Debug, Deserialize)]
+pub struct AnalyticsQuery {
+    pub merchant_id: Option<String>,
+    pub start_date: Option<DateTime<Utc>>,
+    pub end_date: Option<DateTime<Utc>>,
+}
+
+/// Get payment analytics
+pub async fn get_payment_analytics(
+    State(services): State<Arc<ServiceContainer>>,
+    Query(query): Query<AnalyticsQuery>,
+) -> Result<Json<PaymentAnalytics>, (StatusCode, String)> {
+    let end_date = query.end_date.unwrap_or_else(Utc::now);
+    let start_date = query.start_date.unwrap_or_else(|| end_date - Duration::days(30));
+
+    let analytics = services
+        .analytics
+        .get_payment_analytics(query.merchant_id, start_date, end_date)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(analytics))
+}
+
+/// Get merchant performance dashboard
+pub async fn get_merchant_performance(
+    State(services): State<Arc<ServiceContainer>>,
+    Path(merchant_id): Path<String>,
+    Query(query): Query<MerchantPerformanceQuery>,
+) -> Result<Json<MerchantPerformance>, (StatusCode, String)> {
+    let days = query.days.unwrap_or(30);
+
+    let performance = services
+        .analytics
+        .get_merchant_performance(merchant_id, days)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(performance))
+}
+
+#[derive(Debug, Deserialize)]
+pub struct MerchantPerformanceQuery {
+    pub days: Option<i64>,
+}
+
+/// Generate custom report
+pub async fn generate_custom_report(
+    State(services): State<Arc<ServiceContainer>>,
+    Json(request): Json<CustomReportRequest>,
+) -> Result<Json<Vec<Payment>>, (StatusCode, String)> {
+    let payments = services
+        .analytics
+        .generate_custom_report(request)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(payments))
+}
+
+/// Export data to CSV
+pub async fn export_to_csv(
+    State(services): State<Arc<ServiceContainer>>,
+    Json(request): Json<CustomReportRequest>,
+) -> Result<impl IntoResponse, (StatusCode, String)> {
+    let csv = services
+        .analytics
+        .export_to_csv(request)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok((
+        StatusCode::OK,
+        [(axum::http::header::CONTENT_TYPE, "text/csv")],
+        csv,
+    ))
+}

backend/src/app.rs

@@ -200,7 +200,7 @@ pub async fn process_batch(
     Path(batch_id): Path<String>,
 ) -> Result<Json<BatchReportResponse>, ApiError> {
     // Verify batch exists
-    let batch = services
+    let _batch = services
         .batch
         .get_batch(&batch_id)
         .await?

backend/src/http/analytics.rs

@@ -0,0 +1,110 @@
+use axum::{
+    extract::{Path, Query, State},
+    http::StatusCode,
+    Json,
+};
+use serde::{Deserialize, Serialize};
+use std::str::FromStr;
+use std::sync::Arc;
+
+use crate::service::{Currency, ServiceContainer};
+
+#[derive(Debug, Deserialize)]
+pub struct ConvertQuery {
+    amount: i64,
+    from: String,
+    to: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ConvertResponse {
+    original_amount: i64,
+    original_currency: Currency,
+    converted_amount: i64,
+    converted_currency: Currency,
+    rate: f64,
+}
+
+#[derive(Debug, Serialize)]
+pub struct CurrenciesResponse {
+    currencies: Vec<CurrencyInfo>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct CurrencyInfo {
+    code: String,
+    name: String,
+}
+
+/// Convert an amount from one currency to another
+pub async fn convert_currency(
+    State(services): State<Arc<ServiceContainer>>,
+    Query(query): Query<ConvertQuery>,
+) -> Result<Json<ConvertResponse>, (StatusCode, String)> {
+    let from = Currency::from_str(&query.from)
+        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid 'from' currency".to_string()))?;
+    let to = Currency::from_str(&query.to)
+        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid 'to' currency".to_string()))?;
+
+    let converted_amount = services
+        .currency
+        .convert(query.amount, from, to)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    let rate = services
+        .currency
+        .get_exchange_rate(from, to)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(ConvertResponse {
+        original_amount: query.amount,
+        original_currency: from,
+        converted_amount,
+        converted_currency: to,
+        rate: rate.rate,
+    }))
+}
+
+/// Get exchange rate between two currencies
+pub async fn get_exchange_rate(
+    State(services): State<Arc<ServiceContainer>>,
+    Path((from, to)): Path<(String, String)>,
+) -> Result<Json<crate::service::ExchangeRate>, (StatusCode, String)> {
+    let from_currency = Currency::from_str(&from)
+        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid 'from' currency".to_string()))?;
+    let to_currency = Currency::from_str(&to)
+        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid 'to' currency".to_string()))?;
+
+    let rate = services
+        .currency
+        .get_exchange_rate(from_currency, to_currency)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+
+    Ok(Json(rate))
+}
+
+/// Get list of supported currencies
+pub async fn get_supported_currencies(
+    State(services): State<Arc<ServiceContainer>>,
+) -> Json<CurrenciesResponse> {
+    let currencies = services.currency.get_supported_currencies();
+    let currency_info = currencies
+        .into_iter()
+        .map(|c| CurrencyInfo {
+            code: c.as_str().to_string(),
+            name: match c {
+                Currency::USD => "US Dollar".to_string(),
+                Currency::EUR => "Euro".to_string(),
+                Currency::GBP => "British Pound".to_string(),
+                Currency::JPY => "Japanese Yen".to_string(),
+            },
+        })
+        .collect();
+
+    Json(CurrenciesResponse {
+        currencies: currency_info,
+    })
+}