外币折算与汇兑损益

> **本地运行，零网络、免 API Key、数据不出电脑。**
> 四项诚实承诺：① 算不出就说算不出，绝不编造数字；② 高危动作强制人工确认；③ 幂等断点，绝不重复副作用；④ 全程留痕可审计。

# 外币折算与汇兑损益

汇兑损益这块，最危险的不是算错，是**用了一个来路不明的汇率**：

从网上抓一个"今日美元汇率"当结算价、
把银行给的中间价和结汇价混着用、
把权益类项目的汇率变动也塞进损益、
双向报价一套 7.1 一套 0.14 却没人发现。

本包的原则：**汇率必须由你给**。
没有汇率表、明细表里也没有汇率列，就直接报「算不出」——
本包宁可不出表，也不会拿一个内置近似价冒充实时汇率或结汇价。

## 输入

一张外币货币性项目明细表，一行一个项目。列名自动识别（下列顺序即识别优先级）：

| 用途 | 可识别列名 |
|---|---|
| 项目编号 | 项目编号 / 项目编码 / 项目号 / 编号 / 业务编号 / 序号 |
| 项目名称 | 项目名称 / 项目 / 摘要 / 科目 / 事项 |
| 币种 | 币种 / 币种代码 / 货币 / 货币代码 / 原币 / 币种编码 |
| 期初原币 | 期初原币 / 期初原币金额 / 期初外币金额 / 期初外币 / 期初原币额 |
| 期初折人民币 | 期初折人民币 / 期初人民币 / 期初账面人民币 / 期初账面额 / 期初折RMB / 期初账面折人民币 |
| 期末原币 | 期末原币 / 期末原币金额 / 期末外币金额 / 期末外币 / 期末原币额 |
| 期末汇率 | 期末汇率 / 汇率 / 折算汇率 / 结汇汇率 / 期末折率 |
| 期初汇率 | 期初汇率 / 期初折率 / 账面汇率 |
| 货币性项目 | 货币性项目 / 是否货币性项目 / 是否货币性 / 货币性 / 项目类型 / 科目属性 |

汇率来源**二选一，必须给一个**：

1. `--rate-file 汇率表.xlsx` —— 列：币种 / 汇率 / 汇率日期 / 来源
   - 单码写法：`USD` → 7.1000，表示 1 美元 = 7.1000 元人民币
   - 显式方向写法：`USD→CNY` 7.1000 与 `CNY→USD` 0.14085
2. 明细表自带「期末汇率」列 —— 一行一个汇率

两者都没给 → **直接拒绝**；两者都给了 → **直接拒绝**（同一件事两个来源会算出两套结果）。

`--builtin` 是第三种，但只用于试算：内置 25 个币种的近似中间价，
会打印「⚠ 内置参考表为近似中间价（参考值，非实时汇率、非结算价），仅用于试算与量级校验，不得直接入账。」
**绝不联网取汇率。**

支持币种：AUD / BRL / CAD / CHF / CNY(RMB) / DKK / EUR / GBP / HKD / INR / JPY / KRW / MOP / MXN / MYR / NOK / NZD / PLN / RUB / SEK / SGD / THB / TRY / TWD / USD / ZAR。

`货币性项目` 认得：货币性项目（计入汇兑损益）、非货币性项目（按历史成本计量，不计）。
**本包不判断哪些科目属于货币性项目**——只有你标注了，本包才敢算；没标注的会进异常表并声明「结果不完整」。

## 输出四件套

| 文件 | 内容 |
|---|---|
| `fx_主表.csv` | 逐笔折算：编号 / 名称 / 币种 / 期初原币 / 期初折人民币 / 期末原币 / 期末汇率 / 期末折算 / 汇兑损益 / 汇率来源 / 货币性标注 |
| `fx_异常表.csv` | 不可计算项 + 需人工复核项（带原始行号、风险等级） |
| `fx_校验表.csv` | 折算公式、汇兑损益口径、汇率标价、守恒断言、汇率来源、内置表声明、双向一致性、口径声明、拒绝项 |
| `fin-log.jsonl` | 处理日志（追加） |

主表金额合计 = 期初折人民币，异常表金额 = 未计入损益的口径项金额，
「期初折人民币 + 汇兑损益 − 期末折算」必须为 0，差一分钱直接报算不出。

## 用法

```bash
PY="<python 3.8+ 路径>"   # 纯标准库
"$PY" <skill目录>/scripts/fx_conv.py 外币明细.xlsx --rate-file 汇率表.xlsx --execute
```

三种汇率来源：

```bash
"$PY" fx_conv.py 外币明细.xlsx --rate-file 汇率表.xlsx --execute   # 推荐：用户导入汇率表
"$PY" fx_conv.py 外币明细_带汇率列.xlsx --execute                  # 明细表内自带「期末汇率」列
"$PY" fx_conv.py 外币明细.xlsx --builtin --execute                 # 仅试算：内置近似中间价
```

反向折算（人民币→外币）：

```bash
"$PY" fx_conv.py 人民币对外币明细.xlsx --rate-file 汇率表_人民币对外币.xlsx \
      --direction cny-to-fx --execute
"$PY" fx_conv.py 明细.xlsx --rate-file 汇率表.xlsx --operator 张三 --out-dir _out --execute
```

**默认不写盘**——不加 `--execute` 只打印预览，确认无误再真跑。

## 真实输出

```
方案：fx_外币明细.xlsx | 外币项目 5 笔 | 汇率来源：用户导入：fx_汇率表.xlsx（4 条 pair / 0 条单码）

--- 折算结果（4 笔计入汇兑损益）---
  FX-01      USD  期初原币   120,000.00  期初折人民币   852,000.00  期末汇率 7.1000    期末折算   710,000.00  汇兑损益 -142,000.00
  FX-02      EUR  期初原币    50,000.00  期初折人民币   390,000.00  期末汇率 7.8000    期末折算   405,600.00  汇兑损益   15,600.00
  FX-03      JPY  期初原币 4,000,000.00  期初折人民币   188,000.00  期末汇率 0.0470    期末折算   178,600.00  汇兑损益   -9,400.00
  FX-04      HKD  期初原币   200,000.00  期初折人民币   182,000.00  期末汇率 0.9100    期末折算   182,000.00  汇兑损益        0.00

--- 异常 / 口径提示（1 条）---
  [低] FX-05：标注为非货币性项目（按历史成本计量），本包不计其汇兑损益

合计：期初折人民币 1,612,000.00 | 汇兑损益 -135,800.00 | 期末折算 1,476,200.00
  守恒：期初折人民币 + 汇兑损益 − 期末折算 = 0.00 元
--- 校验表 ---
  校验项 | 值
  折算公式 | 折算值 = 原币 × 汇率。外币→人民币方向：汇率取「外币→CNY」，原币列装外币金额；人民币→外币方向：汇率取「CNY→外币」，原币列装人民币金额
  汇兑损益 | 汇兑损益 = 期末折算 − 期初折人民币（只算货币性项目）
  汇率来源 | 用户导入：fx_汇率表.xlsx（4 条 pair / 0 条单码）
  守恒断言 | 期初折人民币 + 本期汇兑损益 = 期末折人民币，差异 > 0.01 元 refuse
  双向一致性 | USD→CNY：双向汇率乘积 0.994000，偏离 1 达 0.006000（> 0.0001）：「USD→CNY」与「CNY→USD」不是互为倒数
  口径声明 | 本包不判断哪些科目属于货币性项目，完全由用户标注；未标注项已列进异常表，结果不完整
  主表行数 | 4
  异常行数 | 1
  输入行数 | 5
  主表金额合计 | 1612000.0
  异常表金额合计 | 213000.0
  守恒差异（入-主-异） | 0.0
```

内置参考表路径的预览提示（真实输出）：

```
方案：fx_外币明细.xlsx | 外币项目 5 笔 | 汇率来源：--builtin 内置参考表（25 个币种近似中间价）
  ⚠ 内置参考表为近似中间价（参考值，非实时汇率、非结算价），仅用于试算与量级校验，不得直接入账。
[预览模式] 未写盘。确认无误后加 --execute 执行。
```

## 拒绝权（什么情况下算不出）

| 情况 | 处理 |
|---|---|
| 汇率来源一个都没给 | **直接拒绝**：本包绝不拿内置参考价冒充实时汇率 / 结算价 |
| 同时给了 `--rate-file` 和表内「期末汇率」列 | **直接拒绝**：同一件事两个来源会算出两套结果 |
| 汇率 ≤ 0（含 0） | **直接拒绝**：「本包不许按 0 或负数折算」 |
| 汇率缺失 / 非数字 | **直接拒绝**：本包不按 0、不拿替代汇率折算 |
| 币种认不出来（如"XYZ"） | **直接拒绝**，并列出全部 27 个支持代码 |
| 同币种同一日期两个不同汇率 | **直接拒绝**：只保留一个汇率；真不同日期请填「汇率日期」列 |
| 期初原币缺失 | **直接拒绝**：本期新开账可填 0，但不能留空 |
| 期初折人民币非数字 | **直接拒绝**：算不出汇兑损益起点 |
| 期初折人民币 + 汇兑损益 ≠ 期末折算（> 0.01 元） | **直接拒绝**：表不自洽，不许"差不多就行" |
| 明细表内「期末汇率」列 | 进异常表（高），逐笔标出反算值与账面值的差 |
| 未标注「货币性项目」 | 进异常表（中），声明「结果不完整」 |
| 标注为非货币性项目 | 进异常表（低），不计其汇兑损益 |

被拒绝的项目**不产生主表行**，金额计入异常表，守恒关系照样成立。

## 关键设计（容易踩的坑）

1. **汇率来源互斥**：`--rate-file` / 表内「期末汇率」列 / `--builtin` 三选一，
   都没给或给了两个都 refuse。本包不会替你"猜一个大概的汇率"。
2. **内置价永不冒充实时价**：`--builtin` 只在 `--rate-file` 没给时可用，
   打印时强制带「参考值，非实时汇率、非结算价，不得直接入账」声明。
3. **守恒断言**：期初折人民币 + 本期汇兑损益 = 期末折算，差异 > 0.01 元直接 refuse。
   这条断言能挡住"期初账面数抄错了"这类低级但致命的错误。
4. **双向汇率一致性**：汇率表里同时有 `USD→CNY` 和 `CNY→USD` 时，
   检查两者乘积是否偏离 1 超过 0.0001；单码写法下检查 `USD` 与 `CNY` 的乘积。
   实测 7.1000 × 0.1400 = 0.994000 会被抓出来（偏差 0.006000）。
5. **货币性项目由你标注**：本包不判断哪些科目属于货币性项目，
   没标注的项目进异常表（中）并声明结果不完整——**宁可提醒你结果不完整，也不替你拍板**。
6. **折算方向只影响两件事**：用哪条汇率路径，以及「原币」列里装的是外币还是人民币金额。
   反向折算（人民币→外币）下，汇率表要写 `CNY→USD` 这样的显式方向；
   只有单码写法时取倒数，并在「汇率来源」列注明「（单码取倒数）」。
7. **反向折算禁用表内汇率列**：「期末汇率」列在反向场景下分不清标价方向
   （1 外币 = R 人民币，还是 1 人民币 = R 外币），会 refuse 并要求改用 `--rate-file`。
8. **绝不联网**：`permissions.network: none`，汇率只能来自你给的表。

## 人工复核（必读）

- 期末汇率是否取的是正确的时点（期末当日中间价 / 银行结汇价口径不同）
- 汇率表「来源」列写的是谁的价格：中间价、结汇价、买入价、卖出价？口径必须一致
- 货币性项目的范围由你标注，未标注项已列进异常表，**结果可能不完整**
- 本包只算货币性项目的汇兑损益；权益类、按历史成本计量的项目不计入
- 汇兑损益的会计处理（计入当期损益 / 资本化）需按企业会计准则判断
- 若存在汇率管制、远期合约、套保工具，本表不适用，请另走衍生工具核算
- 期末汇率与期初账面汇率若跨期变更，需确认是否按新汇率调整期初数

## 相邻路线转交

| 用户要做的事 | 转交给 |
|---|---|
| 外币交易日常业务的折算（非期末调整） | `fx-convert`（本包，但需注明是日常交易而非期末调整） |
| 外币报表折算（功能性货币判断、报表项目折算） | `fx-restatement-translation` |
| 汇算清缴 / 所得税汇缴的汇兑损益调整 | `tax-return` |
| 往来款账龄分析 | `receivable-aging` |
| 账务处理凭证生成 | `voucher-batch-generate` |
| 银行流水与账面对账 | `bank-recon` |

## 可直接复制的说法

```text
把这几笔外币货币性项目按期末汇率折成人民币，并算出期末汇兑损益。
汇率请我自己给（给我 --rate-file 汇率表或在我表里加「期末汇率」列），
你不要去网上抓汇率、不要用内置的近似价冒充实时汇率或结汇价，
一个汇率来源都不给就直说算不出。
期初折人民币 + 本期汇兑损益 必须等于 期末折算，差一分钱你直接拒。
汇率表里 USD→CNY 和 CNY→USD 都有时，检查是不是互为倒数，偏差超过 0.0001 要指出来。
哪些科目算货币性项目你自己别判断，我标了才算，没标的你列出来并说结果不完整。
```

## 做完怎么算完成

- [ ] 期末汇率口径已确认（中间价 / 结汇价 / 买入卖出价），且全部行一致
- [ ] 汇率表「来源」列已填写，可追溯到具体报价出处
- [ ] 守恒断言通过：期初折人民币 + 汇兑损益 = 期末折算
- [ ] 双向汇率一致性无异常，或异常项已查明（是不同时点报价还是报价错误）
- [ ] 「货币性项目」列已逐笔标注，未标注项已逐条追查
- [ ] 非货币性项目已确认按历史成本计量，不计汇兑损益
- [ ] 异常表逐条已追查，无"未说明原因的缺失"
- [ ] 若用 `--builtin` 试算，已确认最终入账数据改走 `--rate-file`

---

本 Skill 采用 BUSL-1.1 许可（源码可见，可自由使用）。

版权所有 © 2026 律令科技（深圳）有限公司（@lexord-technology）。
本技能由律令科技（深圳）有限公司开发，**财友云（caiyouyun.cn）**发布与展示。

允许个人及企业内部免费使用、复制、修改，包括内部生产环境。
未经书面许可，不得将本 Skill 或其修改版作为商业服务对外销售、转售或提供托管服务。
各版本发布之日起 4 年后自动转为 Apache License 2.0。详见随包 `LICENSE.md`。