Initial accounting reports documentation

Docs/CTRM_ACCOUNTING_REPORTING_ARCHITECTURE.md

@@ -0,0 +1,407 @@
+# CTRM Accounting Reporting Architecture
+
+This document defines the **conceptual architecture of accounting and financial reporting** in a CTRM / ERP environment.
+
+The purpose is to provide a **standard framework for financial reporting** independent of the technical data model.
+
+This architecture will later guide:
+
+- ERP / CTRM data mapping
+- SQL query design
+- BI reporting layers
+- reconciliation controls
+- auditability
+
+The framework follows **commodity trading accounting best practices**.
+
+---
+
+# 1. Reporting Layers
+
+In a CTRM environment, reporting must be organized into **five logical layers**.
+Operational Layer
+↓
+Subledger Layer
+↓
+Accounting Layer
+↓
+Financial Reporting Layer
+↓
+Management Analytics Layer
+
+Each layer has different users and reporting objectives.
+
+---
+
+# 2. Operational Layer
+
+This layer contains **trading and operational activity**.
+
+Typical objects:
+
+- contracts
+- trades
+- positions
+- physical deliveries
+- logistics
+- settlements
+
+Reports in this layer are typically **operational dashboards**.
+
+Examples:
+Open positions
+Trade lifecycle
+Contract exposures
+Inventory movements
+
+These reports are **not accounting reports**, but they feed accounting events.
+
+---
+
+# 3. Subledger Layer
+
+Subledgers translate operational activity into **financial transactions**.
+
+Typical subledgers in a CTRM:
+Accounts Receivable
+Accounts Payable
+Inventory
+Cash / Banking
+Derivatives
+Forex
+
+Reports in this layer include:
+Customer balances
+Supplier balances
+Payment status
+Cash movements
+Inventory valuation
+Derivative positions
+
+Subledger reports allow **operational reconciliation** before data reaches the general ledger.
+
+---
+
+# 4. Accounting Layer
+
+This layer represents the **official accounting ledger**.
+
+It contains:
+journal entries
+posting dates
+accounting accounts
+currencies
+documents
+
+Core accounting reports:
+General ledger
+Trial balance
+Journal listing
+Account movements
+
+These reports represent the **single source of truth** for financial reporting.
+
+---
+
+# 5. Financial Reporting Layer
+
+This layer produces **statutory financial statements**.
+
+Typical reports:
+Balance sheet
+Profit & loss
+Cash flow statement
+Comparative financial statements
+
+Characteristics:
+
+- structured by account hierarchy
+- aligned with accounting standards
+- used for management and external reporting
+
+---
+
+# 6. Management Analytics Layer
+
+This layer provides **business performance analytics**.
+
+Examples:
+Trading P&L
+Desk profitability
+Commodity profitability
+Margin analysis
+Risk exposure
+
+Data sources may include:
+
+- accounting entries
+- positions
+- MTM valuations
+- hedging data
+
+This layer often feeds **BI tools and dashboards**.
+
+---
+
+# 7. Core Accounting Objects
+
+To support reporting, the system must expose a minimal conceptual model.
+
+## Journal Entry
+
+Basic accounting object.
+
+Typical attributes:
+entry_id
+journal
+posting_date
+document_number
+account
+currency
+debit
+credit
+description
+
+---
+
+## Accounting Document
+
+Represents the business origin of entries.
+
+Examples:
+invoice
+payment
+bank transaction
+mtm adjustment
+fx settlement
+
+Each document may generate **multiple journal entries**.
+
+---
+
+# 8. Accounting Events
+
+Commodity trading systems generate accounting through **events**.
+
+Examples:
+Trade confirmation
+Physical delivery
+Invoice issuance
+Payment execution
+MTM revaluation
+FX settlement
+Derivative settlement
+
+Each event generates a **defined accounting pattern**.
+
+Example:
+Customer invoice
+
+Debit Accounts Receivable
+Credit Revenue
+
+---
+
+# 9. Realized vs Unrealized Results
+
+A key concept in CTRM reporting is the distinction between:
+Realized results
+Unrealized results
+
+## Realized P&L
+
+Generated when economic events are completed.
+
+Examples:
+sale invoice
+contract settlement
+derivative settlement
+fx settlement
+
+## Unrealized P&L
+
+Generated by **valuation adjustments**.
+
+Examples:
+MTM valuation
+inventory revaluation
+open FX exposures
+
+These entries are usually **reversed in the following period**.
+
+---
+
+# 10. Mark-to-Market Reporting
+
+CTRM systems rely heavily on **MTM valuation**.
+
+Typical reports:
+MTM valuation by contract
+MTM valuation by desk
+MTM valuation by commodity
+
+Accounting representation:
+Debit / Credit Unrealized P&L
+Counterpart MTM reserve account
+
+---
+
+# 11. Hedge Accounting
+
+Many CTRM systems implement **hedge relationships**.
+
+Concepts:
+hedged item
+hedging instrument
+hedge effectiveness
+
+Reports include:
+hedge exposure
+hedge effectiveness
+hedge P&L
+
+Accounting depends on the hedge model used.
+
+---
+
+# 12. Forex Reporting
+
+Commodity trading often involves **multi-currency flows**.
+
+Forex reporting usually includes:
+FX exposures
+Realized FX results
+Unrealized FX results
+FX revaluation
+
+Key accounting processes:
+currency translation
+revaluation of open balances
+FX settlement
+
+---
+
+# 13. Cash and Banking Reporting
+
+Cash reports are essential for reconciliation.
+
+Typical reports:
+Bank ledger
+Cash position
+Payment history
+Bank reconciliation
+
+These reports ensure:
+ERP balances = bank statements
+
+---
+
+# 14. Reconciliation Framework
+
+A CTRM reporting architecture must include reconciliation layers.
+
+Critical reconciliations:
+Subledger vs General Ledger
+MTM vs Accounting MTM
+Positions vs Accounting Inventory
+Bank vs Accounting Cash
+
+These controls are essential for audit.
+
+---
+
+# 15. Multi-Currency Reporting
+
+Commodity trading is inherently multi-currency.
+
+Reports must support:
+transaction currency
+functional currency
+reporting currency
+
+Typical reporting outputs:
+local currency
+group currency
+contract currency
+
+---
+
+# 16. Report Parameterization
+
+Most reports should support standard parameters.
+
+Typical parameters:
+date_from
+date_to
+entity
+account
+currency
+counterparty
+desk
+commodity
+contract
+
+Standardization allows consistent reporting behaviour.
+
+---
+
+# 17. Export and Integration
+
+Accounting reports must support export formats.
+
+Standard outputs:
+CSV
+XLSX
+PDF
+API endpoints
+
+This allows integration with:
+BI tools
+regulatory reporting
+external auditors
+
+---
+
+# 18. Auditability
+
+All reports must guarantee traceability.
+
+Requirements:
+source document reference
+journal entry reference
+posting date
+user identification
+
+This ensures **audit compliance**.
+
+---
+
+# 19. Future ERP Mapping
+
+Once the ERP / CTRM data model is available, the next step will be:
+map reports → tables
+map reports → fields
+define SQL views
+define BI datasets
+
+The current documentation defines the **functional blueprint**.
+
+---
+
+# 20. Summary
+
+The reporting architecture is based on the following layers:
+Operational
+Subledger
+Accounting
+Financial Reporting
+Management Analytics
+
+This layered model ensures:
+clear responsibilities
+robust reconciliation
+auditability
+scalable reporting
+
+It provides the foundation for implementing accounting reporting
+in a CTRM / ERP open-source platform.

Docs/DOCS_GUIDE.md

@@ -0,0 +1,37 @@
+# Documentation Guide
+
+Ce dossier contient les documents transverses qui cadrent l'ensemble du reporting comptable et financier.
+
+Les fichiers de ce dossier servent de reference pour les specifications detaillees situees dans `../Reports`.
+
+## Contenu
+
+| Fichier | Role |
+| --- | --- |
+| `client_specific_excel_reports.md` | Rapports Excel specifiques client identifies pendant le cadrage |
+| `CTRM_ACCOUNTING_REPORTING_ARCHITECTURE.md` | Architecture conceptuelle du reporting CTRM / ERP |
+| `reporting_catalog.md` | Catalogue des domaines et rapports cibles |
+| `reporting_fields_catalog.md` | Dictionnaire des champs de reporting a mapper avec le CTRM / ERP |
+| `reporting_improvement_backlog.md` | Suivi sequentiel des ameliorations a appliquer aux specifications |
+| `reporting_parameters.md` | Parametres communs reutilisables dans les rapports |
+| `reporting_standards.md` | Standards de champs, devises, montants, signes et tris |
+| `Trad On - Rapports Comptables et Financiers.xlsx` | Source initiale issue du cadrage fonctionnel |
+
+## Ordre de travail recommande
+
+1. Mettre a jour le catalogue si un nouveau rapport ou domaine apparait.
+2. Verifier les standards et les parametres communs avant de creer une fiche rapport.
+3. Creer ou completer la fiche dans `../Reports/<DOMAIN>/`.
+4. Reporter le statut dans `../Reports/REPORTS_INDEX.md`.
+5. Ajouter les questions ouvertes dans la fiche du rapport concerne.
+
+## Principes de documentation
+
+- Le catalogue decrit le perimetre.
+- Les standards decrivent les conventions communes.
+- Les fiches dans `Reports` decrivent les besoins report par report.
+- Le modele de donnees, les requetes SQL et les datasets BI seront documentes plus tard, lorsque les sources ERP / CTRM seront connues.
+
+## Source Excel
+
+Le classeur `Trad On - Rapports Comptables et Financiers.xlsx` contient la liste initiale des rapports identifies. Il doit etre considere comme une source de reference, mais les specifications maintenues dans les fichiers Markdown font foi pour le travail courant.

Docs/client_specific_excel_reports.md

@@ -0,0 +1,69 @@
+# Client-Specific Excel Reports
+
+This document describes client-specific Excel reports identified during the reporting scoping work.
+
+These reports are not part of the standard CTRM / ERP reporting catalog yet. They describe existing Excel-based reporting practices and possible future automation through Excel APIs or database queries.
+
+## Status
+
+| Report | Current status | Target direction |
+| --- | --- | --- |
+| `9.1 Posizione Finanziaria & Ecomargin` | Client-specific Excel legacy report | Candidate for future Excel/API automation |
+| `9.2 Consolidated Balance Sheet` | Client-specific Excel legacy report | Candidate for future Excel/API automation |
+| `9.3 Consolidated Income Statement Sheet` | Client-specific Excel legacy report | Candidate for future Excel/API automation |
+
+---
+
+## 9.1 Posizione Finanziaria & Ecomargin
+
+Current situation:
+
+This Excel-specific report provides a consolidated financial position based on bank account balances as of a selected date.
+
+Balances are grouped by bank and fiscal company. The first column identifies the bank account context, including `BANK NAME`, fiscal company and bank account description.
+
+Each bank account balance may be expressed in its original currency. These balances are converted into USD using FX rates manually entered in the Excel file. The converted USD balances are displayed in the `ACCOUNTS BALANCES` column.
+
+The report also includes an `ECOMARGIN` column. This column generally follows the same USD balances as `ACCOUNTS BALANCES`, except for EFG Bank accounts, where a specific USD amount is entered manually.
+
+At the bottom of the bank account list, the report includes a specific adjustment line named `RJO 50% degli effettivi excess`. This line is calculated from three manually entered USD amounts identified by the labels `6639`, `6650` and `6675`. These three amounts are summed, divided by two, and the resulting value is displayed both in `ACCOUNTS BALANCES` and in `ECOMARGIN`.
+
+The report ends with totals for both `ACCOUNTS BALANCES` and `ECOMARGIN`.
+
+Future enhancement:
+
+Use an Excel API allowing queries against the database containing general ledger account movements, in order to extract the general ledger account description, the balances in account currency and base currency for the selected GL accounts by fiscal company, as-of date, general ledger account and account currency.
+
+---
+
+## 9.2 Consolidated Balance Sheet
+
+Current situation:
+
+This Excel-specific report provides a consolidated balance sheet based on general ledger account balances as of a selected date.
+
+Future enhancement:
+
+Use an Excel API allowing queries against the database containing general ledger account movements, in order to extract the general ledger account description, the balances in account currency and base currency for the selected balance sheet accounts by fiscal company, as-of date, general ledger account and account currency.
+
+---
+
+## 9.3 Consolidated Income Statement Sheet
+
+Current situation:
+
+This Excel-specific report provides a consolidated income statement based on general ledger account balances or movements for a selected reporting period or as-of date.
+
+Future enhancement:
+
+Use an Excel API allowing queries against the database containing general ledger account movements, in order to extract the general ledger account description, the balances or movements in account currency and base currency for the selected income statement accounts by fiscal company, reporting period or as-of date, general ledger account and account currency.
+
+---
+
+## Integration Notes
+
+- These reports should remain separated from the standard report catalog until their target application design is confirmed.
+- If they become application reports later, they should be converted into detailed specifications under `Reports/`.
+- The financial position report is likely related to the future cash reporting scope.
+- The consolidated balance sheet and consolidated income statement are likely related to future consolidation or statutory reporting scope.
+- Manual adjustments and Excel-specific calculation rules should be explicitly documented before automation.

Docs/reporting_catalog.md

@@ -0,0 +1,162 @@
+# CTRM / ERP Accounting Reporting Catalog
+
+Source: Trad On - Accounting and Financial Reports
+
+This catalog defines the functional reporting requirements for the accounting reporting framework of a CTRM / ERP platform.
+
+The objective of this document is to define the reporting scope independently from the underlying technical data model.
+
+ERP / CTRM data mapping will be defined at a later stage.
+
+---
+
+# Reporting Domains
+
+1. General Ledger
+2. Statutory Financial Reporting
+3. Accounts Receivable
+4. Accounts Payable
+5. Banking and Cash Management
+6. Foreign Exchange
+7. Trading and Positions
+8. Analytical Accounting
+
+---
+
+# 1 General Ledger
+
+## GL-001 General Ledger
+
+Detailed listing of accounting entries by account.
+
+## GL-002 Accounting Journals
+
+Listing of accounting entries grouped by journal.
+
+---
+
+# 2 Statutory Financial Reports
+
+## FIN-001 Comparative Balance Sheet (Current Year / Prior Year)
+
+Comparative balance sheet presenting current and previous fiscal year balances for the current entity.
+
+## FIN-002 Comparative Profit and Loss Statement (Current Year / Prior Year)
+
+Comparative income statement presenting current and previous fiscal year results for the current entity.
+
+## FIN-003 Trial Balance
+
+Summary of debit and credit balances for all general ledger accounts.
+
+Multi-entity statutory consolidation is out of scope for FIN-001 and FIN-002 and should be handled by a dedicated consolidation report.
+
+---
+
+# 3 Accounts Receivable
+
+## AR-001 Customer Balance Report
+
+Outstanding balances by customer.
+
+## AR-002 Customer Ageing Report
+
+Ageing analysis of customer receivables.
+
+## AR-003 Customer Account Movements
+
+Detailed movements by customer account.
+
+---
+
+# 4 Accounts Payable
+
+## AP-001 Supplier Balance Report
+
+Outstanding balances by supplier.
+
+## AP-002 Supplier Ageing Report
+
+Ageing analysis of supplier payables.
+
+## AP-003 Supplier Account Movements
+
+Detailed movements by supplier account.
+
+---
+
+# 5 Banking and Cash Management
+
+## CASH-001 Bank Ledger
+
+Accounting ledger for bank accounts.
+
+## CASH-002 Cash Position Report
+
+Overview of cash balances as of a selected position date.
+
+## CASH-003 Payment History
+
+Historical record of executed payments.
+
+---
+
+# 6 Foreign Exchange
+
+## FX-001 FX Exposure Report
+
+Foreign exchange exposure by currency.
+
+## FX-002 Realized FX Gains and Losses
+
+Realized foreign exchange gains and losses.
+
+## FX-003 Unrealized FX Gains and Losses
+
+Unrealized foreign exchange gains and losses due to currency revaluation.
+
+---
+
+# 7 Trading and Positions
+
+## TRD-001 Open Trading Positions
+
+List of currently open trading positions.
+
+## TRD-002 Mark-to-Market Valuation
+
+Valuation of open positions using mark-to-market methodology.
+
+## TRD-003 Trading Profit and Loss
+
+Profit and loss generated by trading activities.
+
+---
+
+# 8 Analytical Accounting
+
+## ANA-001 Profitability by Profit Center
+
+Profitability analysis by profit center.
+
+## ANA-002 Profitability by Trading Desk
+
+Profitability analysis by trading desk.
+
+## ANA-003 Margin Analysis
+
+Detailed margin analysis across business activities.
+
+---
+
+# 9 Specific Excel Reports
+
+The client-specific Excel reports identified during scoping are documented separately in `Docs/client_specific_excel_reports.md`.
+
+These reports describe existing Excel-based practices and possible future automation. They are not part of the standard CTRM / ERP report specifications until converted into dedicated report files.
+
+Identified client-specific Excel reports:
+
+- `9.1 Posizione Finanziaria & Ecomargin`
+- `9.2 Consolidated Balance Sheet`
+- `9.3 Consolidated Income Statement Sheet`

Docs/reporting_fields_catalog.md

@@ -0,0 +1,105 @@
+# Reporting Fields Catalog
+
+This document lists the reporting fields currently mentioned in the available report specifications.
+
+It is intended to prepare the future mapping with the target CTRM / ERP. The mapping is not defined yet, so the descriptions below remain functional and source-system independent.
+
+## Mapping Preparation Rules
+
+- Field names use the reporting vocabulary currently defined in the Markdown specifications.
+- The `Used in reports` column identifies where the field is already required or mentioned.
+- A field may map to different CTRM / ERP source fields depending on the module, ledger, subledger or report context.
+- Optional fields should be mapped only when the target CTRM / ERP exposes a distinct value.
+- This catalog does not define SQL logic, source tables or joins.
+
+## Field Catalog
+
+| Field | Description | Used in reports |
+| --- | --- | --- |
+| `account` | General ledger account code. | `GL-001`, `FIN-001`, `FIN-002`, `FIN-003` |
+| `account_group` | Financial statement account group used in statutory statements. | `FIN-001`, `FIN-002` |
+| `account_group_order` | Sort order of the financial statement account group. | `FIN-001`, `FIN-002` |
+| `account_name` | General ledger account name. | `GL-001`, `FIN-001`, `FIN-002`, `FIN-003` |
+| `account_type` | Account classification, such as asset, liability, equity, revenue or expense. | `FIN-003` |
+| `ageing_basis_date` | Date used to calculate ageing. | `AR-002`, `AP-002` |
+| `ageing_bucket` | Ageing bucket label. | `AR-002`, `AP-002` |
+| `ageing_bucket_order` | Sort order of the ageing bucket. | `AR-002`, `AP-002` |
+| `balance_base_currency` | Running balance in base currency. | `GL-001`, `AR-003`, `AP-003` |
+| `balance_current_year_base_currency` | Balance at the selected closing date in base currency. | `FIN-001` |
+| `balance_current_year_transaction_currency` | Balance at the selected closing date in transaction currency, when transaction currency presentation is enabled. | `FIN-001` |
+| `balance_previous_year_base_currency` | Balance at the prior fiscal year comparison date in base currency. | `FIN-001` |
+| `balance_previous_year_transaction_currency` | Balance at the prior fiscal year comparison date in transaction currency, when transaction currency presentation is enabled. | `FIN-001` |
+| `balance_transaction_currency` | Running balance in transaction currency. | `GL-001`, `AR-003`, `AP-003` |
+| `base_currency` | Functional or company base currency. | `GL-001`, `GL-002`, `FIN-001`, `FIN-002`, `FIN-003`, `AR-001`, `AR-002`, `AR-003`, `AP-001`, `AP-002`, `AP-003` |
+| `closing_balance_base_currency` | Closing balance in base currency. | `FIN-003`, `AR-001`, `AP-001` |
+| `closing_balance_transaction_currency` | Closing balance in transaction currency. | `FIN-003`, `AR-001`, `AP-001` |
+| `counterparty` | Customer, supplier, broker or other party. | `GL-001`, `GL-002` |
+| `credit_base_currency` | Credit amount or movement in base currency. | `GL-001`, `GL-002`, `FIN-003`, `AR-001`, `AR-003`, `AP-001`, `AP-003` |
+| `credit_transaction_currency` | Credit amount or movement in transaction currency. | `GL-001`, `GL-002`, `FIN-003`, `AR-001`, `AR-003`, `AP-001`, `AP-003` |
+| `customer` | Customer account code. | `AR-001`, `AR-002`, `AR-003` |
+| `customer_name` | Customer legal or commercial name. | `AR-001`, `AR-002`, `AR-003` |
+| `customer_reference` | Customer reference or external customer document reference, when available. | `AR-003` |
+| `days_overdue` | Number of days overdue at `closing_date`. | `AR-002`, `AP-002` |
+| `debit_base_currency` | Debit amount or movement in base currency. | `GL-001`, `GL-002`, `FIN-003`, `AR-001`, `AR-003`, `AP-001`, `AP-003` |
+| `debit_transaction_currency` | Debit amount or movement in transaction currency. | `GL-001`, `GL-002`, `FIN-003`, `AR-001`, `AR-003`, `AP-001`, `AP-003` |
+| `description` | Entry, document, movement or item description. | `GL-001`, `GL-002`, `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `document_date` | Source document date. | `GL-001`, `GL-002`, `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `document_number` | Accounting, AR or AP document number. | `GL-001`, `GL-002`, `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `document_type` | Accounting or business document type, such as invoice, credit note, debit note, payment or receipt. | `GL-001`, `GL-002`, `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `due_date` | Payment due date. | `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `entered_by` | User who created the entry. | `GL-001`, `GL-002`, `AR-003`, `AP-003` |
+| `entered_date` | Entry creation date. | `GL-001`, `GL-002`, `AR-003`, `AP-003` |
+| `entity` | Legal entity or company code. | `GL-001`, `GL-002`, `AR-001`, `AR-002`, `AR-003`, `AP-001`, `AP-002`, `AP-003` |
+| `journal` | Accounting journal. | `GL-001`, `GL-002`, `AR-003`, `AP-003` |
+| `journal_entry_number` | Journal entry sequence or identifier. | `GL-001`, `GL-002`, `AR-003`, `AP-003` |
+| `journal_name` | Accounting journal name. | `GL-002` |
+| `last_document_number` | Last accounting document number included in the balance, when available. | `AR-001`, `AP-001` |
+| `last_posting_date` | Last accounting posting date included in the balance. | `AR-001`, `AP-001` |
+| `modified_by` | User who last modified the entry. | `GL-001`, `GL-002` |
+| `modified_date` | Last modification date. | `GL-001`, `GL-002` |
+| `open_amount_base_currency` | Open amount in base currency. | `AR-002`, `AP-002` |
+| `open_amount_transaction_currency` | Open amount in transaction currency. | `AR-002`, `AP-002` |
+| `opening_balance_base_currency` | Opening balance in base currency. | `FIN-003`, `AR-001`, `AP-001` |
+| `opening_balance_transaction_currency` | Opening balance in transaction currency. | `FIN-003`, `AR-001`, `AP-001` |
+| `payable_qty` | Payable quantity for commodity-related postings only. | `GL-001` |
+| `payment_reference` | Payment reference, when available. | `AR-003` |
+| `posting_date` | Accounting posting date. | `GL-001`, `GL-002`, `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `posting_status` | Posted, non-posted or other ERP posting status, when exposed by the ERP. | `GL-001`, `GL-002`, `FIN-001`, `FIN-002`, `FIN-003`, `AR-001`, `AR-002`, `AR-003`, `AP-001`, `AP-002`, `AP-003` |
+| `purchase_invoice_number` | ERP purchase invoice number, when different from the accounting document number. | `AP-003` |
+| `reference` | External or source reference. | `GL-001`, `GL-002`, `AR-002`, `AR-003`, `AP-002`, `AP-003` |
+| `remittance_reference` | Remittance advice or payment remittance reference, when available. | `AR-003` |
+| `result_current_year_base_currency` | Current fiscal year result in base currency. | `FIN-002` |
+| `result_current_year_transaction_currency` | Current fiscal year result in transaction currency, when transaction currency presentation is enabled. | `FIN-002` |
+| `result_previous_year_base_currency` | Previous fiscal year result in base currency. | `FIN-002` |
+| `result_previous_year_transaction_currency` | Previous fiscal year result in transaction currency, when transaction currency presentation is enabled. | `FIN-002` |
+| `section` | Financial statement section, such as assets, liabilities, equity, revenue, expenses or net result. | `FIN-001`, `FIN-002` |
+| `section_order` | Sort order of the financial statement section. | `FIN-001`, `FIN-002` |
+| `settlement_date` | Settlement or clearing date, when available. | `AR-003`, `AP-003` |
+| `settlement_status` | Open, partially settled, settled or reversed status, when available. | `AR-003`, `AP-003` |
+| `supplier` | Supplier account code. | `AP-001`, `AP-002`, `AP-003` |
+| `supplier_invoice_number` | Supplier invoice number as provided by the supplier, or AP-related supplier invoice number when available. | `GL-001`, `GL-002`, `AP-002`, `AP-003` |
+| `supplier_name` | Supplier legal or commercial name. | `AP-001`, `AP-002`, `AP-003` |
+| `transaction_currency` | Original transaction currency. | `GL-001`, `GL-002`, `FIN-001`, `FIN-002`, `FIN-003`, `AR-001`, `AR-002`, `AR-003`, `AP-001`, `AP-002`, `AP-003` |
+| `uom` | Unit of measure for payable quantity. | `GL-001` |
+| `variance_base_currency` | Difference between current year and previous year amount in base currency. | `FIN-001`, `FIN-002` |
+| `variance_percent_base_currency` | Percentage variance versus previous year amount in base currency. | `FIN-001`, `FIN-002` |
+| `vendor_reference` | Vendor reference or external supplier reference, when available. | `AP-003` |
+| `voucher_number` | Internal voucher, workflow or accounting reference; optional in AR/AP movements when distinct from document and external references. | `GL-001`, `GL-002`, `AR-003`, `AP-003` |
+
+## Fields Requiring Particular Mapping Attention
+
+| Field | Mapping attention point |
+| --- | --- |
+| `posting_status` | ERP-specific status values must be mapped before implementation. |
+| `document_type` | ERP document type codes must be mapped to the reporting categories used by each report. |
+| `settlement_status` | Open, partially settled, settled and reversed logic depends on the ERP subledger. |
+| `voucher_number` | Should be mapped only if it is distinct from `document_number`, `supplier_invoice_number`, customer references and payment references. |
+| `supplier_invoice_number` | May map to a vendor invoice number, supplier reference or AP invoice field depending on ERP terminology. |
+| `purchase_invoice_number` | Should be mapped only if the ERP exposes a separate internal purchase invoice number. |
+| `customer_reference` | Should be mapped only if the ERP exposes a distinct customer-facing reference. |
+| `payment_reference` | Should be mapped only if payment references are stored separately from document references. |
+| `remittance_reference` | Should be mapped only if remittance advice information is available. |
+| `payable_qty` | CTRM-specific commodity quantity; expected to depend on trade, payable or settlement data. |
+| `uom` | Unit of measure should be mapped consistently with `payable_qty`. |
+| `transaction_currency` | Optional in statutory reports; required for ledger and subledger analysis. |
+| `base_currency` | Should map to the company, functional or ledger currency selected as the base currency for reporting. |

Docs/reporting_improvement_backlog.md

@@ -0,0 +1,42 @@
+# Reporting Improvement Backlog
+
+Ce document suit les ameliorations a appliquer aux specifications existantes.
+
+Il sert a gerer les changements de maniere sequentielle avant modification des fiches de rapports. Chaque item doit etre applique, relu, puis marque comme termine lorsque les rapports concernes et la documentation transverse sont alignes.
+
+## Statuts
+
+| Statut | Signification |
+| --- | --- |
+| `A appliquer` | Amelioration retenue mais non encore appliquee |
+| `En cours` | Modification en cours sur les rapports concernes |
+| `A relire` | Modification appliquee, relecture fonctionnelle requise |
+| `Termine` | Modification validee et documentation alignee |
+
+## Backlog sequentiel
+
+| Seq | Statut | Theme | Rapports concernes | Amelioration a appliquer |
+| --- | --- | --- | --- | --- |
+| 001 | Termine | Drill-down | Rapports resumes | Specifier le drill-down attendu des rapports resumes vers le detail : balance, mouvements, piece comptable, document source. |
+| 002 | A appliquer | Reversal tracking | `GL-001` | Ajouter la tracabilite des pieces annulees ou contre-passees : `reversal_status`, `reversal_document_number`, `reversed_document_number` ou equivalence ERP. |
+| 003 | A appliquer | Source document | Rapports de detail comptable | Ajouter `source_module` et `source_document_number` pour identifier le document source et le module ERP a l'origine de l'ecriture. |
+| 004 | Termine | Statutory currency | `FIN-001`, `FIN-002` | Revoir la pertinence des colonnes en `transaction_currency` pour les etats statutaires ; privilegier `base_currency` et, si necessaire, une devise de reporting. |
+| 005 | A appliquer | Financial statement formulas | `FIN-001`, `FIN-002` | Expliciter les sous-totaux et formules de structure : total assets, total liabilities, equity, gross margin, operating result, net result. |
+| 006 | A appliquer | P&L period basis | `FIN-002` | Preciser si le resultat presente est periodique, year-to-date, ou les deux. |
+| 007 | A appliquer | Trial balance amount columns | `FIN-003` | Ajouter `period_debit`, `period_credit`, `net_movement`, `opening_debit`, `opening_credit`, `closing_debit`, `closing_credit`, ou clarifier que les soldes signes remplacent ces colonnes. |
+| 008 | A appliquer | Dimension set | `FIN-003` | Ajouter une dimension set optionnelle pour permettre une balance par compte seul ou par compte et dimensions financieres. |
+| 009 | A appliquer | Control account | `AR-001`, `AP-001` | Ajouter `control_account` en sortie pour faciliter la reconciliation subledger / general ledger. |
+| 010 | A appliquer | Ageing dates and terms | `AR-002`, `AP-002` | Ajouter `payment_terms` et `original_due_date`; ajouter aussi `promised_payment_date` cote AR lorsque disponible. |
+| 011 | A appliquer | Historical open amount | `AR-002`, `AP-002` | Preciser le traitement des paiements partiels, lettrages partiels et open amounts historiques as of `closing_date`. |
+| 012 | Termine | Document type filter | `AR-003`, `AP-003` | Ajouter une valeur `invoices` a `document_type_filter` pour permettre le filtrage sur les factures seules. |
+| 013 | A relire | Supplier references | `AP-003` | Envisager `purchase_invoice_number` ou `vendor_reference` comme alias fonctionnel selon ERP pour completer `supplier_invoice_number`. |
+| 014 | A relire | Customer references | `AR-003` | Ajouter ou evaluer `customer_reference`, `payment_reference` et `remittance_reference` pour le rapprochement des encaissements. |
+
+## Regles d'application
+
+- Appliquer les items dans l'ordre sequentiel, sauf priorite fonctionnelle explicite.
+- Modifier uniquement les rapports concernes par l'item.
+- Aligner `Docs/reporting_parameters.md` ou `Docs/reporting_standards.md` uniquement si l'amelioration devient une convention commune.
+- Ajouter les questions ouvertes dans les fiches de rapports lorsque le comportement depend du futur ERP cible.
+- Mettre a jour le statut de l'item apres chaque passe de modification.
+- Ne pas supprimer un item termine ; conserver l'historique comme trace de decision.

Docs/reporting_parameters.md

@@ -0,0 +1,21 @@
+# Standard Reporting Parameters
+
+Common parameters available in most reports.
+
+date_from  
+date_to  
+
+account  
+currency  
+
+journal  
+
+entity  
+
+counterparty  
+
+document_type_filter  
+
+analytic_account  
+
+profit_center

Docs/reporting_standards.md

@@ -0,0 +1,91 @@
+# Reporting Standards
+
+These conventions define the default reporting vocabulary and presentation rules. A report may define a specific exception when its functional layout requires it.
+
+---
+
+## Date fields
+
+- `posting_date`
+- `value_date`
+- `document_date`
+
+---
+
+## Currency fields
+
+- `transaction_currency`
+- `base_currency`
+
+There is no separate `reporting_currency` in the current reporting scope.
+
+---
+
+## Amount fields
+
+- `debit`
+- `credit`
+- `balance`
+
+When currency-specific amount fields are required, use the suffix:
+
+- `_transaction_currency`
+- `_base_currency`
+
+Examples:
+
+- `debit_transaction_currency`
+- `credit_transaction_currency`
+- `balance_transaction_currency`
+- `debit_base_currency`
+- `credit_base_currency`
+- `balance_base_currency`
+
+---
+
+## Posting status
+
+When exposed by the ERP, reports should include `posting_status` as an informational field.
+
+The field should identify whether the source transaction is posted, non-posted, reversed, cancelled, pending or another ERP-specific status.
+
+`posting_status` is not a standard filter by default. Each report should keep an open question until the target ERP confirms whether this field is available and which status values should be mapped.
+
+---
+
+## Sign conventions
+
+General financial statement sign conventions:
+
+- Assets: positive debit
+- Liabilities: positive credit
+- Revenue: positive credit
+- Expenses: positive debit
+
+These sign conventions apply to financial statement presentation and summary reports. Detail ledger reports may define their own sign convention when required.
+
+For `GL-001 General Ledger`, debit amounts are positive and credit amounts are negative, as specified in the report definition.
+
+---
+
+## Sorting conventions
+
+Default sorting for accounting detail reports:
+
+1. `account`
+2. `transaction_currency`
+3. `posting_date`
+4. `document_number`
+
+---
+
+## Drill-down conventions
+
+Summary reports should define the expected drill-down path from summarized balances to supporting detail.
+
+Default drill-down path:
+
+1. summarized balance or statement line;
+2. underlying account, customer, supplier or open item movements;
+3. accounting document or journal entry;
+4. source document, when available in the ERP.