Initial accounting reports documentation

Reports/AP/AP_001_supplier_balance_report.md

@@ -0,0 +1,181 @@
+# AP-001 Supplier Balance Report
+
+## 1 Objective
+
+Provide a summarized view of outstanding supplier balances at a selected closing date.
+
+The report is used for:
+
+- accounts payable monitoring;
+- supplier balance review;
+- reconciliation between the accounts payable subledger and the general ledger;
+- payment preparation review;
+- period-end and year-end closing analysis.
+
+---
+
+## 2 Users
+
+- accounting department;
+- accounts payable team;
+- treasury or payment team;
+- finance department;
+- auditors;
+- financial controlling.
+
+---
+
+## 3 Frequency
+
+- daily;
+- weekly payment review;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `closing_date`
+
+Optional parameters:
+
+- `counterparty`
+- `currency`
+- `entity`
+- `include_zero_balances`
+
+Execution scope:
+
+- the report is generated for the current entity unless an entity filter is explicitly supported by the ERP context;
+- supplier balances are calculated as of `closing_date`;
+- only accounts payable supplier balances are in scope.
+
+---
+
+## 5 Filters
+
+- accounting closing date equal to `closing_date`;
+- supplier or supplier range;
+- currency;
+- entity, when supported;
+- include or exclude zero-balance suppliers based on `include_zero_balances`.
+
+Out of scope filters:
+
+- ageing bucket;
+- payment status;
+- invoice due date.
+
+These are handled by `AP-002 Supplier Ageing Report` or `AP-003 Supplier Account Movements`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `supplier`
+2. `transaction_currency`
+
+Secondary sorting:
+
+- `supplier_name`
+- `base_currency`
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `supplier`
+- `transaction_currency`
+
+Totals should be displayed by:
+
+- supplier;
+- transaction currency;
+- base currency;
+- report total.
+
+Presentation requirements:
+
+- each supplier should be displayed once per transaction currency;
+- debit, credit and balance columns should be displayed side by side;
+- opening balance and movement columns are mandatory;
+- suppliers with zero closing balance should be excluded when `include_zero_balances = false`, unless they have movements or open items that must remain visible for reconciliation;
+- blocked, inactive or archived suppliers should be displayed when they have a non-zero balance or non-zero debit or credit amounts;
+- detailed invoice-level open items are out of scope for this report and belong to `AP-002 Supplier Ageing Report`.
+- drill-down should be available from each supplier balance to supplier account movements, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `supplier` | Supplier account code |
+| `supplier_name` | Supplier legal or commercial name |
+| `posting_status` | Posting status scope included in supplier balances, when exposed by the ERP |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `opening_balance_transaction_currency` | Opening supplier balance in transaction currency |
+| `debit_transaction_currency` | Debit movement in transaction currency |
+| `credit_transaction_currency` | Credit movement in transaction currency |
+| `closing_balance_transaction_currency` | Closing supplier balance in transaction currency |
+| `opening_balance_base_currency` | Opening supplier balance in base currency |
+| `debit_base_currency` | Debit movement in base currency |
+| `credit_base_currency` | Credit movement in base currency |
+| `closing_balance_base_currency` | Closing supplier balance in base currency |
+| `last_posting_date` | Last accounting posting date included in the supplier balance |
+| `last_document_number` | Last accounting document number included in the supplier balance, when available |
+
+Amount sign convention for this report:
+
+- supplier payable balances are presented as positive credit balances;
+- supplier debit balances, advances or overpayments are presented as negative balances;
+- debit amounts are positive and credit amounts are negative when movement columns are shown.
+
+---
+
+## 9 Estimated volume
+
+Medium.
+
+The report is a summarized subledger report. It should contain one summarized line per supplier and transaction currency, not detailed invoice-level movements.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF
+
+XLSX and CSV are primary review and reconciliation formats. PDF is used for closing documentation and audit review.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Supplier balance totals should reconcile with the accounts payable control accounts in the general ledger for the same current entity and closing date.
+- Supplier balances in base currency should reconcile with the AP subledger total for the same closing date.
+- Suppliers excluded by `include_zero_balances = false` should not change report totals.
+- Supplier debit balances, advances or overpayments should remain visible and should not be netted against other suppliers.
+- Blocked, inactive or archived suppliers should remain visible when they have a non-zero balance or non-zero debit or credit amounts.
+- The report should retain enough references to reconcile from supplier balance summary to detailed supplier account movements.
+- Drill-down from a supplier balance should reconcile to `AP-003 Supplier Account Movements` for the same current entity, supplier, currency and selected closing date.
+
+---
+
+## 12 Open questions
+
+- Which ERP source will define the mapping between supplier balances and AP control accounts? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/AP/AP_002_supplier_ageing_report.md

@@ -0,0 +1,219 @@
+# AP-002 Supplier Ageing Report
+
+## 1 Objective
+
+Provide an ageing analysis of supplier payables based on open supplier items at a selected closing date.
+
+The report is used for:
+
+- accounts payable follow-up;
+- payment planning;
+- overdue payable monitoring;
+- supplier balance review;
+- reconciliation with supplier balances;
+- audit and closing review.
+
+---
+
+## 2 Users
+
+- accounts payable team;
+- accounting department;
+- treasury or payment team;
+- finance department;
+- auditors.
+
+---
+
+## 3 Frequency
+
+- daily;
+- weekly payment review;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `closing_date`
+
+Optional parameters:
+
+- `counterparty`
+- `currency`
+- `entity`
+- `document_number`
+- `supplier_invoice_number`
+- `ageing_basis`
+- `include_not_due_items`
+- `include_debit_balances`
+- `view_mode`
+
+Execution scope:
+
+- the report is generated for the current entity unless an entity filter is explicitly supported by the ERP context;
+- open supplier items are calculated as of `closing_date`;
+- only accounts payable supplier open items are in scope.
+
+Ageing basis:
+
+- ageing should be calculated from due date by default;
+- posting date should also be available as a selectable ageing basis;
+- document date ageing may be supported if the ERP exposes the required date.
+
+View mode:
+
+- `view_mode = detailed` should display open item details;
+- `view_mode = summarized` should display supplier and ageing bucket totals without document-level detail.
+
+---
+
+## 5 Filters
+
+- open items as of `closing_date`;
+- supplier or supplier range;
+- currency;
+- entity, when supported;
+- accounting document number or supplier invoice number;
+- ageing bucket;
+- include or exclude not-due items based on `include_not_due_items`;
+- include or exclude supplier debit balances based on `include_debit_balances`;
+- detailed or summarized output based on `view_mode`.
+
+Out of scope filters:
+
+- fully settled items after `closing_date`;
+- detailed supplier movement history.
+
+Detailed supplier movement history is handled by `AP-003 Supplier Account Movements`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `supplier`
+2. `transaction_currency`
+3. `ageing_bucket_order`
+4. `due_date`
+5. `document_number`
+
+Secondary sorting:
+
+- `posting_date`
+- `document_date`
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `supplier`
+- `transaction_currency`
+- `ageing_bucket`
+
+Totals should be displayed by:
+
+- supplier;
+- ageing bucket;
+- transaction currency;
+- base currency;
+- report total.
+
+Default ageing buckets:
+
+- not due;
+- 0-30 days overdue;
+- 31-60 days overdue;
+- 61-90 days overdue;
+- over 90 days overdue.
+
+Presentation requirements:
+
+- each open item should be assigned to exactly one ageing bucket;
+- supplier debit balances, advances or overpayments should remain visible and should not be netted against other suppliers;
+- open item details should be available to support payment planning and audit review;
+- summarized view should hide document-level fields and display totals by supplier, transaction currency and ageing bucket;
+- totals should reconcile with `AP-001 Supplier Balance Report` for the same closing date and filters.
+- drill-down should be available from summarized ageing buckets to open item details, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `supplier` | Supplier account code |
+| `supplier_name` | Supplier legal or commercial name |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `document_number` | Accounting or AP document number |
+| `supplier_invoice_number` | Supplier invoice number as provided by the supplier |
+| `document_type` | Document type, such as supplier invoice, credit note, debit note or payment |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP |
+| `posting_date` | Accounting posting date |
+| `document_date` | Source document date |
+| `due_date` | Payment due date |
+| `ageing_basis_date` | Date used to calculate ageing |
+| `days_overdue` | Number of days overdue at `closing_date` |
+| `ageing_bucket` | Ageing bucket label |
+| `ageing_bucket_order` | Sort order of the ageing bucket |
+| `open_amount_transaction_currency` | Open amount in transaction currency |
+| `open_amount_base_currency` | Open amount in base currency |
+| `reference` | External or source reference |
+| `description` | Document or item description |
+
+Amount sign convention for this report:
+
+- open payable amounts are presented as positive credit balances;
+- supplier debit balances, advances or overpayments are presented as negative amounts;
+- open amounts should not be netted across suppliers.
+
+---
+
+## 9 Estimated volume
+
+High.
+
+The report may contain a large number of open items and should support filtering before generation.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF
+
+XLSX and CSV are primary payment planning, review and reconciliation formats. PDF is used for closing documentation and audit review.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Total open amount in base currency should reconcile with `AP-001 Supplier Balance Report` for the same current entity, closing date and filters.
+- Each open item should be assigned to one ageing bucket only.
+- Items not due at `closing_date` should be included or excluded according to `include_not_due_items`.
+- Supplier debit balances should remain visible when `include_debit_balances = true`.
+- Fully settled items as of `closing_date` should be excluded.
+- Supplier invoice items should be identifiable by both `document_number` and `supplier_invoice_number` when the supplier invoice number is available.
+- If the ERP exposes posting status, non-posted operational AP events should be clearly identified through `posting_status`.
+- Open item totals should reconcile with the AP subledger open item balance.
+- Drill-down from a summarized ageing bucket should reconcile to the detailed open items included in the same bucket and then to the related accounting or AP document.
+
+---
+
+## 12 Open questions
+
+- Which ageing buckets should be configurable by users, and which should be fixed by default? This depends on ERP functionality and is currently unknown.
+- Which ERP status defines whether an item is open as of `closing_date`? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/AP/AP_003_supplier_account_movements.md

@@ -0,0 +1,225 @@
+# AP-003 Supplier Account Movements
+
+## 1 Objective
+
+Provide the detailed list of accounting movements posted to supplier accounts over a selected date range.
+
+The report is used for:
+
+- supplier account review;
+- reconciliation of supplier balances;
+- investigation of supplier invoices, credit notes, debit notes and payments;
+- audit review;
+- support for payment preparation and supplier statement review.
+
+---
+
+## 2 Users
+
+- accounts payable team;
+- accounting department;
+- treasury or payment team;
+- finance department;
+- auditors.
+
+---
+
+## 3 Frequency
+
+- daily;
+- weekly payment review;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `date_from`
+- `date_to`
+
+Optional parameters:
+
+- `counterparty`
+- `currency`
+- `entity`
+- `document_number`
+- `supplier_invoice_number`
+- `document_type_filter`
+- `include_settled_items`
+
+Execution scope:
+
+- the report is generated for the current entity unless an entity filter is explicitly supported by the ERP context;
+- supplier movements are selected between `date_from` and `date_to`;
+- only accounts payable supplier account movements are in scope.
+
+---
+
+## 5 Filters
+
+- posting date between `date_from` and `date_to`;
+- supplier or supplier range;
+- currency;
+- entity, when supported;
+- accounting document number or supplier invoice number;
+- document type based on `document_type_filter`;
+- include or exclude settled items based on `include_settled_items`.
+
+Default document type filter values:
+
+- `all`: all supplier account movements;
+- `invoices`: supplier invoices only;
+- `payments`: supplier payments only;
+- `credit_debit_notes`: supplier credit notes and debit notes only.
+
+Out of scope filters:
+
+- ageing bucket;
+- due-date ageing;
+- summarized supplier balance only.
+
+Ageing analysis is handled by `AP-002 Supplier Ageing Report`. Summarized supplier balances are handled by `AP-001 Supplier Balance Report`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `supplier`
+2. `transaction_currency`
+3. `posting_date`
+4. `document_number`
+
+Secondary sorting:
+
+- `document_date`
+- `due_date`
+- `journal_entry_number`
+- `voucher_number`, when available
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `supplier`
+- `transaction_currency`
+
+Totals should be displayed by:
+
+- supplier;
+- transaction currency;
+- base currency;
+- report total.
+
+Presentation requirements:
+
+- each supplier movement should be displayed as a separate line;
+- opening balance rows should be displayed by supplier and transaction currency;
+- closing balance rows should be displayed by supplier and transaction currency;
+- opening balances are mandatory for all executions;
+- running balances should be calculated line by line between opening and closing balance rows;
+- supplier invoices, credit notes, debit notes and payments should remain visible as separate movements.
+- the selected `document_type_filter` should restrict the movement population without changing the displayed `document_type` value.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `supplier` | Supplier account code |
+| `supplier_name` | Supplier legal or commercial name |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `posting_date` | Accounting posting date |
+| `document_date` | Source document date |
+| `due_date` | Payment due date, when available |
+| `journal` | Accounting journal |
+| `journal_entry_number` | Journal entry sequence or identifier |
+| `document_number` | Accounting or AP document number |
+| `supplier_invoice_number` | Supplier invoice number as provided by the supplier |
+| `purchase_invoice_number` | ERP purchase invoice number, when different from the accounting document number |
+| `vendor_reference` | Vendor reference or external supplier reference, when available |
+| `document_type` | Document type, such as supplier invoice, credit note, debit note or payment |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP |
+| `description` | Document or movement description |
+| `reference` | External or source reference |
+| `debit_transaction_currency` | Debit movement in transaction currency |
+| `credit_transaction_currency` | Credit movement in transaction currency |
+| `balance_transaction_currency` | Running supplier balance in transaction currency |
+| `debit_base_currency` | Debit movement in base currency |
+| `credit_base_currency` | Credit movement in base currency |
+| `balance_base_currency` | Running supplier balance in base currency |
+| `settlement_status` | Open, partially settled, settled or reversed status, when available |
+| `settlement_date` | Settlement or clearing date, when available |
+| `entered_date` | Entry creation date |
+| `entered_by` | User who created the entry |
+
+`document_number` is the mandatory accounting audit reference. `supplier_invoice_number` is required for supplier invoice identification when available. `purchase_invoice_number` and `vendor_reference` should be displayed when the ERP uses separate purchase invoice or vendor reference fields. `reference` is an informational reference.
+
+Optional reference columns:
+
+| Column | Description |
+| --- | --- |
+| `voucher_number` | Internal AP voucher or workflow reference, only when the ERP distinguishes it from `document_number` and `supplier_invoice_number` |
+
+`voucher_number` should not duplicate `supplier_invoice_number`. It should be displayed only if it provides a distinct internal AP processing reference.
+
+Amount sign convention for this report:
+
+- debit movements are displayed as positive amounts;
+- credit movements are displayed as negative amounts;
+- running balances are calculated using this debit-positive and credit-negative convention;
+- supplier debit balances, advances or overpayments are presented as negative balances.
+
+---
+
+## 9 Estimated volume
+
+High.
+
+The report may contain a large number of supplier movement lines and should support filtering before generation.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF, including all detail columns
+
+CSV and XLSX are primary analysis and reconciliation formats. PDF is used for audit review and supplier account documentation.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Opening balance plus movements should reconcile to closing balance by supplier and transaction currency.
+- Closing balances should reconcile with `AP-001 Supplier Balance Report` for the same current entity, `date_to` and filters.
+- Movement totals should reconcile with the accounts payable subledger for the selected date range.
+- Movement totals in base currency should reconcile with the related general ledger AP control accounts for the selected date range.
+- Settled items should be included or excluded according to `include_settled_items`.
+- Document type filtering should apply according to `document_type_filter`, with `all` as the default value.
+- Supplier invoice movements should be identifiable by `document_number` and `supplier_invoice_number` when the supplier invoice number is available.
+- When exposed by the ERP, `purchase_invoice_number` and `vendor_reference` should provide additional supplier-side identification for invoice reconciliation.
+- If the ERP exposes posting status, non-posted operational AP events should be clearly identified through `posting_status`.
+- Each line should retain enough audit references to trace back to the accounting document and source document where available.
+
+---
+
+## 12 Open questions
+
+- Which ERP status values should map to `settlement_status`? This information is currently unknown.
+- Which ERP document type values should map to `invoices`, `payments` and `credit_debit_notes`? This information is currently unknown.
+- Does the ERP expose `purchase_invoice_number`, `vendor_reference`, or both as distinct fields from `supplier_invoice_number`? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/AR/AR_001_customer_balance_report.md

@@ -0,0 +1,180 @@
+# AR-001 Customer Balance Report
+
+## 1 Objective
+
+Provide a summarized view of outstanding customer balances at a selected closing date.
+
+The report is used for:
+
+- accounts receivable monitoring;
+- customer balance review;
+- reconciliation between the accounts receivable subledger and the general ledger;
+- credit exposure review;
+- period-end and year-end closing analysis.
+
+---
+
+## 2 Users
+
+- accounting department;
+- credit control;
+- finance department;
+- auditors;
+- financial controlling.
+
+---
+
+## 3 Frequency
+
+- daily;
+- weekly credit review;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `closing_date`
+
+Optional parameters:
+
+- `counterparty`
+- `currency`
+- `entity`
+- `include_zero_balances`
+
+Execution scope:
+
+- the report is generated for the current entity unless an entity filter is explicitly supported by the ERP context;
+- customer balances are calculated as of `closing_date`;
+- only accounts receivable customer balances are in scope.
+
+---
+
+## 5 Filters
+
+- accounting closing date equal to `closing_date`;
+- customer or customer range;
+- currency;
+- entity, when supported;
+- include or exclude zero-balance customers based on `include_zero_balances`.
+
+Out of scope filters:
+
+- ageing bucket;
+- payment status;
+- invoice due date.
+
+These are handled by `AR-002 Customer Ageing Report` or `AR-003 Customer Account Movements`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `customer`
+2. `transaction_currency`
+
+Secondary sorting:
+
+- `customer_name`
+- `base_currency`
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `customer`
+- `transaction_currency`
+
+Totals should be displayed by:
+
+- customer;
+- transaction currency;
+- base currency;
+- report total.
+
+Presentation requirements:
+
+- each customer should be displayed once per transaction currency;
+- debit, credit and balance columns should be displayed side by side;
+- opening balance and movement columns are mandatory;
+- customers with zero closing balance should be excluded when `include_zero_balances = false`, unless they have movements or open items that must remain visible for reconciliation;
+- blocked, inactive or archived customers should be displayed when they have a non-zero balance or non-zero debit or credit amounts;
+- detailed invoice-level open items are out of scope for this report and belong to `AR-002 Customer Ageing Report`.
+- drill-down should be available from each customer balance to customer account movements, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `customer` | Customer account code |
+| `customer_name` | Customer legal or commercial name |
+| `posting_status` | Posting status scope included in customer balances, when exposed by the ERP |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `opening_balance_transaction_currency` | Opening customer balance in transaction currency |
+| `debit_transaction_currency` | Debit movement in transaction currency |
+| `credit_transaction_currency` | Credit movement in transaction currency |
+| `closing_balance_transaction_currency` | Closing customer balance in transaction currency |
+| `opening_balance_base_currency` | Opening customer balance in base currency |
+| `debit_base_currency` | Debit movement in base currency |
+| `credit_base_currency` | Credit movement in base currency |
+| `closing_balance_base_currency` | Closing customer balance in base currency |
+| `last_posting_date` | Last accounting posting date included in the customer balance |
+| `last_document_number` | Last accounting document number included in the customer balance, when available |
+
+Amount sign convention for this report:
+
+- customer receivable balances are presented as positive debit balances;
+- customer credit balances, advances or overpayments are presented as negative balances;
+- debit amounts are positive and credit amounts are negative when movement columns are shown.
+
+---
+
+## 9 Estimated volume
+
+Medium.
+
+The report is a summarized subledger report. It should contain one summarized line per customer and transaction currency, not detailed invoice-level movements.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF
+
+XLSX and CSV are primary review and reconciliation formats. PDF is used for closing documentation and audit review.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Customer balance totals should reconcile with the accounts receivable control accounts in the general ledger for the same current entity and closing date.
+- Customer balances in base currency should reconcile with the AR subledger total for the same closing date.
+- Customers excluded by `include_zero_balances = false` should not change report totals.
+- Customer credit balances should remain visible and should not be netted against other customers.
+- Blocked, inactive or archived customers should remain visible when they have a non-zero balance or non-zero debit or credit amounts.
+- The report should retain enough references to reconcile from customer balance summary to detailed customer account movements.
+- Drill-down from a customer balance should reconcile to `AR-003 Customer Account Movements` for the same current entity, customer, currency and selected closing date.
+
+---
+
+## 12 Open questions
+
+- Which ERP source will define the mapping between customer balances and AR control accounts? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/AR/AR_002_customer_ageing_report.md

@@ -0,0 +1,214 @@
+# AR-002 Customer Ageing Report
+
+## 1 Objective
+
+Provide an ageing analysis of customer receivables based on open customer items at a selected closing date.
+
+The report is used for:
+
+- accounts receivable collection follow-up;
+- credit control;
+- overdue balance monitoring;
+- customer risk review;
+- reconciliation with customer balances;
+- audit and closing review.
+
+---
+
+## 2 Users
+
+- credit control;
+- accounting department;
+- finance department;
+- auditors;
+- sales administration, when customer follow-up is required.
+
+---
+
+## 3 Frequency
+
+- daily;
+- weekly collection review;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `closing_date`
+
+Optional parameters:
+
+- `counterparty`
+- `currency`
+- `entity`
+- `ageing_basis`
+- `include_not_due_items`
+- `include_credit_balances`
+- `view_mode`
+
+Execution scope:
+
+- the report is generated for the current entity unless an entity filter is explicitly supported by the ERP context;
+- open customer items are calculated as of `closing_date`;
+- only accounts receivable customer open items are in scope.
+
+Ageing basis:
+
+- ageing should be calculated from due date by default;
+- posting date should also be available as a selectable ageing basis;
+- document date ageing may be supported if the ERP exposes the required date.
+
+View mode:
+
+- `view_mode = detailed` should display open item details;
+- `view_mode = summarized` should display customer and ageing bucket totals without document-level detail.
+
+---
+
+## 5 Filters
+
+- open items as of `closing_date`;
+- customer or customer range;
+- currency;
+- entity, when supported;
+- ageing bucket;
+- include or exclude not-due items based on `include_not_due_items`;
+- include or exclude customer credit balances based on `include_credit_balances`;
+- detailed or summarized output based on `view_mode`.
+
+Out of scope filters:
+
+- fully settled items after `closing_date`;
+- detailed customer movement history.
+
+Detailed customer movement history is handled by `AR-003 Customer Account Movements`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `customer`
+2. `transaction_currency`
+3. `ageing_bucket_order`
+4. `due_date`
+5. `document_number`
+
+Secondary sorting:
+
+- `posting_date`
+- `document_date`
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `customer`
+- `transaction_currency`
+- `ageing_bucket`
+
+Totals should be displayed by:
+
+- customer;
+- ageing bucket;
+- transaction currency;
+- base currency;
+- report total.
+
+Default ageing buckets:
+
+- not due;
+- 0-30 days overdue;
+- 31-60 days overdue;
+- 61-90 days overdue;
+- over 90 days overdue.
+
+Presentation requirements:
+
+- each open item should be assigned to exactly one ageing bucket;
+- customer credit balances should remain visible and should not be netted against other customers;
+- open item details should be available to support collection and audit review;
+- summarized view should hide document-level fields and display totals by customer, transaction currency and ageing bucket;
+- totals should reconcile with `AR-001 Customer Balance Report` for the same closing date and filters.
+- drill-down should be available from summarized ageing buckets to open item details, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `customer` | Customer account code |
+| `customer_name` | Customer legal or commercial name |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `document_number` | Accounting or AR document number |
+| `document_type` | Document type, such as invoice, credit note, debit note or payment |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP |
+| `posting_date` | Accounting posting date |
+| `document_date` | Source document date |
+| `due_date` | Payment due date |
+| `ageing_basis_date` | Date used to calculate ageing |
+| `days_overdue` | Number of days overdue at `closing_date` |
+| `ageing_bucket` | Ageing bucket label |
+| `ageing_bucket_order` | Sort order of the ageing bucket |
+| `open_amount_transaction_currency` | Open amount in transaction currency |
+| `open_amount_base_currency` | Open amount in base currency |
+| `reference` | External or source reference |
+| `description` | Document or item description |
+
+Amount sign convention for this report:
+
+- open receivable amounts are presented as positive debit balances;
+- customer credit balances, advances or overpayments are presented as negative amounts;
+- open amounts should not be netted across customers.
+
+---
+
+## 9 Estimated volume
+
+High.
+
+The report may contain a large number of open items and should support filtering before generation.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF
+
+XLSX and CSV are primary collection, review and reconciliation formats. PDF is used for closing documentation and audit review.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Total open amount in base currency should reconcile with `AR-001 Customer Balance Report` for the same current entity, closing date and filters.
+- Each open item should be assigned to one ageing bucket only.
+- Items not due at `closing_date` should be included or excluded according to `include_not_due_items`.
+- Customer credit balances should remain visible when `include_credit_balances = true`.
+- Fully settled items as of `closing_date` should be excluded.
+- If the ERP exposes posting status, non-posted operational AR events should be clearly identified through `posting_status`.
+- Open item totals should reconcile with the AR subledger open item balance.
+- Drill-down from a summarized ageing bucket should reconcile to the detailed open items included in the same bucket and then to the related accounting or AR document.
+
+---
+
+## 12 Open questions
+
+- Which ageing buckets should be configurable by users, and which should be fixed by default? This depends on ERP functionality and is currently unknown.
+- Which ERP status defines whether an item is open as of `closing_date`? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/AR/AR_003_customer_account_movements.md

@@ -0,0 +1,223 @@
+# AR-003 Customer Account Movements
+
+## 1 Objective
+
+Provide the detailed list of accounting movements posted to customer accounts over a selected date range.
+
+The report is used for:
+
+- customer account review;
+- reconciliation of customer balances;
+- investigation of invoices, credit notes, debit notes and payments;
+- audit review;
+- support for collection follow-up and customer statement preparation.
+
+---
+
+## 2 Users
+
+- accounting department;
+- credit control;
+- finance department;
+- auditors;
+- customer service or sales administration, when customer follow-up is required.
+
+---
+
+## 3 Frequency
+
+- daily;
+- weekly collection review;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `date_from`
+- `date_to`
+
+Optional parameters:
+
+- `counterparty`
+- `currency`
+- `entity`
+- `document_number`
+- `document_type_filter`
+- `include_settled_items`
+
+Execution scope:
+
+- the report is generated for the current entity unless an entity filter is explicitly supported by the ERP context;
+- customer movements are selected between `date_from` and `date_to`;
+- only accounts receivable customer account movements are in scope.
+
+---
+
+## 5 Filters
+
+- posting date between `date_from` and `date_to`;
+- customer or customer range;
+- currency;
+- entity, when supported;
+- document number;
+- document type based on `document_type_filter`;
+- include or exclude settled items based on `include_settled_items`.
+
+Default document type filter values:
+
+- `all`: all customer account movements;
+- `invoices`: customer invoices only;
+- `receipts`: customer receipts only;
+- `credit_debit_notes`: customer credit notes and debit notes only.
+
+Out of scope filters:
+
+- ageing bucket;
+- due-date ageing;
+- summarized customer balance only.
+
+Ageing analysis is handled by `AR-002 Customer Ageing Report`. Summarized customer balances are handled by `AR-001 Customer Balance Report`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `customer`
+2. `transaction_currency`
+3. `posting_date`
+4. `document_number`
+
+Secondary sorting:
+
+- `document_date`
+- `due_date`
+- `journal_entry_number`
+- `voucher_number`, when available
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `customer`
+- `transaction_currency`
+
+Totals should be displayed by:
+
+- customer;
+- transaction currency;
+- base currency;
+- report total.
+
+Presentation requirements:
+
+- each customer movement should be displayed as a separate line;
+- opening balance rows should be displayed by customer and transaction currency;
+- closing balance rows should be displayed by customer and transaction currency;
+- opening balances are mandatory for all executions;
+- running balances should be calculated line by line between opening and closing balance rows;
+- invoice, credit note, debit note and payment documents should remain visible as separate movements.
+- the selected `document_type_filter` should restrict the movement population without changing the displayed `document_type` value.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `customer` | Customer account code |
+| `customer_name` | Customer legal or commercial name |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `posting_date` | Accounting posting date |
+| `document_date` | Source document date |
+| `due_date` | Payment due date, when available |
+| `journal` | Accounting journal |
+| `journal_entry_number` | Journal entry sequence or identifier |
+| `document_number` | Accounting or AR document number |
+| `customer_reference` | Customer reference or external customer document reference, when available |
+| `payment_reference` | Payment reference, when available |
+| `remittance_reference` | Remittance advice or payment remittance reference, when available |
+| `document_type` | Document type, such as invoice, credit note, debit note or payment |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP |
+| `description` | Document or movement description |
+| `reference` | External or source reference |
+| `debit_transaction_currency` | Debit movement in transaction currency |
+| `credit_transaction_currency` | Credit movement in transaction currency |
+| `balance_transaction_currency` | Running customer balance in transaction currency |
+| `debit_base_currency` | Debit movement in base currency |
+| `credit_base_currency` | Credit movement in base currency |
+| `balance_base_currency` | Running customer balance in base currency |
+| `settlement_status` | Open, partially settled, settled or reversed status, when available |
+| `settlement_date` | Settlement or clearing date, when available |
+| `entered_date` | Entry creation date |
+| `entered_by` | User who created the entry |
+
+`document_number` is the mandatory audit reference. `customer_reference`, `payment_reference` and `remittance_reference` should be displayed when available to support customer payment matching and receipt reconciliation. `reference` is an informational reference.
+
+Optional reference columns:
+
+| Column | Description |
+| --- | --- |
+| `voucher_number` | Internal AR voucher or workflow reference, only when the ERP distinguishes it from `document_number`, customer references and payment references |
+
+`voucher_number` should not duplicate `customer_reference`, `payment_reference` or `remittance_reference`. It should be displayed only if it provides a distinct internal AR processing reference.
+
+Amount sign convention for this report:
+
+- debit movements are displayed as positive amounts;
+- credit movements are displayed as negative amounts;
+- running balances are calculated using this debit-positive and credit-negative convention;
+- customer credit balances, advances or overpayments are presented as negative balances.
+
+---
+
+## 9 Estimated volume
+
+High.
+
+The report may contain a large number of customer movement lines and should support filtering before generation.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF, including all detail columns
+
+CSV and XLSX are primary analysis and reconciliation formats. PDF is used for audit review and customer account documentation.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Opening balance plus movements should reconcile to closing balance by customer and transaction currency.
+- Closing balances should reconcile with `AR-001 Customer Balance Report` for the same current entity, `date_to` and filters.
+- Movement totals should reconcile with the accounts receivable subledger for the selected date range.
+- Movement totals in base currency should reconcile with the related general ledger AR control accounts for the selected date range.
+- Settled items should be included or excluded according to `include_settled_items`.
+- Document type filtering should apply according to `document_type_filter`, with `all` as the default value.
+- Customer references, payment references and remittance references should remain visible when available to support receipt reconciliation.
+- If the ERP exposes posting status, non-posted operational AR events should be clearly identified through `posting_status`.
+- Each line should retain enough audit references to trace back to the accounting document and source document where available.
+
+---
+
+## 12 Open questions
+
+- Which ERP status values should map to `settlement_status`? This information is currently unknown.
+- Which ERP document type values should map to `invoices`, `receipts` and `credit_debit_notes`? This information is currently unknown.
+- Does the ERP expose `customer_reference`, `payment_reference` and `remittance_reference` as distinct fields? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/GL/GL_001_general_ledger.md

@@ -0,0 +1,192 @@
+# GL-001 General Ledger
+
+## 1 Objective
+
+Provide the detailed list of accounting entries for selected accounts over a defined period.
+
+The report is used for:
+
+- accounting control;
+- account reconciliation;
+- audit review;
+- period-end closing analysis.
+
+---
+
+## 2 Users
+
+- accounting department;
+- auditors;
+- financial controlling;
+- finance management.
+
+---
+
+## 3 Frequency
+
+- daily;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Standard parameters:
+
+- `date_from`
+- `date_to`
+- `account`
+- `currency`
+- `journal`
+- `entity`
+
+Additional filter parameters out of scope for this report:
+
+- `counterparty`
+- `analytic_account`
+- `profit_center`
+
+---
+
+## 5 Filters
+
+- posting date between `date_from` and `date_to`;
+- account or account range;
+- currency;
+- journal;
+- entity;
+- document number or voucher number, if available.
+
+---
+
+## 6 Sorting
+
+Default sorting should follow the common reporting standards:
+
+1. `account`
+2. `transaction_currency`
+3. `posting_date`
+4. `document_number`
+
+Secondary sorting:
+
+- `journal`
+- `journal_entry_number`
+- `voucher_number`
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `account`
+- `transaction_currency`
+
+Totals should be displayed by:
+
+- account;
+- transaction currency;
+- base currency;
+- report total.
+
+Optional grouping to confirm:
+
+- entity.
+
+Out of scope grouping:
+
+- journal;
+- counterparty;
+- analytic account;
+- profit center.
+
+Balance presentation:
+
+- opening balance rows should be displayed by account and transaction currency;
+- closing balance rows should be displayed by account and transaction currency;
+- opening and closing balances should be shown in transaction currency and base currency;
+- running balances should be calculated line by line between opening and closing balance rows.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `account` | General ledger account code |
+| `account_name` | General ledger account name |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `posting_date` | Accounting posting date |
+| `document_date` | Source document date |
+| `journal` | Accounting journal |
+| `journal_entry_number` | Journal entry sequence or identifier |
+| `document_number` | Accounting document number |
+| `document_type` | Accounting document type |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP |
+| `supplier_invoice_number` | Supplier invoice number for AP-related entries, when available |
+| `counterparty` | Customer, supplier, broker or other party |
+| `voucher_number` | Voucher or internal accounting reference |
+| `description` | Entry description |
+| `reference` | External or source reference |
+| `payable_qty` | Payable quantity for commodity-related postings only |
+| `uom` | Unit of measure for payable quantity |
+| `debit_transaction_currency` | Debit amount in transaction currency |
+| `credit_transaction_currency` | Credit amount in transaction currency |
+| `balance_transaction_currency` | Running balance in transaction currency |
+| `debit_base_currency` | Debit amount in base currency |
+| `credit_base_currency` | Credit amount in base currency |
+| `balance_base_currency` | Running balance in base currency |
+| `entered_date` | Entry creation date |
+| `entered_by` | User who created the entry |
+| `modified_date` | Last modification date |
+| `modified_by` | User who last modified the entry |
+
+The report should display individual accounts only. Account hierarchy levels are out of scope for this report unless requested later.
+
+`document_number` is the mandatory accounting audit reference. For AP-related entries, `supplier_invoice_number` should be displayed when available to identify the supplier invoice. `voucher_number` and `reference` are informational references.
+
+Amount sign convention for this report:
+
+- debit amounts are displayed as positive amounts;
+- credit amounts are displayed as negative amounts;
+- running balances are calculated using this debit-positive and credit-negative convention.
+
+---
+
+## 9 Estimated volume
+
+High.
+
+The report may contain a large number of accounting lines and should support export and filtering before generation.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF, including all detail columns
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Total debit and credit amounts should reconcile by selected period, account and transaction currency.
+- For each account and transaction currency grouping, opening balance plus movements should reconcile to closing balance.
+- The report total in base currency should reconcile with the trial balance for the same entity, period and account selection.
+- Each line should retain enough audit references to trace back to the accounting document and source document where available.
+- AP-related entries should be identifiable by both `document_number` and `supplier_invoice_number` when the supplier invoice number is available.
+- Debit, credit and balance signs should follow the GL-specific convention defined in this report.
+
+---
+
+## 12 Open questions
+
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/GL/GL_002_accounting_journals.md

@@ -0,0 +1,186 @@
+# GL-002 Accounting Journals
+
+## 1 Objective
+
+Provide the detailed list of accounting entries grouped by accounting journal over a selected date range.
+
+The report is used for:
+
+- journal review;
+- accounting control;
+- audit review;
+- validation of posted accounting batches;
+- period-end closing analysis.
+
+---
+
+## 2 Users
+
+- accounting department;
+- auditors;
+- financial controlling;
+- finance management.
+
+---
+
+## 3 Frequency
+
+- daily;
+- monthly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `date_from`
+- `date_to`
+
+Optional parameters:
+
+- `journal`
+- `currency`
+- `entity`
+
+Additional filter parameters out of scope for this report:
+
+- `counterparty`
+- `analytic_account`
+- `profit_center`
+
+`journal` is optional. When no journal is selected, the report should include all journals for the selected date range and other filters.
+
+---
+
+## 5 Filters
+
+- posting date between `date_from` and `date_to`;
+- journal or journal range;
+- currency;
+- entity;
+- document number or journal entry number, if available.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `journal`
+2. `posting_date`
+3. `journal_entry_number`
+4. `document_number`
+5. `account`
+
+Secondary sorting:
+
+- `transaction_currency`
+- `voucher_number`
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `journal`
+- `journal_entry_number`
+
+Totals should be displayed by:
+
+- journal;
+- journal entry;
+- transaction currency;
+- base currency;
+- report total.
+
+Presentation requirements:
+
+- accounting entries should be grouped by journal first;
+- each journal entry should show all debit and credit lines required to understand the full accounting document;
+- journal entry totals should allow users to verify that each entry balances;
+- running account balances are out of scope for this report and belong to `GL-001 General Ledger`.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `entity` | Legal entity or company code |
+| `journal` | Accounting journal |
+| `journal_name` | Accounting journal name |
+| `journal_entry_number` | Journal entry sequence or identifier |
+| `posting_date` | Accounting posting date |
+| `document_date` | Source document date |
+| `document_number` | Accounting document number |
+| `document_type` | Accounting document type |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP |
+| `supplier_invoice_number` | Supplier invoice number for AP-related entries, when available |
+| `counterparty` | Customer, supplier, broker or other party |
+| `voucher_number` | Voucher or internal accounting reference |
+| `account` | General ledger account code |
+| `account_name` | General ledger account name |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `description` | Entry line description |
+| `reference` | External or source reference |
+| `debit_transaction_currency` | Debit amount in transaction currency |
+| `credit_transaction_currency` | Credit amount in transaction currency |
+| `debit_base_currency` | Debit amount in base currency |
+| `credit_base_currency` | Credit amount in base currency |
+| `entered_date` | Entry creation date |
+| `entered_by` | User who created the entry |
+| `modified_date` | Last modification date |
+| `modified_by` | User who last modified the entry |
+
+`document_number` is the mandatory accounting audit reference. For AP-related entries, `supplier_invoice_number` should be displayed when available to identify the supplier invoice. `voucher_number` and `reference` are informational references.
+
+`counterparty` is an informational output column only and should not be available as a filter in this report.
+
+Amount sign convention for this report:
+
+- debit amounts are displayed as positive amounts;
+- credit amounts are displayed as negative amounts;
+- journal entry totals are calculated using this debit-positive and credit-negative convention.
+
+---
+
+## 9 Estimated volume
+
+High.
+
+The report may contain a large number of journal lines and should support filtering before generation.
+
+---
+
+## 10 Export formats
+
+- CSV
+- XLSX
+- PDF, including all detail columns
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Each journal entry should balance in base currency using the debit-positive and credit-negative convention.
+- Each journal entry should balance in transaction currency when all lines use the same transaction currency.
+- Report totals by journal should reconcile with the general ledger for the same current entity, date range and journal selection.
+- The report should retain enough audit references to trace each line back to the accounting document and source document where available.
+- AP-related entries should be identifiable by both `document_number` and `supplier_invoice_number` when the supplier invoice number is available.
+- If the ERP exposes posting status, non-posted operational or non-final entries should be clearly identified through `posting_status`.
+- Deleted, reversed or cancelled entries should be either excluded or clearly identified depending on ERP posting status rules.
+
+---
+
+## 12 Open questions
+
+- Which ERP statuses should be included by default: posted only, or posted plus reversed/cancelled entries marked separately? ERP dependance Unknown yet
+- Should the report include additional journal entry header fields such as approval status or batch identifier? ERP dependance, Unknown yet
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/REPORTS_INDEX.md

@@ -0,0 +1,84 @@
+# Reports Index
+
+Ce dossier contient les specifications fonctionnelles detaillees des rapports comptables et financiers.
+
+Chaque sous-dossier correspond a un domaine de reporting. Les rapports doivent rester independants du modele technique de donnees tant que le mapping ERP / CTRM n'est pas defini.
+
+## Domaines
+
+| Dossier | Domaine | Role |
+| --- | --- | --- |
+| `GL/` | General Ledger | Grand livre, journaux, mouvements comptables |
+| `STATUTORY/` | Statutory Financial Reporting | Etats financiers statutaires et balances |
+| `AR/` | Accounts Receivable | Clients, factures, paiements, ageing |
+| `AP/` | Accounts Payable | Fournisseurs, factures, paiements, ageing |
+| `CASH/` | Banking and Cash Management | Banque, tresorerie, paiements, rapprochement |
+| `FX/` | Foreign Exchange | Expositions, gains/pertes realises et latents |
+| `TRADING/` | Trading and Positions | Positions, MTM, P&L trading |
+| `ANALYTICS/` | Analytical Accounting | Profit center, trading desk, marges |
+
+## Suivi des specifications
+
+| Code | Rapport | Dossier | Statut |
+| --- | --- | --- | --- |
+| GL-001 | General Ledger | `GL/` | A revoir |
+| GL-002 | Accounting Journals | `GL/` | Brouillon avance |
+| FIN-001 | Comparative Balance Sheet | `STATUTORY/` | Brouillon avance |
+| FIN-002 | Comparative Profit and Loss Statement | `STATUTORY/` | Brouillon avance |
+| FIN-003 | Trial Balance | `STATUTORY/` | Brouillon avance |
+| AR-001 | Customer Balance Report | `AR/` | Brouillon avance |
+| AR-002 | Customer Ageing Report | `AR/` | Brouillon avance |
+| AR-003 | Customer Account Movements | `AR/` | Brouillon avance |
+| AP-001 | Supplier Balance Report | `AP/` | Brouillon avance |
+| AP-002 | Supplier Ageing Report | `AP/` | Brouillon avance |
+| AP-003 | Supplier Account Movements | `AP/` | Brouillon avance |
+| CASH-001 | Bank Ledger | `CASH/` | A creer |
+| CASH-002 | Cash Position Report | `CASH/` | A creer |
+| CASH-003 | Payment History | `CASH/` | A creer |
+| FX-001 | FX Exposure Report | `FX/` | A creer |
+| FX-002 | Realized FX Gains and Losses | `FX/` | A creer |
+| FX-003 | Unrealized FX Gains and Losses | `FX/` | A creer |
+| TRD-001 | Open Trading Positions | `TRADING/` | A creer |
+| TRD-002 | Mark-to-Market Valuation | `TRADING/` | A creer |
+| TRD-003 | Trading Profit and Loss | `TRADING/` | A creer |
+| ANA-001 | Profitability by Profit Center | `ANALYTICS/` | A creer |
+| ANA-002 | Profitability by Trading Desk | `ANALYTICS/` | A creer |
+| ANA-003 | Margin Analysis | `ANALYTICS/` | A creer |
+
+## Gabarit conseille
+
+```markdown
+# CODE-NNN Report Name
+
+## 1 Objective
+
+## 2 Users
+
+## 3 Frequency
+
+## 4 Parameters
+
+## 5 Filters
+
+## 6 Sorting
+
+## 7 Grouping
+
+## 8 Output Structure
+
+## 9 Estimated volume
+
+## 10 Export formats
+
+## 11 Controls / reconciliation rules
+
+## 12 Open questions
+```
+
+## Regles de redaction
+
+- Utiliser les parametres standard de `Docs/reporting_parameters.md` quand ils s'appliquent.
+- Respecter les conventions de champs, montants, signes et tris de `Docs/reporting_standards.md`.
+- Ajouter les colonnes de sortie avec des noms techniques stables, en anglais et en snake_case.
+- Placer les questions ouvertes dans la fiche du rapport plutot que dans des notes separees.
+- Ne pas melanger specification fonctionnelle et implementation SQL tant que le mapping de donnees n'est pas disponible.

Reports/STATUTORY/FIN_001_comparative_balance_sheet.md

@@ -0,0 +1,185 @@
+# FIN-001 Comparative Balance Sheet
+
+## 1 Objective
+
+Provide a statutory balance sheet comparing the current fiscal year position with the previous fiscal year position at a selected closing date.
+
+The report is used for:
+
+- statutory financial reporting;
+- management review;
+- audit review;
+- period-end and year-end closing analysis.
+
+---
+
+## 2 Users
+
+- management;
+- finance department;
+- accounting department;
+- auditors.
+
+---
+
+## 3 Frequency
+
+- monthly closing;
+- quarterly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `closing_date`
+
+Optional parameters:
+
+- `currency`
+- `include_zero_accounts`
+
+Execution scope:
+
+- the report is limited to the current entity;
+- entity selection is not a report parameter;
+- multi-entity and consolidation reporting are out of scope and should be handled by a dedicated consolidation report.
+
+Derived comparison period:
+
+- current fiscal year balance is calculated as of `closing_date`;
+- previous fiscal year balance is calculated as of the equivalent prior fiscal year closing date.
+
+---
+
+## 5 Filters
+
+- accounting closing date equal to `closing_date`;
+- currency, if the report is generated for a selected currency;
+- include or exclude zero-balance accounts based on `include_zero_accounts`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `section_order`
+2. `account_group_order`
+3. `account`
+
+The report should follow the statutory balance sheet structure rather than the accounting detail sorting convention used for ledger reports.
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `section`
+- `account_group`
+- `account`
+
+Expected sections:
+
+- assets;
+- liabilities;
+- equity.
+
+Totals should be displayed by:
+
+- section;
+- account group;
+- report total.
+
+Presentation requirements:
+
+- assets should be presented separately from liabilities and equity;
+- total assets should reconcile with total liabilities and equity;
+- accounts should be displayed through the balance sheet hierarchy, not as a flat ledger listing.
+- drill-down should be available from section or account group totals to account balances, then to general ledger movements, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `section` | Balance sheet section, such as assets, liabilities or equity |
+| `section_order` | Sort order of the balance sheet section |
+| `account_group` | Balance sheet account group |
+| `account_group_order` | Sort order of the account group |
+| `account` | General ledger account code |
+| `account_name` | General ledger account name |
+| `posting_status` | Posting status scope included in source balances, when exposed by the ERP |
+| `base_currency` | Functional or company base currency |
+| `balance_current_year_base_currency` | Balance at the selected closing date in base currency |
+| `balance_previous_year_base_currency` | Balance at the prior fiscal year comparison date in base currency |
+| `variance_base_currency` | Difference between current year and previous year balances in base currency |
+| `variance_percent_base_currency` | Percentage variance versus previous year balance in base currency |
+
+Optional transaction currency columns:
+
+| Column | Description |
+| --- | --- |
+| `transaction_currency` | Original transaction currency, when transaction currency presentation is enabled |
+| `balance_current_year_transaction_currency` | Balance at the selected closing date in transaction currency, when transaction currency presentation is enabled |
+| `balance_previous_year_transaction_currency` | Balance at the prior fiscal year comparison date in transaction currency, when transaction currency presentation is enabled |
+
+Comparison rule:
+
+- the statutory presentation is based on `base_currency` by default;
+- transaction currency balances are optional and should be displayed only when transaction currency presentation is enabled;
+- comparative variance amounts are calculated on base currency balances only;
+- `variance_percent_base_currency` should be hidden or left blank when `balance_previous_year_base_currency` is zero.
+
+Amount sign convention for this report:
+
+- assets are presented as positive debit balances;
+- liabilities are presented as positive credit balances;
+- equity is presented as positive credit balances;
+- variance follows the same presentation sign as the related balance sheet section.
+
+---
+
+## 9 Estimated volume
+
+Medium.
+
+The report is a summarized statutory statement. It should contain grouped balance sheet lines rather than individual journal entry lines.
+
+---
+
+## 10 Export formats
+
+- PDF
+- CSV
+- XLSX
+
+PDF is the primary presentation format. CSV and XLSX are used for review, audit and reconciliation.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Total assets should equal total liabilities and equity for the selected closing date.
+- Current fiscal year balances should reconcile with the trial balance for the current entity and closing date.
+- Previous fiscal year balances should reconcile with the prior fiscal year trial balance.
+- The account mapping to balance sheet sections should be complete for all included balance sheet accounts.
+- Accounts excluded by `include_zero_accounts = false` should not change section totals.
+- Comparative variance should reconcile to the difference between current and previous fiscal year balances in base currency.
+- Sign presentation should follow the financial statement conventions in `Docs/reporting_standards.md`.
+- Drill-down from a balance sheet line should reconcile to the same account balance population used by `FIN-003 Trial Balance`, then to `GL-001 General Ledger` movements for the selected account and date.
+
+---
+
+## 12 Open questions
+
+- Should `closing_date` always imply fiscal year-to-date balances, or should accounting period calendars be parameterized? This depends on ERP functionality and is currently unknown.
+- Which ERP source will define the balance sheet account hierarchy and sort order?
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/STATUTORY/FIN_002_comparative_profit_and_loss_statement.md

@@ -0,0 +1,191 @@
+# FIN-002 Comparative Profit and Loss Statement
+
+## 1 Objective
+
+Provide a statutory profit and loss statement comparing the current fiscal year result with the previous fiscal year result for a selected closing date or reporting period.
+
+The report is used for:
+
+- statutory financial reporting;
+- management review;
+- audit review;
+- period-end and year-end closing analysis;
+- comparison of revenue, expenses and net result versus the prior fiscal year.
+
+---
+
+## 2 Users
+
+- management;
+- finance department;
+- accounting department;
+- auditors.
+
+---
+
+## 3 Frequency
+
+- monthly closing;
+- quarterly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `closing_date`
+
+Optional parameters:
+
+- `currency`
+- `include_zero_accounts`
+
+Execution scope:
+
+- the report is limited to the current entity;
+- entity selection is not a report parameter;
+- multi-entity and consolidation reporting are out of scope and should be handled by a dedicated consolidation report.
+
+Derived comparison period:
+
+- current fiscal year result is calculated up to `closing_date`;
+- previous fiscal year result is calculated up to the equivalent prior fiscal year comparison date.
+
+---
+
+## 5 Filters
+
+- accounting period up to `closing_date`;
+- profit and loss accounts only;
+- currency, if the report is generated for a selected currency;
+- include or exclude zero-balance accounts based on `include_zero_accounts`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `section_order`
+2. `account_group_order`
+3. `account`
+
+The report should follow the statutory profit and loss structure rather than the accounting detail sorting convention used for ledger reports.
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `section`
+- `account_group`
+- `account`
+
+Expected sections:
+
+- revenue;
+- cost of sales;
+- gross result;
+- operating expenses;
+- operating result;
+- financial result;
+- tax;
+- net result.
+
+Totals should be displayed by:
+
+- section;
+- account group;
+- report total.
+
+Presentation requirements:
+
+- revenue and expense accounts should be presented separately;
+- subtotal lines should support gross result, operating result and net result where available in the statutory hierarchy;
+- accounts should be displayed through the profit and loss hierarchy, not as a flat ledger listing;
+- monthly columns are out of scope for this report.
+- drill-down should be available from section, subtotal or account group totals to account results, then to general ledger movements, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `section` | Profit and loss section, such as revenue, expenses or net result |
+| `section_order` | Sort order of the profit and loss section |
+| `account_group` | Profit and loss account group |
+| `account_group_order` | Sort order of the account group |
+| `account` | General ledger account code |
+| `account_name` | General ledger account name |
+| `posting_status` | Posting status scope included in source results, when exposed by the ERP |
+| `base_currency` | Functional or company base currency |
+| `result_current_year_base_currency` | Current fiscal year result in base currency |
+| `result_previous_year_base_currency` | Previous fiscal year result in base currency |
+| `variance_base_currency` | Difference between current year and previous year results in base currency |
+| `variance_percent_base_currency` | Percentage variance versus previous year result in base currency |
+
+Optional transaction currency columns:
+
+| Column | Description |
+| --- | --- |
+| `transaction_currency` | Original transaction currency, when transaction currency presentation is enabled |
+| `result_current_year_transaction_currency` | Current fiscal year result in transaction currency, when transaction currency presentation is enabled |
+| `result_previous_year_transaction_currency` | Previous fiscal year result in transaction currency, when transaction currency presentation is enabled |
+
+Comparison rule:
+
+- the statutory presentation is based on `base_currency` by default;
+- transaction currency results are optional and should be displayed only when transaction currency presentation is enabled;
+- comparative variance amounts are calculated on base currency amounts only;
+- `variance_percent_base_currency` should be hidden or left blank when `result_previous_year_base_currency` is zero.
+
+Amount sign convention for this report:
+
+- revenue is presented as positive credit result;
+- expenses are presented as positive debit result;
+- variance follows the same presentation sign as the related profit and loss section.
+
+---
+
+## 9 Estimated volume
+
+Medium.
+
+The report is a summarized statutory statement. It should contain grouped profit and loss lines rather than individual journal entry lines.
+
+---
+
+## 10 Export formats
+
+- PDF
+- CSV
+- XLSX
+
+PDF is the primary presentation format. CSV and XLSX are used for review, audit and reconciliation.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Current fiscal year result should reconcile with the trial balance profit and loss accounts for the current entity and closing date.
+- Previous fiscal year result should reconcile with the prior fiscal year trial balance profit and loss accounts.
+- The account mapping to profit and loss sections should be complete for all included profit and loss accounts.
+- Accounts excluded by `include_zero_accounts = false` should not change section totals.
+- Comparative variance should reconcile to the difference between current and previous fiscal year results in base currency.
+- Sign presentation should follow the financial statement conventions in `Docs/reporting_standards.md`.
+- Drill-down from a profit and loss line should reconcile to the same account result population used by `FIN-003 Trial Balance`, then to `GL-001 General Ledger` movements for the selected account and period.
+
+---
+
+## 12 Open questions
+
+- Should `closing_date` always imply fiscal year-to-date results, or should accounting period calendars be parameterized? This depends on ERP functionality and is currently unknown.
+- Which ERP source will define the profit and loss account hierarchy and sort order?
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.

Reports/STATUTORY/FIN_003_trial_balance.md

@@ -0,0 +1,175 @@
+# FIN-003 Trial Balance
+
+## 1 Objective
+
+Provide a summarized trial balance listing opening balance, debit, credit and closing balance amounts for all general ledger accounts over a selected date range.
+
+The report is used for:
+
+- accounting control;
+- statutory financial reporting preparation;
+- reconciliation between the general ledger and financial statements;
+- audit review;
+- period-end and year-end closing analysis.
+
+---
+
+## 2 Users
+
+- accounting department;
+- finance department;
+- auditors;
+- financial controlling.
+
+---
+
+## 3 Frequency
+
+- monthly closing;
+- quarterly closing;
+- year-end closing;
+- ad hoc audit requests.
+
+---
+
+## 4 Parameters
+
+Required parameters:
+
+- `date_from`
+- `date_to`
+
+Optional parameters:
+
+- `currency`
+- `include_zero_accounts`
+
+Execution scope:
+
+- the report is limited to the current entity;
+- entity selection is not a report parameter;
+- multi-entity and consolidation reporting are out of scope and should be handled by a dedicated consolidation report.
+
+Balance period:
+
+- `date_from` defaults to the first day of the current fiscal year;
+- `date_to` defaults to today's date;
+- opening balances are calculated as of the day before `date_from`;
+- period movements are calculated from `date_from` to `date_to`;
+- closing balances are calculated as opening balances plus period movements.
+
+---
+
+## 5 Filters
+
+- posting date between `date_from` and `date_to`;
+- all general ledger accounts;
+- currency, if the report is generated for a selected currency;
+- include or exclude zero-balance accounts based on `include_zero_accounts`.
+
+---
+
+## 6 Sorting
+
+Default sorting:
+
+1. `account`
+2. `transaction_currency`
+
+The report should follow account order and should not use the statutory balance sheet or profit and loss hierarchy as its primary sorting structure.
+
+---
+
+## 7 Grouping
+
+Default grouping:
+
+- `account`
+- `transaction_currency`
+
+Totals should be displayed by:
+
+- account;
+- transaction currency;
+- base currency;
+- report total.
+
+Presentation requirements:
+
+- each general ledger account should be displayed once per transaction currency;
+- debit, credit and balance columns should be displayed side by side;
+- opening balance columns are mandatory;
+- zero-balance accounts should be controlled by `include_zero_accounts`;
+- accounts with movements in the selected period should be displayed even when their closing balance is zero;
+- inactive accounts should be displayed when they have movements in the selected period;
+- balance sheet and profit and loss account classification may be shown as informational attributes when available.
+- drill-down should be available from each account and transaction currency balance to the underlying general ledger movements, accounting documents and source documents when available.
+
+---
+
+## 8 Output Structure
+
+Required columns:
+
+| Column | Description |
+| --- | --- |
+| `account` | General ledger account code |
+| `account_name` | General ledger account name |
+| `account_type` | Account classification, such as asset, liability, equity, revenue or expense |
+| `posting_status` | Posting status scope included in trial balance amounts, when exposed by the ERP |
+| `transaction_currency` | Original transaction currency |
+| `base_currency` | Functional or company base currency |
+| `opening_balance_transaction_currency` | Opening balance in transaction currency as of the day before `date_from` |
+| `debit_transaction_currency` | Debit period movement in transaction currency |
+| `credit_transaction_currency` | Credit period movement in transaction currency |
+| `closing_balance_transaction_currency` | Closing balance in transaction currency |
+| `opening_balance_base_currency` | Opening balance in base currency as of the day before `date_from` |
+| `debit_base_currency` | Debit period movement in base currency |
+| `credit_base_currency` | Credit period movement in base currency |
+| `closing_balance_base_currency` | Closing balance in base currency |
+
+Amount sign convention for this report:
+
+- debit movements are displayed as positive amounts;
+- credit movements are displayed as negative amounts;
+- opening and closing balances are displayed using the debit-positive and credit-negative convention;
+- closing balance equals opening balance plus debit movements plus credit movements.
+
+---
+
+## 9 Estimated volume
+
+Medium.
+
+The report is a summarized accounting control report. It should contain one summarized line per account and transaction currency, rather than individual journal entry lines.
+
+---
+
+## 10 Export formats
+
+- PDF
+- CSV
+- XLSX
+
+CSV and XLSX are primary review and reconciliation formats. PDF is used for audit and closing documentation.
+
+---
+
+## 11 Controls / reconciliation rules
+
+- Total debit movements plus total credit movements should reconcile in base currency for the selected date range.
+- Closing balances should reconcile with the general ledger for the same current entity and selected date range.
+- Balance sheet account totals should reconcile with `FIN-001 Comparative Balance Sheet` as of `date_to` when the same account mapping is used.
+- Profit and loss account totals should reconcile with `FIN-002 Comparative Profit and Loss Statement` up to `date_to` when the same account mapping is used.
+- Accounts excluded by `include_zero_accounts = false` should not change report totals.
+- The account list should include all active general ledger accounts with a balance or movements in the selected period.
+- The account list should include inactive general ledger accounts when they have movements in the selected period.
+- Accounts with zero closing balance should still be displayed when they have debit or credit movements in the selected period.
+- Drill-down from an account balance should reconcile to `GL-001 General Ledger` for the same current entity, account, currency and selected date range.
+
+---
+
+## 12 Open questions
+
+- Which ERP source will define account type and financial statement classification? This information is currently unknown.
+- Should `posting_status` be displayed in the first implementation? This depends on the target ERP capabilities.