财税数值工具

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

# 财税数值工具

数值换算看着最"不会错"，其实错得最隐蔽：大写少写一个「零」、
价税分离的税额用了「含税 × 税率」导致两列加起来差一分、
分摊尾巴凑不平却把差额悄悄抹掉——
表都长得像回事，核账时才发现对不上。

本包把 6 类高频换算收在一处，并且**每次都做守恒断言**：
价税分离的「不含税 + 税额」必须严格等于原含税金额，
尾差分摊的各份之和必须严格等于总额，差一分钱就直接报「算不出」。

## 输入

命令行参数算一笔，或传一张批量表逐行算（`.xlsx` / `.csv`）：
一张表只跑一个 `--cmd`，列名自动识别：

| 用途 | 可识别列名 |
|---|---|
| 金额 / 总额 | 金额 / 含税金额 / 不含税金额 / 总额 / 合计 / 数值 / 价款 |
| 税率 | 税率 / 税率(%) / 税率% / 征收率 / 适用税率（**百分数**，13 = 13%） |
| 份数 | 份数 / 分摊份数 / 拆分数 / 份数N |
| 权重 | 权重 / 分摊权重 / 分摊比例 / 份额 |
| 部分金额 | 部分金额 / 部分值 / 其中一个数 / 部分 |
| 占比 | 占比 / 占比(%) / 占比% / 比例 / 百分比 |
| 数量 | 数量 / 件数 / 吨数 / 采购数量 / Qty |
| 编号 | 编号 / 单号 / 项目 / 名称 / 摘要 / 序号 |

`--cmd` 六选一：`cap` 金额大写 / `tax` 含税不含税互算 / `split` 价税分离 /
`apportion` 尾差分摊 / `reverse` 百分比反算 / `unit` 单价汇率。

## 输出四件套

| 文件 | 内容 |
|---|---|
| `nt_主表.csv` | 换算结果（列随 `--cmd` 变化，附 `_来源文件` / `_原始行号`） |
| `nt_异常表.csv` | 不可计算项（原因 + 风险等级） |
| `nt_校验表.csv` | 各类换算口径、守恒差异、拒项统计 |
| `fin-log.jsonl` | 处理日志（追加） |

## 用法

```bash
PY="<python 3.8+ 路径>"   # 纯标准库
"$PY" <skill目录>/scripts/num_tool.py --cmd cap --amount 1234.56 --execute
```

六类换算（命令行单笔）：

```bash
"$PY" num_tool.py --cmd cap --amount 1234.56 --execute          # 金额大写
"$PY" num_tool.py --cmd tax --amount 1000 --tax-rate 13 --execute        # 不含税 → 含税
"$PY" num_tool.py --cmd tax --amount 1130 --tax-rate 13 --to 不含税 --execute  # 含税 → 不含税
"$PY" num_tool.py --cmd split --amount 1000.01 --tax-rate 13 --execute   # 价税分离
"$PY" num_tool.py --cmd apportion --total 10000.01 --parts 3 --execute   # 尾差分摊
"$PY" num_tool.py --cmd reverse --part 30000 --ratio 25 --execute        # 占比 25% 反算总数
"$PY" num_tool.py --cmd unit --amount 30000 --qty 100 --execute          # 单价
```

批量表（一列一行，逐行算）：

```bash
"$PY" num_tool.py 数值换算表.xlsx --cmd split --execute
"$PY" num_tool.py 数值换算表.xlsx --cmd apportion --execute
"$PY" num_tool.py 数值换算表.xlsx --cmd reverse --execute
```

**默认不写盘**——不加 `--execute` 只打印预览，确认无误再真跑。
输出目录用 `--out-dir` 改（默认 `_out`），操作人用 `--operator` 记进日志。

## 真实输出样例（实测粘贴）

金额大写（18 个边界值，`_out/nt_金额大写边界.xlsx`）：

```
方案：nt_金额大写边界.xlsx | 换算类型 cap（金额大写）
--- 换算结果（18 行）---
  CAP-01              0.00  →  零元整
  CAP-02              0.05  →  零元零伍分
  CAP-03              0.56  →  零元伍角陆分
  CAP-04              1.00  →  壹元整
  CAP-05             10.00  →  壹拾元整
  CAP-06            100.00  →  壹佰元整
  CAP-07          1,001.00  →  壹仟零壹元整
  CAP-08          1,010.00  →  壹仟零壹拾元整
  CAP-09          1,100.00  →  壹仟壹佰元整
  CAP-10          1,234.56  →  壹仟贰佰叁拾肆元伍角陆分
  CAP-11         16,409.02  →  壹万陆仟肆佰零玖元零贰分
  CAP-12          1,700.31  →  壹仟柒佰元叁角壹分
  CAP-13         -1,234.56  →  负壹仟贰佰叁拾肆元伍角陆分
  CAP-14    100,000,001.00  →  壹亿零壹元整
  CAP-15    100,010,000.00  →  壹亿零壹万元整
  CAP-16  123,456,789,012.34→  壹仟贰佰叁拾肆亿伍仟陆佰柒拾捌万玖仟零壹拾贰元叁角肆分
  CAP-17          1,234.57  →  壹仟贰佰叁拾肆元伍角柒分     ← 1,234.567 四舍五入到分
  CAP-18          1,234.56  →  壹仟贰佰叁拾肆元伍角陆分     ← 输入 "¥1,234.56"
--- 异常表：本次未发现不可计算项（0 条）---
```

价税分离（`nt_数值换算表.xlsx`，13% / 13% / 6% / 0% / 9% 五行）：

```
--- 换算结果（5 行）---
  G-01      含税     1,130.00 → 不含税     1,000.00 + 税额     130.00（不含税+税额 = 1,130.00）
  G-02      含税     2,260.00 → 不含税     2,000.00 + 税额     260.00（不含税+税额 = 2,260.00）
  G-03      含税     1,000.01 → 不含税       943.41 + 税额      56.60（不含税+税额 = 1,000.01）
  G-04      含税     3,390.00 → 不含税     3,390.00 + 税额       0.00（不含税+税额 = 3,390.00）
  G-05      含税     5,650.00 → 不含税     5,183.49 + 税额     466.51（不含税+税额 = 5,650.00）
```

尾差分摊（同一张表，1,130.00 等分 3 份 + 10,000.01 等分 3 份）：

```
--- 换算结果（15 行）---
  G-01      第1份 权重 1,1,1       分摊额       376.67 本份尾差  1 分 累计     376.67
  G-01      第2份 权重 1,1,1       分摊额       376.67 本份尾差  1 分 累计     753.34
  G-01      第3份 权重 1,1,1       分摊额       376.66 本份尾差  0 分 累计   1,130.00
  ...
  G-03      第1份 权重 1,1,1       分摊额       333.34 本份尾差  1 分 累计     333.34
--- 不可计算 / 异常（1 条）---
  [高] G-05：份数缺失，算不出分摊
```

百分比反算与单价：

```
  G-01      部分    30,000.00 占    25.00% → 总数     120,000.00 另一部分      90,000.00
  G-05      部分    60,000.00 占    60.00% → 总数     100,000.00 另一部分      40,000.00

  G-01      金额     1,130.00 ÷     100.00 → 单价        11.30
  G-03      金额     1,000.01 ÷       0.50 → 单价      2000.02
--- 不可计算 / 异常（1 条）---
  [高] G-05：数量「」不是数字
```

校验表尾段（守恒断言，实测）：

```
  主表行数 | 18
  异常行数 | 0
  输入行数 | 18
  主表金额合计 | 123656822814.41
  异常表金额合计 | 0.0
  守恒差异（入-主-异） | 0.0
```

命令行单笔（预览模式，不加 `--execute` 不写盘）：

```
--- 换算结果（1 行）---
  命令行             1,234.56  →  壹仟贰佰叁拾肆元伍角陆分
--- 异常表：本次未发现不可计算项（0 条）---
[预览模式] 未写盘。确认无误后加 --execute 执行。
```

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

命令行单笔：命中即 `C.refuse`，打印「【算不出】」并退出码 2，不产出任何数字。

| 情况 | 处理 |
|---|---|
| 基数（含税金额 / 总额 / 部分金额 / 金额）≤ 0 | **拒绝**：「本包绝不按 0 或负数算」 |
| 数量 = 0 或负数 | **拒绝**：「本包绝不按 0 或负数算单价」 |
| 税率缺失（命令行没给、表里也没有） | **拒绝**：「不给税率无法做价税分离」 |
| 税率为负 | **拒绝**：负数税率没有意义 |
| 税率 > 100% | **拒绝**：不合理 |
| 占比 ≥ 100% / 总数 ≤ 部分金额 | **拒绝**：反算无意义，不编造 |
| 份数不是正整数 / 权重个数与份数不符 | **拒绝** |
| 金额 / 税率 / 占比不是数字（如"下个月""两成半"） | **拒绝** |
| 金额 ≥ 1 万亿 | **拒绝**：超出能核对的大写范围 |
| `--cmd` 认不出来（如"大写"） | **拒绝**，列出 6 个可选项 |

批量表模式：命中行进**异常表（高）**，不产生任何数值、不参与守恒，
其余行照常出表；只有「一行都算不出来」时才整体拒绝
（如整表无税率）。

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

1. **金额大写按人民银行《正确填写票据和结算凭证的基本规定》**：
   - 先四舍五入取到分（1,234.567 → 壹仟贰佰叁拾肆元伍角柒分，主表「已四舍五入到分」列标「是」）
   - 角为 0 分位非 0 →「元」后写「零」：¥16,409.02 → 壹万陆仟肆佰零玖元**零**贰分
   - 角为 0 分也为 0 → 收「整」；角非 0 分位为 0 →「…x角整」：¥10.00 → 壹拾元整
   - 连续零只写一个「零」：¥1,001.00 → 壹仟**零**壹元整
   - ¥1,700.31 属人民银行规则③「可写零可不写零」，本包选择不写：壹仟柒佰元叁角壹分
   - **金额为 0 输出「零元整」**，绝不输出空串；负数前置「负」；
     绝对值 < 0.005 四舍五入后归零，按「零元整」出，不带「负」
2. **价税分离的税额是倒挤的**：税额 = 含税金额 − 不含税金额，
   不是「含税 × 税率」。后者在分位上会差 1 分（1,000.01 @13% 尤其明显），
   本包用倒挤 + 守恒断言，主表「不含税+税额」列就是给对账用的验算值。
3. **尾差分摊在「分」上做，不在「元」上做**：总额先转成分，
   按权重逐份截尾取整，余数按小数部分从大到小补分，
   各份之和严格等于总额（实测 1,130.00 分 3 份 = 376.67 + 376.67 + 376.66）。
   每份单列「本份尾差(分)」，最后一份「累计分摊」必然等于总额。
4. **含税↔不含税只按 (1+r) 折算**，不做任何"看起来差不多"的近似；
   r 按**百分数**填（13 = 13%，也可写 "13%"）；免税填 0 会照算并标注，
   但**空值不给默认税率**——猜税率比算错更危险。
5. **百分比反算两条路都留**：已知「部分 + 占比」反总数，
   或已知「总数 + 部分」反占比；占比 ≥ 100% 一律拒绝。
6. **单价换算**：单价 = 金额 ÷ 数量；给了 `--price` 就反算数量。
7. 本包只做**数值换算**，不管票据样式、不管审批流程、不管大小写是否进凭证。

## 人工复核（必读）

- 金额大写用于票据/合同前，请对照业务习惯确认「零」的写法取舍
（¥1,700.31 这类规则③允许两种写法的金额，银行都认，但与本单位模板不一致时需统一）
- 税率口径请与合同 / 发票核对（13% 一般税率、9% 交通运输等、6% 现代服务、3% 小规模征收率）
- 价税分离的税额是**倒挤值**，与「含税 × 税率」可能有 1 分差异，属正常
- 尾差分摊的权重口径（面积 / 人数 / 预算占比）请与分摊方案一致，
  本包只负责把金额摊平，不负责决定按什么摊
- 金额 ≥ 1 万亿本包拒绝出大写，请先与业务确认是否误填
- 结果仅供财务复核，入账 / 申报 / 付款口径需人工确认

## 相邻路线转交

| 用户要做的事 | 转交给 |
|---|---|
| 增值税 / 各税种应纳额计算 | `tax-amount-calc` |
| 发票金额与税额核对 | `invoice-book` |
| 成本按部门 / 项目分摊（有科目余额表） | `cost-allocation` |
| 报销金额汇总 | `expense-summary` |
| 应付账款账期与付款排期 | `ap-payment-schedule` |
| 会计期间 / 账期起止日换算 | `period-tool` |

## 可直接复制的说法

```text
帮我把这几个数算一下：金额大写按人民银行写法来，
角为 0 分位不为 0 的要写「零元零X分」，连续零只写一个零，
金额为 0 就写「零元整」，不要留空。
价税分离时税额 = 含税金额 − 不含税金额，不要用「含税 × 税率」，
两列加起来必须严格等于原含税金额，差一分钱就说算不出。
金额要分摊的话，各份加起来也必须严格等于总额，
尾差单列出来，不许默默抹平。
基数为 0 或负数、税率没给、占比超过 100%，直接拒，
不要按 0 算一遍糊弄我，也不要给我一个看着合理的替代数。
```

## 做完怎么算完成

- [ ] 大写金额已逐条对照人民银行写法（零 / 整 / 负 / 零元整）
- [ ] 价税分离的「不含税 + 税额」列已逐行等于原含税金额
- [ ] 尾差分摊各行「累计分摊」最后一行 = 总额，尾差已查明去向
- [ ] 税率口径（13% / 9% / 6% / 3%）已与合同、发票核对
- [ ] 异常表逐条已追查，无「未说明原因的缺失」
- [ ] 被拒绝的行确实是因为缺参数 / 基数为 0，不是脚本没跑到

---

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

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

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