tradon/modules/trade_finance/Documentation/backlog.md

Trade Finance Backlog

This backlog tracks the next development phases for the trade_finance module.

Status values:

todo | in-progress | blocked | done

Priority values:

low | medium | high

Phase 1 - Core Ledger Foundation

Goal: stabilize the Trade Finance file, presentation, and movement ledger.

TF-001 - Validate core model installation

Status: todo Area: test Priority: high

Goal:

• Install/update the module in a real Tryton database with dependencies.
• Confirm the new models, views, sequence, menus, and access rules load.

Implementation notes:

• Run the targeted module test suite in an environment with python-sql and the full Tryton dependency stack.
• Fix any XML/view/model registration issue found during module activation.

Validation:

• python -m unittest modules.trade_finance.tests.test_module
• Manual module activation/update in a development database.

TF-002 - Harden posted movement immutability

Status: todo Area: workflow Priority: high

Goal:

• Ensure posted presentations and posted movement lines cannot be edited or deleted through direct writes, nested One2Many writes, or UI actions.

Implementation notes:

• Review write, delete, and nested child update behavior.
• Keep reversal movements as the only correction path for posted exposure.

Validation:

• Add tests for direct line write/delete after posting.
• Add tests for nested line modification through presentation write.

TF-003 - Add robust exposure helper methods

Status: todo Area: model Priority: high

Goal:

• Provide reusable helpers for exposure by facility limit and by Trade Finance file.

Implementation notes:

• Keep ledger lines as the source of truth.
• Start with Python helpers; SQL/materialized reporting can come later.
• Include as_of_date support for historical exposure.

Validation:

• Tests for current exposure by limit.
• Tests for historical exposure before/after transfer movements.

TF-004 - Improve limit eligibility validation

Status: todo Area: model Priority: high

Goal:

• Validate selected trade_finance.facility_limit against bank, currency, validity dates, financing type, and expected operational status.

Implementation notes:

• Reuse trade_finance.facility_limit_op_status.
• Do not create a separate bank.limit model.
• Consider whether root global limits should be selectable or whether only leaf sub-limits should receive movements.

Validation:

• Tests for rejected bank mismatch.
• Tests for rejected currency mismatch.
• Tests for rejected financing type mismatch.
• Tests for rejected operational status mismatch once connected.

Phase 2 - Basic UX and Operational Entry Points

Goal: make the core usable from operational documents.

TF-005 - Add contextual Start Financing wizard

Status: todo Area: workflow Priority: high

Goal:

• Let users start a Trade Finance presentation from an operational document.

Implementation notes:

• Start with stock shipment and stock move because stock is already a module dependency.
• Use fields.Reference on presentation origin.
• Pre-fill date, origin, stage, company, currency, and suggested quantity where available.

Validation:

• Wizard test from stock.shipment.in.
• Manual UI check from shipment form.

TF-006 - Add purchase contract entry points

Status: todo Area: workflow Priority: medium

Goal:

• Start financing from purchase contract and purchase contract line when the relevant purchase contract module is available.

Implementation notes:

• First identify the actual local model names and module dependency impact.
• Avoid adding a hard dependency until confirmed necessary.
• Prefer optional extension module logic if purchase contract is not part of the base dependency graph.

Validation:

• Tests only if the dependency is activated in the module test environment.

TF-007 - Add invoice financing entry point

Status: todo Area: workflow Priority: medium

Goal:

• Start or continue financing from receivable/invoice stage.

Implementation notes:

• Confirm whether dependency on account_invoice is acceptable.
• Origin should point to account.invoice.
• Presentation type should default to invoice financing.

Validation:

• Test default origin and stage from invoice when dependency is enabled.

TF-008 - Add central exposure summary in the UI

Status: todo Area: view Priority: medium

Goal:

• Show current exposure by facility limit on the Trade Finance file.

Implementation notes:

• Use a read-only derived view/model or function fields first.
• Do not store manual exposure balances.

Validation:

• Manual UI check with multiple posted movements.
• Tests for summary values if implemented as model logic.

Phase 3 - Transfer and Lifecycle Workflow

Goal: support movement between financing stages and limits.

TF-009 - Add transfer proposal helper

Status: todo Area: workflow Priority: high

Goal:

• Generate two movement lines for transfers between facility limits.

Implementation notes:

• Negative line on the source facility limit.
• Positive line on the target facility limit.
• Preserve different haircuts/rates on each line.

Validation:

• Test PREFI to IN_TRANSIT transfer with liquidity gain.

TF-010 - Track liquidity gain/loss

Status: todo Area: model Priority: medium

Goal:

• Calculate liquidity gain/loss when moving collateral between limits with different haircuts.

Implementation notes:

• Keep this derived from movement lines.
• Store applied haircut on each line for audit.

Validation:

• Test gain when target haircut is lower.
• Test loss when target haircut is higher.

TF-011 - Add repayment/release presentation support

Status: todo Area: workflow Priority: medium

Goal:

• Allow users to release financed exposure partially or fully.

Implementation notes:

• Repayment/release should create negative movement lines.
• Avoid editing original posted movements.

Validation:

• Test partial repayment.
• Test full repayment reduces exposure to zero.

Phase 4 - Funding Cost Engine

Goal: calculate funding costs from chronological exposure movements.

TF-012 - Build exposure period calculation

Status: todo Area: model Priority: high

Goal:

• Convert dated movement lines into running exposure periods per facility limit.

Implementation notes:

• Sort by movement date.
• Calculate running balance.
• Build intervals until the next movement date or an explicit end date.

Validation:

• Test one movement.
• Test multiple movements on different dates.
• Test same-day movements.

TF-013 - Calculate interest/funding cost

Status: todo Area: model Priority: high

Goal:

• Calculate funding cost using exposure, applied rate, days, and day-count basis.

Implementation notes:

• Use values copied onto movement lines at posting time.
• Support 360, 365, ACT/360, and ACT/365.

Validation:

• Tests for 360 and 365 bases.
• Test changing facility cost after posting does not alter historical cost.

TF-014 - Add funding cost report screen

Status: todo Area: report Priority: medium

Goal:

• Provide a user-facing report of funding cost by Trade Finance file and by facility limit.

Implementation notes:

• Start with a Tryton model/report view.
• Add export later only if needed.

Validation:

• Manual report check.
• Tests for report backing model if applicable.

Phase 5 - Reporting and Controls

Goal: make exposure auditable and operationally controllable.

TF-015 - Add current exposure by facility limit report

Status: todo Area: report Priority: high

Goal:

• Show exposure grouped by trade_finance.facility_limit.

Implementation notes:

• Source data must be posted movement lines.
• Include quantity and signed financed amount.

Validation:

• Test aggregation across multiple Trade Finance files.

TF-016 - Add historical exposure as-of report

Status: todo Area: report Priority: medium

Goal:

• Show exposure at a selected historical date.

Implementation notes:

• Filter movement lines where movement_date <= as_of_date.
• Group by facility limit and optionally by Trade Finance file.

Validation:

• Tests around before/after transfer dates.

TF-017 - Add over-limit checks and alerts

Status: todo Area: workflow Priority: medium

Goal:

• Detect when posted exposure exceeds facility limit amount.

Implementation notes:

• Decide whether to block posting or warn first.
• Consider parent/global limit and child sub-limit behavior.

Validation:

• Test over child limit.
• Test over global limit if hierarchical aggregation is implemented.

TF-018 - Add expired limit controls

Status: todo Area: workflow Priority: medium

Goal:

• Highlight or block new exposure on expired limits.

Implementation notes:

• Posting already checks movement date validity.
• Add UI filtering and operational alerts.

Validation:

• Manual UI domain check.
• Tests for posting behavior already covered by core validation.

Phase 6 - Advanced Operational Integration

Goal: connect financing to the broader commodity workflow.

TF-019 - Add sale matching support

Status: todo Area: workflow Priority: medium

Goal:

• Continue financing lifecycle when goods are matched with sales.

Implementation notes:

• Identify the actual local matching model.
• Add it to origin selection only after confirming dependency/model names.

Validation:

• Scenario test once model dependency is clear.

TF-020 - Add automatic stage suggestions

Status: todo Area: workflow Priority: medium

Goal:

• Suggest finance stage from origin document status.

Implementation notes:

• Keep suggestions editable.
• Implement stage inference per origin model.

Validation:

• Tests per supported origin type.

TF-021 - Add derived snapshot table if performance requires it

Status: todo Area: report Priority: low

Goal:

• Improve reporting performance for large ledgers.

Implementation notes:

• Snapshot must be derived from ledger lines.
• Ledger remains the source of truth.
• Do not implement until performance data justifies it.

Validation:

• Reconciliation test comparing snapshot totals with ledger totals.