Actual 24.6.0 版本深度解析可编程银行同步、规则 API 与 CAMT.053 导入【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual本指南围绕 Actual 开源个人财务管理应用的 24.6.0 版本发布Docker 标签24.6.0展开重点剖析该版本带来的四大核心能力通过actual-app/api以编程方式驱动 GoCardless / SimpleFin 银行同步、面向规则管理的完整 API 方法、基于X-ACTUAL-PASSWORD请求头的反向代理认证方式以及 CAMT.053 格式 XML 银行流水导入。读完本文你将掌握这些特性的实际用法、底层实现路径与配置前提并能直接在自己的 Actual 实例上复现验证。版本概览24.6.0 带来了什么Actual 24.6.0发布于 2024-06-03对应 Docker 镜像标签24.6.0是一次以「外部集成能力」为核心的迭代。官方发布说明将其归纳为以下几点 Notable ImprovementsAPI新增以编程方式运行第三方银行同步GoCardless、SimpleFin的能力API新增用于操作规则rules的方法认证新增通过 HTTP 请求头X-ACTUAL-PASSWORD认证的选项导入新增对 CAMT.053 格式 XML 文件的导入支持实验性功能月度支出报告Monthly Spending Report。与此同时该版本还包含大量 UI 增强、缺陷修复与维护性改动覆盖预算、交易、报表、银行同步、移动端等多个模块详见下文分类清单。发布说明原文位于 packages/docs/blog/2024-06-03-release-24.6.0.md本文所有结论均可结合仓库源码与测试文件进一步验证。API 增强一以编程方式驱动银行同步24.6.0 之前银行同步bank sync主要依赖客户端界面手动触发24.6.0 起actual-app/api提供了runBankSync方法允许在脚本、定时任务或自动化流程中直接拉取第三方银行GoCardless、SimpleFin的流水。方法签名与用法在 packages/api/methods.ts 中该方法定义如下export async function runBankSync(args?: { accountId: APIAccountEntity[id]; }) { return send(api/bank-sync, args); }不传参数对当前预算文件中所有已配置银行同步源的账户执行全量同步传入accountId仅对指定账户执行同步。典型调用方式import * as actual from actual-app/api; await actual.init({ dataDir: /path/to/data, serverURL: https://your-actual-server, password: your-password, }); await actual.loadBudget(your-budget-id); // 同步全部账户 await actual.runBankSync(); // 或仅同步单个账户 await actual.runBankSync({ accountId: the-account-id }); await actual.shutdown();底层实现batch sync 与 SimpleFin 分流服务端的实现位于 packages/loot-core/src/server/api.ts其行为可以概括为三条分支传入accountId时直接调用accounts-bank-synchandler仅同步该账户不传accountId时先获取全部账户其中account_sync_source simpleFin的账户统一走simplefin-batch-syncSimpleFin 支持批量接口其余账户如 GoCardless走accounts-bank-sync同步所有非 SimpleFin 账户。所有同步产生的错误会被汇总若有错误则以getBankSyncError抛出带错误码的异常。这一实现的测试用例位于 packages/loot-core/src/server/api.test.ts验证了「按账户同步时正确调用accounts-bank-sync」以及「批量同步时的行为」。配置前提runBankSync能否生效取决于账户是否已配置银行同步源account_sync_source字段以及同步服务器Actual Server是否配置了对应的银行同步凭据GoCardless / SimpleFin。账户同步源相关的数据库迁移可参考 1780606215000_add_bank_sync_status.sql银行同步提供方适配器则位于 packages/sync-server/src/app-gocardless 与 packages/sync-server/src/app-simplefin。API 增强二规则Rules管理的完整 API24.6.0 为规则体系补齐了编程接口。此前规则只能通过客户端界面维护现在可以在actual-app/api中直接读取、创建、更新和删除规则便于批量配置、迁移或与外部系统对接。方法一览对应实现均在 packages/api/methods.ts// 获取当前预算中的所有规则 export function getRules() { return send(api/rules-get); } // 获取指定 payee收款方相关的规则 export function getPayeeRules(id: RuleEntity[id]) { return send(api/payee-rules-get, { id }); } // 创建一条规则返回创建的规则 export function createRule(rule: OmitAPIRuleEntity, id) { return send(api/rule-create, { rule }); } // 更新规则整体提交含 id export function updateRule(rule: APIRuleEntity) { return send(api/rule-update, { rule }); } // 删除规则 export function deleteRule(id: RuleEntity[id]) { return send(api/rule-delete, id); }使用要点createRule传入不含id的规则对象OmitAPIRuleEntity, id字段类型参照APIRuleEntity定义见 packages/loot-core/src/server/api-models.ts 或 API 包导出的类型updateRule需要提交完整的规则对象含idgetPayeeRules(id)传入的是 payee 的 id用于查询某个收款方关联的规则。规则在界面侧的联动同版本还改进了「从交易创建规则」的体验PR #2786现在基于交易创建规则时会自动匹配amount金额条件。规则条件与动作的数据结构由 packages/loot-core/src/types/models.ts 中的RuleEntity定义规则条件的数据库迁移可参考 1615745967948_rules.sql。认证增强X-ACTUAL-PASSWORD请求头登录24.6.0 新增了通过 HTTP 请求头X-ACTUAL-PASSWORD携带密码进行认证的能力客户端 PR #2362服务端 PR #312主要面向反向代理 / Auth Proxy 场景由代理负责身份验证后再把密码透传给 Actual Server。服务端实现在 packages/sync-server/src/app-account.js 的/login端点中getLoginMethod(req)会根据请求判定登录方式header分支的逻辑为读取req.get(x-actual-password)若为空返回{ status: error, reason: invalid-header }若不为空调用validateAuthHeader(req)校验代理是否被信任校验通过后用loginWithPassword(headerVal)完成登录并签发 token否则返回proxy-not-trusted。注意console.debug中密码会被*.repeat(headerVal.length)打码避免明文落入日志。启用前提信任代理validateAuthHeader依赖服务端配置的受信任代理来源。登录方式与配置项集中在 packages/sync-server/src/load-config.jsformat: [password, header, openid], default: [password, header, openid],即默认同时启用三种登录方式可通过环境变量按需裁剪。只有将反向代理正确配置为受信任来源后header方式才会放行否则即使请求头携带密码也会被判定为proxy-not-trusted拒绝。这意味着该特性应仅在部署了可信反向代理如 nginx、Caddy 等的环境中使用不要直接暴露给不可信客户端。导入增强CAMT.053 XML 银行流水24.6.0 新增了对CAMT.053ISO 20022 银行对账单XML 文件的导入支持解决了欧洲银行用户无法直接用官方格式导入流水的问题。解析器实现导入链路位于 packages/loot-core/src/server/transactions/import/parse-file.ts当文件扩展名为.xml时会调用xmlCAMT2json见 packages/loot-core/src/server/transactions/import/xmlcamt2json.ts。解析器从 CAMT.053 文档中提取的关键节点包括Ntry每一笔银行条目EntryAmt金额通过convertToNumberOrNull转为数值NtryDtls / TxDtls交易明细支持一笔条目下多条子交易Array.isArray分支会把子交易拆成多条记录RltdPties相关方根据借贷方向取Cdtr贷方/收款人或Dbtr借方/付款人作为 payee 名称RmtInf / Ustrd汇款信息作为备注notesAddtlNtryInf、NtryRef附加信息与条目引用在 payee 缺失时兜底作为 payee 或 notes。金额正负方向由条目类型借/贷决定与 UI 中「收入/支出」的方向约定保持一致。测试与样例文件仓库内置了完整的解析测试与真实样例解析测试packages/loot-core/src/server/transactions/import/parse-file.test.ts含快照 packages/loot-core/src/server/transactions/import/snapshots/parse-file.test.ts.snap标准样例packages/loot-core/src/mocks/files/camt/camt.053.xmlPayee/备注变体样例packages/loot-core/src/mocks/files/camt/camt.053.payee-memo.xml。你可以用这两个文件在「导入交易」功能中实测选择.xml后缀的 CAMT.053 文件系统会自动识别为银行流水导入。实验性功能月度支出报告24.6.0 引入了实验性Monthly Spending Report用于对比本月至今MTD与历史月份的支出情况PR #2622。它属于自定义报表Custom Reports体系同类报表实现集中在 packages/desktop-client/src/components/reports并在客户端中以「月度支出报告」入口开放。该功能以实验性形态发布官方在 packages/docs/blog/2024-06-03-release-24.6.0.md 中邀请用户反馈问题。同版本的自定义报表还有多项配套打磨修复小视觉问题、点击表格单元格时展示对应交易明细PR #2696、将报表文件推进到 TypeScript strictPR #2707/#2726/#2727/#2728等。其他增强与修复完整清单为保证发布说明信息不遗漏以下为 24.6.0 的其余改动汇总。界面与交互增强移动端预算页可快速切换其他预算文件PR #2507拆分日程交易split-schedule仅按相关金额模板化PR #2652移动端日程交易弹窗显示日程名称与日期PR #2664数字格式逗号与句点均可作为小数分隔符若该字符未被用作千位分隔符PR #2672并行拉取云端文件与文件信息以加快下载PR #2700导出文件使用预算名称作为文件名PR #2713修正弹窗边距PR #2714下拉筛选列表按字母排序PR #2719更平滑的预算加载/下载提示文案PR #2730为多个报表页添加页头并重构 Page 组件PR #2733移动端拆分交易金额自动补小数点PR #2746移动端交易录入必须选择账户删除交易需二次确认PR #2754银行同步弹窗中账户按序排列并显示余额PR #2795预算月份选择更易辨识PR #2797。缺陷修复金额筛选同时包含收入与支出PR #2643后被 #2803 回退手动导入时不再改写交易日期PR #2648修复端到端加密预算文件在 API 远程同步中的问题PR #2698修复子交易关联时预览交易未将日程识别为已支付PR #2712空预算文件下净值报表不再显示加载指示PR #2725修复支出报表中的 NaN 错误PR #2745移动端不再记忆上一次输入的类别PR #2754强调文本不再使用下划线PR #2765修复表格合计回调造成的重复列渲染PR #2768日期范围组件对非法日期容错避免崩溃PR #2769修复长类别/组名导致备注图标尺寸与位置变化PR #2773将结转箭头移入可视区域PR #2774收入固定显示在左、支出在右值为 0 时隐藏柱条PR #2775账户页余额筛选仅统计可见交易的问题修复PR #2777银行同步弹窗支持新建预算外账户PR #2788修复当月日期大于 28 时的崩溃PR #2809。维护性改动API 包发布 TypeScript 类型PR #2559与实体外部类型PR #2716Tooltip 组件持续迁移至 react-ariaPR #2631/#2724/#2766/#2778自定义报表相关文件推进 TS strictAPI 包引入 crdt 依赖以导出其类型PR #2738Electron 升级至 31.0.6PR #2763。Actual Server 侧更新新增受信任 Auth Proxy 的 HTTP 请求头认证PR #312即上文的X-ACTUAL-PASSWORD服务端配合GoCardless 新增德国 Sparkasse Karlsruhe 支持PR #346拉取 BNP 银行流水时确保 payee 名称不含交易性信息PR #349SEB 银行适配器扩展支持SEB_KORT_AB_NO_SKHSFI21PR #350新增BANKS_WITH_LIMITED_HISTORY常量并实现 Bankinter 银行适配器PR #355better-sqlite3 升级至 9.6.0PR #357。相关适配器代码可继续查阅 packages/sync-server/src/app-gocardless 与 packages/sync-server/src/app-simplefin 目录。如何升级验证Docker 部署拉取标签24.6.0的镜像即可获得本版本全部能力API 验证在packages/api包的测试与文档基础上packages/api/README.md可先在一个测试预算文件上调用runBankSync与getRules确认返回结构符合预期CAMT.053 验证使用 packages/loot-core/src/mocks/files/camt/camt.053.xml 走一遍导入流程比对快照 packages/loot-core/src/server/transactions/import/snapshots/parse-file.test.ts.snap 中的解析结果Header 认证验证仅在受信任反向代理后启用header登录方式并确认服务端load-config中auth配置未将其禁用。总体而言24.6.0 把 Actual 的「本地优先」架构向外扩展了一大步银行同步与规则管理均可通过官方 API 编程驱动CAMT.053 补齐了欧洲银行场景的导入缺口请求头认证则让 Actual 能无缝嵌入已有反向代理体系是自动化与集成开发者值得关注的一个里程碑版本。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
