月账房 V.2.2

概述

月账房 v2.2

票据丢给我，归档台账全自动

月账房——面向国内企业财务人员的票据轻量化自动整理工具。一般纳税人、小规模纳税人都可以用。名字取自旧时商号里的"账房先生"：管票、管账、管月结，把散票理清、把台账算平。（沿革：月末发票整理助手 v1.0 → 发票整理专家 Pro v2.0 → 月账房 v2.1 → v2.2）

不做财税系统，不做纳税申报——专注财务月末最重复、最机械、最容易出遗漏的票据预处理与月结整理工作：

月份文件夹规范 → 归档 → 去重 → 识别 → 分类 → 汇总计算 → 增值税差额 → 异常筛查 → 完整性核验 → Excel + 规范文档交付

把当月散乱的发票和银行对账单交给它，它帮你把票归好、把账算清、把问题挑出来、把漏票核明白。

一、它解决什么问题

月末整理看起来简单，真正耗时间的是这些机械工作：

• 月份文件夹命名五花八门（带"份"、账期写成 3.1-3.31、缺"年"）
• XML、PDF、OFD 混在多个文件夹里；同一张票有三四个载体
• 一张张判断是进项还是销项、一张张录金额税额
• 银行流水截图和回单命名混乱，月底找不到对应凭证
• 有些票金额对不上、字段缺失，却很容易混过去
• 文件很多时，最后还会担心：是不是漏了一张？

一句话：票据和流水丢进来，自动归档、自动算表、自动算税、自动查问题、自动核漏票。

二、核心能力

三、用户最终拿走什么

① 一套规范目录：

• 00_待人工确认/（含 疑似其他公司/ 子目录）
• 01_进项票据/（专票 / 普票 / 铁路电子客票 / 航空客票 / 通行费 / 其他进项）
• 02_销项发票/（当月无销项也保留空目录，结构固定）
• 03_其他票据/（降级模式归档位置 + 非税收入票据）
• 04_报表汇总/
• 05_银行流水/（银行流水子流程的归档/重命名位置）
• 06_收件箱_发票/、06_收件箱_专票/（新票入口：待整理票据放这里，会被扫描；整理完复制进归档目录，原件保留）
• 99_不入账/（个人订阅收据、非公司抬头凭证等留档文件，永久跳过不扫描）

非税收入票据规则（v2.1 更新）：政府非税收入统一票据（电子）——如北京市政「停车占道费」——不是增值税发票，无进/销项抵扣口径。自动识别、正常解析字段，归档到 03_其他票据/（票种简称「非税票据」），自动归入"费用"方向并按票面项目自动分类（停车→停车费、医疗→医疗、其他→其他），直接进费用汇总，不再需要每轮人工确认；不进进销项统计和增值税抵扣口径。

财政电子票据多省版式（2026-09 升级）：解析采用双层提取——层1 明文标签（财综〔2018〕72 号全国统一式样：票据代码/票据号码/交款人统一社会信用代码/交款人/校验码/开票日期/项目名称/金额合计/收款单位；电子缴款书变体：缴款码/执收单位名称/填制日期/付款人全称/金额(大写)(小写)，缴款码可兜底作票据号码标识）；层2 数据特征（北京 cid 乱码版式，只补层1缺的字段）。检测词覆盖非税收入统一票据、电子缴款书、医疗收费票据、人民法院票据等；带增值税守门标记，卖方名含"财政票据"字样的增值税发票不会被误路由。层2 已经 4 张北京真实票回归验证（与台账逐字段一致）；层1 字段级细节未经真实省级 PDF 样本验证（基于财政部官方式样文档 + 浙江/江西/福建官方文件构造），提取失败安全降级进"待确认"。

② 一份 Excel 发票台账——6 张表一次生成（04_报表汇总/发票台账.xlsx）：

③ 一份人话版整理报告——整理前后对比 + R4 闭环核对结论，原样转述给用户。

④ 交付增强——财务文件夹命名规范.html 自动放置到月份文件夹根目录（已存在则不覆盖）；assets/使用说明.html 是面向财务人员的图文使用手册（快速上手/9 类目录/铁律/勾选清单比对/常见问题），随包发布，用户问"怎么用""有没有说明书"时打开给用户看。

四、能力边界（如实告知用户）

做的事：月份文件夹改名、票据归档、票面信息提取、同票去重、企业主体识别、进销项方向判断、费用用途分类、金额/税额/价税合计统计、增值税差额的票面参考计算、银行对账单规范重命名、异常筛查、Excel 台账生成、命名规范文档放置、全文件闭环核验。

不做的事：银行流水与账目对账（只整理命名，不核对流水与账务）、税务数字账户同步、增值税应纳税额申报、进项税额抵扣资格判断（"增值税计算"sheet 是票面口径参考，红负绿正只帮助读数）、差旅关联、OCR 扫描件识别。

关于图片扫描件：PDF 通过文本提取方式读取。纯扫描图片 PDF 自动判定解析失败并进入待确认，不会 OCR 猜内容。

五、五条硬规则（任何情况下不能违反）

• R1 原件保护：发票原件只复制（shutil.copy2），位置和内容永远不变。银行对账单子流程是唯一例外——就地重命名，但内容与 SHA256 前后一致强制校验、旧名→新名全程审计留痕、任何情况下不删除文件。
• R2 同票不重复记账：同一张发票的 XML/PDF/OFD 多个文件，最终只在台账里算一条。优先用发票号码；号码缺失时退化为"销售方税号 + 购买方税号 + 开票日期 + 价税合计"组合判断。
• R3 处理可追溯：每个文件都在 .invoice-organizer/audit_log.jsonl 留记录；银行对账单改名在 .invoice-organizer/bank_rename_log.jsonl 留记录（旧名/新名/哈希/类型/日期）。JSONL 追加写入，不支持覆盖。
• R4 输入输出完整性核验：交给 Skill 的每一个源文件，最终都必须有明确处理结果，不允许静默丢弃。扫描阶段独立记源文件总数，归档阶段反向统计，交叉核对一致才显示"核对通过"。
• R5 用途确认数据不覆盖原件：用途确认信息.xlsx 只补齐解析缺失的字段；与票面提取值冲突时保留提取值并上报冲突清单，绝不静默改数。

核心流程不依赖任何特定模型才能跑通；唯一用到语义判断的地方（费用分类少数项、银行流水截图看日期）使用当前会话正在运行的模型。

五点五、账期铁律（v2.1 用户拍板，最高优先级业务规则）

票据严格按开票日期归账期：一张票属于哪个月份文件夹，只看票面开票日期，不看收到/支付/入账时间。

• 开票日期 2026-09-15 的票 → 属 2026年10月份 账期2026年9.1-9.30（报税月 = 开票月 + 1）
• 发现行内票面开票日期与所在文件夹账期不符 → 主动提示用户迁移，迁移前用内容哈希确认目标文件夹没有同票副本
• 价值：台账可抵扣口径自动对齐税局勾选属期（勾选清单按开票日期算属期），无需人工对期

执行要点：

1. 整理完一个账期后，主动用税局《用途确认信息.xlsx》（电子发票服务平台导出的勾选清单）跑第七步比对——缺票（已勾选抵扣但台账无票）是 P0 级问题，必须提示用户从平台下载原件补入。
2. 同一供应商同金额的不同票（如腾讯云 340 与 70）是两张票，靠发票号码区分，不要凭印象合并。
3. 用户放入 GUID/下载原名的新票时，先看开票日期判断账期归属，再决定放进哪个收件目录。

六、触发条件

• "帮我整理这个月的发票" / "月末发票整理" / "这些票帮我分一下类"
• "整理银行流水" / "这些截图帮我重命名" / "银行回单整理一下"
• "月份文件夹改名" / "文件夹命名规范化" / "把账期文件夹统一一下"
• 直接把发票文件夹 / 银行对账单文件夹路径发过来

七、执行流程

所有脚本都在 scripts/ 下。首次运行自动检测并静默安装缺失依赖（defusedxml / pdfplumber / openpyxl）。

第零步（可选）：月份文件夹规范化

python scripts/normalize_month_folders.py <年份父目录或月份文件夹>            # 默认 dry-run 预览
python scripts/normalize_month_folders.py <路径> --apply                     # 真正重命名
python scripts/normalize_month_folders.py <路径> --apply --force             # 含技能归档状态的文件夹也改（台账需重跑）

安全设计：含 .invoice-organizer/ 或 04_报表汇总/发票台账.xlsx 的文件夹默认跳过（台账内是绝对路径，改名会失效）；目标名冲突跳过；Windows 目录被占用（当前会话持有 .workbuddy）报告后跳过，提示用户关对话后手动改。

第一步：扫描 + 解析 + 合并

python scripts/scan.py <发票所在目录> <工作目录>

只读。输出 JSON：total_files_found / parseable_files_found / total_records_after_merge / unsupported_files / rescan_merge。

重扫合并（v2.1）：输出里的 rescan_merge 有两个计数——carried_classifications（已确认的费用分类自动带回，prepare 不再重复列出已分类票）和 retained_archived_ids（收件目录里没扫到原件、但归档副本还在的票，自动保留防漏票）。retained_archived_ids 非空时要念给用户听：「某票收件原件已被移走，本轮按归档记录保留」。

用途确认信息.xlsx（v2.0）：位于工作目录或发票目录（含 05_报表汇总/ 子目录）时自动读取，输出 usage_confirm 统计（matched/filled/mismatches）——有 mismatches 时要念给用户听。

两种分支：

• 已有 company.json：返回 existing_company_config，跳过第二步。混入他公司票据时带 other_company_alert（只统计买卖双方均不匹配主体的票据，常客供应商不误报）。
• 首次运行：返回 identification_mode（single/multi/none）和 candidates（candidate_id + 公司名 + 脱敏税号 + 张数）。

隐私：完整税号不进 stdout/模型上下文，只落本地 company_candidates.json。

第二步：确认公司主体（仅首次）

python scripts/confirm_company.py <工作目录> confirm-id <candidate_id>
python scripts/confirm_company.py <工作目录> confirm "<公司全称>" "<完整税号>"
python scripts/confirm_company.py <工作目录> degraded    # 降级：不区分进销项

不提供"跳过"选项——要么确认，要么明确降级。

第三步：异常检查 + 费用规则分类

python scripts/prepare_expense_classification.py <工作目录>

无论有没有需要语义判断的发票都必须执行（异常检查是硬性职责，跳过会让金额对不上的票被当正常票归档）。输出 {"ambiguous": [...]}；语义判断只用 item_summary + counterparty_name 两个最小必要字段。类别：办公用品 / 技术服务 / 咨询服务 / 广告宣传 / 住宿 / 餐饮 / 停车费 / 交通 / 通信 / 快递 / 医疗 / 业务招待 / 福利 / 其他。

非税票据自动归类（v2.1）：非税收入票据在此步自动定为 费用方向 + 票面类别（停车占道费→停车费、医疗→医疗、其他→其他），不出现在 ambiguous 里，无需人工确认。

第四步：写回分类结果

python scripts/apply_expense_classification.py <工作目录> <决策JSON文件路径>

第三步 ambiguous 为空时跳过。

第五步：归档 + 生成台账 + 放置规范文档

python scripts/finalize.py <工作目录>

执行归档（复制）、审计日志、生成 6-sheet 台账（含增值税计算）、放置《财务文件夹命名规范.html》、打印人话报告（含 R4 闭环核对）——原样转述给用户。

台账占用旁路写（v2.1）：发票台账.xlsx 被预览/Excel 占用时自动写入旁路文件 发票台账_新口径.xlsx 并在报告中说明换名步骤——流水线不中断，其余产出照常交付。

第七步（v2.1）：税局勾选清单比对（整理完成后自检）

python scripts/compare_tax_selection.py <工作目录> <用途确认信息.xlsx>

只读。与台账逐票比对勾选清单：matched（对上，含逐票税额校验）/ missing_in_ledger（缺票：已勾选抵扣但台账无票 → P0，提示用户从电子发票服务平台下载原件）/ unselected_in_ledger（台账专票本属期未勾选 → 提示自行确认）。税局 xlsx 维度信息损坏时自动降级普通模式读取。每个账期整理完都应跑一次（清单文件按属期存放在 05_报表汇总/ 或 04_报表汇总/）。

子流程：银行流水/回单整理（独立于五步，随时可跑）

python scripts/bank_statements.py scan <目录>
# → 文件清单 JSON（PDF 自动给建议日期；PNG 无文本层，需看图判断）

python scripts/bank_statements.py apply <目录> <决策JSON路径>
# 决策JSON: {"原文件名.png": {"date": "2026-04-08", "type": "流水", "page": 1}}

Agent 先 scan，再逐张看图（视觉读取截图里的交易日期）或问用户，确定 type ∈ 流水|回单|月度汇总 与日期，组装决策 JSON 后 apply。命名（v2.2 整月连续序号）：流水/回单 YYYYMMDD_类型-序号，序号两位补零、按交易日期整月连续（01、02…后补早日期票自动插入重排，一张多页占连续序号）；月度汇总 YYYYMM_月度汇总。apply 全量校验后才动手（任何一条不合法整体不动）；每次 apply 对目录内全部流水/回单全局重排序号（含已命名文件，重排动作写入审计 bank_renumber）；内容 SHA256 前后校验 + bank_rename_log.jsonl 留痕。

八、异常检查清单（第三步自动执行）

主体识别防误判（2026-09 用户确认）：①税号自修复——PDF 文本层税号带多余字符（19~20 位）时按 GB 32100 校验位滑窗自修复（唯一命中才采纳）；②名称回退——税号修不好但购买方名称与主体全称一致时信任名称；③常客供应商不误报——"其他公司"警报只统计双方均不匹配的占比。

防误报：同一供应商、同一天、同金额但各有完整不同号码的多张票，不判重复。

九、交互设计要点

• 除"确认公司主体""费用语义分类""银行流水看图定日期"三处，全程不打断用户。
• 待确认记录永不强行分类，统一进 00_待人工确认/。
• 重复运行安全：invoice_record_id 是内容确定性哈希；归档与跳过目录（00_~05_ 及 99_ 前缀）不会被再扫，06_收件箱_* 是扫描入口。
• 新票必须放进收件目录（06_收件箱_发票/ 或 06_收件箱_专票/）：用户若把新票直接丢进归档子目录（典型特征：GUID/下载原名出现在 01_~03_ 归档树里），scan 会因归档目录跳过而永远看不到它。处理：先把它移回收件目录（os.rename，保留原文件内容），再走第一步。定位"新放入的票"可用全盘 mtime 倒序扫描年份父目录。
• 降级模式是合法路径，明确告知"不区分进销项"。
• 月份文件夹改名涉及已归档数据时先提示风险（绝对路径失效），不要静默改。

十、隐私与数据处理

核心解析、归档、统计、Excel 生成、审计记录均由本地 Python 完成。完整税号只存本地状态文件，不进模型上下文。费用分类与银行流水判断只使用最小必要字段（商品摘要/往来单位名/截图日期）。银行流水截图的视觉读取发生在当前会话内，不做外部上传。

原始票据和核心数据优先本地处理；少量语义辅助仅用最小必要字段。

十一、已知限制

• XML/OFD 字段抽取经过少量真实数电票样本验证，样本量小不等于"兼容所有数电票"——解析失败诚实进"待确认"，不编造字段。
• 不支持 OCR：纯图片扫描 PDF 无法提取字段（银行对账单 PNG 靠会话内视觉读图，不属于 OCR 通道）。
• 财政电子票据多省版式（2026-09 升级，双层提取）：层2 北京版式经真实样本验证；层1 全国统一式样/缴款书基于官方文件构造、未经真实省级 PDF 验证，失败安全降级。
• PDF 文本层版式容错：标签字间插空格（"发 票 号码"）、税号带前导字符、字体子集 cid 乱码均已收编自动处理。
• 跨轮重跑幂等：上一轮"无法分类"的本轮分类成功后自动清除旧标记。
• 用途确认信息.xlsx 列名按关键词模糊匹配（发票号/日期/销售方/金额/税额）；列名差异过大时自动跳过并在 JSON 里说明。
• 月份文件夹改名后，旧台账/审计日志中的绝对路径失效——工具默认跳过此类文件夹，--force 改名后需重跑整理流程刷新台账。
• "增值税计算" sheet 是票面口径参考：普票不抵扣、航空/通行费计算抵扣与抵扣资格判断不在口径内，不替代纳税申报。
• 不做银行流水对账、税务数字账户对账、差旅关联。

十二、v2.0 功能范围

v1.0 → v2.0 变更（2026-09，原型 financial-invoice-organizer 功能并入）：

1. 技能改名：monthly-invoice-organizer（月末发票整理助手 v1.0）→ invoice-organizer-pro（发票整理专家 Pro v2.0）→ yue-zhangfang（月账房 v2.1，2026-10 定名）。
2. 新增月份文件夹规范化（normalize_month_folders.py，dry-run 默认）。
3. 新增银行流水/回单整理（bank_statements.py，scan+apply 两阶段、哈希校验、审计留痕）。
4. 台账新增"增值税计算"sheet（销项−可抵扣进项=应纳/留抵）。
5. 新增 用途确认信息.xlsx 数据源（只补缺不覆盖，冲突上报）。
6. 归档完成自动放置《财务文件夹命名规范.html》。
7. 财政电子票据多省版式双层提取（全国统一式样/缴款书/北京 cid 版式 + 增值税守门）。

目录结构保持 5 目录体系并扩展 05_银行对账单/，不迁移历史归档数据。业务范围不含银行流水对账、纳税申报、抵扣资格判断。R4（闭环核验）是基础设施保障，不是业务功能。

十三、v2.1 功能范围

v2.0 → v2.1 变更（2026-10-26，9-11 月三个月真实账期实战驱动，全部经真实数据回归验证）：

1. 账期铁律：票据严格按开票日期归账期（用户拍板），台账自动对齐税局勾选属期。实战验证：9 月台账可抵扣 382.07 = 202608 勾选清单分毫不差；10 月台账 72.05 = 202609 勾选清单分毫不差。
2. 重扫防漏票（core/rescan_merge.py）：收件原件被移走后重扫不再静默丢已归档票（飞书 960 事故根治）；已确认分类跨轮记忆，prepare 不再重复列出已分类票。单测 3 场景通过。
3. 非税票据自动归费用：自动定 费用方向 + 类别（停车费/医疗/其他），取消每轮手工 patch。真实回归通过。
4. 税局勾选清单自动比对（compare_tax_selection.py）：一键核对缺票/税额不一致/未勾选票，read-only。真实数据验证：202608 清单 10 张 382.07 全对上；202609 清单 4 张 72.05 全对上。
5. 台账占用旁路写：finalize 遇 发票台账.xlsx 被占用自动写 发票台账_新口径.xlsx，流水线不中断。
6. 归档源缺失容错（core/archive.py）：收件原件丢失但归档副本在 → 复用副本；两者都缺 → 明确报错（不静默）。
7. 费用类别扩充：新增 停车费 / 通信 / 快递 / 医疗 四类（交通里拆出停车），技术服务加"云服务"关键词。
8. 数电票 OFD 类型识别：裸词「专用发票/普通发票」（无"增值税"前缀）正确映射。

同批迁移：原型的 references/business_rules.md 已更新收录（含账期铁律），位于本技能 references/business_rules.md。

十四、v2.2 功能范围

v2.1 → v2.2 变更（2026-10-26 下午，用户看真实文件夹逐项拍板）：

1. 月份文件夹 9 类标准结构：00_待人工确认 / 01_进项票据 / 02_销项发票（当月无销项也保留空目录）/ 03_其他票据 / 04_报表汇总 / 05_银行流水 / 06_收件箱_发票 + 06_收件箱_专票（新票唯一入口）/ 99_不入账（个人收据留档，永久跳过）。数字前缀即语义：00-05 归档、06 扫描入口、99 排除。2026-10-26 已对 9/10/11 三个月完成对齐（10 月：银行流水→05_、AI发票→99_、发票/专票→06_收件箱_*；11 月补建 00_/02_/03_）。
2. scan.py 目录识别修复：跳过前缀补 05_/99_（原来只排 00_-04_，银行流水 PNG 每轮都被误列"不支持文件"）；递归跳过一切隐藏目录（.workbuddy 等不再产生扫描噪音）。只读回归：收件箱 6 文件→5 票（R2 合并重复副本）、归档/不入账目录零干扰。
3. 银行流水/回单整月连续序号：命名从"日期内页码"（换天从 1 重来）改为 YYYYMMDD_类型-序号，序号两位补零、按交易日期整月连续（01、02…后补早日期票自动插入重排、后续顺延，一张多页占连续序号）。apply 每次对目录内全部流水/回单全局重排：本批先挪临时名防碰撞、SHA256 前后校验、出错整体回滚；重排动作以 bank_renumber 写入审计日志。2026-10-26 已重排 9 月份 12 张（-01…-12）、10 月份 5 张（-01…-05）。
4. 命名规范文档同步：《财务文件夹命名规范.html》目录表更新为 9 类（写明"新票丢 06_ 收件箱，别直接丢归档目录"——GUID 票漏扫根因）、银行流水章节改为整月连续序号示例；9 个月份文件夹根目录副本全部重新放置。
5. 技能定名：月账房（目录 yue-zhangfang），取代"发票整理专家 Pro / 月末发票整理助手"旧名；skillhub 发布包同步 v2.2 全部内容。

十五、使用说明（面向最终用户，随技能发布）

票据丢给我，归档台账全自动。面向企业财务人员的票据轻量化自动整理工具，一般纳税人、小规模纳税人都适用。

沿革：月末发票整理助手 v1.0 → 发票整理专家 Pro v2.0 → 月账房 v2.1 → v2.2（2026-10）

使用说明 1、它能帮你做什么

明确不做：银行流水对账、纳税申报、进项抵扣资格判断、OCR 扫描件识别、差旅关联。"进项/销项"是票据归档口径，不构成税务处理结论。

使用说明 2、第一次使用（3 步）

1. 把月份文件夹建好。命名格式 2026年5月_账期2026年4月（报税月在 前、账期在 后）。直接说"帮我把月份文件夹统一一下"也可以。
2. 把票据丢进收件箱。新下载的发票（哪怕文件名是一串 GUID）放进 06_收件箱_发票/ 或 06_收件箱_专票/，银行回单截图放进 05_银行流水/。
3. 说一句话。"帮我整理这个月的发票"——它会扫描、识别、问你一次公司主体（仅第一次）、归档、生成台账，最后给你一份完整报告。

⚠️ 重要：新票一定放 06_收件箱，不要直接丢进 01_~03_ 归档目录——归档目录扫描时会跳过，丢进去的票会"隐身"。

使用说明 3、月份文件夹长什么样（9 类固定结构）

使用说明 4、你最终拿到什么

1. 一份 6 张表的 Excel 台账（04_报表汇总/发票台账.xlsx）：待确认、发票台账（逐票明细）、进销项汇总、增值税计算（销项−可抵扣进项=应纳/留抵）、费用汇总、文件处理清单。
2. 一份人话版整理报告：整理了多少文件、归了多少张票、几张待确认、闭环核对是否通过。
3. 一份《财务文件夹命名规范.html》：自动放在月份文件夹根目录，手工归档时对照用。

使用说明 5、两条业务铁律

账期铁律：一张票属于哪个月，只看票面开票日期——9 月 15 日开的票就归"10 月份（账期 9 月）"，哪怕你 10 月才收到。这样台账可抵扣税额自动和税局勾选属期对上，不用人工对期。发现放错月份的票，它会提示你迁移。

原件保护：发票永远只复制、不修改、不删除；银行对账单只就地重命名，内容哈希前后校验，全程留痕。

使用说明 6、银行流水怎么整理

把截图/回单 PDF 丢进 05_银行流水/，说"整理银行流水"。它会列出文件清单，看图认出每张的交易日期，然后重命名成：

月中补进早日期的回单也不怕——它会自动把整月序号重新排好，谁都不会错位。

使用说明 7、跟税局勾选清单对一下（强烈建议每月做）

从电子发票服务平台导出《用途确认信息.xlsx》，放进 04_报表汇总/，说"跟税局勾选清单对一下"。它会逐票核对：

• ✓ 对上的票（含税额分毫校验）
• ✗ 缺票：税局显示已勾选抵扣、但台账里找不到这张票——P0 级问题，马上去平台下载原件补入
• ⚠️ 未勾选：台账里的专票本属期还没勾选——提醒你自行确认

使用说明 8、常见问题

使用说明 9、五条硬规则（对用户的承诺）