feat: reserve Bank Transactions for Edit in Full Page drafts

[barredterra]

Motivation

Edit in Full Page opened a draft voucher in another tab and relied on a fragile desk doc_update listener to reconcile afterward. Background tabs drop sockets, reconnect does not reliably rejoin document rooms, and blanket frappe.realtime.off("doc_update") could wipe unrelated listeners — leaving submitted vouchers unlinked or a stale list.

Approach

Create drafts now store durable provenance (created_from_bank_transaction) and exclusively reserve the Bank Transaction in the same SQL transaction. Submit reconciles on the server under a row lock and clears the reservation; deleting the draft releases it. The tool keeps reserved transactions in the list with a Draft badge, hides Match Voucher, and only links to the existing draft. Realtime watches (named handlers) refresh the list on submit/delete, with focus/route as fallback.

[greptile-apps]

Confidence Score: 5/5

The PR is safe to merge. The reservation mechanism is correctly serialized with SQL row locks, all Python callers of the changed get_bank_transactions return shape have been updated, and 12 new tests exercise the full reserve/submit/delete lifecycle including failure rollback.

The core locking strategy is sound: for_update=True is acquired before the reservation check and held through the db_set, preventing races between concurrent Edit-in-Full-Page creates. The dual enforcement layers correctly allow the reserved voucher through while blocking all others. The JS backward-compat shim handles the response shape change cleanly. Only two cosmetic findings were flagged: a missing unreachable return after frappe.throw in the typed helper, and an unused clear_voucher_watch alias. Neither affects runtime behavior.

No files require special attention.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant U as User (Browser)
    participant JS as PanelManager / CreateTab
    participant API as bank_reconciliation_tool_beta.py
    participant VR as voucher_reconciliation.py
    participant BT as Bank Transaction (DB)
    participant JE as Journal Entry (DB)

    note over U,BT: Edit-in-Full-Page Create Draft
    U->>JS: "Click Create Voucher allow_edit=True"
    JS->>API: create_journal_entry_bts
    API->>BT: SELECT FOR UPDATE row lock
    API->>JE: journal_entry.insert draft
    API->>BT: db_set reserved_voucher fields
    API-->>JS: return journal_entry
    JS->>JS: reload_transactions Draft badge
    JS->>JS: watch_voucher_until_settled
    JS->>U: open JE in new tab

    note over U,BT: User submits JE
    U->>JE: submit
    JE->>VR: on_submit hook
    VR->>BT: SELECT FOR UPDATE row lock
    VR->>VR: get_voucher_bank_amount validate
    VR->>BT: reconcile_paid_vouchers clear reservation
    VR->>BT: save allocate set_status

    note over JS,BT: Refresh
    JS->>JS: doc_update or focus check
    JS->>JS: reload_transactions

    note over U,BT: Alt User deletes draft
    U->>JE: delete
    JE->>VR: on_trash hook
    VR->>BT: SELECT FOR UPDATE
    VR->>BT: db_set reserved_voucher None
    JS->>JS: reload_transactions

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant U as User (Browser)
    participant JS as PanelManager / CreateTab
    participant API as bank_reconciliation_tool_beta.py
    participant VR as voucher_reconciliation.py
    participant BT as Bank Transaction (DB)
    participant JE as Journal Entry (DB)

    note over U,BT: Edit-in-Full-Page Create Draft
    U->>JS: "Click Create Voucher allow_edit=True"
    JS->>API: create_journal_entry_bts
    API->>BT: SELECT FOR UPDATE row lock
    API->>JE: journal_entry.insert draft
    API->>BT: db_set reserved_voucher fields
    API-->>JS: return journal_entry
    JS->>JS: reload_transactions Draft badge
    JS->>JS: watch_voucher_until_settled
    JS->>U: open JE in new tab

    note over U,BT: User submits JE
    U->>JE: submit
    JE->>VR: on_submit hook
    VR->>BT: SELECT FOR UPDATE row lock
    VR->>VR: get_voucher_bank_amount validate
    VR->>BT: reconcile_paid_vouchers clear reservation
    VR->>BT: save allocate set_status

    note over JS,BT: Refresh
    JS->>JS: doc_update or focus check
    JS->>JS: reload_transactions

    note over U,BT: Alt User deletes draft
    U->>JE: delete
    JE->>VR: on_trash hook
    VR->>BT: SELECT FOR UPDATE
    VR->>BT: db_set reserved_voucher None
    JS->>JS: reload_transactions

Loading

_{Reviews (2): Last reviewed commit: "fix(reconciliation): use reconcile_paid_..." | Re-trigger Greptile}

[barredterra]

@Mergifyio backport version-16-hotfix

[mergify]

backport version-16-hotfix

✅ Backports have been created

Details

• #401 feat: reserve Bank Transactions for Edit in Full Page drafts (backport #400) has been created for branch version-16-hotfix but encountered conflicts

Cherry-pick of b0c03af has failed:

On branch mergify/bp/version-16-hotfix/pr-400
Your branch is up to date with 'origin/version-16-hotfix'.

You are currently cherry-picking commit b0c03af.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	modified:   banking/custom_fields.py
	modified:   banking/hooks.py
	modified:   banking/klarna_kosma_integration/doctype/bank_reconciliation_tool_beta/bank_reconciliation_tool_beta.js
	modified:   banking/klarna_kosma_integration/doctype/bank_reconciliation_tool_beta/test_bank_reconciliation_tool_beta.py
	new file:   banking/overrides/voucher_reconciliation.py
	new file:   banking/patches/add_voucher_reservation_fields.py
	modified:   banking/public/js/bank_reconciliation_beta/actions_panel/actions_panel_manager.js
	modified:   banking/public/scss/bank_reconciliation_beta.scss

Unmerged paths:
  (use "git add <file>..." to mark resolution)
	both modified:   banking/klarna_kosma_integration/doctype/bank_reconciliation_tool_beta/bank_reconciliation_tool_beta.py
	both modified:   banking/overrides/bank_transaction.py
	both modified:   banking/patches.txt
	both modified:   banking/public/js/bank_reconciliation_beta/actions_panel/create_tab.js
	both modified:   banking/public/js/bank_reconciliation_beta/panel_manager.js

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

[barredterra]

🎉 This PR is included in version 15.36.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀