feat: Add currency normalization with migration and backfill tooling; update models and API for currency integration

README.md

@@ -135,6 +135,29 @@ The database is composed of several tables that store different types of informa
 - **Exchange rate** — `exchange_rate`: Contains currency exchange rates.
 - **Simulation result** — `simulation_result`: Stores the results of the Monte Carlo simulations.
 
+### Currency normalization and migrations
+
+The project now includes a referential `currency` table and associated migration and backfill tooling to normalize free-text currency fields into a canonical lookup.
+
+- New model: `models/currency.py` implements the `currency` table (id, code, name, symbol, is_active).
+- Database migration: `scripts/migrations/20251022_create_currency_table_and_fks.sql` creates the `currency` table, seeds common currencies, adds `currency_id` to `capex`/`opex`, backfills where possible, and adds foreign key constraints. The migration is written to be idempotent and safe on databases where parts of the work were already applied.
+- Backfill utility: `scripts/backfill_currency.py` is an idempotent, developer-friendly script to preview and apply backfill updates. It supports `--dry-run` and `--create-missing` flags.
+- API & models: `models/capex.py` and `models/opex.py` now reference `currency_id` and include a compatibility property accepting a legacy `currency_code` during creates/updates. Routes accept either `currency_id` or `currency_code`; see `routes/costs.py` and the new `routes/currencies.py` (GET /api/currencies/).
+- Frontend: server templates and `static/js` now fetch `/api/currencies/` to populate currency selects for cost forms so users can pick a normalized currency instance.
+
+How to run migrations and backfill (development)
+
+1. Ensure `DATABASE_URL` is set in your PowerShell session to point at a development Postgres instance.
+
+```powershell
+$env:DATABASE_URL = 'postgresql://user:pass@host/db'
+python scripts/run_migrations.py
+python scripts/backfill_currency.py --dry-run
+python scripts/backfill_currency.py --create-missing
+```
+
+Use `--dry-run` first to verify what will change. The migration and backfill scripts are designed to be safe and idempotent, but always back up production databases before applying schema changes.
+
 ## Static Parameters
 
 These are values that are not expected to change frequently and are used for configuration purposes. Some examples include: