记账软件 · Budget App v3.7.2

Personal Budget Tracker — Zero-dependency single-page HTML app. Fully offline, runs entirely in your browser.

---

📸 Screenshots

Screenshots coming soon. Open index.html in your browser to see the app in action.

---

📖 Brief Description

记账软件 · Budget App is a personal budget tracking tool designed for everyday use. It stores all your records, categories, budgets, and savings targets entirely in your browser's localStorage — no server, no sign-up, and by default no data leaves your machine (an opt-in, end-to-end-encrypted cloud sync lives in Settings and does nothing until you turn it on). Packaged as a single offline HTML file with zero external dependencies, it is ready to run the moment you open it in a modern browser.

---

🤖 AI 生成声明

本项目的全部代码（HTML / CSS / JavaScript）均由 AI Agent（大型语言模型）生成、审查、修改和完善。

作者（即仓库所有者）的角色仅限于：

• 整体功能设计与规划
• 功能验证与测试
• UI 与交互审美的反馈和决策
• 项目方向把控

作者不具备专业软件开发背景，本项目为个人学习和日常使用目的而创建。公开此项目的目的是分享设计思路和展示 AI 辅助开发的可行性，而非提供专业级软件解决方案。

---

⚠️ 免责声明

请在使用本软件前仔细阅读以下条款。使用即表示您理解并同意以下内容。

1. AI 生成代码风险

本软件的全部代码由 AI Agent 自动生成，未经传统人工安全审计和专业代码审查。可能存在但不限于以下问题：

• 未知的软件缺陷或逻辑错误
• 安全漏洞或数据泄露风险
• 边界情况（edge case）未覆盖
• 代码风格不一致或潜在的性能问题

请在使用前自行评估风险，尤其涉及重要数据时须谨慎。

2. 计算准确性不担保

本软件中的所有数学计算（包括但不限于预算汇总、储蓄预测、预算使用率、统计图表数据、月度报告等）均不保证绝对真实性和准确性。所有数据仅供个人参考，不应作为任何财务决策的唯一依据。

3. 非财务建议

本软件不构成任何形式的财务、税务或投资建议。如有专业财务管理需求，请咨询持牌财务顾问、会计师或相关专业人士。

4. 不合规声明

本项目不符合任何财务 / 会计行业合规标准、审计标准或监管要求。不适用于需要合规认证的业务场景。

5. 数据存储安全

• 所有数据以明文形式存储在浏览器 localStorage 中，不提供加密保护
• 可选的 PIN 锁只在「锁定」状态下把账本加密保存（PBKDF2 + AES-GCM），用来防止别人拿起设备直接翻看；解锁期间账本仍是明文。4–6 位数字 PIN 的组合很少，挡不住拿到这台浏览器存储数据的人离线逐个尝试，不要把它当作强加密
• 虽然设计上以本地存储为框架且经过了 AI Agent 的代码审查，但因代码由 AI 生成，仍不保证数据绝对不外泄
• 请勿在本软件中保存任何关键、敏感或涉密信息
• 若你开启可选的「云端同步」：账本在本机用 AES-GCM-256 加密后才上传，服务器只看到密文；但恢复码和一份账本副本会以明文保存在本机（所以云端同步与 PIN 锁互斥）。这套加密实现同样由 AI 编写，未经专业密码学审计
• 云端后端是一个固定的 Supabase 项目，其地址与「公开 key」写在开源代码里；数据表对外全部锁死（行级安全 RLS 全开、零策略），只能通过 5 个凭密钥访问的函数读写。丢失恢复码 = 云端那份无人能解开（包括作者），本机数据不受影响

6. 数据丢失风险

• 清除浏览器缓存、Cookie、站点数据或历史记录将永久删除所有记录与设置，且无法恢复
• 数据默认仅存在于单一设备上。局域网同步与可选的云端同步能在设备间复制数据，但同步不是备份——它会把改动（包括删除）传给其他设备
• 用户须自行定期通过「设置」页面的 JSON 导出功能备份数据

7. 无担保

本软件按「原样」（AS IS）提供，作者不作任何明示或默示的担保，包括但不限于适销性、特定用途适用性和不侵权的担保。

8. 责任限制

在任何情况下，作者均不对因使用或无法使用本软件而产生的任何数据丢失或财务损失承担责任，即使已被告知此类损失的可能性。

9. 使用者责任

• 使用者应自行评估风险
• 使用者对自身的数据安全和财务决策负全部责任
• 使用者应自行验证所有计算结果

---

✨ Features

📊 总览 Overview

Monthly spending summary with budget and savings progress rings rendered on Canvas. Includes a 7-day spending sparkline, top 5 spending categories, overspend warnings, and a savings prediction engine that supports dual daily limit calculations.

✏️ 记账 Add Record

Quick entry with an expense / income switch, automatic RM currency prefix, a tree-based category picker (emoji + color), date/time fields, and notes. Input validation with shake animation feedback.

💰 收入 Income

Money coming in gets its own half of the ledger. Pick 收入 on the add or edit form and the picker switches to an income category tree — seeded with 工资（月薪 / 奖金 / 加班津贴）、副业（接单 / 卖闲置）、报销退款、理财收益、其他收入, all editable like any other category. Income never touches a spending number: daily averages, category charts, budgets, overspend warnings, heatmap and What-If all keep counting expenses only. What it does feed is the other half — the overview, statistics and report each gained an income / spending / net row, the six-month trend chart gained a green income line, and income rows show green with a leading + in the ledger. Recorded income is deliberately kept separate from the 月收入 setting, which stays a per-month declaration that drives the budget chain.

📋 流水 Records

Advanced multi-filter system supporting keyword, category, date range, amount range, overspent-only and 支出 / 收入 type filters. Multi-level sorting (by date, amount, note, or category name). Toggle between compact and card views. Batch operations for delete and recategorization. Soft delete with a 5-second undo window.

🗂️ 分类 Categories

Infinite nesting tree with accordion UI, split into a 支出分类 and a 收入分类 tree. Set per-category budgets in RM or percentage on expenses; income rows show what actually arrived this month instead — there is no such thing as overspending your salary. Inline budget editing with parent-child budget validation. Merge categories, move nodes with cycle detection, pick from 14 preset colors, and choose emoji icons. Merging and moving never cross the two trees, because that would silently re-type every record underneath.

Reorder with ⬆️ / ⬇️ on every row — roots and subcategories alike, greyed out at the ends of the list. The order lives on the category (sortOrder), so it is part of the ledger, travels through cloud sync and LAN sync, and the other device pulls it already in the order you set. Reordering never renumbers across the two trees, and the whole sibling list is renumbered 0..n-1 so two devices can't end up rendering the same data in different orders.

🔍 选分类 Pickers

Every "pick a category" surface — new record, edit record, the records filter, batch recategorisation, and the merge/move target pickers — is the same component: collapsed by default, opened one branch at a time with the same ▶ affordance as the categories page, plus a search box. Typing a category name or an emoji filters the tree, force-expands every ancestor so the hits are actually visible, counts the hits on each ancestor row, and highlights the matched run. Expansion is remembered for the session, so drilling into 餐饮 › 午餐 to set a budget does not have to be redone on the next record. Clicks are handled by one delegated listener, so no category id is ever interpolated into an onclick attribute.

📈 统计 Statistics

Interactive Canvas charts — elastic animated pie chart with hover pop-out and full drill-down (switchable to a waffle grid where one block = a fixed amount, or a nested treemap where area = spend and boxes nest to show the category hierarchy), animated line chart, bar chart with drill-down, and a calendar heatmap with 6-color gradient. Month-over-month comparison, 6-month trends, and a dedicated savings chart. All charts downloadable as PNG. Custom date range analysis included.

📄 月度报告 Report

Print-optimized monthly summary featuring budget and savings rings, a category breakdown table, a spending sparkline, and natural language savings prediction.

🔮 假设分析 What-If

Adjust future spending assumptions per category with modes: keep trend, set daily limit, fix remaining total, percentage change, adjust by amount, or zero out. Compare projections against current trends with visual savings bars and ring charts. Supports hypothetical new categories and global adjustments.

🧾 分摊收款 Split Bills

Mark a record as a split bill, pick who was in on it, and let the total divide evenly or by amounts you set per person — including "amount unknown" for anyone whose share isn't settled yet, yourself included. The Collection Center tracks who still owes what, by person or by bill. Repayments are amounts, not checkboxes: tick for a full settle, or record a partial. One lump sum can clear several bills at once — select bills (all / none / invert) and spread the money evenly, oldest-first, or by hand, with a live preview before anything is written. Settled bills can be archived or converted into a plain record.

💳 大额分期计划 Purchase Plans

Plan a large purchase in three modes: save up first (先攒后买), buy now and repay (先买后还), or a credit-card instalment (信用卡分期, which backfills real repayment records). The monthly instalment is deducted from your spendable budget, and the ledger is replayed month by month rather than stored — so skipping a month or editing an old record recalculates automatically. Overdue plans prompt to extend, pay off, or abandon. Custom emoji icon per plan.

⚙️ 设置 Settings

Dark/light mode toggle, monthly budget configuration, 2-mode savings target (fixed amount or percentage). Export and import data via JSON (replace or merge), CSV, or Excel (XML Spreadsheet 2003 with 7 sheets and live formulas). Clear all data option available. LAN sync via WebRTC (same Wi-Fi, zero server). Optional cloud sync (off by default): no account — one recovery code; the ledger is encrypted on your device before upload; edits made on several devices are merged record-by-record instead of overwritten; the last few cloud versions are kept.

📱 手机版 Mobile Companion

轻量级手机专用版本 money-wise-mobile.html，支持完整的记账增删改查、分类管理、JSON 导入导出。 适合在手机上快速记录，导出 JSON 后在主应用导入。单 HTML 文件，零依赖。

v3.7.2 合并分类的确认按钮（小版本，无公告）

• 🔀 按钮写明合并到谁、不再莫名变灰：选好目标后，确认按钮以前只写「合并到」，看不出选的是谁；选好后再点别的分类的展开箭头或在搜索框打字，按钮还会变回灰色的「请先选择目标分类」（内部其实还记着目标）。现在按钮写成「合并到 🛒 购物」，展开、搜索之后也保持可点。分类名从分类库里取，不再依赖选择器传来的参数（它传的是 (id, arg, label)，旧的 selectMergeTarget(catId, displayName) 把第二个参数当名字，所以名字一直是空的）；openCatTreeModal 新增可选的 afterRender 钩子，每次重画页脚后由合并框重新同步按钮。回归网：tests/merge-category-test.js。

v3.7.1 全面查错后的一批修复（小版本，无公告）

一轮深度审计（计算、日期、措辞、安全）找出的问题，按"先止血、再核心数字、最后分摊与计划"修了三批，每条都先写会失败的测试再改。逐条编号、位置与验证方式见 audit-report/PROBLEMS.md（本地文件，未入库）。

• 🛡 数据安全：导入 / 云端 / 局域网同步来的名字、标签、备注不再被当代码执行，含撇号的名字也不会让按钮失灵；本地账本 JSON 损坏时先备份原文再提示，不再被空账本覆盖；替换导入遇到畸形文件会拒绝，导入的记录会校验金额和日期；多个窗口同时记账不再互相覆盖；云端返回的 version 会校验。合并分类时选自己的子分类不再卡死。
• 📅 日期与时间：自定义日期范围不再漏最后一天；凌晨 0–8 点的「今日 / 昨日 / 近 7 天 / 近 30 天」不再错一天；清空日期框保存不再记到 8 小时前；每月 1 号收入不再掉成 0；统计页剩余天数、报告页和假设分析在近 30 天模式下的表现、流水页近 30 天窗口都按真实日期算。
• 🔢 数字对得上：报告页已付账单不再重复算；假设分析的基数不再带上「不计日均」和分期；账单类分摊里他人的份额不再被错扣；分类预算设成百分比时按金额比较；Excel 导出的公式重新算对；总览和统计页的「累计已存」改叫「本月还剩」，「含固定账单」开着或关着都是同一个数。
• 🧾 分摊与计划：「一次性补齐」真的补齐；编辑信用卡分期计划后旧流水会跟着重写（注意：这些分期流水会换新 id，手动改过的内容会被覆盖）；分期的分类下拉不再出现收入类；记账页分摊切回均分后不再沿用隐藏的金额；编辑分摊账单改总额时，已结清的人按已还金额算；合并导入不再丢掉本机同月的账单金额（同一项两边都设了仍以导入文件为准）。
• 🖱 流水与统计页：「在流水页查看」只显示该分类本月的记录；编辑流水时选分类不再还原已改的金额和备注；自定义范围下的饼图 / 格子图不再是空的，下钻数字和第一层对得上；卡片视图批量选择不再弹出编辑框，上下滚动不再误触左滑删除（触摸部分只用模拟事件测过，没在真机上试）。
• 🧪 测试：新增 batch1-fixes-test.js、batch2-dates-test.js、batch3-fixes-test.js、calc-consistency-test.js、xlsx-formula-test.js、xlsx-export-test.js、bill-group-drill-test.js；savings-forecast-test.js 等旧测试按新名字和新数字同步。

v3.7.0 预测更准、总览数字对得上（中版本，带公告）

• 🎯 「预计结余」≠「预计储蓄」：总览目标环写「预计存 RM98」而大额计划中心是 0——两个不同的量共用了名字。预计结余 = 月收入 − 预计月末支出（已包含还没付的月账单，还没扣大额计划）；预计储蓄 = 预计结余 − 存 / 还类计划预计拿走的部分（结算瀑布还债优先，余下的才算储蓄）。储蓄目标在 getSpendablePlan 里与大额计划是各自独立扣掉的预留，所以目标只能拿预计储蓄去比。新增 StatsEngine.getSavingsForecast(month) 返回 {surplus, planReserved, free, unpaidBills}（unpaidBills 只用于展示，已在预计支出里），总览 / 统计 / 报告 / 假设分析统一调它；PlanMath._allocate 抽出瀑布，getForecast 与 PlanMath.afterPlans(month, surplus) 共用，所以计划中心和各页的预计储蓄必然相等。有大额计划时目标环下多一行小字「预计结余 X − 计划存 / 还 Y」；信用卡分期的记录已在预计支出里，不会再从结余里扣第二次；假设分析的假设列用它自己的结余重算瀑布。没有大额计划时两个数相等，页面和以前一样。界面用语一律用大白话：「预计结余」→「月底预计剩余」、「预计还款」→「本月计划预计付出」、「预计月末支出」→「月底预计总花费（含固定账单）」，预测明细写「月账单 ＋ 信用卡分期 ＋ 大额消费 ＋ 日常消费预估」，不出现「外推 / 趋势 / 瀑布」这类词。
• 📈 预测里的账单不再外推，没付的月账单也算进来：getPredictedMonthEndTotal / getPeriodPredictedMonthEndTotal 以前把已付账单当「每天花一点」按日均放大（3 号付 RM1000 房租，13 号预测里变 RM2400+），而月账单中心里设了金额、还没付的部分根本不在预测里（用户点「含固定账单」只看到大额数字在变，月账单一直没算）。现在按「含固定账单」开关自己对「固定」的定义拆成五个互不重叠的部分（_predictParts）：bills 账单分类流水、billsUnpaid 月账单里计划了但还没付的（计划 − 已付，不为负）、instalments 信用卡分期流水（带 planId）、large 其余的不计日均大额、normal 日常消费（只有它按日均外推）；之和恒等于预测数，关掉开关恰好少掉前三项。没付的月账单既然已在预测里，所有「收入 − 预测 − 未付账单」的地方（储蓄预测、计划中心、假设分析）都不再额外减一次，数字与以前一致，只是口径统一。明细行写「月账单 ＋ 信用卡分期 ＋ 大额消费 ＋ 日常消费预估」。
• 📝 措辞与口径小修：统计页「当前已存」→「累计已存」并扣未付账单（596e6ca 的决定，统计页漏了）；近 30 天模式下统计 / 报告的储蓄预测不再是「收入 − 近 30 天已花」，与总览一样取当月预测（规则 #11：储蓄口径始终是月）；取消「含固定账单」后总览预测卡改叫「预测月日常支出」；目标环在预测阶段不再写「已达成目标」而是「预计可达成目标」，达成率不再出现负数；环里的「预计存」改「预计储蓄」，避免和图表里计划块的「（预计存）」撞名；计划中心「预计月末支出」标明含固定账单并补一行公式。新增 tests/savings-forecast-test.js（73 条，固定时钟，变异逐一验证会失败）。
• 👆 预测卡片可点切换：总览「预测月总支出」整张卡片是「含固定账单」的开关（toggleOverviewBills），卡片上用胶囊写明当前状态（✅ 含固定账单 / ⬜ 不含固定账单）和「点一下改成…」；和预算进度卡片上的勾选框是同一个设置，两处互相同步，勾选框现在也会刷新上面的卡片（以前只重画圆环）。预测明细里数额为 0 的部分（如「已付账单 RM 0.00」）不再显示，只剩一项时整行隐藏；关掉固定账单后「本月总支出」下不再出现负数的「日常净支出」。

v3.6.7 分类图：下钻和看明细不再挤在同一次点击里

• 👆 点色块 = 下钻，看明细 = 点表格行：以前点饼图 / 格子图 / 矩形图（含展开弹窗）的色块，会同时弹出明细弹窗并下钻，背后的图在弹窗下面已经换了层级。现在色块只管下钻（onChartBlockClick）；想看某个分类的流水，展开「分类明细」点对应的一行（showCategoryRecords），弹窗里原来的「下钻」按钮随之去掉。点到没有子分类的块（叶子分类、「…（直接）」、「月账单」、计划预计金额）会弹一条提示，不再没有反应；计划预计金额行没有流水，整行不可点。表格上方的提示文案同步改为「点击图上色块下钻 · 点击表格行查看明细」。

v3.6.6 大额计划块的标签（小版本，无公告）

• 🐖 「预计存 / 预计还」：图表里大额计划那一块的金额是计划按「剩余金额 ÷ 剩余期数」算出的本月该存 / 该还多少，还没发生，所以不再叫「本月应还」。先攒后买标「（预计存）」，先买后还标「（预计还）」，后缀只有 5 个字，名字被截断时不至于太长；明细表说明行和开关提示同步改成「本月预计要存 / 还的金额（还没发生）」。

v3.6.5 「含固定账单」：月账单成为独立的父级大块（小版本，无公告）

• 📋 「月账单」是一个独立的父级大块：勾选「含固定账单」时，饼图 / 格子图 / 矩形图 / 明细表 / 总览「支出前五分类」里，房租、水电等固定账单归在「月账单」之下，旗下各项是它的子项——1 层只显示「月账单」一整块，2 层 / 全部时展开各项（矩形图里嵌套）；点「月账单」弹出它名下所有账单的流水。固定账单分类存在独立的 billCategories，getCategory / getRootAncestorId 认不出，所以由 getMonthlyBillGroup 把它们合成这个父级（buildPieSliceRows / buildCategoryTreeNodes）。
• 💰 月账单里的都算已付：每项取「已记流水」与「月账单中心设的金额」较大者——没记流水的也算，已记的流水不会被重复算。仅月份视图使用设的金额，自定义范围 / 近 30 天只算已记流水。
• 🐖 大额计划本月预计金额：save / borrow 计划本月预计要存 / 还的金额（PlanMath.getVirtualDueByPlan，= 剩余金额 ÷ 剩余期数，还没发生）作为平级的单独块列出，先攒后买标「（预计存）」、先买后还标「（预计还）」；信用卡分期已有流水，不重复。
• 以上没有流水的部分只用来看全貌：不生成流水，不计入本月总支出 / 日均 / 预算环，明细表下方有说明行。tests/bill-toggle-test.js 同步覆盖。

v3.6.4 「含固定账单」补丁（小版本，无公告）

• 📊 格子图 / 矩形图 / 明细表也随开关刷新：v3.6.3 的开关只重画饼图，格子图和矩形图点了没反应；而且格子图读的是以画布 id 命名的开关（catWaffleChart，没有任何复选框控制它），一直停在「含账单」。现在 buildPieSliceRows 对饼图 / 格子图 / 矩形图 / 明细表统一读 pieChart 这一个开关，refreshPieChart 重画当前视图（updateDrillCharts）并刷新展开层与明细表。tests/bill-toggle-test.js 新增「真点开关」检查（矩形图 / 格子图 / 明细表，旧版会失败）。

v3.6.3 「含固定账单」开关修正

• 📊 图表真的随开关变化：固定账单分类存在独立的 billCategories 里，getRootAncestorId / getCategory 认不出它，汇总到根分类时被悄悄丢掉，所以统计页的饼图 / 格子图 / 矩形图和总览前五分类从来没有账单，勾不勾都一样。现在勾选时每个账单是一个独立的顶层块（点击可看该账单流水），取消勾选去掉。
• 💳 信用卡分期跟着开关走：分期流水记在用户自己选的普通分类下，旧开关只按「分类是否账单」判断，取消勾选时分期仍算日常。新增 StatsEngine.isFixedRecord（账单分类 或 带 planId 的分期流水），日常 / 固定的划分、日均、预测、日常支出、图表统一走它；getSpendablePlan 多返回 planDueCredit，日常可花预算先扣掉分期，所以「剩余日常」数字不变，只是取消勾选时分期不再算进日常。「已付账单 vs 计划账单」对账仍只看账单分类；报告页、假设分析 / 模拟器没有这个开关，口径不变。新增 tests/bill-toggle-test.js。

v3.6.2 记账更顺手 + 数字口径修正

• 📅 记账日期一键换天：日期栏左右两侧加 ‹ › 按钮，按一下切到前一天 / 后一天（跨月、跨年、闰年都按日历走，保留时分）。保存一笔后不再重置日期——连续补记同一天的账不用每笔重选；当日期不是今天时，日期栏会带琥珀色边框提示，免得忘了自己还停在别的日子。
• 💰 金额从「分」开始填（Touch 'n Go 式）：数字键依次从小数点后填入，23642 → RM 236.42，退格删最后一位，不需要小数点键。由新模块 src/js/08-money-input.js 在 document 上委托监听，带 data-money 的输入框即生效，渲染后才出现的弹窗也不用逐个接线；data-money="signed" 的框（假设分析的 ± 值、可负的金额）另有 ± 按钮。全应用的金额框都已转换：记账、编辑记录、预算（RM/% 可切换）、设置、假设分析、分摊（总额 / 各人份额 / 已收）、购物计划、云同步等。只有真正的键盘输入才会被改写，程序代码给输入框预填的值保持原样；粘贴的数字按数值解释（1,234.5 → 1234.50）；光标点到数字中间也只在末尾追加。
• 🤝 追账中心只列未收齐的：getPendingSummary 跳过已归档账单；「按人」隐藏已还清的人，「按账单」隐藏已收齐 / 已归档的账单；已结清 / 已归档账单集中放第三个标签，归档、删除、恢复入口保留。
• 🔮 修正假设分析的重复计算：对父分类设置「每天 −RM 2」时，旧版把调整继承给每个叶子分类各算一遍（4 个子分类就是 4 倍，约 RM 36 的节省被报成 RM 144）。现在以「调整节点所管辖的整组」为单位只算一次，再按各叶子的日均占比分摊；与引导页对「调整父分类 = 整组一起调」的描述一致。
• 📊 「日均」口径统一：报告页底部「本月至今已消费…，日均…」以前是总支出 ÷「有消费记录的天数」（与总览同名不同量，同一份数据总览 7.69、报告页 250.00），现在与总览 / 统计 / 假设分析共用 getDailyAverage：已过天数内我自己的支出（不含他人份额、不含勾了「不计日均」的记录）÷ 已过天数；有「不计日均」大额时句尾注明日均不含它。滚动 30 天的 getPeriodDailyAverage 之前漏了「不计日均」过滤与分摊他人份额扣除，同步修正。

未改动：money-wise-mobile.html（手机独立版）仍是旧的金额输入方式；编辑记录 / 分摊编辑器里的日期栏暂无前一天 / 后一天按钮。

v3.6.1 手机端优化

• 📱 手机上的分类页重新排版（≤600px）：以前一行里要塞 箭头 + 色点 + 图标 + 名称 + 四个操作图标 + 预算框，名称是唯一可压缩的元素，在 375px 下被挤到 11px、子分类直接 0px（子分类每层还要吃掉 48px 缩进，预算框被挤出屏幕右侧）。现在每个分类两行：上行是图标 + 完整名称（最多两行），下行是预算框（左）+ ⬆️⬇️➕⚙️（右）；嵌套缩进收窄到 18px/层；操作图标点击区从约 21×15px 放大到 30×32px。样式全部限定在 #page-categories 的窄屏媒体查询内——桌面端、平板（>600px）和选分类弹窗（共用 .cat-header 类名）像素级不变。

v3.6.0 新增功能

• 📝 口径澄清：「含账单」→「含固定账单」；「收支结余」拆成「预算结余」（月收入设定 − 已花 − 未付账单）与「实际结余」（流水收入 − 流水支出）；「剩余总额/天」→「剩余可花/天（未扣储蓄目标）」，配「日常可花/天（已扣账单+储蓄）」，公式写进小字与悬停说明。本月总支出下方注明「其中日常净支出 ＋ 账单流水」「你的实际承担 ＋ 待收回 ＝ 上方合计」。统计 / 报表 / 引导页同步改名。
• 📊 预测月总支出明细：总览与统计的预测卡下方加一行小字——账单趋势 ＋ 大额已发生（不计入日均） ＋ 日常趋势，三项之和恒等于预测数（含账单关闭时只显示后两项）。
• 👆 分类三图点击看记录：饼图 / 格子图 / 矩形图（含展开弹窗）点任意色块，弹出该领域在当前统计窗口的全部消费记录，可进编辑或跳流水页；有子分类时顺带下钻，原下钻入口不变。
• 🔮 假设分析区分收支：参数面板与结果明细只列支出分类（收入锁定、固定账单另计）；结果页用徽标区分流入 / 流出，储蓄公式注明「收入 − 总支出 − 未付账单」；假设分类明确标为假设支出。

v3.5.0 新增功能

• ↕️ 分类可重排：分类页每行左侧加 ⬆️ / ⬇️，根分类与子分类都能排，首尾自动置灰。顺序存在 sortOrder 上——属于账本数据，云端 / 局域网同步一起带走，另一台设备拉下来就是排好的顺序。
  • 只在「同父 + 同树」内移动：支出根与收入根的 parentId 都是 null，按全局排序会让一次按箭头把「工资」挪到「餐饮」旁边。
  • 每次移动把整组兄弟重编号成 0..n-1，而不是只换两个值。留空洞 / 半新半旧的值正是「两台设备拿着同一份数据却渲染出不同顺序」的来源，而且因为双方都认为这些数字合法，后续每次合并都修不回来。
  • 重排只改 sortOrder 一个字段，走一次 save()，所以三方合并把它当普通的逐条分类编辑处理，不需要任何特例。
• 🔍 选分类弹窗改为默认收起 + 搜索：记账、编辑、流水筛选、批量改分类、分类合并/移动目标——这些原本各自长了一份「默认全部展开」的渲染器，分类一多就只能一路划到底。现在统一成一个组件：默认收起、点箭头逐层展开（沿用分类页同款 ▶）、带搜索框（输入分类名或 emoji 都行，命中结果自动展开到可见，祖先行标出命中数）。展开状态按会话记住，跟分类页的 expandedCategories 一致。
  • 点击改为一个事件委托处理函数，分类 id 不再拼进 onclick 属性。
  • 顺带修掉一个真 bug：搜索无命中时，分区标题仍会渲染出来，导致「没有匹配」的空态永远不显示。

v3.4.0 新增功能

• 💰 收入记账：新增 / 编辑记录页顶部有「支出 / 收入」切换。
  • 独立的收入分类树：工资（月薪 / 奖金 / 加班津贴）、副业（接单 / 卖闲置）、报销退款、理财收益、其他收入，分类页里收支分成两块；收入分类右侧显示本月实际到账金额而不是预算框。
  • 收入一律不进支出统计：日均、分类图表、预算、超支警告、热力图、What-If 全部只算支出，收入不会把任何一个数字撑大。
  • 反过来补上净额：总览 / 统计 / 月度报告各加一行「收入 · 支出 · 结余」（有收入记录时才出现），近半年趋势图多一条绿色收入线，流水里收入显示为绿色带 +。
  • 记录到的收入 ≠ 月收入设定：前者是流水，后者是你每月手填的预算基数，仍然分开算——否则一进来历史数据全部对不上。
  • 导出同步跟进：CSV 多一列「类型」；Excel 消费记录 sheet 多「类型」列、月度统计多「收入记录 / 结余」两列，有收入时另出一张「收入分类统计」sheet。
• 🐛 顺带修掉的既有缺陷：
  • 全新安装（localStorage 为空）走的是 _defaults() 而不经过 _normalize()，因此新装的用户拿不到任何迁移结果——现在两条分支统一走 _normalize()。
  • CSV 原本把 ID 那一列裸着写（r1,"10.00",…）。一旦紧跟其后出现带引号的列，宽松的 CSV 解析器会把第一个逗号当数据，整行塌成一列——现在所有字段统一带引号。
  • 设置页的「统计审计」与记录诊断面板只按支出查月份，收入记录会被误报成「不在任何月份里」。

v3.3.0 新增功能

• ☁️ 可选云端同步（默认关闭，不需要账号）：设置 →「云端同步」。启用时生成一串 28 位恢复码（4 位一组，含校验位），换设备时点「已有恢复码？登录」粘贴即可。只有登录后才会出现同步状态、立即同步、历史版本等功能；未启用时不发任何网络请求、不启动任何定时器。
  • 端到端加密：恢复码经 HKDF 派生出「鉴权钥」与「加密钥」；账本 gzip 压缩后用 AES-GCM-256 加密再上传，服务器只保存密文。
  • 三方合并，不互相覆盖：每台设备记着「上次同步时的样子」。两台设备各自离线改动后再同步，按记录逐条合并——只有一边改的采用改动方；一边删一边改则保留修改并记入冲突；分摊还款金额累加；两边各自新增的都保留。
  • 安全网：账本为空不上传；一次删除 ≥20 条或 ≥50% 需确认；「清除所有数据」「导入（替换）」「局域网替换」后同步前先问「以本机为准 / 以云端为准 / 稍后」；云端版本回退检测；写入后读回校验；启用前自动备份本机，备份失败则不启用。
  • 历史版本：云端保留当前版本 + 最近 5 个历史版本，可导出为 JSON 后用「导入」恢复。
  • 限制：云端同步与 PIN 锁互斥；创建云端账本需要一次性邀请码（向作者索取）；单份账本加密压缩后上限 4 MiB；压缩需要 CompressionStream（Chrome 80+ / Safari 16.4+ / Firefox 113+，缺失时自动不压缩，但无法读取他人压缩过的版本）。
• 🔐 PIN 锁数据丢失修复：过去密文只在「设置 / 修改 PIN」那一刻写入，之后记的账只写明文——设 PIN → 继续记账 → 自动锁定 → 输 PIN 解锁，设 PIN 之后的记录全部丢失；修改 / 关闭 PIN 时同样会拿旧密文覆盖新数据。现在锁定时先用内存中的密钥重新加密并读回校验，通过后才清除明文；解锁不再用旧密文覆盖较新的明文；改 / 关 PIN 以内存中的最新账本为准。
• 🧩 唯一合并实现新增三方模式：DataStore._mergeData 现在也支持「有共同祖先」的三方合并（云端同步使用）；无祖先时行为不变。
• 📣 版本公告：每次打开应用（或解锁 PIN 之后）检测到你还没看过的更新，就弹一次说明。跳过了多条会提示「你错过了 N 次更新」，弹窗内容框左右上侧各有箭头可翻看每一条，到两端自动置灰。设置页的「📣 查看更新日志」随时可回看全部历史。
  • 已读记录的是公告条目的 id而不是版本号，所以不升版本号也能发公告——升版本号本身不弹任何东西。
  • 弹窗走统一的弹窗队列（优先级最低），不会和云同步冲突、大额计划逾期、月初结转提醒抢同一个弹窗。

发版流程（加一条公告）

# 1. 在 src/js/29-changelog.js 的 CHANGELOG 头部插入一条（新 id，填当前版本号）
# 2. 在该文件底部补对应的中英文 i18n
# 3 & 4. 构建 + 测试（测试会挡住 id 重复 / 日期顺序错 / 空条目 / 版本号超前）
bash build.sh && node tests/changelog-test.js
# 5. 只有真的要发新版时，才改 src/js/01-constants.js 的 APP_VERSION 与本文件的版本号

第 5 步是独立的一步：升版本号不会自动发公告，要公告就得插一条。

v3.2.0 新增功能

• 🧾 分摊收款系统：分摊账单编辑器补齐日期时间 / 备注 / 总额 / 分类 / 标签等全部流水字段；分摊方式（平均 / 自定义）与「金额不明」标记均落盘，重开保持原样，自己的份额也可标记为金额不明。
• 💰 部分还款：参与人记「应还 / 已还」金额而非单一勾选框。单笔可直接设定已还金额（含撤销），一次收到的钱也可冲抵多笔账单——支持全选 / 全不选 / 反选，按平均分配 / 按日期先后 / 手动指定三种方式分摊，整数分运算不丢厘，且任何分配都不会让人还超应还额。
• 💳 大额分期消费计划：三模式（先攒后买 / 先买后还 / 信用卡分期），月供自动占用可支配预算，台账逐月重放推导，逾期可延期 / 补齐 / 放弃。起始月改用年 + 月下拉选择（不再是 <input type="month">），带「本月 / 下月」快捷键与起止区间提示，金额 / 期数 / 月份均有边界校验。
• 🎨 分类图标与颜色：新建子分类自动继承父级颜色；编辑分类图标时可直接输入任意 Emoji，不再局限于预设网格。
• ▦ 分类格子图：把金额画成方块阵（一格 = 固定金额），比饼图更容易比较相近的占比。分类支出卡片现为「🥧 饼图 / ▦ 格子图 / ▤ 矩形图」三选一，三者共用同一份数据，下钻、层级（1 层 / 2 层 / 全部）、排除账单开关、配色全部通用，展开弹窗同样支持切换。
• 📈 统计页可读性：分类明细表默认收起（可折叠并记忆状态）；饼图深层展开时标签不再重叠、不越过图例栏，图例按画布高度封顶；热力图格子间距恢复均匀。

并入 v3.3.0：v3.2.0 之后的其他改动

• ▤ 分类矩形图（treemap）：面积正比于金额，子分类的框嵌套在父分类框里——一眼看出「餐饮花得多」是被哪个子分类拉高的。层级控件直接决定嵌套几层，点框下钻。分类卡片的第三种视图。
• 📅 自定义日期范围修复：统计页选日期范围一直没生效——useCustomRange() 以「月份为空」作标记，而 renderStats() 开头会无条件把月份填回去，标记当场被冲掉。现已修复，范围内的统计、图表、明细表口径一致。
• 🔍 展开视图：弹窗放大到 min(96vw, 1500px) / 94vh，图表高度跟随视口（矩形图更高）；修掉三处问题——多张图叠着显示（CSS 的 id 级 !important 压过内联样式）、明细表下钻失效（只重画了隐藏的画布）、以及 canvas 内部分辨率与显示尺寸不符导致的整体模糊。
• 🧮 合计口径说明：分类明细表底部新增「减：已收回分摊」「实际支出」两行。分类金额按账单全额计入其真实分类，而统计页顶部与总览是扣除他人还款后的净额，两者天然不等；现在差额直接列出来，不必再怀疑哪个算错了。
• ▦ 格子图排列：改为行优先——最大的分类在最上面、最小的在最下面（原先是列优先，大的在左边）。
• 🔐 数据导出 / 导入 / 同步完整性修复（19 项）：一次系统性审计后的全面修复，详见 审计报告 与 修复计划。要点：
  • 局域网同步过去会丢光全部消费记录 —— 校验器只认 YYYY-MM-DD，而 App 存的是 2026-08-01T19:30 与 ISO 时间戳，每一条记录都被静默滤掉；replace 模式还会先清空本机。现已修复，并新增「全部被拒则中止同步、绝不清库」的安全网。
  • JSON「合并」导入会重复累加 —— 同一份备份导两次消费翻倍。合并逻辑收敛为唯一实现，按 id 去重、updatedAt 新者胜。
  • 指纹码有 6 个盲区 —— 分类图标/颜色、selfUnknown、payer（决定分摊金额口径）等改动指纹察觉不到。改为全量稳定序列化 + 排除名单，新增字段自动纳入，且与键序、数组顺序无关。
  • 「修复数据」会静默删除记录 —— 带 planId 但计划已不存在的记录被直接删掉。改为解除关联，记录留下。
  • 撤销窗口内点刷新会永久丢失记录 —— 待删缓冲现已持久化，跨刷新、跨重载都能撤销。
  • 手机版会抹掉主应用的分摊账单与大额计划 —— 它用的还是 v1 的 6 键结构却共享同一份存储。现在对不认识的键保持中立。
  • 没登记收入的月份，欠款会凭空归零 —— 系统把「不知道收入」按「这个月照计划还了」处理（实测：欠 1050 → 收入记录一丢就变成已还清）。这个乐观推定保留了（否则不记收入的用户会看到计划永远停滞），但 Excel 现在逐月标出「实测 / 推定」，状态栏写明「N 个月无收入记录，按计划推定」——不再把猜的当实测。
  • 另有：归档账单的欠款不再永久挂账、Excel 分摊子行串列、CSV 补「子分类 / 所属计划」两列等。

v2.7.0 新增功能

• 📊 统计范围切换：设置页新增「本月」/「近30天」切换开关，总览/统计/报告/流水/假设分析全页面联动。预算/储蓄环图保持月口径。
• 🔐 PIN锁 + AES-GCM 加密：设置页启用PIN码后，数据使用 Web Crypto API (PBKDF2 + AES-GCM) 加密存储。启动需验证PIN，支持自定义自动锁定时间（1/5/15/30分钟/从不）。
• 🏷️ 标签系统：记录支持多标签（场景标记，与分类互补不重叠）。添加记录时可选择标签，流水页可按标签筛选，统计页新增 Waffle Chart 方格图可视化标签分布。
• 🔲 Waffle Chart 标签分布图：统计页底部展示标签花费占比的方格矩阵，5档密度可调（24~600格），Scale Pop 入场动画，悬停高亮+动效，点击跳转流水页筛选，独立时间段选择，标签颜色自定义，导出PNG。

---

🔥 Highlights

• Zero external dependencies — Pure HTML, CSS, and JavaScript. No CDN, no frameworks, no libraries.
• Modular source structure — 16 CSS + 28 JS files organized by domain in src/, built into a single deployable HTML via build.sh.
• IIFE scope isolation — 28 JS files each wrapped in an IIFE, only explicitly exported symbols (window.*) are shared across files, preventing global namespace pollution.
• Elastic animated pie chart — Smooth hover pop-out effects and full drill-down navigation.
• Calendar heatmap — Spending ratio visualized with a 6-color gradient across the month.
• Soft delete with 5-second undo — Accidentally deleted a record? Undo it within 5 seconds.
• Native Excel export — Generates real XML SpreadsheetML 2003 with SUM, AVERAGE, and IF formulas — no library required.
• Page guide system — Each page has a ❓ guide button explaining features, usage, and parameters. Supports simple/detailed toggle mode.
• Responsive design — Desktop sidebar layout with a mobile bottom tab navigation bar, including safe-area support.
• Dark mode throughout — All Canvas charts, UI elements, and exports adapt automatically.
• CSP & XSS protection — Content Security Policy headers and HTML injection sanitization (escHtml) built in. The only network exception is connect-src for the single Supabase host used by the optional cloud sync.

---

🚀 Quick Start (用户)

1. Download index.html (主应用) 或 money-wise-mobile.html (手机版)
2. 主应用在电脑浏览器打开，手机版在手机浏览器打开
3. Start tracking your expenses — everything is saved automatically in your browser

No installation, no server, no internet connection required after download.

---

🛠️ Developer Quick Start

# Clone the repository
git clone https://github.com/Xiaobailong788/budget-app.git
cd budget-app

# Build index.html from source files
bash build.sh

# Open index.html in your browser
# Edit src/css/*.css and src/js/*.js, then rebuild

Tests

The suites load the built index.html under jsdom, so always rebuild before running them — otherwise you are testing the previous build.

npm i --no-save jsdom                      # the only test dependency
bash build.sh                              # required first
for t in tests/*.js; do node "$t"; done    # each file exits non-zero on failure

See the 测试 section in STRUCTURE.md for what each suite covers and the gotchas when adding new ones.

---

📝 Usage Guide

总览 (Overview) — Your landing dashboard. Review monthly totals, check your budget ring and savings ring, view the 7-day trend line, and see which categories are overspent.

记账 (Add Record) — Log a new expense by entering an amount, picking a category from the nested tree, setting a date and time, and optionally adding notes. The form validates your input and shakes on error.

流水 (Records) — Browse, search, and filter all your past expenses. Use the advanced filters to narrow results, switch between compact and card views, select multiple records for batch operations, or delete with a 5-second undo.

分类 (Categories) — Organize your spending categories in an infinitely nestable tree. Assign budgets per category, choose colors and emoji icons, merge duplicates, and move items with automatic cycle detection.

统计 (Statistics) — Explore your spending visually. Drill into pie chart slices, view trends on the line and bar charts, check your monthly heatmap, and export any chart as a PNG image.

月度报告 (Report) — Generate a print-friendly summary of any month. Use it for personal review or archiving.

假设分析 (What-If) — Run spending simulations by adjusting per-category assumptions. Compare projected savings against current trends with visual charts and detailed breakdowns.

设置 (Settings) — Configure your monthly budget, choose a savings target mode, toggle dark mode, and manage your data through JSON, CSV, or Excel export/import. Use LAN sync to transfer data between devices on the same Wi-Fi, or turn on the optional end-to-end-encrypted cloud sync (Settings → 云端同步) to keep several devices in step with one recovery code.

---

🛠 Tech Stack

• Language: Pure HTML5 / CSS3 / JavaScript (ES2020+)
• UI: Native DOM API, CSS Custom Properties, Flexbox, Grid
• Charts: Canvas 2D API with requestAnimationFrame
• Storage: Browser localStorage
• Export: Native JSON, CSV, XML Spreadsheet 2003 (SpreadsheetML)
• Sync: WebRTC P2P (LAN sync, zero server); optional cloud sync — Web Crypto (HKDF + AES-GCM-256, client side) over fetch to a Supabase Postgres RPC backend (supabase/migrations/), three-way merge on the client
• Build: Simple bash script (concatenation)
• Dependencies: None — zero external libraries

---

📁 Project Structure

budget-app/
├── index.html               # 构建产物（生成，直接用于浏览器 / GitHub Pages）
├── build.sh                 # 构建脚本：拼接 src/ → index.html
├── src/
│   ├── index.html           # HTML 骨架（含 <!--build:css--> / <!--build:js--> 标记）
│   ├── css/                 # 16 个 CSS 文件（变量、布局、组件、动画、响应式、引导、云同步…）
│   └── js/                  # 28 个 JS 文件（按功能域拆分）
│       ├── 01-constants.js       # 颜色表、默认分类
│       ├── 02-datastore.js       # DataStore（localStorage CRUD）
│       ├── 03-excel-export.js    # Excel XML 导出
│       ├── 04-stats-engine.js    # 统计引擎
│       ├── 05-simulation-engine.js # 假设分析引擎
│       ├── 06-router.js          # 页面导航
│       ├── 07-ui-core.js         # 主题、Toast、Modal、工具函数
│       ├── 09-category-picker.js # 分类选择器
│       ├── 10-render-overview.js # 总览页
│       ├── 11-theme-colors.js    # Canvas 主题色
│       ├── 12-budget-progress.js # 预算进度卡片
│       ├── 13-canvas-drawing.js  # 环形图、迷你折线
│       ├── 14-render-add.js      # 记账页
│       ├── 15-render-records.js  # 流水页
│       ├── 16-render-categories.js # 分类页
│       ├── 17-stats-charts.js    # 统计页 + 全部图表绘制
│       ├── 18-render-settings.js # 设置页
│       ├── 19-render-report.js   # 月度报告
│       ├── 20-what-if.js         # 假设分析
│       ├── 21-month-rollover.js  # 月初结转
│       ├── 22-init.js            # 初始化
│       ├── 23-lan-sync.js        # WebRTC 局域网同步
│       ├── 24-diagnostics.js    # 数据诊断工具（一致性检查、存储用量、审计日志）
│       ├── 25-page-guides.js    # 页面引导系统（8 页简明/详尽双模式引导文案）
│       ├── 26-split-bills.js    # 分摊收款系统（追账中心/分摊编辑器/部分还款/归档与转普通记账）
│       ├── 27-purchase-plans.js # 大额分期消费计划（先攒后买/先买后还/信用卡分期）
│       └── 28-cloud-sync.js     # 可选云端同步（恢复码/端到端加密/三方合并/防护/界面）
├── supabase/migrations/     # 云端同步的数据库定义（私有 schema + RLS + 5 个 RPC）
├── tests/                   # jsdom 测试套件（见 STRUCTURE.md 的「测试」章节）
├── money-wise-mobile.html   # 手机版：轻量记账，支持导入导出JSON (~1,384 lines)
├── STRUCTURE.md             # 完整函数地图（供 AI Agent 使用）
├── features/                # Feature docs (v2.0.0-era snapshots — see each file's header)
├── technical/               # Technical development logs (local only)
├── user/                    # User-facing changelogs (local only)
└── logs/                    # Consolidated project logs (local only)

---

🌐 Browser Support

Browser	Support
Chrome	✅ Full
Firefox	✅ Full
Edge	✅ Full
Safari	✅ Full
Internet Explorer	❌ Not supported

Requires ES2020+ support. Modern browsers only. The optional cloud sync additionally needs Web Crypto (crypto.subtle, available on secure origins such as https or localhost); it is checked at run time and the toggle simply refuses to start where it is missing.

---

📄 License

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.