Actual 预算应用 API 事务合并指南使用 mergeTransactions 去重重复交易【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual导读本文围绕 Actual 即将发布的mergeTransactionsAPI 能力展开介绍如何通过一个方法把同账户内两条重复交易合并为一条。你将掌握mergeTransactions的调用方式、存活交易surviving transaction的判定规则、底层合并算法与失败条件并了解它在银行同步去重、手动账目清理等场景中的实战用法。功能背景API 层新增的交易合并能力在upcoming-release-notes/api-merge-transactions.md中Actual 以一条简短的 release note 预告了本次增强AddmergeTransactionsto the API so integrations can merge two duplicate transactions其核心意图是让第三方集成integrations能够通过公开 API 合并两条重复交易。在此之前合并操作主要发生在应用界面与loot-core服务端内部外部集成难以直接调用。mergeTransactions的加入把这一能力正式暴露给 API 消费者使自动化的重复交易清理成为可能。从源码结构看这一能力横跨三个层次packages/api/methods.ts浏览器/桌面端 API 层的对外方法定义packages/loot-core/src/server/transactions/app.ts服务端把transactions-merge方法注册进消息路由并通过mutator(undoable(...))包装说明该操作支持撤销undopackages/loot-core/src/server/transactions/merge.ts合并算法的核心实现。API 签名与调用方式mergeTransactions的 API 定义位于 packages/api/methods.tsexport function mergeTransactions( ids: [TransactionEntity[id], TransactionEntity[id]], ) { return send(api/transactions-merge, { ids }); }调用参数是恰好两条交易 ID 组成的元组返回值是存活交易的 IDPromiseTransactionEntity[id]另一条交易将被删除。官方 API 参考文档 packages/docs/docs/api/reference.md 中的说明Merge exactly two distinct transactions from the same account into one. Returns the id of the surviving transaction; the other one is deleted.典型用法const survivingId await mergeTransactions([txIdA, txIdB]); console.log(survivingId); // 保留下来的一条交易在实际集成中通常是先查询出疑似重复的交易例如通过getTransactions按时间范围取出交易后按金额、日期、payee 分组过滤再对每组恰好两条的重复项调用mergeTransactions完成去重。存活交易的判定规则官方文档明确说明传参顺序不决定哪条交易存活。判定规则packages/docs/docs/api/reference.md银行同步导入的交易优先于手动输入的交易被保留否则日期更早的交易被保留。这一规则在服务端 merge.ts 的determineKeepDrop函数中完整实现且优先级比文档描述得更细先看imported_id若其中一条有imported_id银行同步导入而另一条没有手动录入保留导入的那条再看imported_payee同样的逻辑优先保留有导入 payee 的一条最后比较日期a.date.localeCompare(b.date) 0时保留较早的一条。例如测试用例 merge.test.ts 验证了第一条是银行同步、第二条是手动的场景下保留银行同步值而it(two banksynced transactions keeps older transaction)L148则验证了两条都是银行同步导入时保留日期更早的那条。字段合并策略存活交易保留自身的字段值并用被删除交易中的值填补空字段packages/docs/docs/api/reference.mdThe surviving transaction keeps its own field values and fills in any empty ones from the deleted transaction. It is marked cleared if either transaction was.对应实现位于mergeTransactionsNoTransfermerge.tsawait db.updateTransaction({ id: keep.id, payee: keep.payee || drop.payee, category: keep.category || drop.category, notes: keep.notes || drop.notes, cleared: keep.cleared || drop.cleared, reconciled: keep.reconciled || drop.reconciled, schedule: keep.schedule || drop.schedule, } as TransactionEntity);可以看到采用保留方优先、||回退到被删方的合并策略payee、category、notes、cleared、reconciled、schedule 六个字段都会被合并其中cleared已清算状态只要任一方为真即保留。底层实现原理参数校验必须恰好两条且互不相同mergeTransactions入口merge.ts首先做数量校验const txIds transactions?.map(x x?.id).filter(Boolean) || []; if (txIds.length ! 2 || new Set(txIds).size ! 2) { throw new Error( Merging is only possible with 2 distinct transactions, but found JSON.stringify(transactions), ); }传入同一条交易两次new Set去重后不足 2或传入其他数量都会直接抛错。测试 merge.test.ts 专门验证了同一条交易传两次会失败。合并合法性校验通过数量校验后mapAndValidateTransactionsmerge.ts会读取两条交易的最新数据并调用共享模块 packages/loot-core/src/shared/merge.ts 中的validForMergeExplanation做合法性校验以下任一情况都会导致合并失败失败原因说明交易不存在两条交易中任意一条无法在数据库中取到属于不同账户account字段不一致金额不同amount字段不一致转账到不同账户两条都是转账都有transfer_id且 payee 不同例如 A→B 与 A→C 不能合并A→B 与 A→B 可以这部分校验逻辑被 UI 与 API 共用validForMerge是validForMergeExplanation的取反包装merge.ts保证界面上的合并按钮与 API 调用遵循同一套规则。转账transfer的特别处理合并涉及转账时逻辑更复杂merge.ts两条都不是转账无transfer_id时直接走mergeTransactionsNoTransfer任一条是转账时先把四条相关交易两条原交易 两条转账交易的transfer_id清空再合并转账mergeTransfers最后把存活交易重新关联回合并后的转账若转账目标是预算内on-budget账户且另一条不是转账还需清空存活交易的 category——因为预算内账户间的转账不应带分类merge.ts。测试transfer link is preserved on dropmerge.test.ts与merging two transfers selects the best transaction in each account to preserveL469覆盖了转账场景。拆分交易split的子交易迁移当被删除的交易带有拆分split子交易而存活交易没有时子交易会被重新指向存活交易并把它标记为父交易merge.ts随后用deleteTransaction的共享实现配合batchUpdateTransactions智能删除被删交易及其级联子交易merge.ts。测试 L353 验证了拆分交易与未分类的导入交易合并时保留拆分分类。服务端路由与撤销支持mergeTransactions在服务端注册为消息方法packages/loot-core/src/server/transactions/app.tsapp.method(transactions-merge, mutator(undoable(mergeTransactions)));app.method把transactions-merge映射到mergeTransactions实现API 层的send(api/transactions-merge, { ids })即通过这条通道调用mutator保证只有带写权限的会话能触发修改undoable表明合并操作进入撤销栈集成若误合并可在界面中撤销。类型声明同步维护在 app.ts确保transactions-merge的处理器签名与 API 层一致。典型应用场景重复交易去重mergeTransactions最常见的应用是银行同步与手动录入产生重复交易后的自动清理。合并判定中导入交易优先保留的规则imported_id/imported_payee优先正是为此设计自动对账时若发现同账户、同金额、相近日期出现两条交易一条来自同步、一条为手动补录集成脚本可以直接调用import { init, mergeTransactions, getTransactions } from actual-app/api; await init({ dataDir: /path/to/budget/data, serverURL: http://localhost:5006, }); const [txA, txB] getCandidates(); // 从 getTransactions 结果中识别出的疑似重复对 try { const keptId await mergeTransactions([txA.id, txB.id]); console.log(重复交易已合并保留 ${keptId}); } catch (e) { console.warn(合并失败, e.message); // 金额不同 / 不同账户 / 同 id 等 }由于合并失败会抛出带具体原因的Error来自 merge.ts 的validForMergeError集成侧可以捕获并记录失败原因交由人工处理避免盲目删除数据。适用前提与注意事项仅限同账户、同金额跨账户或金额不一致的交易无法合并这是 shared/merge.ts 的硬性校验必须恰好两条不同交易数量不等于 2 或传入重复 ID 都会抛错合并结果可撤销服务端以undoable注册误操作可回退版本前提该 API 属于 upcoming release见 upcoming-release-notes/api-merge-transactions.md需在包含此变更的 Actual 版本及对应版本的actual-app/api中才可用本文基于当前仓库源码packages/api/methods.ts与 API 参考文档packages/docs/docs/api/reference.md撰写。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考