WorthPath/docs/update-2026-10-02.md

2026-10-02 更新验收与使用

本次范围

按主目录 update.md 的要求完成 13 项代码更新，包括执行期间追加的红色金额和收支日历；完成时间为 2026-10-02 17:37（Asia/Hong_Kong）。

• 资产账户转出余额不足时允许透支。原币、8 位小数和双方事务不变；16 位整数范围改为检查金额绝对值。还款/收款超过剩余债务仍拒绝。
• 欠款在债务列表、详情、选择器和历史中显示负数，内部仍保存正的剩余本金并通过 side 参与净资产计算；债务详情只显示对应方向的“还款”或“收款”。
• 欠债、负债、负余额和支出金额使用红色。金额显示采用 ¥、HK$、US$、€、£、JP¥ 等符号；选择币种时仍保留代码。
• 新增/编辑账户可输入自定义分组。账户页按分组筛选；转账和借贷的账户选择使用可搜索弹窗，支持全部账户与分组视图。
• 账户页“快速记账”开启后，点击未归档账户直接编辑当前余额。保存新增历史，退出该模式恢复账户详情导航。
• 净资产轨迹裁掉第一条可见余额之前的日期；已有记录的零余额日期保留，空空间返回空轨迹。
• 新增定时支出/转账，支持一次性或每 N 天重复、暂停、删除。打开账户页或点击“执行到期计划”按需处理，每批最多 20 项；较长欠执行期可分批补记。一次性计划完成后不能重新启用。
• 新增独立“收支日历”入口：上方月历展示每日收入/支出，下方展示所选日期明细，默认今天。支持历史月份、未来日期不可选。
• 调整余额、债务方向与记录时间的文案，新增文案有 English 和繁体翻译。
• 内置图库从 20 扩充至 31：汇丰香港、恒生、渣打香港、东亚、星展香港、花旗香港、中银香港，以及 Binance、Gate、Bybit、Bitget。图标来自公开品牌站点，记录来源与下载摘要；PNG 已入库文件，页面无需访问品牌网站。

计划与收支的统计口径

计划只记账，不调用银行或交易所，不执行真实资金划转。一次执行写入当前业务分钟，备注保留原到期时间；不向既有余额历史中插入过去的支出，避免覆盖当前余额。重复计划按原到期时间加固定天数推进，尚未补完时下一批继续；每月不是固定天数，请按需要选择间隔。

每项计划在 Serializable 事务内锁定计划行，然后按固定顺序锁定账户；余额记录、转账记录和计划推进同事务提交。确定的“计划 ID + 到期时间”执行标识及完成状态用于防重复执行。失败不推进计划，保留错误提示供重试。隐藏账户未解锁时不显示/执行有关计划；归档账户计划执行失败并保留。所有资源按会话用户隔离。

现有数据保存的是余额快照，日历因此采用“账户余额变动估算”口径，不能视为完整交易流水：资产账户增加为收入、减少为支出，负债账户相反。只统计 balance/correction/scheduled_expense；初始余额（包括被更正的第一条记录）、估值、账户内部转账和借贷本金配对变化不计入。手动更新欠款减少也会被估算为收入，页面已注明负债账户反向计算；精确的经营收入/消费统计需要后续显式收支记录模型。

按变动发生日的可用历史汇率换算，保留十进制精度后汇总至两位小数；缺少汇率则该日标记不完整，不把外币当本位币。月查询只重放该月历史并为每个账户读取月前最后余额；点击日期只读取该日记录，避免为每次点击重复传整月明细。

数据与备份

迁移 20261002000400_groups_schedules 增加 Position.groupName 与 Schedule，不更改既有迁移。备份 ZIP manifest 升为 v7，新增 schedules.json，账户分组与计划余额/进度一并导出。旧 v3/v4/v5/v6 ZIP 和 JSON 仍支持；恢复时重映射计划账户 ID，一次性已完成计划不会再次扣款。备份后清空同时删除当前用户计划，财务数据/计划变化会使旧清空确认凭据失效。

应用本工作树更新后，在配置好数据库的环境执行：

pnpm install --frozen-lockfile
pnpm db:generate
pnpm db:migrate
pnpm build
pnpm --filter @worthpath/api icons:seed
pnpm test
pnpm test:integration

初始化图库仅按既有的固定内置图标 ID 追加/更新，不覆盖上传图标。

已验证与边界

• 前后端 pnpm typecheck 与生产 pnpm build 通过。
• pnpm test 28 项通过：透支/负转入余额、债务超额还款拒绝、请求去重、金额范围、债务符号/币种、轨迹裁剪、计划完成/重复/失败推进、日历口径/小数汇总/缺汇率、ZIP v7 分组计划往返及旧版兼容。
• 浏览器使用明确的模拟数据检查分组弹窗切换、转账选择和月历默认今天/日期切换/上下布局及红色支出，未操作真实用户财务数据。
• 新增 test/update-integration.test.ts，覆盖真实 MySQL 中计划并发执行一次、透支、补记、分组恢复、隐藏账户与日历隔离，纳入 pnpm test:integration。
• 本环境尝试连接现有数据库时发生 PROTOCOL_CONNECTION_LOST，因此本轮未应用数据库迁移、未向实际数据库导入新图标、未运行真实数据库集成测试。上述命令需在数据库可连接后完成；历史验收文档的旧测试结果不代表本轮已通过。