[COST-7252] Implement constant currency Phase 1

Pipfile

@@ -53,6 +53,7 @@ pandas = "<3.0"
 scipy = ">=1.16"
 boto3 = "*"
 sqlalchemy = ">=2.0.0"
+Babel = "*"
 
 [dev-packages]
 argh = ">=0.26.2"

docs/architecture/api-settings-endpoints.md

@@ -516,6 +516,80 @@ PUT /settings/aws_category_keys/disable/
 
 ---
 
+## Currency Enablement
+
+### **Purpose**
+Control which ISO 4217 currencies are available for selection across the tenant. Only enabled currencies can be used in account settings, cost models, and report filters.
+
+### **Endpoints**
+
+#### List Enabled Currencies
+```
+GET /currency/
+```
+
+Returns only the currencies that an administrator has enabled via the `EnabledCurrency` table. Metadata (name, symbol, description) is computed at response time via babel.
+
+**Query Parameters:**
+- `limit` (integer) - Results per page
+- `offset` (integer) - Pagination offset
+
+**Response:**
+```json
+{
+  "meta": {
+    "count": 2
+  },
+  "data": [
+    {
+      "code": "EUR",
+      "name": "Euro",
+      "symbol": "€",
+      "description": "EUR (€) - Euro"
+    },
+    {
+      "code": "USD",
+      "name": "US Dollar",
+      "symbol": "$",
+      "description": "USD ($) - US Dollar"
+    }
+  ]
+}
+```
+
+#### Enable a Currency
+```
+POST /settings/currency/exchange_rate/<code>/enable/
+```
+
+#### Disable a Currency
+```
+DELETE /settings/currency/exchange_rate/<code>/enable/
+```
+
+Enable or disable a single currency by its ISO 4217 code in the URL path.
+
+**Path Parameters:**
+- `code` (string) - ISO 4217 currency code (case-insensitive, normalized to uppercase)
+
+**Response:** `204 No Content`
+
+**Error Responses:**
+
+**Invalid Currency Code (400 Bad Request):**
+```json
+{
+  "code": ["Invalid ISO 4217 currency code: INVALID"]
+}
+```
+
+**Behavior:**
+- `POST` — idempotently creates an `EnabledCurrency` row for the code
+- `DELETE` — idempotently deletes the `EnabledCurrency` row if it exists
+- Currency code in the URL is case-insensitive (`/settings/currency/exchange_rate/usd/enable/` enables `USD`)
+
+---
+
 ## Cost Groups (OpenShift)
 
 ### **Purpose**

docs/architecture/constant-currency/README.md

@@ -126,25 +126,22 @@ again.
 **Problem**: Should all currencies returned by the exchange rate API be
 immediately available for use, or should an administrator explicitly enable them?
 
-**Resolution**: Explicit enablement. Currencies fetched from the dynamic exchange
-rate API arrive in Cost Management as **disabled** by default (stored in the
-`EnabledCurrency` table with `enabled=False`). An administrator must explicitly
-enable currencies through the Settings UI before they appear in the target
-currency dropdown.
+**Resolution**: Explicit enablement. The full list of known currencies comes from
+Babel's ISO 4217 registry. Only currencies that an administrator has explicitly
+enabled are stored in the `EnabledCurrency` table. An administrator must enable
+currencies through the Settings API (`POST settings/currency/enabled-currencies/{code}/`) before
+they appear in the target currency dropdown.
 
 All currencies are always stored in `MonthlyExchangeRate` regardless of their
-enabled status — the `enabled` flag only controls dropdown visibility, not
-data storage. This ensures the underlying data is complete and
+enabled status — the `EnabledCurrency` table only controls dropdown visibility,
+not data storage. This ensures the underlying data is complete and
 ready when an administrator enables a currency.
 
 **Rationale**: Explicit enablement gives administrators control over which
 currencies appear in their UI. In on-premise environments, customers may only
-need a small subset of the ~170 currencies available from the API. Showing all
-currencies by default would clutter the dropdown.
+need a small subset of the ~300 ISO 4217 currencies. Showing all currencies by
+default would clutter the dropdown.
 
-**Exception**: Static exchange rate pairs always make their currencies available
-in the dropdown, regardless of `EnabledCurrency` status. If an administrator
-defines a `USD→EUR` static rate, both `USD` and `EUR` are immediately available.
 
 ### IQ-6: Rate resolution without `CURRENCY_URL` — RESOLVED
 
@@ -153,15 +150,17 @@ configured (e.g., airgapped or disconnected deployments)?
 
 **Resolution**: The system does not require `CURRENCY_URL` to function. Rate
 resolution follows a simple priority: **static rates first, dynamic rates as
-fallback, error if neither exists** for a given currency pair. When
-`CURRENCY_URL` is empty or unset:
+fallback**. When `CURRENCY_URL` is empty or unset:
 
 - The daily Celery task skips the API fetch step (no dynamic rates are fetched)
 - Static exchange rates defined via the CRUD API work normally
 - If dynamic rates were previously fetched (before the URL was removed), they
   remain available as fallback
-- If no rate exists for a given pair (static or dynamic), the API returns an
-  actionable error
+- If `MonthlyExchangeRate` is completely empty (no rates configured at all),
+  the feature is inactive — no currencies are enabled, so the user cannot
+  select a target currency and costs are returned as-is in their original
+  bill currency
+- If rates exist but not for a given pair, the API returns an actionable error
 
 The `CURRENCY_URL` setting is documented with the production API URL
 (`open.er-api.com`) as a reference example. Only the free tier of the Open
@@ -170,7 +169,9 @@ Exchange Rates API is supported in this design.
 **Rationale**: The system should work with whatever data is available rather
 than treating the absence of `CURRENCY_URL` as a special mode. Customers can
 define their own exchange rates via the CRUD API regardless of whether dynamic
-rates are being fetched.
+rates are being fetched. Deployments that never configure exchange rates
+continue to work exactly as before — costs are returned in their original
+currency with no conversion.
 
 ### IQ-7: No-rate corner case — RESOLVED
 
@@ -254,28 +255,27 @@ graph LR
     API["open.er-api.com<br/>(or custom URL)"] -->|"daily fetch<br/>(skipped if no URL)"| CT["Celery Task:<br/>get_daily_currency_rates"]
     CT -->|upsert| ER["ExchangeRates<br/>(public schema)"]
     CT -->|rebuild| ERD["ExchangeRateDictionary<br/>(public schema)"]
-    CT -->|"discover currencies<br/>create as disabled"| EC["EnabledCurrency<br/>(tenant schema)<br/>enabled/disabled per currency"]
+    CT -->|"no currency discovery"| EC["EnabledCurrency<br/>(tenant schema)<br/>admin-managed"]
     CT -->|"Writer 1: per-tenant<br/>skip static pairs<br/>all currencies"| MER["MonthlyExchangeRate<br/>(tenant schema)<br/>single source of truth"]
     MER -->|"all months:<br/>per-month rates"| QH["QueryHandler<br/>Subquery annotation"]
     QH -->|"per-month rates +<br/>rate metadata"| REPORT["Report Response<br/>+ exchange_rates_applied"]
-    QH -->|"no rate? →<br/>actionable error"| ERR["Error: no exchange rate<br/>available"]
+    QH -->|"no rate +<br/>feature active? →<br/>actionable error"| ERR["Error: no exchange rate<br/>available"]
     ADMIN["CM Admin"] -->|"enable/disable<br/>currencies"| EC
     USER["Price List Admin"] -->|CRUD| SER["Serializer"]
     SER -->|"write canonical<br/>rate record"| STATIC["StaticExchangeRate<br/>(tenant schema)"]
     SER -->|"Writer 2: upsert<br/>rate_type=static"| MER
-    EC -->|"dropdown filter:<br/>enabled dynamic ∪<br/>static rate currencies"| DD["Target Currency<br/>Dropdown"]
-    STATIC -->|"static currencies<br/>always available"| DD
+    EC -->|"dropdown filter:<br/>enabled currencies only"| DD["Target Currency<br/>Dropdown"]
 ```
 
 **Key changes**:
 
 1. **Single source of truth**: `MonthlyExchangeRate` stores rates for all months (current and past); query handlers read from this one table
 2. **Two writers**: Celery task writes dynamic rates daily for the current month; CRUD serializer writes static rates for affected months
-3. **Rate resolution**: All months read from `MonthlyExchangeRate`; M2 migration seeds current-month data at deployment; pre-deployment months fall back to earliest available rate; error if no rate exists at all for a currency pair
+3. **Rate resolution**: All months read from `MonthlyExchangeRate`; M2 migration seeds current-month data at deployment; pre-deployment months fall back to earliest available rate. When `MonthlyExchangeRate` is empty (feature not configured), no currencies are enabled and costs are returned as-is; when rows exist but not for the target currency, an actionable error is returned
 4. Report responses include rate provenance metadata
 5. **Currency enablement**: Dynamic currencies arrive as disabled; administrator enables them via Settings to make them visible in the dropdown (all currencies are always stored)
-6. **Dropdown visibility**: Target currency dropdown shows only the union of enabled dynamic currencies and static rate currencies (disabled currencies are stored but hidden from the dropdown)
-7. **No-rate error**: If user selects a currency with no conversion path from the bill currency, an actionable error is returned
+6. **Dropdown visibility**: Target currency dropdown shows only currencies that an administrator has explicitly enabled (static rate currencies still require enablement)
+7. **No-rate handling**: If `MonthlyExchangeRate` is empty, the feature is inactive — no currencies are enabled, so costs are returned as-is. If rows exist but not for the selected currency, an actionable error is returned
 
 ---
 
@@ -289,14 +289,13 @@ graph LR
 | 4 | **No multi-hop conversion** | No chain conversion (e.g., USD→EUR→CNY) to avoid prioritization complexity |
 | 5 | **Bidirectional implicit inverse** | USD→EUR at 0.87 implies EUR→USD = 1/0.87 unless explicitly defined |
 | 6 | **Natural month boundaries** | Start/end dates must align to first/last day of month; no mid-month validity periods |
-| 7 | **Simple integer versioning** | Auto-increment on `StaticExchangeRate.version`; Phase 2 adds full audit history |
-| 8 | **Automatic finalized month locking** | Dynamic rows overwritten daily during current month; untouched after month ends |
-| 9 | **Forward-only with current-month seed** | M2 migration seeds current-month data from `ExchangeRateDictionary`; pre-deployment months fall back to earliest available rate |
-| 10 | **Per-pair rows, not JSON blob** | Enables `unique_together` constraint, simpler queries, cleaner ORM integration |
-| 11 | **Explicit currency enablement** | Dynamic currencies arrive disabled; administrator enables them in Settings to control which currencies appear in the dropdown. All currencies are always stored regardless of enabled status. |
-| 12 | **Configurable exchange rate URL** | `CURRENCY_URL` is a variable; empty value skips dynamic rate fetching. System works with whatever rates are available (static first, dynamic fallback, error if neither). Documentation references `open.er-api.com` (free tier) as the production example |
-| 13 | **Show-then-error for no-rate currencies** | Available currencies appear in dropdown even without a conversion path from the bill currency; actionable error returned on selection |
-| 14 | **Static rates bypass enablement** | Currencies in static exchange rate pairs are always available in dropdowns regardless of `EnabledCurrency` status |
+| 7 | **Automatic finalized month locking** | Dynamic rows overwritten daily during current month; untouched after month ends |
+| 8 | **Forward-only with current-month seed** | M2 migration seeds current-month data from `ExchangeRateDictionary`; pre-deployment months fall back to earliest available rate |
+| 9 | **Per-pair rows, not JSON blob** | Enables `unique_together` constraint, simpler queries, cleaner ORM integration |
+| 10 | **Explicit currency enablement** | Dynamic currencies arrive disabled; administrator enables them in Settings to control which currencies appear in the dropdown. All currencies are always stored regardless of enabled status. |
+| 11 | **Configurable exchange rate URL** | `CURRENCY_URL` is a variable; empty value skips dynamic rate fetching. System works with whatever rates are available (static first, dynamic fallback). Documentation references `open.er-api.com` (free tier) as the production example |
+| 12 | **Show-then-error for no-rate currencies** | Available currencies appear in dropdown even without a conversion path from the bill currency; actionable error returned on selection. When `MonthlyExchangeRate` is empty (no rates configured at all), the feature is inactive — no currencies are enabled and costs are returned as-is |
+| 13 | **Enablement is always required for reports** | Static exchange rate currencies must still be explicitly enabled to appear in the report dropdown. The settings admin page shows them regardless for management purposes. |
 
 ---
 
@@ -313,3 +312,7 @@ graph LR
 | v1.6 | 2026-03-30 | Removed `ExchangeRateDictionary` fallback from query handler. M2 seeds current-month data. Decision #9 updated. |
 | v1.7 | 2026-04-12 | Updated data flow diagram: query handler uses `Subquery` annotation instead of `Case`/`When`. |
 | v1.8 | 2026-04-13 | Synced pre-deployment month references: fall back to earliest available rate (aligns with pipeline-changes.md v2.1). |
+| v1.9 | 2026-04-28 | Updated currency enablement URL reference to `settings/currency/enabled-currencies/{code}/`. |
+| v2.0 | 2026-04-28 | Removed static-rate enablement bypass (decision #13). Report dropdown governed solely by `EnabledCurrency`; settings admin page shows static rates regardless. |
+| v2.1 | 2026-04-28 | Added "costs as-is" behavior: when `MonthlyExchangeRate` is empty, feature is inactive, validation skipped, costs returned in original currency. Updated IQ-6, decision #12, data flow key changes. |
+| v2.2 | 2026-04-30 | Fixed currency enablement URL to `settings/currency/enabled-currencies/{code}/`. Clarified "costs as-is": no currencies enabled means serializer blocks currency selection; costs returned as-is. |