发票整理

发票整理

把散落在一堆目录里、命名混乱的发票收据，整理成一份可用于报销或报税的结构化台账。核心工作是：找出所有票据文件 → 提取关键信息 → 按日期/类别/金额归类 → 生成汇总清单和明细台账。目标是省掉人工逐张登记的苦力活，而不是替用户做财务判断。

目标

对指定目录里的发票收据，产出两份可直接使用的成果：一份 CSV 明细台账（每张票据一行，字段规整，可导入 Excel/报销系统）和一份 Markdown 汇总报告（按类别/月份的金额小计、总计、待核对清单）。整理过程只读不删，金额或信息存疑的一律标注"待核对"，把判断权留给用户。

工作流步骤

步骤 1：确认范围与规则

动手前先和用户确认（缺失则询问）：

• 目标目录：要整理哪个目录？是否含子目录？
• 用途：报销还是报税？这决定分类维度（报销常按人/项目/月份，报税常按发票类型/月份/税额）。
• 时间范围：只整理某段时间的票据吗？
• 分类维度：按类别（交通/住宿/餐饮/办公/通讯/会议等）、按月份、按项目或按人。默认按"类别 + 月份"双维度。
• 币种：是否多币种，是否需要换算（换算需用户提供汇率，不自行假设）。

步骤 2：扫描目录、识别票据文件

用 Glob 和 Bash 找出候选文件，不修改任何文件。

• 用 Glob 按常见票据格式扫描：**/*.pdf、**/*.jpg、**/*.jpeg、**/*.png、**/*.ofd（国内电子发票）、**/*.xml、**/*.xlsx。
• 用 Bash 辅助列出文件清单及元信息（大小、修改时间），例如用 ls -la、find 统计数量和分布。只用只读命令（ls/find/stat/file/wc 等），不使用任何移动、重命名、删除类命令。
• 初步过滤：明显不是票据的文件（截图、无关文档）先标为"疑似非票据"，交由后续判断，不擅自排除。
• 统计总数并向用户报告扫描结果概览（找到多少个候选文件、分布在哪些目录、各格式数量）。

步骤 3：提取关键信息

对每个候选文件提取台账所需字段。能确定的字段就填，不能确定的留空并标注，绝不猜数字。

需要提取的核心字段：

• 开票日期（date）
• 商户 / 开票方（vendor）
• 金额（价税合计）（amount）
• 税额（tax，如有）
• 发票类型（专票/普票/电子发票/收据等）
• 类别（transportation/accommodation/meals/office/... 按步骤 1 约定）
• 文件路径（source_path，保留原始位置，便于溯源）
• 备注 / 状态（note：如"待核对""图片模糊""金额不清"）

提取方式：

• 文本类文件（PDF 文本层、XML、OFD 解析出的文本、xlsx）：用 Read 读取内容后解析字段。
• 图片和扫描件：本技能不做 OCR 图像识别。对无法直接读出文本的图片，在台账中登记文件路径和从文件名/目录能推断的信息，其余字段留空并标注"待核对：需人工录入"。
• 从文件名和目录名可以推断的信息（很多人用"20240315-高铁-352元"这类命名）可作为线索，但必须标注为"推断"，不能当作确认值——文件名可能是错的。

步骤 4：归类与汇总

• 按步骤 1 约定的维度给每条记录归类（类别 + 月份为默认双维度）。
• 计算各维度小计和总计：按类别汇总金额、按月份汇总金额、总金额、总税额。
• 金额校验：对能读到明细的票据，若"价税合计 ≠ 不含税金额 + 税额"，标注"金额待核对"。发现同一张票据疑似重复（相同金额+日期+商户）时标注"疑似重复"，列出但不自动删除。
• 汇总数字要能对得上：明细行金额之和应等于总计，把这个校验也写进报告。

步骤 5：生成台账与报告

用 Write 输出两份文件到用户指定位置（默认目标目录下，或用户给的路径）：

1. CSV 明细台账（invoice-ledger.csv）：一张票一行，字段见输出格式。
2. Markdown 汇总报告（invoice-summary.md）：金额小计、总计、待核对清单、疑似重复清单、非票据文件清单。

最后向用户报告：共整理多少张、总金额、有多少张需要人工核对、有哪些疑似问题。

输出格式

CSV 台账（invoice-ledger.csv） 表头：

序号,开票日期,商户,类别,金额,税额,发票类型,状态,文件路径
1,2026-03-15,某高铁,交通,352.00,,电子发票,已确认,./2026-03/高铁-352.pdf
2,2026-03-16,某酒店,住宿,,,图片,待核对:金额不清,./2026-03/hotel.jpg

Markdown 汇总报告（invoice-summary.md） 结构：

# 发票整理汇总（<时间范围>）

- 整理目录：<path>
- 票据总数：N 张（已确认 X，待核对 Y）
- 合计金额：¥ZZZ（其中税额 ¥WW）
- 生成时间：<date>

## 按类别汇总
| 类别 | 张数 | 金额 |
|------|------|------|
| 交通 | 12   | 4,230.00 |

## 按月份汇总
| 月份 | 张数 | 金额 |
|------|------|------|

## 待核对清单（需人工确认）
| 序号 | 文件 | 原因 |
|------|------|------|

## 疑似重复
| 序号 | 文件 | 说明 |

## 疑似非票据文件
- <path>

边界

• 只整理，绝不删除或移动：本技能不删除、不重命名、不移动任何原始文件，Bash 仅用于只读扫描（ls/find/stat/file 等）。整理产物是新生成的台账文件。
• 不臆造金额和信息：读不出来的字段一律留空并标注"待核对"，绝不填一个"看起来合理"的数字。从文件名推断的信息必须标注为推断值。
• 金额存疑必标注：价税不符、图片模糊、疑似重复、疑似非票据的，全部标注并汇总到"待核对/疑似"清单，把核对判断权交回用户。
• 不做 OCR 图像识别：对纯图片扫描件，只登记路径和可推断信息，提示用户人工录入或使用专门 OCR 工具，不假装识别出了内容。
• 不提供税务/合规裁定：本技能整理数据、做算术汇总，不判定发票是否合规、能否抵扣、能否报销——这些是财税专业判断，明确提示由用户或财务/税务人员决定。
• 保护财务隐私：台账仅生成在本地用户指定位置，不外传；涉及金额和商户等敏感信息，不写入任何外部渠道。