Add trade finance ledger foundation

modules/trade_finance/Documentation/backlog.md

@@ -0,0 +1,414 @@
+# 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.

modules/trade_finance/Documentation/development_guidance.md

@@ -0,0 +1,175 @@
+# Trade Finance Development Guidance
+
+This file captures implementation guidance for the next development steps of
+the `trade_finance` module.
+
+It complements `tryton_trade_finance_architecture.md` and should be used as the
+practical working note before creating or changing code.
+
+## 1. Important Existing Model Mapping
+
+The architecture document uses the conceptual name `bank.limit`.
+
+In this codebase, do not create a new `bank.limit` model for the Trade Finance
+ledger unless there is a later explicit design decision to do so.
+
+Use the existing facility structure instead:
+
+```text
+Concept in architecture doc        Existing model in this module
+---------------------------        -----------------------------
+bank.limit                         trade_finance.facility_limit
+bank / banking facility            trade_finance.facility
+bank reference / provider          trade_finance.facility.tfe
+limit amount                       trade_finance.facility_limit.amount
+limit currency                     trade_finance.facility_limit.currency
+limit validity                     trade_finance.facility_limit.date_from/date_to
+limit financing type               trade_finance.facility_limit.financing_type
+limit haircut rules                trade_finance.facility_limit_haircut
+limit accepted currencies          trade_finance.facility_limit_currency
+limit cost/rate rules              trade_finance.facility_limit_cost
+limit operational eligibility      trade_finance.facility_limit_op_status
+```
+
+Any future presentation ledger line should therefore reference
+`trade_finance.facility_limit`, not a hypothetical `bank.limit`.
+
+## 2. Development Principles
+
+- Keep the existing facility/limit model as the contractual source of truth.
+- Treat presentation lines as an exposure movement ledger.
+- Store signed amounts and signed quantities on movement lines.
+- Do not store or manually update current exposure balances as source data.
+- Copy applied haircut/rate/cost values onto posted movement lines for audit.
+- Use reversal movements for cancellations instead of editing posted movements.
+- Keep contextual origin links polymorphic with `fields.Reference`.
+- Add new operational start points by extending the reference selection and
+  action logic, not by adding many foreign keys to a header model.
+
+## 3. Suggested Documentation Structure
+
+Use a small set of focused markdown files under `modules/trade_finance/documentation/`.
+
+Recommended structure:
+
+```text
+documentation/
+  tryton_trade_finance_architecture.md
+  development_guidance.md
+  roadmap.md
+  backlog.md
+  bugs.md
+  decisions.md
+  test_plan.md
+```
+
+Purpose of each file:
+
+```text
+tryton_trade_finance_architecture.md
+  Long-form target architecture and conceptual model.
+
+development_guidance.md
+  Practical implementation rules, mappings to existing models, and local
+  conventions for developers.
+
+roadmap.md
+  Ordered development phases. Stable enough to show where the module is going.
+
+backlog.md
+  Concrete features/tasks not yet scheduled. One item per small deliverable.
+
+bugs.md
+  Known defects, reproduction notes, expected behavior, and current status.
+
+decisions.md
+  Architecture decision records. Use for choices that should not be rediscovered
+  every time, such as using facility_limit instead of bank.limit.
+
+test_plan.md
+  Targeted validation strategy, scenarios to cover, and commands to run.
+```
+
+Do not create every file upfront if it would remain empty. Create them when
+there is useful content to record.
+
+## 4. Suggested Item Formats
+
+### Backlog Item
+
+```text
+## TF-001 - Short title
+
+Status: todo | in-progress | blocked | done
+Area: model | workflow | view | report | test | data
+Priority: low | medium | high
+
+Goal:
+- What business behavior should exist?
+
+Implementation notes:
+- Smallest expected code change.
+- Existing model(s) to reuse.
+
+Validation:
+- Target test file or scenario.
+- Manual check if needed.
+```
+
+### Bug Item
+
+```text
+## BUG-001 - Short title
+
+Status: open | reproduced | fixed | closed
+Severity: low | medium | high | critical
+Area: model | workflow | view | report | test | data
+
+Observed:
+- What happens now?
+
+Expected:
+- What should happen?
+
+Reproduction:
+- Minimal steps or test data.
+
+Fix notes:
+- Linked commit/test once fixed.
+```
+
+### Decision Record
+
+```text
+## ADR-001 - Short title
+
+Date: YYYY-MM-DD
+Status: proposed | accepted | superseded
+
+Context:
+- Why a decision is needed.
+
+Decision:
+- What we decided.
+
+Consequences:
+- What this enables.
+- What tradeoffs remain.
+```
+
+## 5. Immediate Next Development Focus
+
+Recommended next implementation sequence:
+
+1. Create the Trade Finance file/header model.
+2. Create the presentation/event model.
+3. Create the presentation line ledger model linked to
+   `trade_finance.facility_limit`.
+4. Add sequence/configuration for internal Trade Finance references.
+5. Add minimal list/form views and access rules.
+6. Add targeted tests around creation, references, signed movements, and limit
+   validity checks.
+
+The first implementation should stay narrow: no funding-cost engine, no
+snapshot table, and no automatic exposure summary as source of truth until the
+ledger model is stable.