会计档案归档

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

# 会计档案归档

会计档案最怕的不是整理得慢，是**整理完发现对不上**：
凭证号重号、复印件当正本、附件漏了、归档后谁动过不知道。

本包只做三件实事，一件都不含糊：

1. 按 `归档/<年度>/<凭证号>/附件_NN<扩展名>` 把附件**复制**（不是移动）到位，源文件原地不动；
2. 逐文件算全量 sha256 存进清单，做「文件名 / 相对路径 / 字节数 / SHA256 / 是否命中凭证号目录」五要素归档；
3. 凭证号缺失、含 `_duplicate_` 标记、清单内重号、附件与清单附件数对不上，一律识别并进异常表，一个都不悄悄归档。

**默认不写盘**：不加 `--execute` 只给你看「将要如何组织」的目录树预览。

## 输入

| 用途 | 参数 / 可识别列名 |
|---|---|
| 凭证清单表 | 位置参数 `file`，`.xlsx` / `.csv`，一行一条凭证 |
| 凭证号 | 凭证号 / 凭证编号 / 记账凭证号 / 凭证号码 / 凭证 |
| 年度 | 年度 / 年份 / 记账年度 / 所属年度 / 会计年度 |
| 附件数 | 附件数 / 附件数量 / 附件张数 |
| 所属期间 | 所属期间 / 会计期间 / 记账期间 / 期间 |
| 金额 | 金额 / 发生额 / 凭证金额 / 借贷金额 / 合计金额 |
| 附件实体目录 | `--attach-dir <目录>`，可含子目录，递归扫描 |

凭证号列**必须有**——没有它就报算不出，本包不猜哪个是凭证号。
年度优先取「年度」列；读不到就从凭证号里找四位年份（如 `记-2026-001` → 2026）；
两边都读不到就标 `_未知年度` 并进异常表，绝不自己编一个年份出来。

## 输出

| 文件 | 内容 |
|---|---|
| `aa_归档清单_主表.csv` | 每个附件的归档路径 / 凭证号 / 年度 / 文件名 / 源相对路径 / 字节数 / SHA256 / 是否命中凭证号目录 / 动作 |
| `aa_归档清单_异常表.csv` | 凭证号缺失、重号、`_duplicate_` 标记、未命中附件、附件数对不上（带风险等级与清单行号） |
| `aa_归档清单_校验表.csv` | 归档结构、年度来源、命中规则、覆盖策略、命中/未命中数量、复制后摘要校验 |
| `fin-log.jsonl` | 处理日志（追加） |
| `aa_凭证汇总.csv` | 按凭证汇总：年度 / 期间 / 摘要 / 金额 / 清单附件数 / 实际附件数 / 附件实体清单 |

另外在 `--out-dir/归档/` 下生成真实归档目录（`归档/<年度>/<凭证号>/附件_NN<扩展名>`）。

## 用法

```bash
PY="<python 3.8+ 路径>"   # 纯标准库

# 1) 先看预览：只打印将要如何组织，不写盘
"$PY" <skill目录>/scripts/archive_build.py 凭证清单.xlsx --attach-dir ./附件库

# 2) 确认无误再真跑（复制，不是移动）
"$PY" <skill目录>/scripts/archive_build.py 凭证清单.xlsx --attach-dir ./附件库 \
      --out-dir _out --operator 张会计 --execute
```

| 参数 | 说明 |
|---|---|
| `file` | 凭证清单表（`.xlsx` / `.csv`） |
| `--attach-dir` | 附件实体目录，**必填**，不存在即拒绝 |
| `--out-dir` | 输出目录，归档根 = `<out-dir>/归档`，默认 `_out` |
| `--operator` | 操作人，写进日志 |
| `--execute` | 不加只预览；加了才建目录、复制文件 |

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

预览模式（不写盘）：

```
方案：凭证清单 aa_凭证清单.xlsx（5 行，5 个有效凭证） | 附件目录 _out/aa_附件库（9 个文件）
[预览模式] 未建归档目录并复制附件。确认无误后加 --execute 执行。

--- 归档目录树（预览，未写盘）---
归档/
├─ 2025/
│  └─ 记-2025-087/
│     └─ 附件_01.xlsx  [60 B]
└─ 2026/
   ├─ 记-2026-001/
   │  ├─ 附件_01.pdf  [61 B]
   │  └─ 附件_02.jpg  [62 B]
   ├─ 记-2026-002/
   │  └─ 附件_01.xlsx  [57 B]
   └─ 记-2026-003/
      ├─ 附件_01.pdf  [62 B]
      ├─ 附件_02.pdf  [62 B]
      └─ 附件_03.pdf  [59 B]
  （共 2 个年度 / 4 个凭证 / 7 个附件）

[预览模式] 将新建 7 个文件、4 个目录，确认无误后加 --execute
```

执行模式（`--execute`）：

```
方案：凭证清单 aa_凭证清单.xlsx（5 行，5 个有效凭证） | 附件目录 _out/aa_附件库（9 个文件）

--- 归档结果 ---
  复制 7 个附件 | 新建 4 个目录 | 命中 7 | 未命中 1 | 覆盖冲突 0
  [高] 记-2026-005_副本_duplicate_：凭证号含「_duplicate_」标记，可能是重号/复印件，需人工确认后再归档
  [中] misc/待归类扫描件.pdf：附件实体未命中任何凭证号目录（附件命名与凭证号对不上，或该凭证号本身缺失/重号）
  [高] 附件1.pdf：凭证号重复或含 _duplicate_ 标记，未生成目标路径
  [高] 待归类扫描件.pdf：未命中凭证号目录

已生成凭证汇总：aa_凭证汇总.csv（5 个凭证）
--- 校验表 ---
  命中凭证附件 | 7
  未命中附件 | 1
  _duplicate_/重号凭证数 | 1
  已复制文件 | 7
  新建目录数 | 4
  覆盖冲突数 | 0
  复制后校验一致 | 7 / 7
```

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

| 情况 | 处理 |
|---|---|
| 凭证清单文件不存在 | **直接拒绝**：「找不到凭证清单」 |
| 没传 `--attach-dir` | **直接拒绝**：「本包不知道附件实体在哪里」 |
| 附件目录不存在 / 不是目录 / 目录为空 | **直接拒绝**，出不了归档清单 |
| 凭证清单里没有凭证号列 | **直接拒绝**，归档目录无法命名 |
| 凭证号缺失（空值） | 进异常表（高），该行不产生归档目录 |
| 凭证号含 `_duplicate_` 标记 | 进异常表（高），识别为疑似重号，附件**不复制**，等人工确认 |
| 凭证号在清单里重复出现 | 第二条进异常表（中），只归档第一条 |
| 年度缺失且凭证号里读不出年份 | 进异常表（高），归入 `_未知年度` |
| 附件实体命中不了任何凭证号 | 进异常表（中），清单里标「未命中」，不复制 |
| 归档目标已存在同名文件 | **直接拒绝并列出全部冲突**，一个字节都不写 |
| 复制后 SHA256 与源不一致 | **直接拒绝**，不给未经校验的归档结论 |

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

1. **复制，不是移动**：附件实体留在原处，归档是副本。源文件被挪走就再也复核不了了。
2. **归档根在 `_out` 里**：`归档/` 建在 `--out-dir` 下，源文件目录一个字节都不动。
3. **命中规则**：路径段或文件主名「去掉 `-` `_` `.` 空格等分隔符号后」与凭证号相等，
   或取其开头连续字母数字段与凭证号相等（这样 `记-2026-001` 目录能认出凭证号 `2026-001`）。
   认不出来就进异常表，**不硬套、不就近塞进别的凭证**。
4. **附件编号**：同一凭证内按源相对路径排序，编号为 `附件_01` 起，保留原扩展名。
5. **覆盖即停**：先扫全部目标再动手，发现有同名文件就整单拒绝——不做「覆盖一部分」这种半吊子结果。
6. **摘要双算**：复制完重新读目标文件算 sha256，与源比对；不一致直接 refuse。
7. **本包不管归档后的保管期限、调阅、销毁**：那是《会计档案管理办法》里另一套流程，本包不做判断。

## 人工复核（必读）

- 重号 / `_duplicate_` 的凭证，**本包已停在你这里**，人工确认前不要放行
- 「未命中凭证号目录」的附件，通常是命名与凭证号对不上（如附件名没带凭证号），需人工归类
- 清单「附件数」与实际命中数对不上，说明可能漏扫或漏登记，以附件实体为准再补清单
- SHA256 只证明「复制后没被改动」，不证明附件内容本身正确（如传错了一张发票，哈希照样一致）
- 归档目录建在输出目录里，不要把输出目录指到附件原件目录，否则等于就地覆盖

## 相邻路线转交

| 用户要做的事 | 转交给 |
|---|---|
| 凭证号是否重号 / 分录平衡校验 | `accounting-entry-check` |
| 凭证批量生成 | `voucher-batch-generate` |
| 附件 PDF 文字提取与核对 | `invoice-pdf-extract` |
| 发票重复报销、重复票核对 | `invoice-duplicate-check` |
| 账套备份与可恢复性验证 | `book-backup-verify` |
| 归档目录里按凭证查操作记录 | `audit-trail-view` |

## 可直接复制的说法

```text
把这张凭证清单和附件库按年度-凭证号归档，目录结构用
归档/<年度>/<凭证号>/附件_NN，附件是复制不是移动。
每个附件都要记文件名、相对路径、字节数、SHA256，以及是否命中了凭证号目录。
凭证号缺失、凭证号里带 _duplicate_ 的、清单里重号的，全部标出来进异常表，
这些先别归档，等人确认。
目标位置已经有同名文件就别覆盖，把冲突列给我。
先给我看预览，确认了再加 --execute。
```

## 做完怎么算完成

- [ ] 预览的目录树已与业务上的归档口径核对（年度 / 凭证号层级一致）
- [ ] 重号 / `_duplicate_` 的凭证已逐条人工确认，确认结论已回写清单
- [ ] 「未命中凭证号目录」的附件已查明去向，没有遗留
- [ ] 异常表逐条追到底，无「未说明原因的缺失」
- [ ] 附件原件仍在原位，未被移动或删除
- [ ] 「复制后校验一致」为 N / N，无遗漏
- [ ] 归档目录在约定的保管介质 / 位置已妥善转存

---

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

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

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