# Trade Finance Backlog

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

Status values:

```text
todo | in-progress | blocked | done
```

Priority values:

```text
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.
