makemd/docs/01_Architecture/10_Currency_Management.md

# 多国跨境货币显示方案

## 一、核心架构

### 1. 货币管理服务
- **CurrencyService**：管理支持的货币列表、货币基本信息
- **ExchangeRateService**：管理汇率数据、汇率更新、汇率缓存
- **数据模型**：
  - `cf_currency`：货币基础信息（代码、名称、符号、小数位数）
  - `cf_exchange_rate`：最新汇率数据
  - `cf_exchange_rate_history`：汇率历史记录

### 2. 货币转换与计算服务
- **CurrencyConversionService**：处理货币间转换
- **CurrencyCalculationService**：处理价格、成本、利润等计算
- **支持的转换策略**：最新汇率、历史汇率、平均汇率、固定汇率

### 3. 货币显示与本地化
- **CurrencyFormatter**：处理货币显示格式
- **LocalizationService**：处理地区特定的显示规则
- **支持的格式**：货币符号位置、千位分隔符、小数位数、小数点符号

## 二、不同场景的货币显示方案

### 1. 报表场景
- **多货币切换**：用户可选择显示货币，系统自动换算
- **汇率选择**：可选择最新汇率、报表生成时汇率或自定义日期汇率
- **多货币并列**：支持主货币+对比货币同时显示
- **总计显示**：支持按主货币汇总，同时显示其他货币换算值
- **导出支持**：Excel/CSV导出时保持货币格式

### 2. 定价场景
- **平台本地货币**：按平台要求显示当地货币
- **目标市场货币**：显示目标客户所在地区货币
- **多货币对比**：同一商品显示多种货币价格
- **价格策略**：基于不同货币的定价策略（如区域定价）
- **动态更新**：汇率变化时自动更新价格显示

### 3. 分析场景
- **基准货币**：可设置分析基准货币
- **多货币对比**：不同货币的销售、利润对比
- **趋势分析**：汇率波动对业务的影响分析
- **预测模型**：基于汇率预测的业务预测

## 三、技术实现

### 1. 后端服务
- **CurrencyService**：管理货币数据，提供货币列表、货币信息查询
- **ExchangeRateService**：对接第三方汇率API（如Open Exchange Rates），定期更新汇率
- **CurrencyConversionService**：提供货币转换功能，支持批量转换
- **CurrencyCalculationService**：提供价格、成本、利润等计算功能

### 2. 前端实现
- **货币显示组件**：`CurrencyDisplay` 组件，支持不同显示格式
- **货币选择器**：`CurrencySelector` 组件，支持货币切换
- **本地化配置**：基于用户地区的自动货币格式
- **实时更新**：汇率变化时自动更新显示

### 3. 数据库设计
- **cf_currency**：货币基础信息表
- **cf_exchange_rate**：最新汇率表
- **cf_exchange_rate_history**：汇率历史表

### 4. API设计
- **GET /api/currencies**：获取支持的货币列表
- **GET /api/exchange-rates**：获取汇率数据
- **POST /api/currency/convert**：货币转换
- **POST /api/currency/calculate**：货币计算

## 四、集成方案

### 1. 与现有服务集成
- **产品服务**：商品价格多货币显示
- **订单服务**：订单金额多货币计算
- **财务服务**：财务报表多货币汇总
- **分析服务**：多货币数据分析

### 2. 与前端集成
- **全局货币设置**：用户偏好货币存储
- **页面级货币切换**：各页面独立货币选择
- **组件级货币显示**：统一的货币显示组件

### 3. 与第三方API集成
- **汇率API**：对接Open Exchange Rates、XE等
- **支付API**：支持多货币支付处理

## 五、性能优化

### 1. 缓存策略
- **汇率缓存**：Redis缓存汇率数据，减少API调用
- **货币格式缓存**：缓存本地化货币格式
- **计算结果缓存**：缓存常用转换结果

### 2. 批量处理
- **批量转换**：支持批量货币转换，减少API调用
- **批量计算**：支持批量价格计算

### 3. 异步更新
- **汇率异步更新**：后台定时更新汇率，不影响用户操作
- **货币数据异步同步**：后台同步货币信息

## 六、示例实现

### 后端服务示例
```typescript
// CurrencyService.ts
export class CurrencyService {
  getCurrencies(): Promise<Currency[]> {
    // 返回支持的货币列表
  }
  
  getCurrencyByCode(code: string): Promise<Currency> {
    // 根据代码获取货币信息
  }
}

// ExchangeRateService.ts
export class ExchangeRateService {
  getExchangeRate(fromCurrency: string, toCurrency: string): Promise<number> {
    // 获取汇率
  }
  
  updateExchangeRates(): Promise<void> {
    // 从第三方API更新汇率
  }
}

// CurrencyConversionService.ts
export class CurrencyConversionService {
  convert(amount: number, fromCurrency: string, toCurrency: string): Promise<number> {
    // 货币转换
  }
}
```

### 前端组件示例
```typescript
// CurrencyDisplay.tsx
export const CurrencyDisplay: React.FC<{
  amount: number;
  currency: string;
  formatOptions?: FormatOptions;
}> = ({ amount, currency, formatOptions }) => {
  // 货币显示逻辑
  return <span>{formattedAmount}</span>;
};

// CurrencySelector.tsx
export const CurrencySelector: React.FC<{
  value: string;
  onChange: (currency: string) => void;
}> = ({ value, onChange }) => {
  // 货币选择逻辑
  return <select value={value} onChange={(e) => onChange(e.target.value)}>
    {currencies.map(currency => (
      <option key={currency.code} value={currency.code}>
        {currency.name} ({currency.symbol})
      </option>
    ))}
  </select>;
};
```

## 七、总结

本方案提供了一个完整的多国跨境货币显示解决方案，包括：
- 货币管理和汇率服务架构
- 货币显示格式和本地化策略
- 多货币转换和计算服务
- 不同场景的货币显示方案
- 技术实现和集成方案
- 性能优化策略

通过这个方案，系统可以：
- 支持全球主要货币的显示和转换
- 适应不同地区的货币显示习惯
- 提供准确的汇率数据和转换计算
- 在报表、定价、分析等场景中灵活应用
- 与现有系统无缝集成

此方案确保了多国跨境业务中货币显示的一致性、准确性和用户友好性，为全球业务拓展提供了有力支持。