feat: reserve Bank Transactions for Edit in Full Page drafts (backport #400)

[mergify]

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.

---

This is an automatic backport of pull request #400 done by [Mergify](https://mergify.com).

[barredterra]

@greptileai

[greptile-apps]

Confidence Score: 5/5

Safe to merge — the reservation and reconciliation logic is well-designed, the previous destructuring bug is fixed, and all reconciliation paths are guarded server-side with row locks.

The core locking design (SELECT FOR UPDATE held across insert + db_set within a single DB transaction) correctly prevents double-reservations even under concurrent requests. on_submit and on_trash hooks release or reconcile atomically. The JS layer correctly assigns the transaction array without destructuring and uses named handlers to avoid listener leaks. Test coverage for the new paths is thorough.

No files require special attention — the two observations are about an unused method alias and an unguarded write to a Frappe internal Set, neither of which affects the happy path.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant UI as Browser / UI
    participant BRT as BRT Python API
    participant BT as Bank Transaction (DB)
    participant JE as Journal / Payment Entry (DB)
    participant Hook as on_submit Hook

    UI->>BRT: "create_journal_entry_bts(allow_edit=True)"
    BRT->>BT: SELECT FOR UPDATE (row lock)
    BRT->>JE: "insert draft (created_from_bank_transaction=BT)"
    BRT->>BT: "db_set reserved_voucher=JE (locked)"
    BRT-->>UI: return draft JE + reload_transactions()
    UI->>UI: show reserved BT row with Draft badge
    UI->>UI: watch_voucher_until_settled(JE)

    Note over UI,BT: User edits and submits JE in new tab

    UI->>UI: on_voucher_doc_update / focus fallback
    UI->>UI: "check_voucher_settled -> handle_voucher_settled"
    UI->>UI: unwatch + reload_transactions()

    JE-->>Hook: on_submit fires reconcile_created_from_bank_transaction
    Hook->>BT: SELECT FOR UPDATE
    Hook->>BT: reconcile_paid_vouchers (add payment row)
    Hook->>BT: clear reserved_voucher, save()
    Hook->>BT: release row lock on commit

    Note over UI,BT: Delete draft path

    JE-->>Hook: on_trash fires release_bank_transaction_reservation
    Hook->>BT: SELECT FOR UPDATE
    Hook->>BT: "db_set reserved_voucher=None"
    Hook->>BT: release row lock on commit
    UI->>UI: "check_voucher_settled(!exists) -> reload"

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 UI as Browser / UI
    participant BRT as BRT Python API
    participant BT as Bank Transaction (DB)
    participant JE as Journal / Payment Entry (DB)
    participant Hook as on_submit Hook

    UI->>BRT: "create_journal_entry_bts(allow_edit=True)"
    BRT->>BT: SELECT FOR UPDATE (row lock)
    BRT->>JE: "insert draft (created_from_bank_transaction=BT)"
    BRT->>BT: "db_set reserved_voucher=JE (locked)"
    BRT-->>UI: return draft JE + reload_transactions()
    UI->>UI: show reserved BT row with Draft badge
    UI->>UI: watch_voucher_until_settled(JE)

    Note over UI,BT: User edits and submits JE in new tab

    UI->>UI: on_voucher_doc_update / focus fallback
    UI->>UI: "check_voucher_settled -> handle_voucher_settled"
    UI->>UI: unwatch + reload_transactions()

    JE-->>Hook: on_submit fires reconcile_created_from_bank_transaction
    Hook->>BT: SELECT FOR UPDATE
    Hook->>BT: reconcile_paid_vouchers (add payment row)
    Hook->>BT: clear reserved_voucher, save()
    Hook->>BT: release row lock on commit

    Note over UI,BT: Delete draft path

    JE-->>Hook: on_trash fires release_bank_transaction_reservation
    Hook->>BT: SELECT FOR UPDATE
    Hook->>BT: "db_set reserved_voucher=None"
    Hook->>BT: release row lock on commit
    UI->>UI: "check_voucher_settled(!exists) -> reload"

Loading

_{Reviews (2): Last reviewed commit: "fix: reload_transactions" | Re-trigger Greptile}

[barredterra]

Tested, works as expected

[barredterra]

🎉 This PR is included in version 16.2.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀