企业官网建设流程全解析

Whisper Money 是一款开源的个人财务管理工具，帮你告别 Excel 表格记账。它的多币种管理功能是核心卖点之一：每个账户（美元银行卡、欧元信用卡、比特币钱包）各自保留自己的账户币种，而仪表盘和各项分析则统一换算成你选定的主显示币种。这篇指南带你看懂 Whisper Money 多币种管理的正确打开方式：账户币种、主显示币种、汇率转换三层机制，让多币种数据始终一笔不错。

一、先分清两个“币种”：账户币种 vs 主显示币种

💡 Whisper Money 的多币种模型只有两层，分清它们能避免 90% 的困惑：

两者完全独立：一位以 CNY 为主显示币种的用户，可以同时持有 USD 银行账户和 BTC 钱包，打开仪表盘看到的是统一的 CNY 总额。

• 账户与交易各自携带币种：app/Models/Account.php、app/Models/Transaction.php
• 主显示币种跟着用户走：app/Models/User.php

设置主显示币种

在设置 → 账户资料页面有 Currency 下拉框，可选项由后端的primaryOptions()提供。系统还会根据你的 format locale（如zh-CN、en-US的地域部分）推荐一个默认币种，推荐逻辑见 app/Services/CurrencyOptions.php。

为每个账户选择币种

新建账户时同样有一个币种下拉框，可选项来自accountOptions()。注意：部分币种只能当账户币种、不能当主显示币种——典型如 BTC，它能持有、能展示，但不适合作为全局汇总口径。能力区分由配置中的allows_primary/allows_account两个独立开关控制，见 config/currencies.php。

主显示币种生效的地方

凡是“跨账户汇总”的视图，都会先按当日汇率把各账户折算成主显示币种，例如月度总结报告：

二、汇率转换是如何工作的：按交易日期取价，而不是今天

核心原则：历史余额用历史汇率

这是最容易误解的一点。Whisper Money 转换一笔交易时，取的是交易发生当天的汇率，而不是“最新汇率”。这样你的历史余额曲线不会因为汇率波动而失真。

• 转换入口：app/Services/ExchangeRateService.php
• 汇率来源与抓取：app/Services/CurrencyConversionService.php

数据来源、回退与缓存策略

• 主数据源：@fawazahmed0/currency-api的每日汇率文件，另备一个备用源自动切换；
• 历史回退：某天没有汇率时，最多向前回溯 7 天，取最近的可用日；
• 分级缓存：最新汇率缓存 6 小时，历史汇率（不可变）缓存 30 天，源不可用时只缓存 10 分钟以便快速恢复，见 app/Services/CurrencyConversionService.php；
• 落库复用：拉到的汇率会写入exchange_rates表供后续请求复用，建表迁移见 database/migrations/2026_02_20_074846_create_exchange_rates_table.php。

找不到汇率时怎么办？

系统会优雅降级而不是报错：convert()返回未换算的金额并记录 warning，保证总额仍然对得上；需要严格区分的场景则用convertOrNull()返回 null，见 app/Services/ExchangeRateService.php。

三、不同币种精度不同：一个容易踩的坑

各币种的最小记账单位小数位并不相同：EUR 是 2 位（分）、JPY 是 0 位、COP 是 0 位、BTC 是 8 位（satoshi）。

Whisper Money 的所有金额统一以整数最小单位存储，小数位由配置显式声明（未知币种回退为 2 位）。为什么这么讲究？如果把汇率直接乘在存储的整数上，两种精度不同的币种之间会差出一个 10 的幂次。正确做法是：先还原成主单位 → 应用汇率 → 再缩放回目标币种的最小单位。这段注释值得读一读：config/currencies.php。

四、支持哪些币种？如何新增一个币种

• 币种总表：config/currencies.php，覆盖主流法币（USD、EUR、GBP、JPY、CNY、CHF、CAD 等）以及加密资产；
• 新增币种是一次配置变更，不是一个功能：加一个配置项 + 一行翻译即可，校验、下拉框选项、汇率转换全部自动生效。官方开发者指南见 docs/adding-a-currency.md；
• 两个注意点（指南里特别强调）：
  1. 必须使用现行 ISO 4217 代码。加纳的例子：旧代码GHC仍存在但汇率被重定价放大 10000 倍，正确代码是GHS，否则所有余额会膨胀 10000 倍；
  2. 确认汇率数据源确实覆盖该代码且汇率合理，否则该币种仍可选择，只是不会发生换算。

五、文件导入与多币种：导入时按账户原币记账

通过全量导入功能搬入历史数据时，币种机制同样生效：

1. 映射账户：先确认文件中每一列属于哪个账户，每个账户保持自己的币种；

2. 预览交易：预览页显示的金额是账户的原币金额，并标出 New / Duplicate 状态；

3. 导入完成后：仪表盘、现金流等视图自动按各交易日汇率折算为主显示币种，无需任何手动操作。

六、多币种管理最佳实践清单

• ✅ 主显示币种选你日常开支用的那个（CNY / USD / EUR）；
• ✅ 每个账户的币种就设成银行流水实际记账的币种，不要为了“好看”去人为统一；
• ✅ 查看历史余额时别期望“按今天的汇率”，Whisper Money 按交易日取价，这恰恰更准确；
• ✅ BTC 等加密资产可以当账户币种，但不能当主显示币种；
• ✅ 需要的币种不在列表里？先读 docs/adding-a-currency.md，这是一个 5 分钟就能完成的配置变更。

七、相关文件速查

• 币种配置与精度定义：config/currencies.php
• 汇率拉取与缓存：app/Services/CurrencyConversionService.php
• 换算服务（含精度缩放）：app/Services/ExchangeRateService.php、app/Support/Money.php
• 币种选项与下拉框数据源：app/Services/CurrencyOptions.php
• 新增币种官方指南：docs/adding-a-currency.md