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    /// Stable per-line transaction identifier.
704    ///
705    /// Deterministically derived from `(document_id, line_number)` so it stays
706    /// consistent across regenerations of the same dataset. Populated lazily
707    /// at write time from [`JournalEntryLine::derive_transaction_id`] when
708    /// not already set.
709    #[serde(default, skip_serializing_if = "Option::is_none")]
710    pub transaction_id: Option<String>,
711}
712
713impl JournalEntryLine {
714    /// Create a new debit line item.
715    #[inline]
716    pub fn debit(document_id: Uuid, line_number: u32, gl_account: String, amount: Decimal) -> Self {
717        Self {
718            document_id,
719            line_number,
720            gl_account: gl_account.clone(),
721            account_code: gl_account,
722            account_description: None,
723            debit_amount: amount,
724            credit_amount: Decimal::ZERO,
725            local_amount: amount,
726            group_amount: None,
727            cost_center: None,
728            profit_center: None,
729            segment: None,
730            functional_area: None,
731            line_text: None,
732            text: None,
733            reference: None,
734            value_date: None,
735            tax_code: None,
736            tax_amount: None,
737            assignment: None,
738            offsetting_account: None,
739            is_suspense: false,
740            trading_partner: None,
741            quantity: None,
742            unit_of_measure: None,
743            unit: None,
744            project_code: None,
745            auxiliary_account_number: None,
746            auxiliary_account_label: None,
747            lettrage: None,
748            lettrage_date: None,
749            transaction_id: None,
750        }
751    }
752
753    /// Create a new credit line item.
754    #[inline]
755    pub fn credit(
756        document_id: Uuid,
757        line_number: u32,
758        gl_account: String,
759        amount: Decimal,
760    ) -> Self {
761        Self {
762            document_id,
763            line_number,
764            gl_account: gl_account.clone(),
765            account_code: gl_account,
766            account_description: None,
767            debit_amount: Decimal::ZERO,
768            credit_amount: amount,
769            local_amount: -amount,
770            group_amount: None,
771            cost_center: None,
772            profit_center: None,
773            segment: None,
774            functional_area: None,
775            line_text: None,
776            text: None,
777            reference: None,
778            value_date: None,
779            tax_code: None,
780            tax_amount: None,
781            assignment: None,
782            offsetting_account: None,
783            is_suspense: false,
784            trading_partner: None,
785            quantity: None,
786            unit_of_measure: None,
787            unit: None,
788            project_code: None,
789            auxiliary_account_number: None,
790            auxiliary_account_label: None,
791            lettrage: None,
792            lettrage_date: None,
793            transaction_id: None,
794        }
795    }
796
797    /// Check if this is a debit posting.
798    #[inline]
799    pub fn is_debit(&self) -> bool {
800        self.debit_amount > Decimal::ZERO
801    }
802
803    /// Check if this is a credit posting.
804    #[inline]
805    pub fn is_credit(&self) -> bool {
806        self.credit_amount > Decimal::ZERO
807    }
808
809    /// Get the signed amount (positive for debit, negative for credit).
810    #[inline]
811    pub fn signed_amount(&self) -> Decimal {
812        self.debit_amount - self.credit_amount
813    }
814
815    /// Derive a stable per-line transaction id from `(document_id, line_number)`.
816    ///
817    /// Deterministic: the same input always returns the same id, so the
818    /// value is stable across regenerations of the same dataset and across
819    /// crate versions. Uses UUID v5 (SHA-1) under `Uuid::NAMESPACE_OID`.
820    pub fn derive_transaction_id(document_id: Uuid, line_number: u32) -> String {
821        let mut input = Vec::with_capacity(20);
822        input.extend_from_slice(document_id.as_bytes());
823        input.extend_from_slice(&line_number.to_le_bytes());
824        Uuid::new_v5(&Uuid::NAMESPACE_OID, &input).to_string()
825    }
826
827    /// Populate `transaction_id` from `(document_id, line_number)` if unset.
828    pub fn ensure_transaction_id(&mut self) {
829        if self.transaction_id.is_none() {
830            self.transaction_id = Some(Self::derive_transaction_id(
831                self.document_id,
832                self.line_number,
833            ));
834        }
835    }
836
837    // Convenience accessors for compatibility
838
839    /// Get the account code (alias for gl_account).
840    #[allow(clippy::misnamed_getters)]
841    pub fn account_code(&self) -> &str {
842        &self.gl_account
843    }
844
845    /// Get the account description (currently returns empty string as not stored).
846    pub fn account_description(&self) -> &str {
847        // Account descriptions are typically looked up from CoA, not stored per line
848        ""
849    }
850}
851
852impl Default for JournalEntryLine {
853    fn default() -> Self {
854        Self {
855            document_id: Uuid::nil(),
856            line_number: 0,
857            gl_account: String::new(),
858            account_code: String::new(),
859            account_description: None,
860            debit_amount: Decimal::ZERO,
861            credit_amount: Decimal::ZERO,
862            local_amount: Decimal::ZERO,
863            group_amount: None,
864            cost_center: None,
865            profit_center: None,
866            segment: None,
867            functional_area: None,
868            line_text: None,
869            text: None,
870            reference: None,
871            value_date: None,
872            tax_code: None,
873            tax_amount: None,
874            assignment: None,
875            offsetting_account: None,
876            is_suspense: false,
877            trading_partner: None,
878            quantity: None,
879            unit_of_measure: None,
880            unit: None,
881            project_code: None,
882            auxiliary_account_number: None,
883            auxiliary_account_label: None,
884            lettrage: None,
885            lettrage_date: None,
886            transaction_id: None,
887        }
888    }
889}
890
891/// Complete journal entry with header and line items.
892///
893/// Represents a balanced double-entry bookkeeping transaction where
894/// total debits must equal total credits.
895///
896/// Uses `SmallVec<[JournalEntryLine; 4]>` for line items: entries with
897/// 4 or fewer lines (the common case) are stored inline on the stack,
898/// avoiding heap allocation. Entries with more lines spill to the heap
899/// transparently.
900#[derive(Debug, Clone, Serialize, Deserialize)]
901pub struct JournalEntry {
902    /// Header with document metadata
903    pub header: JournalEntryHeader,
904    /// Line items (debit and credit postings).
905    /// Inline for ≤4 lines (common case), heap-allocated for >4.
906    pub lines: SmallVec<[JournalEntryLine; 4]>,
907}
908
909impl JournalEntry {
910    /// Create a new journal entry with header and empty lines.
911    pub fn new(header: JournalEntryHeader) -> Self {
912        Self {
913            header,
914            lines: SmallVec::new(),
915        }
916    }
917
918    /// Create a new journal entry with basic parameters (convenience constructor).
919    ///
920    /// This is a simplified constructor for backwards compatibility that creates
921    /// a journal entry with the specified document number, company code, posting date,
922    /// and description.
923    pub fn new_simple(
924        document_number: String,
925        company_code: String,
926        posting_date: NaiveDate,
927        description: String,
928    ) -> Self {
929        let mut header = JournalEntryHeader::new(company_code, posting_date);
930        header.header_text = Some(description);
931        header.reference = Some(document_number);
932        Self {
933            header,
934            lines: SmallVec::new(),
935        }
936    }
937
938    /// Add a line item to the journal entry.
939    ///
940    /// Automatically sets the line's `document_id` to match the header's `document_id`.
941    #[inline]
942    pub fn add_line(&mut self, mut line: JournalEntryLine) {
943        line.document_id = self.header.document_id;
944        self.lines.push(line);
945    }
946
947    /// Get the total debit amount.
948    pub fn total_debit(&self) -> Decimal {
949        self.lines.iter().map(|l| l.debit_amount).sum()
950    }
951
952    /// Get the total credit amount.
953    pub fn total_credit(&self) -> Decimal {
954        self.lines.iter().map(|l| l.credit_amount).sum()
955    }
956
957    /// Check if the journal entry is balanced (debits = credits).
958    pub fn is_balanced(&self) -> bool {
959        self.total_debit() == self.total_credit()
960    }
961
962    /// Get the out-of-balance amount (should be zero for valid entries).
963    pub fn balance_difference(&self) -> Decimal {
964        self.total_debit() - self.total_credit()
965    }
966
967    /// Get the number of line items.
968    pub fn line_count(&self) -> usize {
969        self.lines.len()
970    }
971
972    /// Check if the line count is even.
973    pub fn has_even_line_count(&self) -> bool {
974        self.lines.len().is_multiple_of(2)
975    }
976
977    /// Get the count of debit and credit lines.
978    pub fn debit_credit_counts(&self) -> (usize, usize) {
979        let debits = self.lines.iter().filter(|l| l.is_debit()).count();
980        let credits = self.lines.iter().filter(|l| l.is_credit()).count();
981        (debits, credits)
982    }
983
984    /// Check if debit and credit line counts are equal.
985    pub fn has_equal_debit_credit_counts(&self) -> bool {
986        let (d, c) = self.debit_credit_counts();
987        d == c
988    }
989
990    /// Get unique GL accounts used in this entry.
991    pub fn unique_accounts(&self) -> Vec<&str> {
992        let mut accounts: Vec<&str> = self.lines.iter().map(|l| l.gl_account.as_str()).collect();
993        accounts.sort();
994        accounts.dedup();
995        accounts
996    }
997
998    /// Check if any line posts to a suspense account.
999    pub fn has_suspense_posting(&self) -> bool {
1000        self.lines.iter().any(|l| l.is_suspense)
1001    }
1002
1003    // Convenience accessors for header fields
1004
1005    /// Get the company code.
1006    pub fn company_code(&self) -> &str {
1007        &self.header.company_code
1008    }
1009
1010    /// Get the document number (document_id as string).
1011    pub fn document_number(&self) -> String {
1012        self.header.document_id.to_string()
1013    }
1014
1015    /// Get the posting date.
1016    pub fn posting_date(&self) -> NaiveDate {
1017        self.header.posting_date
1018    }
1019
1020    /// Get the document date.
1021    pub fn document_date(&self) -> NaiveDate {
1022        self.header.document_date
1023    }
1024
1025    /// Get the fiscal year.
1026    pub fn fiscal_year(&self) -> u16 {
1027        self.header.fiscal_year
1028    }
1029
1030    /// Get the fiscal period.
1031    pub fn fiscal_period(&self) -> u8 {
1032        self.header.fiscal_period
1033    }
1034
1035    /// Get the currency.
1036    pub fn currency(&self) -> &str {
1037        &self.header.currency
1038    }
1039
1040    /// Check if this entry is marked as fraud.
1041    pub fn is_fraud(&self) -> bool {
1042        self.header.is_fraud
1043    }
1044
1045    /// Check if this entry has a SOD violation.
1046    pub fn has_sod_violation(&self) -> bool {
1047        self.header.sod_violation
1048    }
1049
1050    /// Get the description (header text).
1051    pub fn description(&self) -> Option<&str> {
1052        self.header.header_text.as_deref()
1053    }
1054
1055    /// Set the description (header text).
1056    pub fn set_description(&mut self, description: String) {
1057        self.header.header_text = Some(description);
1058    }
1059}
1060
1061#[cfg(test)]
1062#[allow(clippy::unwrap_used)]
1063mod tests {
1064    use super::*;
1065
1066    #[test]
1067    fn test_balanced_entry() {
1068        let header = JournalEntryHeader::new(
1069            "1000".to_string(),
1070            NaiveDate::from_ymd_opt(2024, 1, 15).unwrap(),
1071        );
1072        let mut entry = JournalEntry::new(header);
1073
1074        entry.add_line(JournalEntryLine::debit(
1075            entry.header.document_id,
1076            1,
1077            "100000".to_string(),
1078            Decimal::from(1000),
1079        ));
1080        entry.add_line(JournalEntryLine::credit(
1081            entry.header.document_id,
1082            2,
1083            "200000".to_string(),
1084            Decimal::from(1000),
1085        ));
1086
1087        assert!(entry.is_balanced());
1088        assert_eq!(entry.line_count(), 2);
1089        assert!(entry.has_even_line_count());
1090        assert!(entry.has_equal_debit_credit_counts());
1091    }
1092
1093    #[test]
1094    fn test_unbalanced_entry() {
1095        let header = JournalEntryHeader::new(
1096            "1000".to_string(),
1097            NaiveDate::from_ymd_opt(2024, 1, 15).unwrap(),
1098        );
1099        let mut entry = JournalEntry::new(header);
1100
1101        entry.add_line(JournalEntryLine::debit(
1102            entry.header.document_id,
1103            1,
1104            "100000".to_string(),
1105            Decimal::from(1000),
1106        ));
1107        entry.add_line(JournalEntryLine::credit(
1108            entry.header.document_id,
1109            2,
1110            "200000".to_string(),
1111            Decimal::from(500),
1112        ));
1113
1114        assert!(!entry.is_balanced());
1115        assert_eq!(entry.balance_difference(), Decimal::from(500));
1116    }
1117}
datasynth_core/models/journal_entry.rs

datasynth_core/models/
journal_entry.rs
