Financial Truth Model

The single source of truth for what every financial number in TSync Intelligence means. Each metric the Intelligence layer exposes via tsync_finance() has exactly one definition here, so every advanced module (Dynamic Valuation, FX Exposure, KPI) computes on the same basis and the results are reproducible and auditable.

Scope. This document defines methodology. Phase 1 ships the baseline definitions below (implemented in Tsync_finance_service). Items marked [Phase 2] are formally defined here but their full computation is deferred.

0. Conventions

  • Base currency — tsync_fx()->base() (the accounting base, e.g. RON), from option tsync_acc_base_currency. All aggregates are expressed in base.
  • Accounting rate — tsync_fx()->rate(CUR, date): the rate of CUR→base on a date, sourced from Tsync_currency. Rate-date rule: Romania uses the previous business day's BNR rate; Moldova uses the same day's rate. The base currency is rate 1.0 by definition.
  • Conversion — always via base: convert(amount, from, to) = amount × rate(from) ÷ rate(to).
  • Rounding — monetary aggregates round to 2 decimals; per-unit costs and snapshot item values retain 4 decimals internally.
  • Versioning — every metric row carries calc_version + calculated_at (bumped on each recompute) so a stale value is detectable. A change to a definition here is a methodology version bump (see §8).

1. Inventory valuation

$$\text{InventoryValue} = \sum_{\text{stock rows}} (,qty \times avg_cost,)$$

  • Source: tsync_stock — canonical on-hand column qty (never qty_on_hand), unit cost avg_cost.
  • Cost method: AVCO (moving weighted average) — avg_cost is maintained by the warehouse posting path on every receipt.
  • tsync_finance()->getInventoryValue(). Already in base (stock is valued in base).

2. Receivables

$$\text{Receivables} = \sum_{\text{open customer invoices}} (,total - \text{payments},)$$

  • Open = invoice status ∈ { unpaid (1), partially_paid (3), overdue (4) }. Paid (2) and cancelled (5) are excluded.
  • total is the invoice gross; payments is the sum of recorded payments for it.
  • tsync_finance()->getReceivables(). Non-base invoices: see §6.

3. Payables

$$\text{Payables} = \sum_{\text{open supplier invoices}} (,total - \text{payments},)$$

  • Open = supplier-invoice status not in { paid, cancelled }.
  • tsync_finance()->getPayables().

4. Cash balance (operational-cash proxy)

$$\text{Cash} = \sum \text{customer payments} - \sum \text{supplier payments} - \sum \text{expenses}$$

  • A movement-based proxy, not a reconciled bank balance. True bank/period-close reconciliation is [Phase 2].
  • tsync_finance()->getCashBalance().

5. Currency exposure

$$\text{Exposure} = \sum_{\substack{\text{open receivables}\ \text{cur} \neq \text{base}}} \text{baseValue(open amount)}$$

  • The base-currency value of open, non-base-currency receivables — the amount at risk to FX moves. tsync_finance()->getCurrencyExposure().
  • Baseline indicator: it measures exposure, not realised/unrealised gain/loss.

6. FX gain / loss methodology [Phase 2 computation]

Formally: for a foreign-currency item booked at rate $r_0$ on date $d_0$ and valued/settled at rate $r_1$ on date $d_1$,

$$\text{FX gain/loss} = \text{amount}_{\text{cur}} \times (r_1 - r_0)$$

  • Unrealised (open items): $r_1$ = reporting-date rate.
  • Realised (on settlement): $r_1$ = settlement-date rate.
  • Rule: revenue/expense and asset/liability items are recorded at the historical rate ($r_0$) at recognition; revaluation uses the current rate ($r_1$); the difference is the FX gain/loss. Phase 1 records exposure (§5) and the rates (§0); the booked gain/loss line is Phase 2.

7. Operational profit

Phase 1 baseline — tsync_finance()->getOperationalProfit($days):

$$\text{OpProfit}{\text{baseline}} = \text{revenue}{\text{window}} - \text{expenses}_{\text{window}}$$

[Phase 2] true operational profit — formally:

$$\text{OpProfit} = \text{revenue} - \text{COGS} - \text{operating expenses} \pm \text{FX gain/loss} - \text{accruals/deferrals}$$

where COGS is drawn from AVCO at the moment of sale (not period-end cost), FX gain/loss per §6, and accruals/deferrals per recognition date. Operational cost = COGS + operating expenses (excludes financing and tax). The baseline deliberately omits COGS, FX gain/loss and accruals — do not treat it as audited profit.

8. Methodology versioning & reproducibility

  • Each metric stores calc_version (data recompute count) and is produced under a methodology version (the version of this document). A change to any formula here increments the methodology version; snapshots record the methodology in effect so a historical figure can always be reproduced from the same inputs.
  • Reproducibility contract: the same dataset + the same methodology version must produce the same numbers (the basis for the audit/research mode).

9. Phase 2 roadmap (not yet binding)

COGS-based operational profit, booked FX gain/loss, bank/period-close reconciliation, accruals/deferrals, multi-company consolidation, and historical-rate vs current-rate revaluation scenarios.

Implemented by application/libraries/Tsync_finance_service.php (baseline) and Tsync_fx_service.php (rates). Validated by tests/sim/intelligence_finance_snapshot_sim.php and tests/fx_service_test.php.