Actual Budget 22.12.03 版本全解析：突破金额上限、账户备注与导入器修复

Actual Budget 22.12.03 版本全解析突破金额上限、账户备注与导入器修复【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读Actual 22.12.03配套 Docker 镜像标签 22.12.9是一个聚焦「数字精度、数据导入与用户体验」的重要发布核心层移除了金额的 32 位整数上限从根上解决了大额记账场景下的溢出与显示错误账户新增备注Notes能力YNAB 4 与 nYNAB 数据导入器得到修复同时清理了多处导致崩溃的边界情况。阅读本文你将了解该版本每项关键变更的来龙去脉、背后的源码级实现金额安全上限、账户更新 API 等以及升级时的 Docker 标签注意事项与后续影响。升级前必读两个关键警告官方发布说明在本版本开头给出了两条直接影响升级动作的警告务必先行确认跨版本升级要求如果你当前运行的版本早于 22.10.25必须先去阅读 22.10.25 的发布说明其中包含一项破坏性变更breaking change的处理步骤。22.12.03 的说明本身未复述该步骤因此从更老版本升级时不要跳过中间说明。Docker 标签陷阱官方明确提示Docker 镜像标签22.12.3与22.12.8存在错误请务必使用22.12.9。当前仓库中 Actual Server 的构建说明 与 Dockerfile、docker-compose.yml 均以镜像方式分发升级时核对标签即可规避该问题。核心亮点一突破 32 位金额上限支持大额数值发布说明中的 Large values are supported 对应的正是 PR #387Remove 32bit limit on amounts。这是本版本最实质性的技术变更它改变了 Actual 内部对金额数值的表示与安全边界。底层实现从 32 位整数到安全数值上限在 22.12.03 之前金额字段存在 32 位整数的容量约束超过上限的金额会导致溢出或无法正确显示。该版本移除了这一限制并在 packages/loot-core/src/shared/util.ts 中确立了新的安全模型// We dont use Number.MAX_SAFE_NUMBER and such here because those // numbers are so large that its not safe to convert them to floats // (i.e. N / 100). For example, 9007199254740987 / 100 // 90071992547409.88. While the internal arithemetic would be correct // because we always do that on numbers, the app would potentially // display wrong numbers. Instead of 2**53 we use 2**51 which // gives division more room to be correct export const MAX_SAFE_NUMBER 2 ** 51 - 1; const MIN_SAFE_NUMBER -MAX_SAFE_NUMBER; export function safeNumber(value: number) { if (!Number.isInteger(value)) { throw new Error( safeNumber: number is not an integer: JSON.stringify(value), ); } if (value MAX_SAFE_NUMBER || value MIN_SAFE_NUMBER) { throw new Error( safeNumber: cant safely perform arithmetic with number: value, ); } return value; }关键设计考量为什么不直接用Number.MAX_SAFE_INTEGER2^53−1源码注释给出了精确解释——虽然内部运算基于整数是正确的但涉及除以 100即把整数金额换算回浮点小数的场景时2^53 量级的数值转换会丢失精度。例如9007199254740987 / 100 90071992547409.88显示出来就是错的。2^51−1 的选择保留足够的余量让除法运算结果依然精确。金额以「去掉小数点的整数」存储见同文件中IntegerAmount类型注释因此 2^51−1 对应的可用金额范围对于绝大多数记账场景已绰绰有余同时彻底摆脱了 32 位整数±2^31的瓶颈。对上层的影响金额上下限的放宽会自然传导到所有涉及金额运算的模块预算、报表、账户余额等。在 packages/loot-core/src/shared/currencies.ts 中也有对应注释明确金额格式化依赖util.ts中的安全上限定义可见该常量为全局金额逻辑的单一事实来源。核心亮点二账户新增备注Notes能力发布说明中的 Accounts can now have notesPR #385为账户实体引入了备注字段让用户可以为每个账户附加说明性文本例如「联名账户」「仅用于旅行支出」等。数据层与 API 层实现账户备注通过账户更新接口写入。在 packages/loot-core/src/server/accounts/app.ts 中updateAccount接收账户的id以及可选的name、last_reconciled、account_group_id字段并透传给底层数据库更新async function updateAccount({ id, name, last_reconciled, account_group_id, }: PickAccountEntity, id Partial PickAccountEntity, name | last_reconciled | account_group_id ) { await db.update(accounts, { id, ...(name ! undefined { name }), ...(last_reconciled { last_reconciled }), ...(account_group_id ! undefined { account_group_id }), }); return {}; }该接口通过app.method(account-update, mutator(undoable(updateAccount)))app.ts注册为可撤销undoable的变更操作意味着在桌面客户端中修改账户信息含备注后支持撤销回退。客户端联动在 packages/desktop-client/src/components/accounts/Account.tsx 与 移动端 AccountPage 中账户编辑统一通过useUpdateAccountMutation触发更新桌面端与移动端行为保持一致。说明note字段在账户模型中的能力与「交易备注」不同——交易备注由来已久在 sync.ts 的导入查询与快照中可见notes列与reconciled、cleared、amount并列。本版本新增的是「账户级备注」。核心亮点三YNAB 4 与 nYNAB 导入器修复Fix YNAB 4 and nYnab importers 是本版本对数据迁移体验的重要修复。导入器将旧格式数据转换为 Actual 的标准表结构其正确性直接决定迁移成败。导入流程中的备注与字段映射虽然发布说明未列出具体 PR 编号但从当前源码可以确认导入链路中备注与字段映射的处理逻辑位于 packages/loot-core/src/server/accounts/sync.tsconst notes trans[mapping.get(notes)]; // ... notes: importNotes notes ? notes.trim().replace(/#/g, ##) : null,这里有两处细节值得注意导入时对备注做trim()去除首尾空白避免迁移后残留多余空格将备注中的#替换为##——这是对 Actual 备注格式中转义符的兼容处理防止迁移数据中的#被误解析为特殊标记。从源码结构看该映射表同时覆盖date、payee、imported_payee、category、amount、reconciled、cleared等核心字段sync.ts任何字段映射错误都会在导入测试的快照中暴露相关测试见 sync.test.ts 及 同步快照。其余稳定性与体验改进发布说明还包含一批 UI 与稳定性修复完整清单如下对应 Actual 22.12.03变更说明Fix enter to create accounts#218修复回车键创建账户的快捷键行为Update contenteditable="false">【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考