Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/tests/test_bank_reconciliation.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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):
2the matcher, evidence immutability, and the resolution verbs.
3
4The control being tested is not "does it match things" but "can anyone make
5the evidence agree with the books by hand" -- the answer must be no, and
6every act of reconciliation must carry a name.
7"""
8
9import json
10import pathlib
11
12import object_execution
13import object_records
14import python_object_runtime
15from conftest import stage_collection
16
17REPO_ROOT = pathlib.Path(__file__).resolve().parents[1]
18PACKAGES = REPO_ROOT / "packages"
19BANKING_OBJECTS = PACKAGES / "app-banking" / "objects"
20RUNTIME = python_object_runtime.PythonObjectRuntime()
21
22ACCOUNT, ACCOUNT_2 = "bank-1", "bank-2"
23CASH, CASH_2 = "acct-cash", "acct-savings"
24FEES, INTEREST, AR, REV = "acct-fees", "acct-interest", "acct-ar", "acct-rev"
25DAN = {"user_id": "dan"}
26
27
28def 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
57def 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
65def 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
73def 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
80def 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
88def 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
99def line(data_dir, lid):
100 return object_records.get_collection_record("bank_lines", lid, base_dir=data_dir)
101
102
103def journals(data_dir):
104 return object_records.read_collection_records("fin_journals", base_dir=data_dir)
105
106
107def 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
115def 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
129def 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
144def 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
158def 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
176def 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
187def 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
194def 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
213def 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
224def 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
247def 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
265def 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
275def 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
287def 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
310def 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
319def 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
341def 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"]