koprogo_api/infrastructure/web/handlers/

expense_handlers.rs

use crate::application::dto::{
    ApproveInvoiceDto, CreateExpenseDto, CreateInvoiceDraftDto, PageRequest, PageResponse,
    RejectInvoiceDto, SubmitForApprovalDto, UpdateInvoiceDraftDto,
};
use crate::domain::entities::UserRole;
use crate::infrastructure::audit::{AuditEventType, AuditLogEntry};
use crate::infrastructure::web::handlers::conformity_response::try_build_conformity_response;
use crate::infrastructure::web::middleware::scope_guard::{
    verify_acp_org_access, verify_building_org_access,
};
use crate::infrastructure::web::{AppState, AuthenticatedUser};
use actix_web::{get, post, put, web, HttpResponse, Responder, ResponseError};
use chrono::{DateTime, Utc};
use serde::Deserialize;
use std::str::FromStr;
use uuid::Uuid;
use validator::Validate;

/// Story 3.1 — Resolve the typed `UserRole` from the JWT string.
///
/// Returns `None` when the JWT carries an unknown / malformed role (treated as
/// no privilege — caller emits 403 `invalid_role`).
fn user_role(user: &AuthenticatedUser) -> Option<UserRole> {
    UserRole::from_str(&user.role).ok()
}

/// Helper function to check if owner role is trying to modify data.
/// Note: Accountant CAN create expenses and mark them as paid.
fn verify_owner_readonly(user: &AuthenticatedUser) -> Option<HttpResponse> {
    if user.role == "owner" {
        Some(HttpResponse::Forbidden().json(serde_json::json!({
            "error": "Owner role has read-only access",
            "code": "invalid_role",
        })))
    } else {
        None
    }
}

/// Helper function to check if user has syndic role (for approval workflow).
fn verify_syndic_role(user: &AuthenticatedUser) -> Option<HttpResponse> {
    match user_role(user) {
        Some(UserRole::Syndic) | Some(UserRole::SuperAdmin) => None,
        _ => Some(HttpResponse::Forbidden().json(serde_json::json!({
            "error": "Only syndic or superadmin can approve/reject invoices",
            "code": "invalid_role",
        }))),
    }
}

/// Story 3.1 — Authorise *emitting* expenses / call-for-funds (sortie financière).
/// INV-10 séparation des pouvoirs : un encodeur seul est rejeté ici.
fn check_can_emit_expenses(user: &AuthenticatedUser) -> Option<HttpResponse> {
    match user_role(user) {
        Some(role) if role.can_emit_expenses() => None,
        _ => Some(HttpResponse::Forbidden().json(serde_json::json!({
            "error":
                "Only syndic, superadmin, or accountant émetteur can create/pay expenses",
            "code": "invalid_role",
        }))),
    }
}

/// Story 3.1 — Authorise *encoding* invoices / drafts (entrée comptable amont).
fn check_can_encode_invoices(user: &AuthenticatedUser) -> Option<HttpResponse> {
    match user_role(user) {
        Some(role) if role.can_encode_invoices() => None,
        _ => Some(HttpResponse::Forbidden().json(serde_json::json!({
            "error":
                "Only syndic, superadmin, or accountant encodeur can create/edit invoices",
            "code": "invalid_role",
        }))),
    }
}

/// Helper function to check if user has accountant role (for creating/editing invoices).
///
/// Story 3.1: alias kept for backwards-compat — delegates to `check_can_encode_invoices`.
fn verify_accountant_role(user: &AuthenticatedUser) -> Option<HttpResponse> {
    check_can_encode_invoices(user)
}

/// Cloisonne une dépense AVANT de la muter (#864).
///
/// ── Ce que ces quatre routes laissaient passer ────────────────────────────
///
/// `cancel_expense`, `mark_expense_overdue`, `reactivate_expense` et
/// `unpay_expense` prenaient `AuthenticatedUser` et ne s'en servaient que
/// pour journaliser. `get_expense`, dans ce même fichier, remonte pourtant
/// `expense → building → acp → organization` depuis le hotfix #603.
///
/// ── Une différence avec `get_expense`, et elle est volontaire ─────────────
///
/// `get_expense` enchaîne des `if let Ok(...)` : quand l'immeuble ou l'ACP
/// ne se résout pas, il ne refuse RIEN et sert la dépense. Sur une lecture
/// c'est déjà une fuite ; sur une écriture ce serait un blanc-seing. Ici,
/// une chaîne qui ne se résout pas REFUSE.
///
/// Rend `Some(réponse)` quand l'appel doit être refusé, `None` sinon.
async fn verify_expense_org_access(
    state: &web::Data<AppState>,
    user: &AuthenticatedUser,
    id: Uuid,
) -> Option<HttpResponse> {
    let expense = match state.expense_use_cases.get_expense(id).await {
        Ok(Some(e)) => e,
        Ok(None) => {
            return Some(HttpResponse::NotFound().json(serde_json::json!({
                "error": "Expense not found"
            })))
        }
        Err(err) => {
            return Some(HttpResponse::InternalServerError().json(serde_json::json!({
                "error": err.to_string()
            })))
        }
    };

    let acp_id = match Uuid::parse_str(&expense.acp_id) {
        Ok(id) => id,
        Err(_) => {
            return Some(HttpResponse::Forbidden().json(serde_json::json!({
                "error": "Impossible de rattacher cette dépense à une ACP"
            })))
        }
    };

    match verify_acp_org_access(user, acp_id, &state.acp_use_cases).await {
        Ok(()) => None,
        Err(err) => Some(err.error_response()),
    }
}

#[utoipa::path(
    post,
    path = "/expenses",
    tag = "Expenses",
    summary = "Créer une dépense",
    request_body = CreateExpenseDto,
    responses(
        (status = 201, description = "Dépense créée"),
        (status = 400, description = "Requête invalide"),
        (status = 401, description = "Non authentifié"),
        (status = 403, description = "Rôle sans droit d'encodage"),
    ),
    security(("bearer_auth" = []))
)]
#[post("/expenses")]
pub async fn create_expense(
    state: web::Data<AppState>,
    user: AuthenticatedUser, // JWT-extracted user info (SECURE!)
    mut dto: web::Json<CreateExpenseDto>,
) -> impl Responder {
    if let Some(response) = verify_owner_readonly(&user) {
        return response;
    }
    // Story 3.1 INV-10 : un encodeur ne peut PAS émettre. POST /expenses est une
    // sortie financière, donc réservé aux émetteurs (syndic/superadmin/accountant
    // générique/accountant.emetteur).
    if let Some(response) = check_can_emit_expenses(&user) {
        return response;
    }

    // Override the organization_id from DTO with the one from JWT token
    // This prevents users from creating expenses in other organizations
    let organization_id = match user.require_organization() {
        Ok(org_id) => org_id,
        Err(e) => {
            return HttpResponse::Unauthorized().json(serde_json::json!({
                "error": e.to_string()
            }))
        }
    };
    dto.organization_id = organization_id.to_string();

    // Isolation multi-tenant à l'ÉCRITURE : l'immeuble visé doit relever d'une
    // ACP dont ce syndic a la gestion.
    //
    // L'affectation ci-dessus protège le mauvais champ : elle empêche
    // d'ESTAMPILLER l'enregistrement au nom d'autrui, pas de le RATTACHER au
    // patrimoine d'autrui. Mesuré le 2026-09-02 entre deux cabinets syndics
    // indépendants : `POST /expenses` sur l'immeuble d'un tiers répondait 201,
    // et la dépense apparaissait dans la liste des charges de cet immeuble.
    let building_uuid = match Uuid::parse_str(&dto.building_id) {
        Ok(id) => id,
        Err(_) => {
            return HttpResponse::BadRequest()
                .json(serde_json::json!({ "error": "Invalid building_id format" }))
        }
    };
    if let Err(err) = verify_building_org_access(
        &user,
        building_uuid,
        &state.building_use_cases,
        &state.acp_use_cases,
    )
    .await
    {
        return err.error_response();
    }

    if let Err(errors) = dto.validate() {
        return HttpResponse::BadRequest().json(serde_json::json!({
            "error": "Validation failed",
            "details": errors.to_string()
        }));
    }

    match state
        .expense_use_cases
        .create_expense(dto.into_inner())
        .await
    {
        Ok(expense) => {
            // Audit log: successful expense creation
            AuditLogEntry::new(
                AuditEventType::ExpenseCreated,
                Some(user.user_id),
                Some(organization_id),
            )
            .with_resource("Expense", Uuid::parse_str(&expense.id).unwrap())
            .log();

            HttpResponse::Created().json(expense)
        }
        Err(err) => {
            // Audit log: failed expense creation
            AuditLogEntry::new(
                AuditEventType::ExpenseCreated,
                Some(user.user_id),
                Some(organization_id),
            )
            .with_error(err.clone())
            .log();

            // Track H Story H2 — pre-check validate-before-compute → 422 narratif
            if let Some(resp) = try_build_conformity_response(&err) {
                return resp;
            }
            HttpResponse::BadRequest().json(serde_json::json!({
                "error": err
            }))
        }
    }
}

#[utoipa::path(
    get,
    path = "/expenses/{id}",
    tag = "Expenses",
    summary = "Lire une dépense",
    responses(
        (status = 200, description = "Dépense"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[get("/expenses/{id}")]
pub async fn get_expense(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    match state.expense_use_cases.get_expense(*id).await {
        Ok(Some(expense)) => {
            // Hotfix #603 — multi-tenant isolation via ACP→organization resolution.
            if let Ok(building_id) = Uuid::parse_str(&expense.building_id) {
                if let Ok(Some(building)) = state.building_use_cases.get_building(building_id).await
                {
                    let acp_id = match Uuid::parse_str(&building.acp_id) {
                        Ok(id) => id,
                        Err(_) => {
                            return HttpResponse::InternalServerError().json(serde_json::json!({
                                "error": "Invalid building.acp_id format"
                            }));
                        }
                    };
                    if let Err(err) =
                        verify_acp_org_access(&user, acp_id, &state.acp_use_cases).await
                    {
                        return err.error_response();
                    }
                }
            }
            HttpResponse::Ok().json(expense)
        }
        Ok(None) => HttpResponse::NotFound().json(serde_json::json!({
            "error": "Expense not found"
        })),
        Err(err) => HttpResponse::InternalServerError().json(serde_json::json!({
            "error": err
        })),
    }
}

#[utoipa::path(
    get,
    path = "/expenses",
    tag = "Expenses",
    summary = "Lister les dépenses de l'organisation",
    responses(
        (status = 200, description = "Liste paginée"),
        (status = 401, description = "Non authentifié"),
    ),
    security(("bearer_auth" = []))
)]
#[get("/expenses")]
pub async fn list_expenses(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    page_request: web::Query<PageRequest>,
) -> impl Responder {
    let organization_id = user.organization_id;

    match state
        .expense_use_cases
        .list_expenses_paginated(&page_request, organization_id)
        .await
    {
        Ok((expenses, total)) => {
            let response =
                PageResponse::new(expenses, page_request.page, page_request.per_page, total);
            HttpResponse::Ok().json(response)
        }
        Err(err) => HttpResponse::InternalServerError().json(serde_json::json!({
            "error": err
        })),
    }
}

#[utoipa::path(
    get,
    path = "/buildings/{building_id}/expenses",
    tag = "Expenses",
    summary = "Lister les dépenses d'un immeuble",
    responses(
        (status = 200, description = "Liste"),
        (status = 401, description = "Non authentifié"),
        (status = 403, description = "Immeuble hors de votre organisation"),
        (status = 404, description = "Immeuble introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[get("/buildings/{building_id}/expenses")]
pub async fn list_expenses_by_building(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    building_id: web::Path<Uuid>,
) -> impl Responder {
    // Hotfix #603 — multi-tenant isolation via ACP→organization resolution.
    match state.building_use_cases.get_building(*building_id).await {
        Ok(Some(building)) => {
            let acp_id = match Uuid::parse_str(&building.acp_id) {
                Ok(id) => id,
                Err(_) => {
                    return HttpResponse::InternalServerError().json(serde_json::json!({
                        "error": "Invalid building.acp_id format"
                    }));
                }
            };
            if let Err(err) = verify_acp_org_access(&user, acp_id, &state.acp_use_cases).await {
                return err.error_response();
            }
        }
        Ok(None) => {
            return HttpResponse::NotFound().json(serde_json::json!({
                "error": "Building not found"
            }));
        }
        Err(err) => {
            return HttpResponse::InternalServerError().json(serde_json::json!({
                "error": err
            }));
        }
    }

    match state
        .expense_use_cases
        .list_expenses_by_building(*building_id)
        .await
    {
        Ok(expenses) => HttpResponse::Ok().json(expenses),
        Err(err) => HttpResponse::InternalServerError().json(serde_json::json!({
            "error": err
        })),
    }
}

#[utoipa::path(
    put,
    path = "/expenses/{id}/mark-paid",
    tag = "Expenses",
    summary = "Marquer une dépense comme payée",
    responses(
        (status = 200, description = "Dépense mise à jour"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[put("/expenses/{id}/mark-paid")]
pub async fn mark_expense_paid(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    if let Some(response) = verify_owner_readonly(&user) {
        return response;
    }
    // Story 3.1 INV-10 : marquage payé = mouvement financier sortant.
    if let Some(response) = check_can_emit_expenses(&user) {
        return response;
    }

    match state.expense_use_cases.mark_as_paid(*id).await {
        Ok(expense) => {
            // Audit log: successful expense marked paid
            AuditLogEntry::new(
                AuditEventType::ExpenseMarkedPaid,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Expense", *id)
            .log();

            HttpResponse::Ok().json(expense)
        }
        Err(err) => {
            // Audit log: failed expense marked paid
            AuditLogEntry::new(
                AuditEventType::ExpenseMarkedPaid,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Expense", *id)
            .with_error(err.clone())
            .log();

            HttpResponse::BadRequest().json(serde_json::json!({
                "error": err
            }))
        }
    }
}

#[utoipa::path(
    post,
    path = "/expenses/{id}/mark-overdue",
    tag = "Expenses",
    summary = "Marquer une dépense en retard",
    responses(
        (status = 200, description = "Dépense mise à jour"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[post("/expenses/{id}/mark-overdue")]
pub async fn mark_expense_overdue(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    // Cloisonnement AVANT la mutation (#864).
    if let Some(refus) = verify_expense_org_access(&state, &user, *id).await {
        return refus;
    }

    match state.expense_use_cases.mark_as_overdue(*id).await {
        Ok(expense) => {
            AuditLogEntry::new(
                AuditEventType::ExpenseMarkedOverdue,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Expense", *id)
            .log();

            HttpResponse::Ok().json(expense)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

#[utoipa::path(
    post,
    path = "/expenses/{id}/cancel",
    tag = "Expenses",
    summary = "Annuler une dépense",
    responses(
        (status = 200, description = "Dépense annulée"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[post("/expenses/{id}/cancel")]
pub async fn cancel_expense(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    // Cloisonnement AVANT la mutation (#864).
    if let Some(refus) = verify_expense_org_access(&state, &user, *id).await {
        return refus;
    }

    match state.expense_use_cases.cancel_expense(*id).await {
        Ok(expense) => {
            AuditLogEntry::new(
                AuditEventType::ExpenseCancelled,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Expense", *id)
            .log();

            HttpResponse::Ok().json(expense)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

#[utoipa::path(
    post,
    path = "/expenses/{id}/reactivate",
    tag = "Expenses",
    summary = "Réactiver une dépense annulée",
    responses(
        (status = 200, description = "Dépense réactivée"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[post("/expenses/{id}/reactivate")]
pub async fn reactivate_expense(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    // Cloisonnement AVANT la mutation (#864).
    if let Some(refus) = verify_expense_org_access(&state, &user, *id).await {
        return refus;
    }

    match state.expense_use_cases.reactivate_expense(*id).await {
        Ok(expense) => {
            AuditLogEntry::new(
                AuditEventType::ExpenseReactivated,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Expense", *id)
            .log();

            HttpResponse::Ok().json(expense)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

#[utoipa::path(
    post,
    path = "/expenses/{id}/unpay",
    tag = "Expenses",
    summary = "Annuler le paiement d'une dépense",
    responses(
        (status = 200, description = "Dépense remise en attente"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[post("/expenses/{id}/unpay")]
pub async fn unpay_expense(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    // Cloisonnement AVANT la mutation (#864).
    if let Some(refus) = verify_expense_org_access(&state, &user, *id).await {
        return refus;
    }

    match state.expense_use_cases.unpay_expense(*id).await {
        Ok(expense) => {
            AuditLogEntry::new(
                AuditEventType::ExpenseUnpaid,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Expense", *id)
            .log();

            HttpResponse::Ok().json(expense)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

// ========== Invoice Workflow Endpoints (Issue #73) ==========

/// POST /invoices/draft - Create a new invoice draft with VAT
#[utoipa::path(
    post,
    path = "/invoices/draft",
    tag = "Expenses",
    summary = "Créer une facture brouillon avec TVA",
    request_body = CreateInvoiceDraftDto,
    responses(
        (status = 201, description = "Brouillon créé"),
        (status = 400, description = "Requête invalide"),
        (status = 401, description = "Non authentifié"),
        (status = 403, description = "Rôle sans droit d'encodage"),
    ),
    security(("bearer_auth" = []))
)]
#[post("/invoices/draft")]
pub async fn create_invoice_draft(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    mut dto: web::Json<CreateInvoiceDraftDto>,
) -> impl Responder {
    if let Some(response) = verify_accountant_role(&user) {
        return response;
    }

    // Override organization_id from JWT token
    let organization_id = match user.require_organization() {
        Ok(org_id) => org_id,
        Err(e) => {
            return HttpResponse::Unauthorized().json(serde_json::json!({
                "error": e.to_string()
            }))
        }
    };
    dto.organization_id = organization_id.to_string();

    // Isolation multi-tenant à l'ÉCRITURE : l'immeuble visé doit relever d'une
    // ACP dont ce syndic a la gestion.
    //
    // L'affectation ci-dessus protège le mauvais champ : elle empêche
    // d'ESTAMPILLER l'enregistrement au nom d'autrui, pas de le RATTACHER au
    // patrimoine d'autrui. Mesuré le 2026-09-02 entre deux cabinets syndics
    // indépendants : `POST /expenses` sur l'immeuble d'un tiers répondait 201,
    // et la dépense apparaissait dans la liste des charges de cet immeuble.
    let building_uuid = match Uuid::parse_str(&dto.building_id) {
        Ok(id) => id,
        Err(_) => {
            return HttpResponse::BadRequest()
                .json(serde_json::json!({ "error": "Invalid building_id format" }))
        }
    };
    if let Err(err) = verify_building_org_access(
        &user,
        building_uuid,
        &state.building_use_cases,
        &state.acp_use_cases,
    )
    .await
    {
        return err.error_response();
    }

    if let Err(errors) = dto.validate() {
        return HttpResponse::BadRequest().json(serde_json::json!({
            "error": "Validation failed",
            "details": errors.to_string()
        }));
    }

    match state
        .expense_use_cases
        .create_invoice_draft(dto.into_inner())
        .await
    {
        Ok(invoice) => {
            AuditLogEntry::new(
                AuditEventType::ExpenseCreated,
                Some(user.user_id),
                Some(organization_id),
            )
            .with_resource("Invoice", Uuid::parse_str(&invoice.id).unwrap())
            .log();

            HttpResponse::Created().json(invoice)
        }
        Err(err) => {
            AuditLogEntry::new(
                AuditEventType::ExpenseCreated,
                Some(user.user_id),
                Some(organization_id),
            )
            .with_error(err.clone())
            .log();

            // Track H Story H2 — pre-check validate-before-compute → 422 narratif
            if let Some(resp) = try_build_conformity_response(&err) {
                return resp;
            }
            HttpResponse::BadRequest().json(serde_json::json!({
                "error": err
            }))
        }
    }
}

/// PUT /invoices/{id} - Update invoice draft (only if Draft or Rejected)
#[utoipa::path(
    put,
    path = "/invoices/{id}",
    tag = "Expenses",
    summary = "Modifier une facture brouillon ou rejetée",
    request_body = UpdateInvoiceDraftDto,
    responses(
        (status = 200, description = "Brouillon modifié"),
        (status = 400, description = "Requête invalide"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[put("/invoices/{id}")]
pub async fn update_invoice_draft(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
    dto: web::Json<UpdateInvoiceDraftDto>,
) -> impl Responder {
    if let Some(response) = verify_accountant_role(&user) {
        return response;
    }

    if let Err(errors) = dto.validate() {
        return HttpResponse::BadRequest().json(serde_json::json!({
            "error": "Validation failed",
            "details": errors.to_string()
        }));
    }

    match state
        .expense_use_cases
        .update_invoice_draft(*id, dto.into_inner())
        .await
    {
        Ok(invoice) => {
            AuditLogEntry::new(
                AuditEventType::InvoiceUpdated,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Invoice", *id)
            .log();

            HttpResponse::Ok().json(invoice)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

/// PUT /invoices/{id}/submit - Submit invoice for approval (Draft → PendingApproval)
#[utoipa::path(
    put,
    path = "/invoices/{id}/submit",
    tag = "Expenses",
    summary = "Soumettre une facture pour validation",
    request_body = SubmitForApprovalDto,
    responses(
        (status = 200, description = "Facture soumise"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[put("/invoices/{id}/submit")]
pub async fn submit_invoice_for_approval(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    if let Some(response) = verify_accountant_role(&user) {
        return response;
    }

    match state
        .expense_use_cases
        .submit_for_approval(*id, SubmitForApprovalDto {})
        .await
    {
        Ok(invoice) => {
            AuditLogEntry::new(
                AuditEventType::InvoiceSubmitted,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Invoice", *id)
            .log();

            HttpResponse::Ok().json(invoice)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

/// PUT /invoices/{id}/approve - Approve invoice (PendingApproval → Approved)
/// Only syndic or superadmin can approve
#[utoipa::path(
    put,
    path = "/invoices/{id}/approve",
    tag = "Expenses",
    summary = "Approuver une facture",
    request_body = ApproveInvoiceDto,
    responses(
        (status = 200, description = "Facture approuvée"),
        (status = 401, description = "Non authentifié"),
        (status = 403, description = "Rôle sans droit d'approbation"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[put("/invoices/{id}/approve")]
pub async fn approve_invoice(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    if let Some(response) = verify_syndic_role(&user) {
        return response;
    }

    let dto = ApproveInvoiceDto {
        approved_by_user_id: user.user_id.to_string(),
    };

    match state.expense_use_cases.approve_invoice(*id, dto).await {
        Ok(invoice) => {
            AuditLogEntry::new(
                AuditEventType::InvoiceApproved,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Invoice", *id)
            .log();

            HttpResponse::Ok().json(invoice)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

/// PUT /invoices/{id}/reject - Reject invoice with reason (PendingApproval → Rejected)
/// Only syndic or superadmin can reject
#[utoipa::path(
    put,
    path = "/invoices/{id}/reject",
    tag = "Expenses",
    summary = "Rejeter une facture avec motif",
    request_body = RejectInvoiceDto,
    responses(
        (status = 200, description = "Facture rejetée"),
        (status = 400, description = "Motif manquant"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[put("/invoices/{id}/reject")]
pub async fn reject_invoice(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
    dto: web::Json<RejectInvoiceDto>,
) -> impl Responder {
    if let Some(response) = verify_syndic_role(&user) {
        return response;
    }

    if let Err(errors) = dto.validate() {
        return HttpResponse::BadRequest().json(serde_json::json!({
            "error": "Validation failed",
            "details": errors.to_string()
        }));
    }

    let mut reject_dto = dto.into_inner();
    reject_dto.rejected_by_user_id = user.user_id.to_string();

    match state
        .expense_use_cases
        .reject_invoice(*id, reject_dto)
        .await
    {
        Ok(invoice) => {
            AuditLogEntry::new(
                AuditEventType::InvoiceRejected,
                Some(user.user_id),
                user.organization_id,
            )
            .with_resource("Invoice", *id)
            .log();

            HttpResponse::Ok().json(invoice)
        }
        Err(err) => HttpResponse::BadRequest().json(serde_json::json!({
            "error": err
        })),
    }
}

/// GET /invoices/pending - Get all pending invoices (for syndic dashboard)
/// Only syndic or superadmin can view pending invoices
#[utoipa::path(
    get,
    path = "/invoices/pending",
    tag = "Expenses",
    summary = "Lister les factures en attente d'approbation",
    responses(
        (status = 200, description = "Liste"),
        (status = 401, description = "Non authentifié"),
    ),
    security(("bearer_auth" = []))
)]
#[get("/invoices/pending")]
pub async fn get_pending_invoices(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
) -> impl Responder {
    if let Some(response) = verify_syndic_role(&user) {
        return response;
    }

    let organization_id = match user.require_organization() {
        Ok(org_id) => org_id,
        Err(e) => {
            return HttpResponse::Unauthorized().json(serde_json::json!({
                "error": e.to_string()
            }))
        }
    };

    match state
        .expense_use_cases
        .get_pending_invoices(organization_id)
        .await
    {
        Ok(pending_list) => HttpResponse::Ok().json(pending_list),
        Err(err) => HttpResponse::InternalServerError().json(serde_json::json!({
            "error": err
        })),
    }
}

/// GET /invoices/{id} - Get full invoice details (enriched with all fields)
#[utoipa::path(
    get,
    path = "/invoices/{id}",
    tag = "Expenses",
    summary = "Lire une facture",
    responses(
        (status = 200, description = "Facture"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[get("/invoices/{id}")]
pub async fn get_invoice(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
) -> impl Responder {
    match state.expense_use_cases.get_invoice(*id).await {
        Ok(Some(invoice)) => {
            // Hotfix #603 — multi-tenant isolation via ACP→organization resolution.
            if let Ok(building_id) = Uuid::parse_str(&invoice.building_id) {
                if let Ok(Some(building)) = state.building_use_cases.get_building(building_id).await
                {
                    let acp_id = match Uuid::parse_str(&building.acp_id) {
                        Ok(id) => id,
                        Err(_) => {
                            return HttpResponse::InternalServerError().json(serde_json::json!({
                                "error": "Invalid building.acp_id format"
                            }));
                        }
                    };
                    if let Err(err) =
                        verify_acp_org_access(&user, acp_id, &state.acp_use_cases).await
                    {
                        return err.error_response();
                    }
                }
            }
            HttpResponse::Ok().json(invoice)
        }
        Ok(None) => HttpResponse::NotFound().json(serde_json::json!({
            "error": "Invoice not found"
        })),
        Err(err) => HttpResponse::InternalServerError().json(serde_json::json!({
            "error": err
        })),
    }
}

/// Export Work Quote to PDF
///
/// GET /expenses/{expense_id}/export-quote-pdf?contractor_name={name}&contractor_contact={email}&timeline={description}
///
/// Generates a "Devis de Travaux" PDF for work-related expenses.
#[derive(Debug, Deserialize)]
pub struct ExportWorkQuoteQuery {
    pub contractor_name: String,
    pub contractor_contact: String,
    pub timeline: String, // e.g., "2-3 weeks" or "Délai: 15 jours ouvrables"
}

#[utoipa::path(
    get,
    path = "/expenses/{id}/export-quote-pdf",
    tag = "Expenses",
    summary = "Exporter un devis en PDF",
    responses(
        (status = 200, description = "PDF"),
        (status = 401, description = "Non authentifié"),
        (status = 404, description = "Introuvable"),
    ),
    security(("bearer_auth" = []))
)]
#[get("/expenses/{id}/export-quote-pdf")]
pub async fn export_work_quote_pdf(
    state: web::Data<AppState>,
    user: AuthenticatedUser,
    id: web::Path<Uuid>,
    query: web::Query<ExportWorkQuoteQuery>,
) -> impl Responder {
    use crate::domain::entities::{Building, Expense};
    use crate::domain::services::{QuoteLineItem, WorkQuoteExporter};

    let organization_id = match user.require_organization() {
        Ok(org_id) => org_id,
        Err(e) => {
            return HttpResponse::Unauthorized().json(serde_json::json!({
                "error": e.to_string()
            }))
        }
    };

    let expense_id = *id;

    // 1. Get expense
    let expense_dto = match state.expense_use_cases.get_expense(expense_id).await {
        Ok(Some(dto)) => dto,
        Ok(None) => {
            return HttpResponse::NotFound().json(serde_json::json!({
                "error": "Expense not found"
            }))
        }
        Err(err) => {
            return HttpResponse::InternalServerError().json(serde_json::json!({
                "error": err
            }))
        }
    };

    // 2. Parse expense DTO fields
    let expense_building_id = match Uuid::parse_str(&expense_dto.building_id) {
        Ok(id) => id,
        Err(e) => {
            return HttpResponse::BadRequest().json(serde_json::json!({
                "error": format!("Invalid building_id: {}", e)
            }))
        }
    };
    let expense_id_uuid = match Uuid::parse_str(&expense_dto.id) {
        Ok(id) => id,
        Err(e) => {
            return HttpResponse::BadRequest().json(serde_json::json!({
                "error": format!("Invalid expense_id: {}", e)
            }))
        }
    };

    // 3. Get building
    let building_dto = match state
        .building_use_cases
        .get_building(expense_building_id)
        .await
    {
        Ok(Some(dto)) => dto,
        Ok(None) => {
            return HttpResponse::NotFound().json(serde_json::json!({
                "error": "Building not found"
            }))
        }
        Err(err) => {
            return HttpResponse::InternalServerError().json(serde_json::json!({
                "error": err
            }))
        }
    };

    // Convert DTOs to domain entities — Story 1.2 : DTO field renamed
    // `organization_id` → `acp_id` (FK vers acps.id). `organization_id`
    // upstream (de require_organization()) reste utilisé pour audit
    // mais n'est plus stocké sur Building.
    let _ = organization_id;
    let building_acp_id = Uuid::parse_str(&building_dto.acp_id).unwrap_or_else(|_| Uuid::new_v4());

    let building_created_at = DateTime::parse_from_rfc3339(&building_dto.created_at)
        .map(|dt| dt.with_timezone(&Utc))
        .unwrap_or_else(|_| Utc::now());

    let building_updated_at = DateTime::parse_from_rfc3339(&building_dto.updated_at)
        .map(|dt| dt.with_timezone(&Utc))
        .unwrap_or_else(|_| Utc::now());

    let building_entity = Building {
        id: Uuid::parse_str(&building_dto.id).unwrap_or(expense_building_id),
        name: building_dto.name.clone(),
        address: building_dto.address,
        city: building_dto.city,
        postal_code: building_dto.postal_code,
        country: building_dto.country,
        total_units: building_dto.total_units,
        total_tantiemes: building_dto.total_tantiemes,
        construction_year: building_dto.construction_year,
        syndic_name: None,
        syndic_email: None,
        syndic_phone: None,
        syndic_address: None,
        syndic_office_hours: None,
        syndic_emergency_contact: None,
        slug: None,
        acp_id: building_acp_id,
        created_at: building_created_at,
        updated_at: building_updated_at,
    };

    let expense_date = DateTime::parse_from_rfc3339(&expense_dto.expense_date)
        .map(|dt| dt.with_timezone(&Utc))
        .unwrap_or_else(|_| Utc::now());

    let expense_entity = Expense {
        id: expense_id_uuid,
        acp_id: Uuid::parse_str(&expense_dto.acp_id).unwrap_or(organization_id),
        organization_id,
        building_id: expense_building_id,
        category: expense_dto.category.clone(),
        description: expense_dto.description.clone(),
        amount: expense_dto.amount,
        amount_excl_vat: None,
        vat_rate: None,
        vat_amount: None,
        amount_incl_vat: None,
        expense_date,
        invoice_date: None,
        due_date: None,
        paid_date: None,
        approval_status: expense_dto.approval_status.clone(),
        submitted_at: None,
        approved_by: None,
        approved_at: None,
        rejection_reason: None,
        payment_status: expense_dto.payment_status.clone(),
        supplier: expense_dto.supplier.clone(),
        invoice_number: expense_dto.invoice_number.clone(),
        account_code: expense_dto.account_code.clone(),
        contractor_report_id: None,
        created_at: Utc::now(),
        updated_at: Utc::now(),
    };

    // Create a single line item from expense amount (simplified for now)
    // Note: For full invoice support with line items, we would need to:
    // 1. Get the invoice via get_invoice()
    // 2. Add a repository method to fetch line items
    // For now, we use simplified single line item approach
    let quote_line_items: Vec<QuoteLineItem> = vec![QuoteLineItem {
        description: expense_dto.description.clone(),
        quantity: rust_decimal::Decimal::ONE,
        unit_price: expense_dto.amount,
        total: expense_dto.amount,
    }];

    // 4. Generate PDF
    match WorkQuoteExporter::export_to_pdf(
        &building_entity,
        &expense_entity,
        &quote_line_items,
        &query.contractor_name,
        &query.contractor_contact,
        &query.timeline,
    ) {
        Ok(pdf_bytes) => {
            // Audit log
            AuditLogEntry::new(
                AuditEventType::ReportGenerated,
                Some(user.user_id),
                Some(organization_id),
            )
            .with_resource("Expense", expense_id)
            .with_metadata(serde_json::json!({
                "report_type": "work_quote_pdf",
                "building_name": building_entity.name,
                "contractor_name": query.contractor_name,
                "amount": expense_dto.amount
            }))
            .log();

            HttpResponse::Ok()
                .content_type("application/pdf")
                .insert_header((
                    "Content-Disposition",
                    format!(
                        "attachment; filename=\"Devis_Travaux_{}_{}.pdf\"",
                        building_entity.name.replace(' ', "_"),
                        expense_entity.id
                    ),
                ))
                .body(pdf_bytes)
        }
        Err(err) => HttpResponse::InternalServerError().json(serde_json::json!({
            "error": format!("Failed to generate PDF: {}", err)
        })),
    }
}