Actual 23.7.2 版本发布详解：修复交易录入、分类排序与同步 schema 错误处理

Actual 23.7.2 版本发布详解修复交易录入、分类排序与同步 schema 错误处理【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual 是一款本地优先local-first的个人财务管理应用23.7.2 是其 2023 年 7 月发布的补丁版本主要围绕账目浏览、预算显示、触摸设备交互、同步机制与 CI 维护进行修复。本文将基于该版本的发布说明结合仓库源码逐一解析每项变更的实现原理与影响帮助读者理解 Actual 的账户切换交互、分类排序逻辑、预算显示格式化、数据库迁移机制以及invalid-schema同步错误的处理链路掌握如何在升级或自托管部署时评估这些修复。版本概览Actual 23.7.2 发布于 2023 年 7 月 9 日对应的 Docker 镜像 tag 为23.7.2。本次发布同时覆盖两个组件ActualVersion 23.7.2包含 6 项 bugfix 与 3 项维护性改动Actual ServerVersion 23.7.2服务端随客户端同步发版。从改动分布看本次版本聚焦于「交互细节修复」与「同步健壮性」两个方向前者包括切换账户时退出新增交易模式、触摸设备上的分类排序回退、预算--0.00显示问题后者包括账户类型字段在同步中的恢复、invalid-schema错误日志改进以及升级路径与 CI 迁移检查的完善。交互与显示层修复切换账户时关闭“新增交易”录入模式修复内容#1305在账户页面之间切换时关闭“add transaction”新增交易的录入模式。在 Actual 的账户视图中用户点击“新增交易”后界面会进入录入态此时若直接切换账户之前残留的录入模式会导致新账户页面出现未预期的输入框状态。该修复在账户切换的事件链路上主动结束录入模式确保每次进入账户页面时都处于干净的初始状态。从交互层面看这是典型的“状态跨页面泄漏”问题——录入态应属于单个账户页面而非全局共享。触摸设备上回退分类排序修复内容#1306在触摸设备touch devices上回退Revert分类排序功能。分类排序允许用户通过拖拽调整预算/交易分类的顺序但触摸设备上的拖拽手势与滚动、点击等其他手势存在冲突导致排序行为不稳定。23.7.2 选择在触摸设备上回退该功能恢复为禁用/固定顺序优先保证基本浏览与编辑的稳定性桌面端行为保持不变。这是一个务实的取舍当某项交互在特定输入设备上无法可靠实现时回退功能优于提供有缺陷的交互。修复预算显示--0.00问题修复内容#1308修复预算有时显示--0.00数值的问题。--0.00是 JavaScript 中-0值在格式化后的典型表现当预算计算结果为-0负零时直接格式化会输出--0.00或类似带符号的零值对用户造成困惑。Actual 的预算表格基于电子表格spreadsheet计算引擎实时求值相关逻辑位于 packages/desktop-client/src/spreadsheet本次修复在数值格式化/归零阶段将-0归一化为0保证余额、可用金额等位置在数值为零时始终显示正常的0.00。这类问题常见于对负数四舍五入后恰好落在零边界的情况属于显示层而非计算层的修正。同步与数据层修复恢复账户类型列修复 edge 版本升级导致的同步问题修复内容#1317修复同步问题——重新添加账户类型列add back account type column。这是本次发布中数据层最关键的一项修复背后涉及一段迁移历史。Actual 的数据库迁移按时间戳顺序存放在 packages/loot-core/migrations 目录1686139660866_remove_account_type.sql 曾在 2023 年 6 月的迁移中执行ALTER TABLE accounts DROP COLUMN type移除了账户类型字段随后的 1688841238000_add_account_type.sql 又通过ALTER TABLE accounts ADD COLUMN type TEXT将其加了回来。在 23.7.2 之前的某些edge开发版构建中账户类型列的状态不一致部分设备的数据库缺少type列导致服务端在拉取/比对 schema 时产生分歧同步消息应用失败。修复方式是在迁移体系中补齐账户类型列确保所有客户端与服务端在同步时拥有一致的accounts.type字段。从源码结构看accounts表的字段演进体现了 Actual 对 schema 的持续调整后续迁移中还新增了account_groups等表见 1787013118115_add_account_groups.sql而每次字段增删都必须同步考虑与既有数据的兼容。改进invalid-schema错误日志修复内容#1302为invalid-schema问题改进错误日志。invalid-schema是 Actual 同步引擎中的一类已知错误。在 packages/loot-core/src/server/sync/index.ts 中数据库写入失败时会被包装为SyncError(invalid-schema, ...)例如在同步事务应用 SQL 更新失败时第 102 行附近或在批量拉取记录失败时第 144 行附近错误对象会携带原始error.message、error.stack以及触发失败的querySQL 与参数便于定位是哪条同步操作触发了 schema 不匹配。服务端捕获到invalid-schema后会通过app.events.emit(sync, { type: error, subtype: invalid-schema, meta })将错误广播给客户端见 sync/index.ts。客户端侧的错误格式化逻辑位于 packages/loot-core/src/shared/errors.tsgetSyncError与getDownloadError会先通过isDatabaseSchemaMismatch(meta)判断底层错误信息是否匹配/no such (column|table)/i正则——若匹配则判定为“数据库 schema 比当前版本更新”并向用户展示明确提示This budget could not be loaded because it uses a newer database schema than this version of Actual supports. Make sure you are using the latest version, then try again.23.7.2 对这类错误日志的改进意味着当用户遇到invalid-schema时日志中会包含更完整的 SQL 语句与栈信息帮助开发者判断是迁移缺失还是字段定义不一致。相关错误类型定义与测试见 packages/loot-core/src/types/server-events.ts、packages/loot-core/src/shared/errors.test.ts桌面端面向用户的多语言错误文案在 packages/desktop-client/src/util/error.ts。修复从旧 edge 版本升级的路径修复内容#1309处理从某些较新的edge版本升级到更新版本 Actual 时的问题。该修复与上面的账户类型列问题同源某些edge版本之间迁移状态不一致升级时无法顺利应用后续迁移。修复确保迁移系统能够识别并处理这类中间状态使升级路径保持平滑。结合迁移文件按时间戳排序、逐条应用的机制见 packages/loot-core/default-filesystem.mjs 中migrationsDir的加载方式可以推断该修复涉及对迁移编号/已应用状态的校验避免因缺失中间迁移而导致升级中断。维护性改进修复文档链接 404修复内容#1297修复一个会将用户引导到“页面不存在”的链接。这是一个纯文档/站点维护修复修正了帮助文档或界面中指向错误地址的链接。实际项目文档仓库位于 packages/docs/docs其中 releases.md 汇总了各版本发布说明。改进回填迁移backdated migrations的 CI 检查修复内容#1307改进 CI 中用于捕获“回填/过期迁移”backdated migrations的检查。所谓 backdated migration是指新增迁移文件的时间戳早于已发布的迁移例如把新迁移的时间戳写回过去这会造成已升级用户的迁移顺序错乱。23.7.2 增强了 CI 检查规则在合并前自动拦截此类问题。对应的迁移检查实现位于 packages/ci-actions/src/migrations/check.ts测试见 packages/ci-actions/src/migrations/check.test.ts。这属于仓库工程治理层面的改进对最终用户无直接功能影响但对保持迁移链完整、防止升级事故至关重要。升级与自托管部署指引Actual 提供多端部署方式桌面端、移动端以及自托管服务端。使用 Docker 自托管的用户可直接拉取对应镜像docker pull actualbudget/actual-server:23.7.2 # 或使用通用稳定 tag docker pull actualbudget/actual-server:latest也可以参考仓库根目录的 docker-compose.yml 与 Dockerfile 自行构建。若你正在使用早于 23.7.2 的edge版本尤其是出现过同步报错或invalid-schema提示的环境建议优先升级到 23.7.2 或更新的稳定版本——该版本补齐了账户类型列并改善了同步错误诊断能显著降低升级链路断裂的概率。总结Actual 23.7.2 是一个典型的补丁版本功能上无大改但在细节体验与数据健壮性上颇为关键。它修复了账户切换时录入模式的残留、触摸设备上的分类排序问题、预算--0.00显示异常数据层面恢复账户类型列以修复 edge 版本升级后的同步问题并改进invalid-schema错误日志工程层面则通过增强 CI 迁移检查避免未来出现回填迁移。对于自托管用户建议关注同步类修复#1317、#1309、#1302对升级路径的积极影响对于桌面端用户账户切换与分类排序的体验修复值得在升级后直接验证。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考