发票台账

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

# 发票台账

税局要求「台账」不是为了好看，是要能一句话答出：这个月销项多少钱、进项多少钱、哪几个客户的票占了大头、有没有税率填错的。

本包做两件事：**把散乱的字段标准化**（方向/销方/购方/金额/税额/税率/日期，列名千奇百怪也能认），**按你要的维度汇总**（月份、客户、税率、 anybody 组合都行）。汇总结果不做税务判断——申报口径是「开票期」还是「所属期」由你定，本包两种都能出，但不会替你选。

## 输出四件套（每次运行必有）

| 文件 | 内容 |
|---|---|
| `book_主表.csv` | 标准化后的逐票台账（原列 + 标准化列） |
| `book_汇总.csv` | 按维度聚合：票量 / 不含税金额 / 税额 / 占比 |
| `book_异常表.csv` | 税率缺失、方向未知、金额为负、税额勾稽不成立 |
| `book_校验表.csv` | 汇总口径、维度、字段映射来源、人工复核声明 |
| `fin-log.jsonl` | 处理日志（追加，四件套之外多一份汇总表） |

## 环境准备

```bash
PY="<python 3.8+ 路径>"   # 纯标准库
"$PY" <skill目录>/scripts/invoice_book.py <发票明细表> [参数]
```

## 用法

### 默认按月 / 销方 / 税率汇总

```bash
invoice_book.py 发票明细.xlsx
```

真实输出：

```
方案：发票明细.xlsx | 数据行=426 | 识别方向列=发票类型(进/销)
  进项票 218 张 / 销项票 208 张
--- 汇总预览（前 6 行，按月+销方+税率）---
  期间     | 方向 | 客户                 | 税率  | 票量 | 不含税金额      | 税额
  2026-09  | 销项 | 深圳市甲公司         | 13%   |  12  | 486320.00       | 63221.60
  2026-09  | 进项 | 广州乙公司           | 9%    |   8  | 178400.00       | 16056.00
```

### 换汇总维度

```bash
invoice_book.py 发票明细.xlsx --group 开票月份,购方名称
```

维度用逗号分隔，输出顺序按金额从大到小，同一维度下进项与销项并列——**加减方向你自己看**，本包不做净额。

### 只算某个方向

```bash
invoice_book.py 发票明细.xlsx --direction 销项
```

## 字段是怎么认出来的

不许猜，认不出来就列进异常表：

| 标准字段 | 候选列名（命中即认） |
|---|---|
| 方向 | 发票类型 / 票种 / 方向 / 进项销项 / 视同 |
| 销方 | 销售方名称 / 销方名称 / 销方 / 销售方 |
| 购方 | 购买方名称 / 购方名称 / 购方 / 购买方 |
| 不含税金额 | 金额 / 不含税金额 / 不含税 / 价税分离后金额 |
| 税额 | 税额 / 增值税税额 |
| 税率 | 税率 / 税率或征收率 |
| 开票日期 | 开票日期 / 开票时间 / 日期 |

**金额字段认不出就拒绝**：这是汇总的地基。认得出时按「含税 → 价税分离」处理：不含税额 = 含税/(1+税率)，税额 = 含税 - 不含税额，四舍五入到分。

## 安全与边界（拒绝权）

- **源文件零改动**：输出进 `_out/`，原表一个字节不动
- **默认预览**：不加 `--execute` 不写盘
- **方向认不出不猜**：一张票不知道是进还是销，只能进异常表，绝不默认塞进销项
- **税率缺失不补全**：没有税率的票单独列进异常表，汇总是「部分汇总」，校验表里写明范围

## 人工复核（必读）

- 汇总的「不含税金额」是从含税额反算的，与票面直接取的口径可能差几分，以票面为准时请核对
- 申报用的是「所属期」，勾选平台统计用的是「开票期」，两者会打架。本包两种口径都能出，选哪个由你决定
- 台账生成后应与勾选平台的统计数核对，差异要能逐票追溯

## 相邻路线转交

| 用户要做的事 | 转交给 |
|---|---|
| 查有没有重复票 | `invoice-duplicate-check` |
| 进销项按月对不上、找跨期票 | `vat-monthly-recon` |
| 发票合规项预检 | `invoice-rule-check` |
| 先把脏表洗干净 | `fin-table-clean` |

## 可直接复制的说法

```text
把这份发票明细做成台账，字段按标准名认一遍（方向/销方/购方/金额/税额/税率/日期），
认不出来的单独列出来别猜。然后按月、按销方、按税率汇总，输出票量、不含税金额、税额。
销项和进项分开列，不要给我净额。汇总里没有税率的票单独走异常表。
```

## 做完怎么算完成

- [ ] 异常表里的票能逐条说明原因，没有含糊的"格式问题"
- [ ] 汇总的合计行数 = 台账行数（进 + 销 + 异常）
- [ ] 申报口径（开票期 / 所属期）已确认
- [ ] 与勾选平台数据核对过，差异可追溯

---

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

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

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