偿债日历

概述

个人与家庭多头借贷的账单整理与还款规划工具。把分散在银行 App、网贷平台、亲友之间的借款，整理成一份可核对、可打印、可导入日历的还款计划。

版本：v1.5.2

一句话：把银行借款与网贷账单整理成一份可核对的报表——每笔剩余待还、每月应还金额、每日还款日历。

定位：OCR 辅助的借款账单整理工具。OCR 只负责提取文本，机构、金额、期数、还款日由使用者核对后录入；不是「截图导入即自动生成日历」的端到端工具。

计算原则：看不清的数字不推测 · 以剩余待还为口径而非借款总额 · 看板与日历必须同源同值。

一、能做什么

• 摘要：三块核心信息——下一笔还款（日期、机构、金额、剩余天数）、本月应还、剩余待还（本息）。存在逾期时，逾期卡置顶并显示逾期笔数、金额与最长逾期天数。
• 日历：按月的日历视图，每日应还金额直接标注在日期格内，不做单位缩写。默认展示 3 个月，可在页面内展开全部。
• 看板：借款明细（可排序、筛选、搜索）与逾期明细（按序号列出并给出合计）。
• 状态：待还、已还、逾期三类状态用固定色系区分，颜色只承载状态，不承载金额大小。
• 类型：等额分期、一次性到期、期末一次性还本（气球贷）、循环额度（随借随还）四类，在同一张表内表达。
• 核销：按整月标记，或按「第几期、实还多少」的逐期记录精确核销；核销只冲减对应期次，不覆盖原始计划。
• 应收：别人欠你的钱单列一张表，不混入负债合计。
• 导出：HTML 报表、ICS 日历提醒（每个还款日两个提醒）、可选 CSV 明细，支持打印与另存 PDF。
• 移动：640px 以下单列排版，表格转卡片，日期格金额不溢出。

技术形态：Python 3 单文件引擎，无第三方运行时依赖，无数据库。输出单文件 HTML，无外部资源、无网络请求，双击即可查看。

二、产品优势

1. 口径统一：日格、月卡、看板、合计使用同一套计算结论，不存在「两个页面两个数」；计算核心与展示层分离，界面变化不影响数值。
2. 只算剩余待还：以未来实际现金流为准，不用原始借款总额充当负债规模，避免高估。
3. 宁可报错，不静默归零：缺还款方式、期次与金额对不上、末期还本额漏填导致现金流明显偏低，均直接终止并给出填法，不生成一份看起来正常、实际少算的报表。
4. 数据不出本机：无账号体系、无云端存储、无埋点，报表文件只写在使用者指定的目录。
5. 零部署：单个 HTML 文件即可分发与归档，不需要安装客户端，也不依赖网络。
6. 可验证：246 项冒烟测试覆盖计算口径、字段校验、边界输入与产物结构，改动可回归。

三、怎么用

方式一 · 通过 AI 助手（推荐）：把账单截图、Word 表格或文字清单交给已加载本技能的助手，助手调用本地 OCR 提取文本、逐条列出「机构、剩余期数、每期金额、还款日」供核对，确认后生成报表与日历文件。首次导入会先输出一张待确认清单，未确认项不会直接计入确定金额。

方式二 · 命令行：

python scripts/build_report.py --init-template        # 生成空白清单模板
python scripts/build_report.py 借款清单.csv            # 用 Excel 填好后生成报表

方式三 · 示例预览：运行 build_report.py --demo，不读取任何输入文件，使用内置示例数据生成一份带「示例」标记的报表，用于先确认界面效果再录入真实数据。

参数：

数据模式自动判定：未指定 --real 或 --demo 时，按输入文件名判断——含「示例」「模板」或位于 examples/ 下为示例模式，其余一律按真实模式处理。理由是示例被误判为真实只会多一行提示，真实负债被误判为示例则可能导致误公开。程序会打印判定结果。

四、适用范围与边界

• 适用：个人或家庭的多头借贷台账——银行贷款、消费金融、网贷平台、亲友借款、循环额度。共同特征是「有多笔、有期数、要按月还」。
• 不处理：投资账户、信用卡消费明细（非借贷）、企业资产负债表。
• 静态快照：报表与日历文件生成后不会自动更新。还款后需重新生成、重新导入；当月已还的月份仍会以绿色「已还」显示，跨月重跑后才会移出窗口。--paid 标记的手工剩余本金值不随扣减，需使用者自行更新。
• OCR 是辅助提取：只输出文本，不自动识别机构、金额与还款日，结果必须逐条核对确认。
• 计算范围：不含罚息、手续费与违约金；循环额度的未来新增利息不计入；短月还款日按月末顺延处理，是程序的保守假设，不代表各机构实际规则。
• 金额以确认值为准：工具不与任何借款平台核对数据，所有数字需使用者确认。
• 隐私：真实模式报表含完整负债信息，页脚会显示提示。请勿上传至公开仓库、群聊或第三方网盘；归档时建议加密。
• 不构成金融、法律或债务建议，不建议作为唯一还款依据。
• .doc 老格式提取为实验性功能，复杂文档可能乱序，建议转 .docx 或使用截图。

执行规范（Agent 专用）

以上为产品说明。以下为加载本技能后的执行规范，全部分节均为强制要求。

五、触发与输入

• 触发词：借款整理、还款日历、贷款汇总、负债分析、还剩多少要还、每月还款、还款提醒
• 输入：.doc/.docx（内嵌多张截图最常见）、.csv（推荐）、.xlsx（需 openpyxl）、用户粘贴的文字清单
• 不处理：投资账户、信用卡消费明细（非借贷）、企业资产负债表

六、工作流（5 步）

1 · 提取文档文本

• .doc（老格式）：用 scripts/doc_text.py（olefile 读 WordDocument 流，整段按 UTF-16LE 解码；不要写死字节切片，会截断）。
• .docx/.xlsx：按 XML/ZIP 解析或 openpyxl。
• 截图是二进制内嵌，文本提取拿不到数字，必须走步骤 2。

2 · OCR 截图（绝不可跳过）

⚠️ 模型"看图"读数字会编造 —— 截图数字一律走 OCR。

⚠️ OCR 只是"提取"不是"确认"：提取后逐条与截图核对、交用户确认再入表。

• 工具 scripts/ocr_extract.py（系统 tesseract CLI + chi_sim/eng；没装时脚本给安装指引）。
• 畸形图：先用 Pillow 转 PNG 重试一次；仍读不出 → 单独列出让用户确认，不猜。
• 常见串字 3↔5、6↔0、8↔9、1↔7，小数点易偏移；金额多/漏一个零是高频错误 → 用「每期 × 期数」反推校验，偏差 >5% 标存疑（5% 只能拦大错，最终以用户核对为准）。详见 references/ocr_guide.md。

首次导入确认（强制，v1.4.7）

解析/OCR 结束后不要直接生成报表，先在对话里弹一张「待确认」确认卡：

待确认（3 项）
1  示例消金②  10月15日  ¥1,700.00   金额/期次 OCR 存疑
2  示例网贷A   11月7日   ¥3,000.00   还款日截图模糊
3  示例银行①   2027年6月  ¥150,000.00  末期还本额需确认
回复「1 确认 / 2 改成 3000 / 3 删除」即可

• 用户确认的项目 → 置信度=OK，正常入表；改金额/日期的 → 更新后重新校验；删除的 → 移出清单。
• 用户全部处理完才生成报表；首次生成的页面不应残留「待确认」标记（用户明确说"先这样"除外）。
• 后续用同一份清单重新生成时不再重复弹确认卡；只有新增账单或重新导入时才再次确认。
• 用户没逐项回复、只说"就这样" → 未确认项保留 存疑，并在生成前明确告知"这几笔会显示待确认"。

3 · 整理成结构化清单（先判类型，再填字段）

⚠️ 必须按用户截图判断类型，不可预设某平台一定是随借随还 —— 显示"剩余 X 期 / 每期 Y 元"的多数有固定还款日，应填 schedule + day 进日历。

分期类：schedule（每期列表）与 per+remain_terms 二选一，都不给 → 报错终止，不静默算成 0。

随借随还类（仅当截图明确显示"随借随还 / 无固定还款日 / 按日计息"时才用）：

4 · 按"剩余待还"算（不是借款总额）

例：原借 41,000，剩 4 期每期 3,660 → 剩余待还 14,640，不是 41,000。

三类互斥状态，日格 / 月卡 / 看板 / 窗口合计同一套口径：

• 确定：未还且已确认 → 页面主数字
• 待确认：conf=存疑 → 以「＋¥Y」并排显示，绝不混入确定额；单独成日时显示存疑额并打 ?。这是首次导入确认卡的兜底：用户跳过或没确认的项目才走这里，正常情况下首次生成不应残留。
• 已还：--paid 标记的整月，绿色标注
• 剩余本金：纯本金（气球贷 remain_override、随借随还 remain_principal；等额分期反推不出时标「待确认」）

两个合计必然同源同值：看板「剩余待还(本息)」＝未还各期之和（含息）＝ 底部「窗口内未来还款合计」；END_MODE="fixed" 未覆盖的部分，页面给出对账说明（差多少、差在哪）。月均给两个数：「日常月均」剔除末期一次性大额，「含末期月均」保留原始均值，避免末期一笔把均值拉爆。

⚠️ 脚本强制校验（防静默算成 0）

未标 repaid=True 的借款必须满足三选一，否则 ValueError 终止：

① 分期 day +（schedule 或 per+remain_terms）　② 一次性 due + 金额　③ 随借随还 remain_principal。

• 空 schedule=[] 不算有效结构；已结清请显式写 repaid=True。
• schedule 逐项校验：必须有限、非负（拦 None/字符串/负数/NaN/inf）；type 必填。
• 冲突也报错：day+due 同时填、schedule 与 per×remain_terms 不一致、手写 schedule 与 final_date 的末期月对不上、repaid=True 却仍有金额。
• 漏填末期还本（现金流 < 剩余本金 50%）→ 报错并给填法，绝不静默少算。
• ICS 与 HTML 严格同窗口，每事件带 DTSTAMP + 两个 VALARM（提前 1 天、前一晚 21:00）—— 文件侧已合规，但是否响铃取决于用户日历 App 的导入方式与通知权限，别向用户承诺"一定会响"。

4.5 · 已还款怎么更新

报表是静态快照，不会随时间变；"消隐"靠重新生成脚本。

• 还了几期未结清 → 把已还月加入 PAID_MONTHS（该月标「已还」、合计同步扣减），或把 first_ym 顺延并缩减期数；整笔保留。

当月已还的月卡仍会显示（绿色「已还」），跨入次月后重新生成报表，该月才从窗口移除 —— 用户问"我还了怎么还显示"时，说明这是设计如此，不是 bug。

• 整笔结清 → 写 repaid=True（不要只清空 schedule）。
• 用户说"某笔不存在 / 已销账" → 直接删除。
• 每次改完重算并告知新的剩余合计与月均，让用户确认变化合理。

5 · 生成报表

python scripts/build_report.py --init-template              # ① 先出 借款清单模板.csv（Excel 填好另存 CSV，零依赖）
python scripts/build_report.py 借款清单.csv                  # 出报表（模式自动判定，见下）
python scripts/build_report.py 借款清单.csv --real           # 强制真实数据模式（页脚隐私提示、文件名不带"示例"）
python scripts/build_report.py 借款清单.csv --demo           # 强制示例模式（文件名带"示例"、页脚不出现真实负债提示）
python scripts/build_report.py 借款清单.csv --paid 2026-09   # 整月标记已还（可逗号分隔多月）
python scripts/build_report.py 借款清单.csv --out DIR --csv  # 指定输出目录 + 导出明细 CSV
python scripts/build_report.py 借款清单.csv --payments 还款记录.csv   # 逐期还款记录（哪几期还了、还多少）
python scripts/build_report.py --init-payment-template                # 出 还款记录模板.csv
python scripts/build_report.py 借款清单.csv --receivable 借出应收清单.csv   # 附带「借出应收」（别人欠我的钱）
python scripts/build_report.py --init-receivable-template     # 出 借出应收清单模板.csv
python scripts/build_report.py --demo                       # ② 不给 CSV：跑脚本内置示例数据（仅演示）
python tests/test_smoke.py                                  # 冒烟测试（246 项，应输出 ALL PASS）

数据模式（真实 / 示例）怎么定：不写 --real / --demo 时程序按输入文件名判定——文件名含「示例」「模板」，或路径在 examples/ 下 → 示例模式；其余一律按真实模式处理（宁可把示例当真实，也不让真实负债被当成示例公开）。不确定就显式写一个，程序会打印判定结果。

实际还款记录（可选，解决「只还了部分 / 只还了某几期」）：--paid 只能标整月，要精确到"哪一笔的第几期、实还多少"就用 还款记录.csv。CSV 列（7 列）：机构 / 期次 / 应还日期 / 实还日期 / 实还金额 / 状态 / 备注。

• 期次从 1 起，按该笔还款顺序数（与页面月历里从上到下的期次一致）
• 状态填 paid（已还清）/ partial（部分还）/ uncertain（金额存疑）
• 计划与实还分开记账：实还只减少该期余额，不覆盖计划金额
• 同一期重复登记、期次超出该笔期数、机构名对不上 → 都直接报错，不静默吞掉
• 已还记录保留；改金额直接改那一行，删行即撤销
• 没有这个文件时完全走老逻辑，老 CSV 一行不用改
• 逾期判断：应还日 < 今天 且 该期剩余 > 0（只陈述事实，不给催收建议）

借出应收（可选，方向与负债相反）：别人欠我的钱单列一张表，绝不混入任何负债合计。CSV 列（6 列）：借出对象 / 借出本金 / 尚未收回 / 借出日 / 约定收回日 / 备注。--receivable 每跑一次覆盖上次；本次不传该参数则应收板块不显示。

CSV 列（19 列）：机构 / 类型 / 还款方式（留空自动判断）/ 每期金额 / 待还期数 / 每月还款日 / 到期日 / 借款本金 / 剩余本金 / 已计利息 / 最后还款日 / 末期还本额 / 末期日期 / 首期年月 / 利率 / 借款时长 / 已还期数 / 置信度 / 备注。金额里的 ¥、千分位、空格自动清掉。

「首期年月」= 固定这笔计划的起点（如 2026-10）。填了它，以后换月份查看时计划不再整体后移——长期维护同一份台账时每笔都应该填。不填则计划从"运行当月"展开，跨月重跑会往后挪（页面会提示风险）。

气球贷一行搞定（每月只还息、到期一次性还本）：「每期金额」填月息 +「每月还款日」照填 +「末期还本额」填本金 +「末期日期」填到期日（如 2028-05-27），不用拆两笔；「待还期数」留空，脚本自动从当月推算。末期那期 = 月息 + 还本，日历上是单独的大额事件。

随借随还没有还款日：「最后还款日」留空，只填「剩余本金」即可，本金在看板下方提示，不会消失。

产出：借款还款总览.html + 借款还款日历.ics（示例模式文件名带 _示例）。页面自上而下：首屏（下一笔还款主卡 + 本月应还 + 剩余待还；有逾期时红卡置顶）→ 日历 / 看板 / 说明三个并列标签（默认日历；日历默认显本月+后两月，可展开全部）→ 页脚（数据截止 + 意见反馈入口）。看板分「借款明细」「逾期明细」两块；随借随还并入借款明细、显示为「无到期日」，计入合计但不进日历。

七、避坑清单

1. 截图一律 OCR，绝不靠模型看图编数字。
2. 按剩余待还算，别用借款总额（用户最常纠正的点）。
3. 先判类型再填字段：有"待还计划"的按固定分期处理。
4. 存疑就问，不替用户删/留任何一笔。
5. 缺结构就报错，不许静默算 0。
6. .doc 只当实验性（可能乱码/错序），建议转 .docx 或走截图 OCR，提取后必人工核对。
7. 中文路径注意 UTF-8 编码。

页面样式与移动端适配由 scripts/build_report.py 实现，改样式直接改脚本。

用户反馈入口：页面标题行「意见反馈」与页脚「反馈问题」→ 飞书表单（公开，不携带个人数据；表单地址由 FEEDBACK_URL 配置，留空则页脚隐藏入口）。表单打不开时可发邮件至 hasconvar@163.com（附「版本号 + 复现步骤 + 实际 vs 期望」能一轮定位）。

许可协议：MIT。