# Exchange Rate

For business scenarios involving multiple currencies, the platform needs the daily exchange rate to convert amounts, for example when the policy currency is different from the payment currency during premium calculation or claim settlement.

The exchange rate is designed to be configured for the daily exchange rate. Users can manage exchange rate data either via the dedicated menu path **Global Configuration** > **Exchange Rate** or through uploading and downloading from Excel.

## User Scenario

For anyone who needs to maintain the currency conversion rates used by products, rating, rules, or settlement logic on our platform.

## Rate Data Model

Each exchange rate record consists of:

* **Source Currency**: the currency to convert from, e.g. CNY. Only currencies activated in the currency code table can be selected.
* **Effective Date**: the date from which the rates take effect. One source currency can only have one rate record per date.
* **Exchange Rates**: the rates to one or multiple target currencies, e.g. USD = 0.13, EUR = 0.12. One record holds the rates from the source currency to all target currencies for that date.

There is no rate type (e.g. buy/sell/mid rate) — each currency pair has a single rate value.

## Search

Users can search the existing rates by **Source Currency** and **Effective Date**, and the result list shows the source currency, effective date, and the full rate map. The list is sorted by effective date descending and is paginated.

## Add a Rate

1. Click **Add**, and in the maintenance dialog choose a **Source Currency** and an **Effective Date**.
2. Add one or more rows of **Target Currency** and the corresponding rate value. Users can add rows, edit, save, or remove a single row, and then click **Save** to submit the whole list.

Validations applied during maintenance:

* Source currency and effective date are mandatory.
* The same target currency cannot appear twice in one record.
* A record without any target rate cannot be saved.
* Duplicating an existing source currency + effective date combination will be rejected — use **Edit** instead.

## Edit and Delete

* **Edit** loads the existing rate record for the source currency and effective date. Note the **effective date cannot be changed after creation**; users can only adjust the target currencies and rate values. Saving will overwrite the whole rate list of that record.
* **Delete** removes the entire rate record, i.e. the rates from the source currency to all target currencies on that date.

## Excel Upload and Download

* **DownloadExcel** exports all current rate data as an Excel file, with each row representing one source-to-target currency pair.
* **UploadExcel** accepts a file in the same layout. Multiple rows sharing the same source currency and effective date are merged into one record automatically, and duplicated target currencies in the file will be rejected.

The Excel upload is recorded in the Configuration Audit Log as a batch operation, together with the uploaded file.

## How the Rate Is Used at Runtime

* **Latest effective rate**: when business logic looks up a rate for a date, the platform uses the record with the most recent effective date on or before that date. Future-dated rates are never used in advance, and if no rate is found for the exact date, the last effective one applies.
* **Default date**: if the business date is not specified in the query, the current business date is used.
* **Rule DSL**: the native DSL function `GetExchangeRate(sourceCurrency, targetCurrency, date)` can be used directly in rules and rating scripts to fetch a rate, e.g. for premium conversion.
* Rate changes take effect immediately — the cached rates are refreshed automatically after each save or delete.

## Change History

Each record in the list has a **ChangeHistory** entry that jumps to the Configuration Audit Log and shows the change history of that specific rate record, with the before/after values. See [Audit Log](./audit_log.md).

 ![exchange rate add](./image/public_setting/exchangerate_add.png)

 ![exchange rate upload/download](./image/public_setting/exchangerate_dl_ul.png)