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. 异步更新

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

六、示例实现

后端服务示例

// 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> {
    // 货币转换
  }
}

前端组件示例

// 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>;
};

七、总结

本方案提供了一个完整的多国跨境货币显示解决方案，包括：

• 货币管理和汇率服务架构
• 货币显示格式和本地化策略
• 多货币转换和计算服务
• 不同场景的货币显示方案
• 技术实现和集成方案
• 性能优化策略

通过这个方案，系统可以：

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

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