koprogo_api/application/use_cases/

account_use_cases.rs

// Application Use Cases: Account Management
//
// CREDITS & ATTRIBUTION:
// Business logic inspired by the Noalyss project (https://gitlab.com/noalyss/noalyss)
// Noalyss is a free accounting software for Belgian and French accounting
// License: GPL-2.0-or-later (GNU General Public License version 2 or later)
// Copyright: (C) 1989, 1991 Free Software Foundation, Inc.
// Copyright: Dany De Bontridder <dany@alchimerys.eu>

use crate::application::ports::AccountRepository;
use crate::domain::entities::{Account, AccountType};
use std::sync::Arc;
use uuid::Uuid;

/// Use cases for managing accounts in the Belgian PCMN
///
/// This orchestrates account operations, including:
/// - CRUD operations for accounts
/// - Seeding Belgian PCMN chart of accounts (inspired by Noalyss mono-belge.sql)
/// - Hierarchical account management
/// - Account validation and business rules
pub struct AccountUseCases {
    repository: Arc<dyn AccountRepository>,
}

impl AccountUseCases {
    pub fn new(repository: Arc<dyn AccountRepository>) -> Self {
        Self { repository }
    }

    /// Create a new account
    ///
    /// # Arguments
    /// * `code` - Account code (e.g., "700", "604001")
    /// * `label` - Account description
    /// * `parent_code` - Optional parent account code
    /// * `account_type` - Account classification
    /// * `direct_use` - Whether account can be used in transactions
    /// * `organization_id` - Organization ID
    ///
    /// # Returns
    /// Created account or error message
    pub async fn create_account(
        &self,
        code: String,
        label: String,
        parent_code: Option<String>,
        account_type: AccountType,
        direct_use: bool,
        organization_id: Uuid,
    ) -> Result<Account, String> {
        // Validation: check if account code already exists
        if self.repository.exists(&code, organization_id).await? {
            return Err(format!(
                "Account code '{}' already exists for this organization",
                code
            ));
        }

        // Validation: if parent_code is specified, ensure it exists
        if let Some(ref parent) = parent_code {
            if !self.repository.exists(parent, organization_id).await? {
                return Err(format!("Parent account code '{}' does not exist", parent));
            }
        }

        // Create domain entity with validation
        let account = Account::new(
            code,
            label,
            parent_code,
            account_type,
            direct_use,
            organization_id,
        )?;

        // Persist to database
        self.repository.create(&account).await
    }

    /// Get account by ID
    pub async fn get_account(&self, id: Uuid) -> Result<Option<Account>, String> {
        self.repository.find_by_id(id).await
    }

    /// Get account by code within an organization
    pub async fn get_account_by_code(
        &self,
        code: &str,
        organization_id: Uuid,
    ) -> Result<Option<Account>, String> {
        self.repository.find_by_code(code, organization_id).await
    }

    /// List all accounts for an organization
    pub async fn list_accounts(&self, organization_id: Uuid) -> Result<Vec<Account>, String> {
        self.repository.find_by_organization(organization_id).await
    }

    /// List accounts by type (for financial reports)
    pub async fn list_accounts_by_type(
        &self,
        account_type: AccountType,
        organization_id: Uuid,
    ) -> Result<Vec<Account>, String> {
        self.repository
            .find_by_type(account_type, organization_id)
            .await
    }

    /// List child accounts of a parent
    pub async fn list_child_accounts(
        &self,
        parent_code: &str,
        organization_id: Uuid,
    ) -> Result<Vec<Account>, String> {
        self.repository
            .find_by_parent_code(parent_code, organization_id)
            .await
    }

    /// List accounts that can be used directly in transactions
    pub async fn list_direct_use_accounts(
        &self,
        organization_id: Uuid,
    ) -> Result<Vec<Account>, String> {
        self.repository
            .find_direct_use_accounts(organization_id)
            .await
    }

    /// Search accounts by code pattern (e.g., "60%" for all class 6 accounts)
    pub async fn search_accounts(
        &self,
        code_pattern: &str,
        organization_id: Uuid,
    ) -> Result<Vec<Account>, String> {
        self.repository
            .search_by_code_pattern(code_pattern, organization_id)
            .await
    }

    /// Update an existing account
    pub async fn update_account(
        &self,
        id: Uuid,
        label: Option<String>,
        parent_code: Option<Option<String>>,
        account_type: Option<AccountType>,
        direct_use: Option<bool>,
    ) -> Result<Account, String> {
        let mut account = self
            .repository
            .find_by_id(id)
            .await?
            .ok_or_else(|| "Account not found".to_string())?;

        // Validation: if parent_code is being changed, ensure it exists
        if let Some(Some(ref new_parent)) = parent_code {
            if !self
                .repository
                .exists(new_parent, account.organization_id)
                .await?
            {
                return Err(format!(
                    "Parent account code '{}' does not exist",
                    new_parent
                ));
            }
        }

        account.update(label, parent_code, account_type, direct_use)?;
        self.repository.update(&account).await
    }

    /// Delete an account
    ///
    /// Validates:
    /// - Account has no children
    /// - Account is not used in expenses
    pub async fn delete_account(&self, id: Uuid) -> Result<(), String> {
        self.repository.delete(id).await
    }

    /// Count accounts in an organization
    pub async fn count_accounts(&self, organization_id: Uuid) -> Result<i64, String> {
        self.repository.count_by_organization(organization_id).await
    }

    /// Seed Belgian PCMN (Plan Comptable Minimum Normalisé) for a new organization
    ///
    /// Creates a standard chart of accounts for Belgian property management.
    /// This seed data is inspired by Noalyss' mono-belge.sql, curated for
    /// property management (syndic de copropriété).
    ///
    /// # Arguments
    /// * `organization_id` - Organization to seed accounts for
    ///
    /// # Returns
    /// Number of accounts created or error message
    ///
    /// # Belgian PCMN Structure
    /// - Class 1: Liabilities (Capital, Reserves)
    /// - Classes 2-5: Assets (Fixed assets, Receivables, Bank)
    /// - Class 6: Expenses (Electricity, Maintenance, Insurance, etc.)
    /// - Class 7: Revenue (Regular fees, Extraordinary fees, Interest)
    ///
    /// Reference: Noalyss contrib/mono-dossier/mono-belge.sql
    pub async fn seed_belgian_pcmn(&self, organization_id: Uuid) -> Result<i64, String> {
        // Check if accounts already exist
        let existing_count = self
            .repository
            .count_by_organization(organization_id)
            .await?;
        if existing_count > 0 {
            return Err(format!(
                "Organization already has {} accounts. Cannot seed PCMN.",
                existing_count
            ));
        }

        // Belgian PCMN seed data inspired by Noalyss mono-belge.sql
        // Curated for property management (copropriété/mede-eigendom)
        let accounts_data = get_belgian_pcmn_seed_data();

        let mut created_count = 0i64;

        for (code, label, parent_code, account_type, direct_use) in accounts_data {
            let account = Account::new(
                code.to_string(),
                label.to_string(),
                parent_code.map(|s| s.to_string()),
                account_type,
                direct_use,
                organization_id,
            )?;

            self.repository.create(&account).await?;
            created_count += 1;
        }

        Ok(created_count)
    }
}

/// Belgian PCMN seed data for property management
///
/// Returns: Vec<(code, label, parent_code, account_type, direct_use)>
///
/// CREDITS: Inspired by Noalyss contrib/mono-dossier/mono-belge.sql
/// License: GPL-2.0-or-later
/// Copyright: Dany De Bontridder <dany@alchimerys.eu>
///
/// This is a curated subset of the Belgian PCMN relevant for property management.
/// Full PCMN has 100+ accounts; we focus on the most common for syndic operations.
fn get_belgian_pcmn_seed_data() -> Vec<(
    &'static str,
    &'static str,
    Option<&'static str>,
    AccountType,
    bool,
)> {
    vec![
        // ====================================================================
        // CLASS 1: LIABILITIES (Capital, Reserves, Provisions)
        // ====================================================================
        (
            "1",
            "Fonds propres, provisions pour risques et charges",
            None,
            AccountType::Liability,
            false,
        ),
        ("10", "Capital", Some("1"), AccountType::Liability, false),
        (
            "100",
            "Capital souscrit",
            Some("10"),
            AccountType::Liability,
            true,
        ),
        ("13", "Réserves", Some("1"), AccountType::Liability, false),
        (
            "130",
            "Réserve légale",
            Some("13"),
            AccountType::Liability,
            true,
        ),
        (
            "131",
            "Réserves disponibles",
            Some("13"),
            AccountType::Liability,
            true,
        ),
        (
            "14",
            "Provisions pour risques et charges",
            Some("1"),
            AccountType::Liability,
            true,
        ),
        // ====================================================================
        // CLASS 2-3: FIXED ASSETS & INVENTORY (minimal for property mgmt)
        // ====================================================================
        ("2", "Actifs immobilisés", None, AccountType::Asset, false),
        (
            "22",
            "Terrains et constructions",
            Some("2"),
            AccountType::Asset,
            false,
        ),
        ("220", "Terrains", Some("22"), AccountType::Asset, true),
        ("221", "Constructions", Some("22"), AccountType::Asset, true),
        // ====================================================================
        // CLASS 4: RECEIVABLES & PAYABLES
        // ====================================================================
        (
            "4",
            "Créances et dettes à un an au plus",
            None,
            AccountType::Asset,
            false,
        ),
        // Owners receivables (appels de fonds)
        (
            "40",
            "Créances commerciales",
            Some("4"),
            AccountType::Asset,
            false,
        ),
        (
            "400",
            "Copropriétaires - Appels de fonds",
            Some("40"),
            AccountType::Asset,
            true,
        ),
        (
            "401",
            "Copropriétaires - Charges courantes",
            Some("40"),
            AccountType::Asset,
            true,
        ),
        (
            "402",
            "Copropriétaires - Travaux extraordinaires",
            Some("40"),
            AccountType::Asset,
            true,
        ),
        (
            "409",
            "Réductions de valeur actées (provisions)",
            Some("40"),
            AccountType::Asset,
            true,
        ),
        // Suppliers payables
        (
            "44",
            "Dettes commerciales",
            Some("4"),
            AccountType::Liability,
            false,
        ),
        (
            "440",
            "Fournisseurs",
            Some("44"),
            AccountType::Liability,
            true,
        ),
        (
            "441",
            "Effets à payer",
            Some("44"),
            AccountType::Liability,
            true,
        ),
        // VAT
        (
            "45",
            "Dettes fiscales, salariales et sociales",
            Some("4"),
            AccountType::Liability,
            false,
        ),
        (
            "451",
            "TVA à payer",
            Some("45"),
            AccountType::Liability,
            true,
        ),
        (
            "411",
            "TVA récupérable",
            Some("4"),
            AccountType::Asset,
            true,
        ),
        // Other receivables/payables
        (
            "46",
            "Acomptes reçus",
            Some("4"),
            AccountType::Liability,
            true,
        ),
        (
            "47",
            "Dettes diverses",
            Some("4"),
            AccountType::Liability,
            true,
        ),
        // ====================================================================
        // CLASS 5: BANK & CASH
        // ====================================================================
        (
            "5",
            "Placements de trésorerie et valeurs disponibles",
            None,
            AccountType::Asset,
            false,
        ),
        (
            "55",
            "Établissements de crédit",
            Some("5"),
            AccountType::Asset,
            false,
        ),
        (
            "550",
            "Compte courant bancaire",
            Some("55"),
            AccountType::Asset,
            true,
        ),
        (
            "551",
            "Compte épargne",
            Some("55"),
            AccountType::Asset,
            true,
        ),
        ("57", "Caisse", Some("5"), AccountType::Asset, true),
        // ====================================================================
        // CLASS 6: EXPENSES (Charges) - CORE FOR PROPERTY MANAGEMENT
        // ====================================================================
        ("6", "Charges", None, AccountType::Expense, false),
        // Class 60: Purchases and inventory
        (
            "60",
            "Approvisionnements et marchandises",
            Some("6"),
            AccountType::Expense,
            false,
        ),
        (
            "604",
            "Achats de fournitures",
            Some("60"),
            AccountType::Expense,
            false,
        ),
        (
            "604001",
            "Électricité",
            Some("604"),
            AccountType::Expense,
            true,
        ),
        ("604002", "Eau", Some("604"), AccountType::Expense, true),
        (
            "604003",
            "Gaz / Chauffage",
            Some("604"),
            AccountType::Expense,
            true,
        ),
        ("604004", "Mazout", Some("604"), AccountType::Expense, true),
        // Class 61: Services and goods
        (
            "61",
            "Services et biens divers",
            Some("6"),
            AccountType::Expense,
            false,
        ),
        (
            "610",
            "Loyers et charges locatives",
            Some("61"),
            AccountType::Expense,
            false,
        ),
        (
            "610001",
            "Loyer local syndic",
            Some("610"),
            AccountType::Expense,
            true,
        ),
        (
            "610002",
            "Charges locatives",
            Some("610"),
            AccountType::Expense,
            true,
        ),
        (
            "611",
            "Entretien et réparations",
            Some("61"),
            AccountType::Expense,
            false,
        ),
        (
            "611001",
            "Entretien bâtiment",
            Some("611"),
            AccountType::Expense,
            true,
        ),
        (
            "611002",
            "Entretien ascenseur",
            Some("611"),
            AccountType::Expense,
            true,
        ),
        (
            "611003",
            "Entretien chauffage",
            Some("611"),
            AccountType::Expense,
            true,
        ),
        (
            "611004",
            "Entretien espaces verts",
            Some("611"),
            AccountType::Expense,
            true,
        ),
        (
            "611005",
            "Nettoyage parties communes",
            Some("611"),
            AccountType::Expense,
            true,
        ),
        (
            "612",
            "Fournitures faites à l'entreprise",
            Some("61"),
            AccountType::Expense,
            false,
        ),
        (
            "612001",
            "Petit matériel",
            Some("612"),
            AccountType::Expense,
            true,
        ),
        (
            "612002",
            "Produits d'entretien",
            Some("612"),
            AccountType::Expense,
            true,
        ),
        (
            "613",
            "Rétributions de tiers",
            Some("61"),
            AccountType::Expense,
            false,
        ),
        (
            "613001",
            "Honoraires syndic",
            Some("613"),
            AccountType::Expense,
            true,
        ),
        (
            "613002",
            "Honoraires experts",
            Some("613"),
            AccountType::Expense,
            true,
        ),
        (
            "613003",
            "Honoraires comptables",
            Some("613"),
            AccountType::Expense,
            true,
        ),
        (
            "613004",
            "Honoraires avocats",
            Some("613"),
            AccountType::Expense,
            true,
        ),
        (
            "614",
            "Publicité et propagande",
            Some("61"),
            AccountType::Expense,
            true,
        ),
        ("615", "Assurances", Some("61"), AccountType::Expense, false),
        (
            "615001",
            "Assurance incendie immeuble",
            Some("615"),
            AccountType::Expense,
            true,
        ),
        (
            "615002",
            "Assurance responsabilité civile",
            Some("615"),
            AccountType::Expense,
            true,
        ),
        (
            "615003",
            "Assurance tous risques",
            Some("615"),
            AccountType::Expense,
            true,
        ),
        (
            "617",
            "Personnel intérimaire",
            Some("61"),
            AccountType::Expense,
            true,
        ),
        (
            "618",
            "Rémunérations, charges sociales et pensions",
            Some("61"),
            AccountType::Expense,
            false,
        ),
        (
            "618001",
            "Salaires personnel",
            Some("618"),
            AccountType::Expense,
            true,
        ),
        (
            "618002",
            "Charges sociales",
            Some("618"),
            AccountType::Expense,
            true,
        ),
        (
            "618003",
            "Assurances sociales",
            Some("618"),
            AccountType::Expense,
            true,
        ),
        (
            "619",
            "Autres charges d'exploitation",
            Some("61"),
            AccountType::Expense,
            false,
        ),
        (
            "619001",
            "Frais postaux",
            Some("619"),
            AccountType::Expense,
            true,
        ),
        (
            "619002",
            "Frais bancaires",
            Some("619"),
            AccountType::Expense,
            true,
        ),
        (
            "619003",
            "Taxes et impôts divers",
            Some("619"),
            AccountType::Expense,
            true,
        ),
        // Class 62: Depreciation
        (
            "62",
            "Amortissements, réductions de valeur",
            Some("6"),
            AccountType::Expense,
            false,
        ),
        (
            "620",
            "Dotations aux amortissements",
            Some("62"),
            AccountType::Expense,
            true,
        ),
        // Class 63: Provisions
        (
            "63",
            "Provisions pour risques et charges",
            Some("6"),
            AccountType::Expense,
            false,
        ),
        (
            "630",
            "Dotations aux provisions",
            Some("63"),
            AccountType::Expense,
            true,
        ),
        // Class 64-65: Financial expenses & Other
        (
            "64",
            "Autres charges d'exploitation",
            Some("6"),
            AccountType::Expense,
            true,
        ),
        (
            "65",
            "Charges financières",
            Some("6"),
            AccountType::Expense,
            false,
        ),
        (
            "650",
            "Charges des dettes",
            Some("65"),
            AccountType::Expense,
            true,
        ),
        (
            "651",
            "Réductions de valeur sur actifs circulants",
            Some("65"),
            AccountType::Expense,
            true,
        ),
        // Class 66-67: Exceptional & Tax expenses
        (
            "66",
            "Charges exceptionnelles",
            Some("6"),
            AccountType::Expense,
            true,
        ),
        (
            "67",
            "Impôts sur le résultat",
            Some("6"),
            AccountType::Expense,
            true,
        ),
        // ====================================================================
        // CLASS 7: REVENUE (Produits) - CORE FOR PROPERTY MANAGEMENT
        // ====================================================================
        ("7", "Produits", None, AccountType::Revenue, false),
        // Class 70: Operating revenue (appels de fonds)
        (
            "70",
            "Chiffre d'affaires",
            Some("7"),
            AccountType::Revenue,
            false,
        ),
        (
            "700",
            "Appels de fonds copropriétaires",
            Some("70"),
            AccountType::Revenue,
            false,
        ),
        (
            "700001",
            "Appels de fonds ordinaires",
            Some("700"),
            AccountType::Revenue,
            true,
        ),
        (
            "700002",
            "Appels de fonds extraordinaires",
            Some("700"),
            AccountType::Revenue,
            true,
        ),
        (
            "700003",
            "Provisions mensuelles",
            Some("700"),
            AccountType::Revenue,
            true,
        ),
        // Class 74: Other operating revenue
        (
            "74",
            "Autres produits d'exploitation",
            Some("7"),
            AccountType::Revenue,
            false,
        ),
        (
            "740",
            "Subsides d'exploitation",
            Some("74"),
            AccountType::Revenue,
            true,
        ),
        (
            "743",
            "Indemnités perçues",
            Some("74"),
            AccountType::Revenue,
            true,
        ),
        (
            "744",
            "Récupération charges antérieures",
            Some("74"),
            AccountType::Revenue,
            true,
        ),
        // Class 75: Financial revenue
        (
            "75",
            "Produits financiers",
            Some("7"),
            AccountType::Revenue,
            false,
        ),
        (
            "750",
            "Produits des immobilisations financières",
            Some("75"),
            AccountType::Revenue,
            true,
        ),
        (
            "751",
            "Produits des actifs circulants",
            Some("75"),
            AccountType::Revenue,
            false,
        ),
        (
            "751001",
            "Intérêts compte bancaire",
            Some("751"),
            AccountType::Revenue,
            true,
        ),
        (
            "751002",
            "Intérêts compte épargne",
            Some("751"),
            AccountType::Revenue,
            true,
        ),
        // Class 76-77: Exceptional & Other revenue
        (
            "76",
            "Produits exceptionnels",
            Some("7"),
            AccountType::Revenue,
            true,
        ),
        (
            "77",
            "Régularisation d'impôts",
            Some("7"),
            AccountType::Revenue,
            true,
        ),
        // ====================================================================
        // CLASS 9: OFF-BALANCE (Memorandum accounts)
        // ====================================================================
        (
            "9",
            "Comptes hors bilan",
            None,
            AccountType::OffBalance,
            false,
        ),
        (
            "90",
            "Droits et engagements",
            Some("9"),
            AccountType::OffBalance,
            true,
        ),
    ]
}

// ============================================================================
// UNIT TESTS
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_belgian_pcmn_seed_data_structure() {
        let data = get_belgian_pcmn_seed_data();

        // Should have substantial number of accounts
        assert!(data.len() >= 80, "Should have at least 80 accounts");

        // Check root accounts exist
        let codes: Vec<&str> = data.iter().map(|(code, _, _, _, _)| *code).collect();
        assert!(codes.contains(&"1"), "Should have class 1 (Liabilities)");
        assert!(codes.contains(&"6"), "Should have class 6 (Expenses)");
        assert!(codes.contains(&"7"), "Should have class 7 (Revenue)");

        // Check essential property management accounts
        assert!(codes.contains(&"604001"), "Should have Electricity account");
        assert!(
            codes.contains(&"611002"),
            "Should have Elevator maintenance"
        );
        assert!(codes.contains(&"615001"), "Should have Building insurance");
        assert!(
            codes.contains(&"700001"),
            "Should have Regular fees revenue"
        );
    }

    #[test]
    fn test_account_hierarchy_consistency() {
        let data = get_belgian_pcmn_seed_data();
        let codes: Vec<&str> = data.iter().map(|(code, _, _, _, _)| *code).collect();

        // For each account with a parent, ensure parent exists in the list
        for (code, _, parent_code, _, _) in &data {
            if let Some(parent) = parent_code {
                assert!(
                    codes.contains(parent),
                    "Account '{}' references non-existent parent '{}'",
                    code,
                    parent
                );
            }
        }
    }

    #[test]
    fn test_account_types_match_pcmn_classes() {
        let data = get_belgian_pcmn_seed_data();

        for (code, _, _, account_type, _) in &data {
            let detected_type = AccountType::from_code(code);
            // Parent accounts might have different types than detected
            // This is OK, we're just checking consistency for leaf accounts
            if code.len() > 1 {
                // For detailed accounts, type should generally match detection
                // (Some exceptions exist for special accounts)
                let _ = (account_type, detected_type); // Just ensure no panic
            }
        }
    }
}