askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
test_bank_reconciliation.py · 16.0 KB · 349 lines
| 1 | """Bank reconciliation (plan/bank-import-reconciliation-spec.md, slice 2): |
| 2 | the matcher, evidence immutability, and the resolution verbs. |
| 3 | |
| 4 | The control being tested is not "does it match things" but "can anyone make |
| 5 | the evidence agree with the books by hand" -- the answer must be no, and |
| 6 | every act of reconciliation must carry a name. |
| 7 | """ |
| 8 | |
| 9 | import json |
| 10 | import pathlib |
| 11 | |
| 12 | import object_execution |
| 13 | import object_records |
| 14 | import python_object_runtime |
| 15 | from conftest import stage_collection |
| 16 | |
| 17 | REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] |
| 18 | PACKAGES = REPO_ROOT / "packages" |
| 19 | BANKING_OBJECTS = PACKAGES / "app-banking" / "objects" |
| 20 | RUNTIME = python_object_runtime.PythonObjectRuntime() |
| 21 | |
| 22 | ACCOUNT, ACCOUNT_2 = "bank-1", "bank-2" |
| 23 | CASH, CASH_2 = "acct-cash", "acct-savings" |
| 24 | FEES, INTEREST, AR, REV = "acct-fees", "acct-interest", "acct-ar", "acct-rev" |
| 25 | DAN = {"user_id": "dan"} |
| 26 | |
| 27 | |
| 28 | def setup_env(tmp_path, monkeypatch, *, settings=()): |
| 29 | data_dir = tmp_path / "data" |
| 30 | wanted = [("app-banking", "value_accounts"), ("app-banking", "bank_import_profiles"), |
| 31 | ("app-banking", "bank_statement_imports"), ("app-banking", "bank_lines"), |
| 32 | ("app-finance", "fin_accounts"), ("app-finance", "fin_journals"), |
| 33 | ("app-finance", "fin_journal_lines"), |
| 34 | ("app-payments", "payments"), ("app-payments", "refunds"), |
| 35 | ("app-invoices", "invoices")] |
| 36 | for pkg, name in wanted: |
| 37 | stage_collection(data_dir, pkg, name) |
| 38 | |
| 39 | rows = "" |
| 40 | for i, (k, v) in enumerate(settings): |
| 41 | rows += f"s{i}\t{k}\t{v}\t\n" |
| 42 | stage_collection(data_dir, "app-settings", "app_settings", rows=rows) |
| 43 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 44 | |
| 45 | for acct, kind in ((CASH, "asset"), (CASH_2, "asset"), (FEES, "expense"), |
| 46 | (INTEREST, "income"), (AR, "asset"), (REV, "income")): |
| 47 | object_records.create_collection_record( |
| 48 | "fin_accounts", {"id": acct, "name": acct, "account_type": kind, |
| 49 | "owner_id": "dan"}, base_dir=data_dir) |
| 50 | for bank, cash, name in ((ACCOUNT, CASH, "Checking"), (ACCOUNT_2, CASH_2, "Savings")): |
| 51 | object_records.create_collection_record( |
| 52 | "value_accounts", {"id": bank, "name": name, "fin_account_id": cash, |
| 53 | "owner_id": "dan"}, base_dir=data_dir) |
| 54 | return data_dir |
| 55 | |
| 56 | |
| 57 | def make_line(data_dir, lid, *, amount, on="2026-07-02", desc="", account=ACCOUNT, **extra): |
| 58 | rec = {"id": lid, "bank_account_id": account, "posted_on": on, |
| 59 | "amount_cents": str(amount), "description": desc, "raw": f"raw:{desc}", |
| 60 | "line_hash": f"h-{lid}", "match_status": "unmatched", "owner_id": "dan"} |
| 61 | rec.update(extra) |
| 62 | return object_records.create_collection_record("bank_lines", rec, base_dir=data_dir) |
| 63 | |
| 64 | |
| 65 | def make_payment(data_dir, pid, *, cents, on="2026-07-02", reference="", invoice="inv1"): |
| 66 | return object_records.create_collection_record( |
| 67 | "payments", |
| 68 | {"id": pid, "invoice_id": invoice, "amount_cents": str(cents), "method": "card", |
| 69 | "received_on": on, "reference": reference, "status": "received", "owner_id": "dan"}, |
| 70 | base_dir=data_dir) |
| 71 | |
| 72 | |
| 73 | def make_invoice(data_dir, iid="inv1"): |
| 74 | return object_records.create_collection_record( |
| 75 | "invoices", {"id": iid, "number": "N-1", "customer_name": "Acme", |
| 76 | "status": "sent", "total_cents": "500000", "owner_id": "dan"}, |
| 77 | base_dir=data_dir) |
| 78 | |
| 79 | |
| 80 | def run_object(object_id, payload, method="POST"): |
| 81 | return object_execution.execute_object( |
| 82 | RUNTIME, |
| 83 | object_execution.ObjectExecutionRequest( |
| 84 | object_id, method=method, payload={"_identity": DAN, **payload}), |
| 85 | roots=[BANKING_OBJECTS]).result |
| 86 | |
| 87 | |
| 88 | def hook(action, record=None, existing=None, changes=None): |
| 89 | return object_execution.execute_object( |
| 90 | RUNTIME, |
| 91 | object_execution.ObjectExecutionRequest( |
| 92 | "hook_bank_lines", method="BEFORE_WRITE", |
| 93 | payload={"action": action, "collection": "bank_lines", |
| 94 | "record": record or {}, "existing": existing or {}, |
| 95 | "changes": changes or {}}), |
| 96 | roots=[BANKING_OBJECTS]).result |
| 97 | |
| 98 | |
| 99 | def line(data_dir, lid): |
| 100 | return object_records.get_collection_record("bank_lines", lid, base_dir=data_dir) |
| 101 | |
| 102 | |
| 103 | def journals(data_dir): |
| 104 | return object_records.read_collection_records("fin_journals", base_dir=data_dir) |
| 105 | |
| 106 | |
| 107 | def lines_for(data_dir, journal_id): |
| 108 | return {l["account_id"]: l for l in |
| 109 | object_records.read_collection_records("fin_journal_lines", base_dir=data_dir) |
| 110 | if l["journal_id"] == journal_id} |
| 111 | |
| 112 | |
| 113 | # --- the matcher -------------------------------------------------------------- |
| 114 | |
| 115 | def test_reference_plus_amount_auto_matches_at_tier_1(tmp_path, monkeypatch): |
| 116 | data_dir = setup_env(tmp_path, monkeypatch) |
| 117 | make_invoice(data_dir) |
| 118 | make_payment(data_dir, "p1", cents=150000, reference="INV-1001") |
| 119 | make_line(data_dir, "L1", amount=150000, desc="ACME CORP PAYMENT INV-1001") |
| 120 | |
| 121 | result = run_object("system_bank_matcher", {}) |
| 122 | assert result["auto_matched"] == 1 |
| 123 | row = line(data_dir, "L1") |
| 124 | assert row["match_status"] == "matched" |
| 125 | assert row["matched_to"] == "payments/p1" |
| 126 | assert json.loads(row["suggestions"])[0]["tier"] == 1 |
| 127 | |
| 128 | |
| 129 | def test_amount_only_is_suggested_never_auto_matched(tmp_path, monkeypatch): |
| 130 | data_dir = setup_env(tmp_path, monkeypatch) |
| 131 | make_invoice(data_dir) |
| 132 | make_payment(data_dir, "p1", cents=150000, on="2026-07-01", reference="INV-9999") |
| 133 | make_line(data_dir, "L1", amount=150000, on="2026-07-02", desc="DEPOSIT") |
| 134 | |
| 135 | result = run_object("system_bank_matcher", {}) |
| 136 | assert result["auto_matched"] == 0 and result["suggested"] == 1 |
| 137 | row = line(data_dir, "L1") |
| 138 | assert row["match_status"] == "suggested" |
| 139 | assert row["matched_to"] == "" # a suggestion is not a decision |
| 140 | proposal = json.loads(row["suggestions"])[0] |
| 141 | assert proposal["tier"] == 2 and proposal["refs"] == ["payments/p1"] |
| 142 | |
| 143 | |
| 144 | def test_batched_deposit_is_proposed_as_a_combination(tmp_path, monkeypatch): |
| 145 | data_dir = setup_env(tmp_path, monkeypatch) |
| 146 | make_invoice(data_dir) |
| 147 | make_payment(data_dir, "p1", cents=60000) |
| 148 | make_payment(data_dir, "p2", cents=90000) |
| 149 | make_line(data_dir, "L1", amount=150000, desc="BATCH DEPOSIT") |
| 150 | |
| 151 | run_object("system_bank_matcher", {}) |
| 152 | proposals = json.loads(line(data_dir, "L1")["suggestions"]) |
| 153 | combo = [p for p in proposals if p["tier"] == 3] |
| 154 | assert combo and sorted(combo[0]["refs"]) == ["payments/p1", "payments/p2"] |
| 155 | assert line(data_dir, "L1")["match_status"] == "suggested" |
| 156 | |
| 157 | |
| 158 | def test_out_of_window_and_claimed_records_are_not_proposed(tmp_path, monkeypatch): |
| 159 | data_dir = setup_env(tmp_path, monkeypatch, |
| 160 | settings=(("reconcile.date_window_days", "2"),)) |
| 161 | make_invoice(data_dir) |
| 162 | make_payment(data_dir, "p1", cents=150000, on="2026-06-01") # far outside the window |
| 163 | make_line(data_dir, "L1", amount=150000, on="2026-07-02", desc="DEPOSIT") |
| 164 | assert run_object("system_bank_matcher", {})["suggested"] == 0 |
| 165 | |
| 166 | make_payment(data_dir, "p2", cents=150000, on="2026-07-02", reference="INV-1001") |
| 167 | make_line(data_dir, "L2", amount=150000, on="2026-07-02", desc="PAYMENT INV-1001") |
| 168 | make_line(data_dir, "L3", amount=150000, on="2026-07-02", desc="PAYMENT INV-1001") |
| 169 | run_object("system_bank_matcher", {}) |
| 170 | # One book record cannot satisfy two bank lines. |
| 171 | matched = [l for l in object_records.read_collection_records("bank_lines", base_dir=data_dir) |
| 172 | if l.get("matched_to") == "payments/p2"] |
| 173 | assert len(matched) == 1 |
| 174 | |
| 175 | |
| 176 | def test_auto_match_can_be_switched_off_entirely(tmp_path, monkeypatch): |
| 177 | data_dir = setup_env(tmp_path, monkeypatch, |
| 178 | settings=(("reconcile.auto_match_tier", "0"),)) |
| 179 | make_invoice(data_dir) |
| 180 | make_payment(data_dir, "p1", cents=150000, reference="INV-1001") |
| 181 | make_line(data_dir, "L1", amount=150000, desc="PAYMENT INV-1001") |
| 182 | result = run_object("system_bank_matcher", {}) |
| 183 | assert result["auto_matched"] == 0 and result["suggested"] == 1 |
| 184 | assert line(data_dir, "L1")["match_status"] == "suggested" |
| 185 | |
| 186 | |
| 187 | def test_matcher_is_a_no_op_without_banking_data(tmp_path, monkeypatch): |
| 188 | setup_env(tmp_path, monkeypatch) |
| 189 | assert run_object("system_bank_matcher", {})["scanned"] == 0 |
| 190 | |
| 191 | |
| 192 | # --- evidence immutability ---------------------------------------------------- |
| 193 | |
| 194 | def test_the_bank_words_cannot_be_edited(tmp_path, monkeypatch): |
| 195 | data_dir = setup_env(tmp_path, monkeypatch) |
| 196 | make_line(data_dir, "L1", amount=150000, desc="ACME CORP PAYMENT") |
| 197 | existing = line(data_dir, "L1") |
| 198 | |
| 199 | for field, value in (("amount_cents", "140000"), ("posted_on", "2026-07-03"), |
| 200 | ("description", "SOMETHING ELSE"), ("raw", "tampered"), |
| 201 | ("bank_account_id", ACCOUNT_2)): |
| 202 | outcome = hook("update", existing=existing, changes={field: value}) |
| 203 | assert outcome["status"] == 409, field |
| 204 | assert "cannot be edited" in outcome["error"] |
| 205 | |
| 206 | # Reconciliation work on the same record is allowed. |
| 207 | assert hook("update", existing=existing, |
| 208 | changes={"match_status": "matched", "matched_to": "payments/p1"}) is None |
| 209 | assert hook("update", existing=existing, |
| 210 | changes={"resolved_as": "fee", "match_status": "resolved"}) is None |
| 211 | |
| 212 | |
| 213 | def test_matched_requires_a_well_formed_target(tmp_path, monkeypatch): |
| 214 | data_dir = setup_env(tmp_path, monkeypatch) |
| 215 | make_line(data_dir, "L1", amount=150000) |
| 216 | existing = line(data_dir, "L1") |
| 217 | bare = hook("update", existing=existing, changes={"match_status": "matched"}) |
| 218 | assert bare["status"] == 400 and "matched_to" in bare["error"] |
| 219 | malformed = hook("update", existing=existing, |
| 220 | changes={"match_status": "matched", "matched_to": "p1"}) |
| 221 | assert malformed["status"] == 400 |
| 222 | |
| 223 | |
| 224 | def test_confirming_a_match_is_an_ordinary_attributed_update(tmp_path, monkeypatch): |
| 225 | """Deliberately NOT an action object: a normal write already carries the |
| 226 | actor into the change log, which is what makes reconciliation auditable.""" |
| 227 | data_dir = setup_env(tmp_path, monkeypatch) |
| 228 | make_invoice(data_dir) |
| 229 | make_payment(data_dir, "p1", cents=150000) |
| 230 | make_line(data_dir, "L1", amount=150000, desc="DEPOSIT") |
| 231 | run_object("system_bank_matcher", {}) |
| 232 | |
| 233 | object_records.update_collection_record( |
| 234 | "bank_lines", "L1", {"match_status": "matched", "matched_to": "payments/p1"}, |
| 235 | base_dir=data_dir, actor="dan") |
| 236 | assert line(data_dir, "L1")["match_status"] == "matched" |
| 237 | import object_record_changes |
| 238 | entries = object_record_changes.list_record_changes( |
| 239 | "bank_lines", record_id="L1", base_dir=data_dir)["changes"] |
| 240 | confirmations = [e for e in entries |
| 241 | if "match_status" in (e.get("changed_fields") or [])] |
| 242 | assert confirmations and confirmations[0]["actor"] == "dan" |
| 243 | |
| 244 | |
| 245 | # --- resolution verbs --------------------------------------------------------- |
| 246 | |
| 247 | def test_fee_composes_a_posted_journal_and_is_idempotent(tmp_path, monkeypatch): |
| 248 | data_dir = setup_env(tmp_path, monkeypatch, |
| 249 | settings=(("reconcile.journal.fees_account", FEES),)) |
| 250 | make_line(data_dir, "L1", amount=-2500, desc="MONTHLY SERVICE FEE") |
| 251 | |
| 252 | result = run_object("action_resolve_bank_line", {"line_id": "L1", "kind": "fee"}) |
| 253 | assert result["status"] == 200 and result["journal"]["posted"] is True |
| 254 | row = line(data_dir, "L1") |
| 255 | assert row["match_status"] == "resolved" and row["resolved_as"] == "fee" |
| 256 | booked = lines_for(data_dir, result["journal"]["journal_id"]) |
| 257 | assert booked[FEES]["debit_cents"] == "2500" |
| 258 | assert booked[CASH]["credit_cents"] == "2500" |
| 259 | |
| 260 | again = run_object("action_resolve_bank_line", {"line_id": "L1", "kind": "fee"}) |
| 261 | assert again["status"] == 409 # already resolved |
| 262 | assert len(journals(data_dir)) == 1 |
| 263 | |
| 264 | |
| 265 | def test_interest_books_the_other_direction(tmp_path, monkeypatch): |
| 266 | data_dir = setup_env(tmp_path, monkeypatch, |
| 267 | settings=(("reconcile.journal.interest_account", INTEREST),)) |
| 268 | make_line(data_dir, "L1", amount=812, desc="INTEREST PAID") |
| 269 | result = run_object("action_resolve_bank_line", {"line_id": "L1", "kind": "interest"}) |
| 270 | booked = lines_for(data_dir, result["journal"]["journal_id"]) |
| 271 | assert booked[CASH]["debit_cents"] == "812" |
| 272 | assert booked[INTEREST]["credit_cents"] == "812" |
| 273 | |
| 274 | |
| 275 | def test_transfer_moves_between_two_own_accounts(tmp_path, monkeypatch): |
| 276 | data_dir = setup_env(tmp_path, monkeypatch) |
| 277 | make_line(data_dir, "L1", amount=-100000, desc="TRANSFER TO SAVINGS") |
| 278 | result = run_object("action_resolve_bank_line", |
| 279 | {"line_id": "L1", "kind": "transfer", |
| 280 | "counterpart_bank_account_id": ACCOUNT_2}) |
| 281 | assert result["status"] == 200 |
| 282 | booked = lines_for(data_dir, result["journal"]["journal_id"]) |
| 283 | assert booked[CASH_2]["debit_cents"] == "100000" # money into savings |
| 284 | assert booked[CASH]["credit_cents"] == "100000" # out of checking |
| 285 | |
| 286 | |
| 287 | def test_nsf_bounces_the_payment_and_reverses_its_journal(tmp_path, monkeypatch): |
| 288 | data_dir = setup_env(tmp_path, monkeypatch, settings=( |
| 289 | ("payments.accounting_basis", "cash"), |
| 290 | ("payments.journal.cash_account", CASH), |
| 291 | ("payments.journal.revenue_account", REV))) |
| 292 | make_invoice(data_dir) |
| 293 | make_payment(data_dir, "p1", cents=150000, reference="INV-1001") |
| 294 | make_line(data_dir, "L1", amount=-150000, desc="RETURNED ITEM NSF") |
| 295 | |
| 296 | result = run_object("action_resolve_bank_line", |
| 297 | {"line_id": "L1", "kind": "nsf", "payment_id": "p1"}) |
| 298 | assert result["status"] == 200 |
| 299 | payment = object_records.get_collection_record("payments", "p1", base_dir=data_dir) |
| 300 | assert payment["status"] == "bounced" |
| 301 | reversal = [j for j in journals(data_dir) |
| 302 | if j["generated_from"] == "payments/p1:bounced"] |
| 303 | assert reversal and reversal[0]["kind"] == "reversing" |
| 304 | booked = lines_for(data_dir, reversal[0]["id"]) |
| 305 | assert booked[REV]["debit_cents"] == "150000" # revenue reversed |
| 306 | assert booked[CASH]["credit_cents"] == "150000" # cash taken back out |
| 307 | assert line(data_dir, "L1")["matched_to"] == "payments/p1" |
| 308 | |
| 309 | |
| 310 | def test_timing_items_carry_forward_without_a_journal(tmp_path, monkeypatch): |
| 311 | data_dir = setup_env(tmp_path, monkeypatch) |
| 312 | make_line(data_dir, "L1", amount=50000, desc="DEPOSIT IN TRANSIT") |
| 313 | result = run_object("action_resolve_bank_line", {"line_id": "L1", "kind": "timing"}) |
| 314 | assert result["status"] == 200 and result["journal"] is None |
| 315 | assert line(data_dir, "L1")["resolved_as"] == "timing" |
| 316 | assert journals(data_dir) == [] |
| 317 | |
| 318 | |
| 319 | def test_resolution_refusals(tmp_path, monkeypatch): |
| 320 | data_dir = setup_env(tmp_path, monkeypatch) |
| 321 | make_line(data_dir, "L1", amount=-2500, desc="FEE") |
| 322 | # Unconfigured expense account: refuse rather than post to nowhere. |
| 323 | assert run_object("action_resolve_bank_line", |
| 324 | {"line_id": "L1", "kind": "fee"})["status"] == 409 |
| 325 | assert run_object("action_resolve_bank_line", |
| 326 | {"line_id": "L1", "kind": "nonsense"})["status"] == 400 |
| 327 | assert run_object("action_resolve_bank_line", |
| 328 | {"line_id": "missing", "kind": "fee"})["status"] == 404 |
| 329 | # A transfer with no counterpart named. |
| 330 | assert run_object("action_resolve_bank_line", |
| 331 | {"line_id": "L1", "kind": "transfer"})["status"] == 400 |
| 332 | anon = object_execution.execute_object( |
| 333 | RUNTIME, |
| 334 | object_execution.ObjectExecutionRequest( |
| 335 | "action_resolve_bank_line", method="POST", |
| 336 | payload={"line_id": "L1", "kind": "timing"}), |
| 337 | roots=[BANKING_OBJECTS]).result |
| 338 | assert anon["status"] == 403 |
| 339 | |
| 340 | |
| 341 | def test_a_bank_account_without_a_book_account_cannot_post(tmp_path, monkeypatch): |
| 342 | data_dir = setup_env(tmp_path, monkeypatch, |
| 343 | settings=(("reconcile.journal.fees_account", FEES),)) |
| 344 | object_records.create_collection_record( |
| 345 | "value_accounts", {"id": "bank-3", "name": "Unlinked", "owner_id": "dan"}, |
| 346 | base_dir=data_dir) |
| 347 | make_line(data_dir, "L9", amount=-2500, desc="FEE", account="bank-3") |
| 348 | outcome = run_object("action_resolve_bank_line", {"line_id": "L9", "kind": "fee"}) |
| 349 | assert outcome["status"] == 409 and "fin_account_id" in outcome["error"] |