tradon/modules/trade_finance/Documentation/development_guidance.md

# 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.