datasynth_core/models/
journal_entry.rs

1//! Journal Entry data structures for General Ledger postings.
2//!
3//! This module defines the core journal entry structures that form the basis
4//! of double-entry bookkeeping. Each journal entry consists of a header and
5//! one or more line items that must balance (total debits = total credits).
6
7use chrono::{DateTime, NaiveDate, NaiveDateTime, Utc};
8use rust_decimal::Decimal;
9use serde::{Deserialize, Serialize};
10use smallvec::SmallVec;
11use uuid::Uuid;
12
13use super::anomaly::FraudType;
14use super::approval::ApprovalWorkflow;
15
16/// Typed reference to a source document that originated this journal entry.
17///
18/// Allows downstream consumers to identify the document type without
19/// parsing prefix strings from the `reference` field.
20#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
21pub enum DocumentRef {
22    /// Purchase order reference (e.g., "PO-2024-000001")
23    PurchaseOrder(String),
24    /// Vendor invoice reference (e.g., "INV-2024-000001")
25    VendorInvoice(String),
26    /// Customer invoice / sales order reference (e.g., "SO-2024-000001")
27    CustomerInvoice(String),
28    /// Goods receipt reference (e.g., "GR-2024-000001")
29    GoodsReceipt(String),
30    /// Delivery reference
31    Delivery(String),
32    /// Payment reference (e.g., "PAY-2024-000001")
33    Payment(String),
34    /// Receipt reference
35    Receipt(String),
36    /// Manual entry with no source document
37    Manual,
38}
39
40impl DocumentRef {
41    /// Parse a reference string into a `DocumentRef` based on known prefixes.
42    ///
43    /// Returns `None` if the prefix is not recognized as a typed document reference.
44    pub fn parse(reference: &str) -> Option<Self> {
45        if reference.starts_with("PO-") || reference.starts_with("PO ") {
46            Some(Self::PurchaseOrder(reference.to_string()))
47        } else if reference.starts_with("INV-") || reference.starts_with("INV ") {
48            Some(Self::VendorInvoice(reference.to_string()))
49        } else if reference.starts_with("SO-") || reference.starts_with("SO ") {
50            Some(Self::CustomerInvoice(reference.to_string()))
51        } else if reference.starts_with("GR-") || reference.starts_with("GR ") {
52            Some(Self::GoodsReceipt(reference.to_string()))
53        } else if reference.starts_with("PAY-") || reference.starts_with("PAY ") {
54            Some(Self::Payment(reference.to_string()))
55        } else {
56            None
57        }
58    }
59
60    /// Return the inner document identifier, if any. `Manual` returns `None`.
61    pub fn document_id(&self) -> Option<&str> {
62        match self {
63            Self::PurchaseOrder(id)
64            | Self::VendorInvoice(id)
65            | Self::CustomerInvoice(id)
66            | Self::GoodsReceipt(id)
67            | Self::Delivery(id)
68            | Self::Payment(id)
69            | Self::Receipt(id) => Some(id.as_str()),
70            Self::Manual => None,
71        }
72    }
73}
74
75/// Source of a journal entry transaction.
76///
77/// Distinguishes between manual human entries and automated system postings,
78/// which is critical for audit trail analysis and fraud detection.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
80#[serde(rename_all = "snake_case")]
81pub enum TransactionSource {
82    /// Manual entry by human user during working hours
83    #[default]
84    Manual,
85    /// Automated system posting (interfaces, batch jobs, EDI)
86    Automated,
87    /// Recurring scheduled posting (depreciation, amortization)
88    Recurring,
89    /// Reversal of a previous entry
90    Reversal,
91    /// Period-end adjustment entry
92    Adjustment,
93    /// Statistical posting (memo only, no financial impact)
94    Statistical,
95}
96
97impl std::fmt::Display for TransactionSource {
98    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
99        match self {
100            Self::Manual => write!(f, "manual"),
101            Self::Automated => write!(f, "automated"),
102            Self::Recurring => write!(f, "recurring"),
103            Self::Reversal => write!(f, "reversal"),
104            Self::Adjustment => write!(f, "adjustment"),
105            Self::Statistical => write!(f, "statistical"),
106        }
107    }
108}
109
110// Note: FraudType is defined in anomaly.rs and re-exported from mod.rs
111// Use `crate::models::FraudType` for fraud type classification.
112
113/// Business process that originated the transaction.
114///
115/// Aligns with standard enterprise process frameworks for process mining
116/// and analytics integration.
117#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
118#[serde(rename_all = "UPPERCASE")]
119pub enum BusinessProcess {
120    /// Order-to-Cash: sales, billing, accounts receivable
121    O2C,
122    /// Procure-to-Pay: purchasing, accounts payable
123    P2P,
124    /// Record-to-Report: GL, consolidation, reporting
125    #[default]
126    R2R,
127    /// Hire-to-Retire: payroll, HR accounting
128    H2R,
129    /// Acquire-to-Retire: fixed assets, depreciation
130    A2R,
131    /// Source-to-Contract: sourcing, supplier qualification, RFx
132    S2C,
133    /// Manufacturing: production orders, quality, cycle counts
134    #[serde(rename = "MFG")]
135    Mfg,
136    /// Banking operations: KYC/AML, accounts, transactions
137    #[serde(rename = "BANK")]
138    Bank,
139    /// Audit engagement lifecycle
140    #[serde(rename = "AUDIT")]
141    Audit,
142    /// Treasury operations
143    Treasury,
144    /// Tax accounting
145    Tax,
146    /// Intercompany transactions
147    Intercompany,
148    /// Project accounting lifecycle
149    #[serde(rename = "PROJECT")]
150    ProjectAccounting,
151    /// ESG / Sustainability reporting
152    #[serde(rename = "ESG")]
153    Esg,
154}
155
156/// Document type classification for journal entries.
157///
158/// Standard SAP-compatible document type codes.
159#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
160pub struct DocumentType {
161    /// Two-character document type code (e.g., "SA", "KR", "DR")
162    pub code: String,
163    /// Human-readable description
164    pub description: String,
165    /// Associated business process
166    pub business_process: BusinessProcess,
167    /// Is this a reversal document type
168    pub is_reversal: bool,
169}
170
171impl DocumentType {
172    /// Standard GL account document
173    pub fn gl_account() -> Self {
174        Self {
175            code: "SA".to_string(),
176            description: "G/L Account Document".to_string(),
177            business_process: BusinessProcess::R2R,
178            is_reversal: false,
179        }
180    }
181
182    /// Vendor invoice
183    pub fn vendor_invoice() -> Self {
184        Self {
185            code: "KR".to_string(),
186            description: "Vendor Invoice".to_string(),
187            business_process: BusinessProcess::P2P,
188            is_reversal: false,
189        }
190    }
191
192    /// Customer invoice
193    pub fn customer_invoice() -> Self {
194        Self {
195            code: "DR".to_string(),
196            description: "Customer Invoice".to_string(),
197            business_process: BusinessProcess::O2C,
198            is_reversal: false,
199        }
200    }
201
202    /// Vendor payment
203    pub fn vendor_payment() -> Self {
204        Self {
205            code: "KZ".to_string(),
206            description: "Vendor Payment".to_string(),
207            business_process: BusinessProcess::P2P,
208            is_reversal: false,
209        }
210    }
211
212    /// Customer payment
213    pub fn customer_payment() -> Self {
214        Self {
215            code: "DZ".to_string(),
216            description: "Customer Payment".to_string(),
217            business_process: BusinessProcess::O2C,
218            is_reversal: false,
219        }
220    }
221
222    /// Asset posting
223    pub fn asset_posting() -> Self {
224        Self {
225            code: "AA".to_string(),
226            description: "Asset Posting".to_string(),
227            business_process: BusinessProcess::A2R,
228            is_reversal: false,
229        }
230    }
231
232    /// Payroll posting
233    pub fn payroll() -> Self {
234        Self {
235            code: "PR".to_string(),
236            description: "Payroll Document".to_string(),
237            business_process: BusinessProcess::H2R,
238            is_reversal: false,
239        }
240    }
241}
242
243/// Header information for a journal entry document.
244///
245/// Contains all metadata about the posting including timing, user, and
246/// organizational assignment.
247#[derive(Debug, Clone, Serialize, Deserialize)]
248pub struct JournalEntryHeader {
249    /// Unique identifier for this journal entry (UUID v7 for time-ordering)
250    pub document_id: Uuid,
251
252    /// Company code this entry belongs to
253    pub company_code: String,
254
255    /// Fiscal year (4-digit)
256    pub fiscal_year: u16,
257
258    /// Fiscal period (1-12, or 13-16 for special periods)
259    pub fiscal_period: u8,
260
261    /// Posting date (when the entry affects the books)
262    pub posting_date: NaiveDate,
263
264    /// Document date (date on source document)
265    pub document_date: NaiveDate,
266
267    /// Entry timestamp (when created in system)
268    #[serde(with = "crate::serde_timestamp::utc")]
269    pub created_at: DateTime<Utc>,
270
271    /// Document type code
272    pub document_type: String,
273
274    /// Transaction currency (ISO 4217)
275    pub currency: String,
276
277    /// Exchange rate to local currency (1.0 if same currency)
278    #[serde(with = "crate::serde_decimal")]
279    pub exchange_rate: Decimal,
280
281    /// Reference document number (external reference)
282    pub reference: Option<String>,
283
284    /// Header text/description
285    pub header_text: Option<String>,
286
287    /// User who created the entry
288    pub created_by: String,
289
290    /// User persona classification for behavioral analysis
291    pub user_persona: String,
292
293    /// Transaction source (manual vs automated)
294    pub source: TransactionSource,
295
296    /// Business process reference
297    pub business_process: Option<BusinessProcess>,
298
299    /// Ledger (0L = Leading Ledger)
300    pub ledger: String,
301
302    /// Is this entry part of a fraud scenario
303    pub is_fraud: bool,
304
305    /// Fraud type if applicable
306    pub fraud_type: Option<FraudType>,
307
308    /// Whether `is_fraud` was propagated from a source document (document-level
309    /// fraud injection) rather than injected directly onto this line.
310    /// Used by downstream consumers to distinguish scheme-level from
311    /// slip-level fraud patterns.
312    #[serde(default)]
313    pub is_fraud_propagated: bool,
314
315    /// When `is_fraud_propagated` is true, the external document ID
316    /// (PO number, invoice number, etc.) that was the origin of the fraud.
317    #[serde(default, skip_serializing_if = "Option::is_none")]
318    pub fraud_source_document_id: Option<String>,
319
320    // --- Anomaly Tracking Fields ---
321    /// Whether this entry has an injected anomaly
322    #[serde(default)]
323    pub is_anomaly: bool,
324
325    /// Unique anomaly identifier for label linkage
326    #[serde(default)]
327    pub anomaly_id: Option<String>,
328
329    /// Type of anomaly if applicable (serialized enum name)
330    #[serde(default)]
331    pub anomaly_type: Option<String>,
332
333    /// Simulation batch ID for traceability
334    pub batch_id: Option<Uuid>,
335
336    // --- ISA 240 Audit Flags ---
337    /// Whether this is a manual journal entry (vs automated/system-generated).
338    /// Manual entries are higher fraud risk per ISA 240.32(a).
339    #[serde(default)]
340    pub is_manual: bool,
341
342    /// Whether this entry was posted after the period-end close date.
343    /// Post-closing entries require additional scrutiny per ISA 240.
344    #[serde(default)]
345    pub is_post_close: bool,
346
347    /// Source system/module that originated this entry.
348    /// Examples: "SAP-FI", "SAP-MM", "SAP-SD", "manual", "interface", "spreadsheet"
349    #[serde(default)]
350    pub source_system: String,
351
352    /// Timestamp when the entry was created (may differ from posting_date).
353    /// For automated entries this is typically before posting_date; for manual
354    /// entries created_date and posting_date are often on the same day.
355    #[serde(default, with = "crate::serde_timestamp::naive::option")]
356    pub created_date: Option<NaiveDateTime>,
357
358    // --- Internal Controls / SOX Compliance Fields ---
359    /// Internal control IDs that apply to this transaction
360    #[serde(default)]
361    pub control_ids: Vec<String>,
362
363    /// Whether this is a SOX-relevant transaction
364    #[serde(default)]
365    pub sox_relevant: bool,
366
367    /// Control status for this transaction
368    #[serde(default)]
369    pub control_status: super::internal_control::ControlStatus,
370
371    /// Whether a Segregation of Duties violation occurred
372    #[serde(default)]
373    pub sod_violation: bool,
374
375    /// Type of SoD conflict if violation occurred
376    #[serde(default)]
377    pub sod_conflict_type: Option<super::sod::SodConflictType>,
378
379    /// Whether this is a consolidation elimination entry
380    #[serde(default)]
381    pub is_elimination: bool,
382
383    // --- Intercompany Pair Linkage (group audit v5.0, Task 3.1) ---
384    /// Intercompany pair identifier. Set on both seller-side and buyer-side JEs
385    /// that are two halves of the same IC transaction. Aggregate-phase matching
386    /// joins JEs on this value. `None` for non-IC transactions.
387    #[serde(default, skip_serializing_if = "Option::is_none")]
388    pub ic_pair_id: Option<crate::models::IcPairId>,
389
390    /// Entity code of the IC counterparty. For a seller JE, this is the
391    /// buyer's entity; for a buyer JE, the seller's. `None` for non-IC transactions.
392    #[serde(default, skip_serializing_if = "Option::is_none")]
393    pub ic_partner_entity: Option<String>,
394
395    // --- Approval Workflow ---
396    /// Approval workflow for high-value transactions
397    #[serde(default)]
398    pub approval_workflow: Option<ApprovalWorkflow>,
399
400    // --- Source Document + Approval Tracking ---
401    /// Typed reference to the source document (derived from `reference` field prefix)
402    #[serde(default)]
403    pub source_document: Option<DocumentRef>,
404    /// Employee ID of the approver (for SOD analysis)
405    #[serde(default)]
406    pub approved_by: Option<String>,
407    /// Date of approval
408    #[serde(default)]
409    pub approval_date: Option<NaiveDate>,
410
411    // --- OCPM (Object-Centric Process Mining) Traceability ---
412    /// OCPM event IDs that triggered this journal entry
413    #[serde(default)]
414    pub ocpm_event_ids: Vec<Uuid>,
415
416    /// OCPM object IDs involved in this journal entry
417    #[serde(default)]
418    pub ocpm_object_ids: Vec<Uuid>,
419
420    /// OCPM case ID for process instance tracking
421    #[serde(default)]
422    pub ocpm_case_id: Option<Uuid>,
423}
424
425impl JournalEntryHeader {
426    /// Create a new journal entry header with default values.
427    pub fn new(company_code: String, posting_date: NaiveDate) -> Self {
428        Self {
429            document_id: Uuid::now_v7(),
430            company_code,
431            fiscal_year: posting_date.year() as u16,
432            fiscal_period: posting_date.month() as u8,
433            posting_date,
434            document_date: posting_date,
435            created_at: Utc::now(),
436            document_type: "SA".to_string(),
437            currency: "USD".to_string(),
438            exchange_rate: Decimal::ONE,
439            reference: None,
440            header_text: None,
441            created_by: "SYSTEM".to_string(),
442            user_persona: "automated_system".to_string(),
443            source: TransactionSource::Automated,
444            business_process: Some(BusinessProcess::R2R),
445            ledger: "0L".to_string(),
446            is_fraud: false,
447            fraud_type: None,
448            is_fraud_propagated: false,
449            fraud_source_document_id: None,
450            // Anomaly tracking
451            is_anomaly: false,
452            anomaly_id: None,
453            anomaly_type: None,
454            batch_id: None,
455            // ISA 240 audit flags
456            is_manual: false,
457            is_post_close: false,
458            source_system: String::new(),
459            created_date: None,
460            // Internal Controls / SOX fields
461            control_ids: Vec::new(),
462            sox_relevant: false,
463            control_status: super::internal_control::ControlStatus::default(),
464            sod_violation: false,
465            sod_conflict_type: None,
466            // Consolidation elimination flag
467            is_elimination: false,
468            // Intercompany pair linkage (group audit v5.0, Task 3.1)
469            ic_pair_id: None,
470            ic_partner_entity: None,
471            // Approval workflow
472            approval_workflow: None,
473            // Source document + approval tracking
474            source_document: None,
475            approved_by: None,
476            approval_date: None,
477            // OCPM traceability
478            ocpm_event_ids: Vec::new(),
479            ocpm_object_ids: Vec::new(),
480            ocpm_case_id: None,
481        }
482    }
483
484    /// Create a new journal entry header with a deterministic document ID.
485    ///
486    /// Used for reproducible generation where the document ID is derived
487    /// from a seed and counter.
488    pub fn with_deterministic_id(
489        company_code: String,
490        posting_date: NaiveDate,
491        document_id: Uuid,
492    ) -> Self {
493        Self {
494            document_id,
495            company_code,
496            fiscal_year: posting_date.year() as u16,
497            fiscal_period: posting_date.month() as u8,
498            posting_date,
499            document_date: posting_date,
500            created_at: Utc::now(),
501            document_type: "SA".to_string(),
502            currency: "USD".to_string(),
503            exchange_rate: Decimal::ONE,
504            reference: None,
505            header_text: None,
506            created_by: "SYSTEM".to_string(),
507            user_persona: "automated_system".to_string(),
508            source: TransactionSource::Automated,
509            business_process: Some(BusinessProcess::R2R),
510            ledger: "0L".to_string(),
511            is_fraud: false,
512            fraud_type: None,
513            is_fraud_propagated: false,
514            fraud_source_document_id: None,
515            // Anomaly tracking
516            is_anomaly: false,
517            anomaly_id: None,
518            anomaly_type: None,
519            batch_id: None,
520            // ISA 240 audit flags
521            is_manual: false,
522            is_post_close: false,
523            source_system: String::new(),
524            created_date: None,
525            // Internal Controls / SOX fields
526            control_ids: Vec::new(),
527            sox_relevant: false,
528            control_status: super::internal_control::ControlStatus::default(),
529            sod_violation: false,
530            sod_conflict_type: None,
531            // Consolidation elimination flag
532            is_elimination: false,
533            // Intercompany pair linkage (group audit v5.0, Task 3.1)
534            ic_pair_id: None,
535            ic_partner_entity: None,
536            // Approval workflow
537            approval_workflow: None,
538            // Source document + approval tracking
539            source_document: None,
540            approved_by: None,
541            approval_date: None,
542            // OCPM traceability
543            ocpm_event_ids: Vec::new(),
544            ocpm_object_ids: Vec::new(),
545            ocpm_case_id: None,
546        }
547    }
548
549    /// Look up this header's source document id in a fraud map (keyed by
550    /// document id → fraud type) and, if found, mark this header as
551    /// propagated fraud. Returns `true` when the header was tagged.
552    ///
553    /// Unlike direct line-level fraud injection, this sets
554    /// `is_fraud_propagated = true` and records `fraud_source_document_id`
555    /// so downstream consumers can distinguish scheme-level fraud (many
556    /// correlated lines tagged by one document) from slip-level fraud (a
557    /// single tagged line with no document origin).
558    pub fn propagate_fraud_from_documents(
559        &mut self,
560        fraud_map: &std::collections::HashMap<String, crate::models::FraudType>,
561    ) -> bool {
562        let doc_id = match self
563            .source_document
564            .as_ref()
565            .and_then(DocumentRef::document_id)
566        {
567            Some(id) => id,
568            None => return false,
569        };
570        if let Some(ft) = fraud_map.get(doc_id) {
571            self.is_fraud = true;
572            self.fraud_type = Some(*ft);
573            self.is_fraud_propagated = true;
574            self.fraud_source_document_id = Some(doc_id.to_string());
575            return true;
576        }
577        false
578    }
579}
580
581use chrono::Datelike;
582
583/// Individual line item within a journal entry.
584///
585/// Each line represents a debit or credit posting to a specific GL account.
586/// Line items must be balanced within a journal entry (sum of debits = sum of credits).
587#[derive(Debug, Clone, Serialize, Deserialize)]
588pub struct JournalEntryLine {
589    /// Parent document ID (matches header)
590    pub document_id: Uuid,
591
592    /// Line item number within document (1-based)
593    pub line_number: u32,
594
595    /// GL account number
596    pub gl_account: String,
597
598    /// Account code (alias for gl_account for compatibility)
599    #[serde(default)]
600    pub account_code: String,
601
602    /// Account description (for display)
603    #[serde(default)]
604    pub account_description: Option<String>,
605
606    /// Debit amount in transaction currency (positive or zero)
607    #[serde(with = "crate::serde_decimal")]
608    pub debit_amount: Decimal,
609
610    /// Credit amount in transaction currency (positive or zero)
611    #[serde(with = "crate::serde_decimal")]
612    pub credit_amount: Decimal,
613
614    /// Amount in local/company currency
615    #[serde(with = "crate::serde_decimal")]
616    pub local_amount: Decimal,
617
618    /// Amount in group currency (for consolidation)
619    #[serde(default, with = "crate::serde_decimal::option")]
620    pub group_amount: Option<Decimal>,
621
622    /// Cost center assignment
623    pub cost_center: Option<String>,
624
625    /// Profit center assignment
626    pub profit_center: Option<String>,
627
628    /// Segment for segment reporting
629    pub segment: Option<String>,
630
631    /// Functional area
632    pub functional_area: Option<String>,
633
634    /// Line item text/description
635    pub line_text: Option<String>,
636
637    /// Text field (alias for line_text for compatibility)
638    #[serde(default)]
639    pub text: Option<String>,
640
641    /// Reference field
642    #[serde(default)]
643    pub reference: Option<String>,
644
645    /// Value date (for interest calculations)
646    #[serde(default)]
647    pub value_date: Option<NaiveDate>,
648
649    /// Tax code
650    pub tax_code: Option<String>,
651
652    /// Tax amount
653    #[serde(default, with = "crate::serde_decimal::option")]
654    pub tax_amount: Option<Decimal>,
655
656    /// Assignment field (for account assignment)
657    pub assignment: Option<String>,
658
659    /// Reference to offsetting account (for network generation)
660    pub offsetting_account: Option<String>,
661
662    /// Is this posting to a suspense/clearing account
663    pub is_suspense: bool,
664
665    /// Trading partner company code (for intercompany)
666    pub trading_partner: Option<String>,
667
668    /// Quantity (for quantity-based postings)
669    #[serde(default, with = "crate::serde_decimal::option")]
670    pub quantity: Option<Decimal>,
671
672    /// Unit of measure
673    pub unit_of_measure: Option<String>,
674
675    /// Unit (alias for unit_of_measure for compatibility)
676    #[serde(default)]
677    pub unit: Option<String>,
678
679    /// Project code
680    #[serde(default)]
681    pub project_code: Option<String>,
682
683    /// Auxiliary account number (FEC column 7: Numéro de compte auxiliaire)
684    /// Populated for AP/AR lines under French GAAP with the business partner ID.
685    #[serde(default, skip_serializing_if = "Option::is_none")]
686    pub auxiliary_account_number: Option<String>,
687
688    /// Auxiliary account label (FEC column 8: Libellé de compte auxiliaire)
689    /// Populated for AP/AR lines under French GAAP with the business partner name.
690    #[serde(default, skip_serializing_if = "Option::is_none")]
691    pub auxiliary_account_label: Option<String>,
692
693    /// Lettrage code (FEC column 14: Lettrage)
694    /// Links offset postings in a completed document chain (e.g. invoice ↔ payment).
695    #[serde(default, skip_serializing_if = "Option::is_none")]
696    pub lettrage: Option<String>,
697
698    /// Lettrage date (FEC column 15: Date de lettrage)
699    /// Date when the matching was performed (typically the payment posting date).
700    #[serde(default, skip_serializing_if = "Option::is_none")]
701    pub lettrage_date: Option<NaiveDate>,
702}
703
704impl JournalEntryLine {
705    /// Create a new debit line item.
706    #[inline]
707    pub fn debit(document_id: Uuid, line_number: u32, gl_account: String, amount: Decimal) -> Self {
708        Self {
709            document_id,
710            line_number,
711            gl_account: gl_account.clone(),
712            account_code: gl_account,
713            account_description: None,
714            debit_amount: amount,
715            credit_amount: Decimal::ZERO,
716            local_amount: amount,
717            group_amount: None,
718            cost_center: None,
719            profit_center: None,
720            segment: None,
721            functional_area: None,
722            line_text: None,
723            text: None,
724            reference: None,
725            value_date: None,
726            tax_code: None,
727            tax_amount: None,
728            assignment: None,
729            offsetting_account: None,
730            is_suspense: false,
731            trading_partner: None,
732            quantity: None,
733            unit_of_measure: None,
734            unit: None,
735            project_code: None,
736            auxiliary_account_number: None,
737            auxiliary_account_label: None,
738            lettrage: None,
739            lettrage_date: None,
740        }
741    }
742
743    /// Create a new credit line item.
744    #[inline]
745    pub fn credit(
746        document_id: Uuid,
747        line_number: u32,
748        gl_account: String,
749        amount: Decimal,
750    ) -> Self {
751        Self {
752            document_id,
753            line_number,
754            gl_account: gl_account.clone(),
755            account_code: gl_account,
756            account_description: None,
757            debit_amount: Decimal::ZERO,
758            credit_amount: amount,
759            local_amount: -amount,
760            group_amount: None,
761            cost_center: None,
762            profit_center: None,
763            segment: None,
764            functional_area: None,
765            line_text: None,
766            text: None,
767            reference: None,
768            value_date: None,
769            tax_code: None,
770            tax_amount: None,
771            assignment: None,
772            offsetting_account: None,
773            is_suspense: false,
774            trading_partner: None,
775            quantity: None,
776            unit_of_measure: None,
777            unit: None,
778            project_code: None,
779            auxiliary_account_number: None,
780            auxiliary_account_label: None,
781            lettrage: None,
782            lettrage_date: None,
783        }
784    }
785
786    /// Check if this is a debit posting.
787    #[inline]
788    pub fn is_debit(&self) -> bool {
789        self.debit_amount > Decimal::ZERO
790    }
791
792    /// Check if this is a credit posting.
793    #[inline]
794    pub fn is_credit(&self) -> bool {
795        self.credit_amount > Decimal::ZERO
796    }
797
798    /// Get the signed amount (positive for debit, negative for credit).
799    #[inline]
800    pub fn signed_amount(&self) -> Decimal {
801        self.debit_amount - self.credit_amount
802    }
803
804    // Convenience accessors for compatibility
805
806    /// Get the account code (alias for gl_account).
807    #[allow(clippy::misnamed_getters)]
808    pub fn account_code(&self) -> &str {
809        &self.gl_account
810    }
811
812    /// Get the account description (currently returns empty string as not stored).
813    pub fn account_description(&self) -> &str {
814        // Account descriptions are typically looked up from CoA, not stored per line
815        ""
816    }
817}
818
819impl Default for JournalEntryLine {
820    fn default() -> Self {
821        Self {
822            document_id: Uuid::nil(),
823            line_number: 0,
824            gl_account: String::new(),
825            account_code: String::new(),
826            account_description: None,
827            debit_amount: Decimal::ZERO,
828            credit_amount: Decimal::ZERO,
829            local_amount: Decimal::ZERO,
830            group_amount: None,
831            cost_center: None,
832            profit_center: None,
833            segment: None,
834            functional_area: None,
835            line_text: None,
836            text: None,
837            reference: None,
838            value_date: None,
839            tax_code: None,
840            tax_amount: None,
841            assignment: None,
842            offsetting_account: None,
843            is_suspense: false,
844            trading_partner: None,
845            quantity: None,
846            unit_of_measure: None,
847            unit: None,
848            project_code: None,
849            auxiliary_account_number: None,
850            auxiliary_account_label: None,
851            lettrage: None,
852            lettrage_date: None,
853        }
854    }
855}
856
857/// Complete journal entry with header and line items.
858///
859/// Represents a balanced double-entry bookkeeping transaction where
860/// total debits must equal total credits.
861///
862/// Uses `SmallVec<[JournalEntryLine; 4]>` for line items: entries with
863/// 4 or fewer lines (the common case) are stored inline on the stack,
864/// avoiding heap allocation. Entries with more lines spill to the heap
865/// transparently.
866#[derive(Debug, Clone, Serialize, Deserialize)]
867pub struct JournalEntry {
868    /// Header with document metadata
869    pub header: JournalEntryHeader,
870    /// Line items (debit and credit postings).
871    /// Inline for ≤4 lines (common case), heap-allocated for >4.
872    pub lines: SmallVec<[JournalEntryLine; 4]>,
873}
874
875impl JournalEntry {
876    /// Create a new journal entry with header and empty lines.
877    pub fn new(header: JournalEntryHeader) -> Self {
878        Self {
879            header,
880            lines: SmallVec::new(),
881        }
882    }
883
884    /// Create a new journal entry with basic parameters (convenience constructor).
885    ///
886    /// This is a simplified constructor for backwards compatibility that creates
887    /// a journal entry with the specified document number, company code, posting date,
888    /// and description.
889    pub fn new_simple(
890        document_number: String,
891        company_code: String,
892        posting_date: NaiveDate,
893        description: String,
894    ) -> Self {
895        let mut header = JournalEntryHeader::new(company_code, posting_date);
896        header.header_text = Some(description);
897        header.reference = Some(document_number);
898        Self {
899            header,
900            lines: SmallVec::new(),
901        }
902    }
903
904    /// Add a line item to the journal entry.
905    ///
906    /// Automatically sets the line's `document_id` to match the header's `document_id`.
907    #[inline]
908    pub fn add_line(&mut self, mut line: JournalEntryLine) {
909        line.document_id = self.header.document_id;
910        self.lines.push(line);
911    }
912
913    /// Get the total debit amount.
914    pub fn total_debit(&self) -> Decimal {
915        self.lines.iter().map(|l| l.debit_amount).sum()
916    }
917
918    /// Get the total credit amount.
919    pub fn total_credit(&self) -> Decimal {
920        self.lines.iter().map(|l| l.credit_amount).sum()
921    }
922
923    /// Check if the journal entry is balanced (debits = credits).
924    pub fn is_balanced(&self) -> bool {
925        self.total_debit() == self.total_credit()
926    }
927
928    /// Get the out-of-balance amount (should be zero for valid entries).
929    pub fn balance_difference(&self) -> Decimal {
930        self.total_debit() - self.total_credit()
931    }
932
933    /// Get the number of line items.
934    pub fn line_count(&self) -> usize {
935        self.lines.len()
936    }
937
938    /// Check if the line count is even.
939    pub fn has_even_line_count(&self) -> bool {
940        self.lines.len().is_multiple_of(2)
941    }
942
943    /// Get the count of debit and credit lines.
944    pub fn debit_credit_counts(&self) -> (usize, usize) {
945        let debits = self.lines.iter().filter(|l| l.is_debit()).count();
946        let credits = self.lines.iter().filter(|l| l.is_credit()).count();
947        (debits, credits)
948    }
949
950    /// Check if debit and credit line counts are equal.
951    pub fn has_equal_debit_credit_counts(&self) -> bool {
952        let (d, c) = self.debit_credit_counts();
953        d == c
954    }
955
956    /// Get unique GL accounts used in this entry.
957    pub fn unique_accounts(&self) -> Vec<&str> {
958        let mut accounts: Vec<&str> = self.lines.iter().map(|l| l.gl_account.as_str()).collect();
959        accounts.sort();
960        accounts.dedup();
961        accounts
962    }
963
964    /// Check if any line posts to a suspense account.
965    pub fn has_suspense_posting(&self) -> bool {
966        self.lines.iter().any(|l| l.is_suspense)
967    }
968
969    // Convenience accessors for header fields
970
971    /// Get the company code.
972    pub fn company_code(&self) -> &str {
973        &self.header.company_code
974    }
975
976    /// Get the document number (document_id as string).
977    pub fn document_number(&self) -> String {
978        self.header.document_id.to_string()
979    }
980
981    /// Get the posting date.
982    pub fn posting_date(&self) -> NaiveDate {
983        self.header.posting_date
984    }
985
986    /// Get the document date.
987    pub fn document_date(&self) -> NaiveDate {
988        self.header.document_date
989    }
990
991    /// Get the fiscal year.
992    pub fn fiscal_year(&self) -> u16 {
993        self.header.fiscal_year
994    }
995
996    /// Get the fiscal period.
997    pub fn fiscal_period(&self) -> u8 {
998        self.header.fiscal_period
999    }
1000
1001    /// Get the currency.
1002    pub fn currency(&self) -> &str {
1003        &self.header.currency
1004    }
1005
1006    /// Check if this entry is marked as fraud.
1007    pub fn is_fraud(&self) -> bool {
1008        self.header.is_fraud
1009    }
1010
1011    /// Check if this entry has a SOD violation.
1012    pub fn has_sod_violation(&self) -> bool {
1013        self.header.sod_violation
1014    }
1015
1016    /// Get the description (header text).
1017    pub fn description(&self) -> Option<&str> {
1018        self.header.header_text.as_deref()
1019    }
1020
1021    /// Set the description (header text).
1022    pub fn set_description(&mut self, description: String) {
1023        self.header.header_text = Some(description);
1024    }
1025}
1026
1027#[cfg(test)]
1028#[allow(clippy::unwrap_used)]
1029mod tests {
1030    use super::*;
1031
1032    #[test]
1033    fn test_balanced_entry() {
1034        let header = JournalEntryHeader::new(
1035            "1000".to_string(),
1036            NaiveDate::from_ymd_opt(2024, 1, 15).unwrap(),
1037        );
1038        let mut entry = JournalEntry::new(header);
1039
1040        entry.add_line(JournalEntryLine::debit(
1041            entry.header.document_id,
1042            1,
1043            "100000".to_string(),
1044            Decimal::from(1000),
1045        ));
1046        entry.add_line(JournalEntryLine::credit(
1047            entry.header.document_id,
1048            2,
1049            "200000".to_string(),
1050            Decimal::from(1000),
1051        ));
1052
1053        assert!(entry.is_balanced());
1054        assert_eq!(entry.line_count(), 2);
1055        assert!(entry.has_even_line_count());
1056        assert!(entry.has_equal_debit_credit_counts());
1057    }
1058
1059    #[test]
1060    fn test_unbalanced_entry() {
1061        let header = JournalEntryHeader::new(
1062            "1000".to_string(),
1063            NaiveDate::from_ymd_opt(2024, 1, 15).unwrap(),
1064        );
1065        let mut entry = JournalEntry::new(header);
1066
1067        entry.add_line(JournalEntryLine::debit(
1068            entry.header.document_id,
1069            1,
1070            "100000".to_string(),
1071            Decimal::from(1000),
1072        ));
1073        entry.add_line(JournalEntryLine::credit(
1074            entry.header.document_id,
1075            2,
1076            "200000".to_string(),
1077            Decimal::from(500),
1078        ));
1079
1080        assert!(!entry.is_balanced());
1081        assert_eq!(entry.balance_difference(), Decimal::from(500));
1082    }
1083}
datasynth_core/models/journal_entry.rs

datasynth_core/models/
journal_entry.rs
