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_books_spine.py · 13.5 KB · 312 lines
| 1 | """Books spine (plan/books-spine-spec.md): the billing ledger composes real |
| 2 | double-entry journals — payment/refund/bounce/issue composers (system_books, |
| 3 | an event handler), the Reverse action on posted journals, and the |
| 4 | fin_recurring runner (the schema that shipped without an engine). |
| 5 | |
| 6 | All reactions per docs/logic-decisions.md #6: post-commit, best-effort, |
| 7 | idempotent by generated_from provenance, balanced by construction and |
| 8 | re-verified before posting. |
| 9 | """ |
| 10 | |
| 11 | import json |
| 12 | import pathlib |
| 13 | |
| 14 | import object_execution |
| 15 | import object_records |
| 16 | import python_object_runtime |
| 17 | from conftest import schema_header, stage_collection |
| 18 | |
| 19 | REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] |
| 20 | PACKAGES = REPO_ROOT / "packages" |
| 21 | |
| 22 | CASH, AR, REV = "acct-cash", "acct-ar", "acct-rev" |
| 23 | |
| 24 | |
| 25 | def setup_env(tmp_path, monkeypatch, *, basis="cash", configured=True, books=True): |
| 26 | data_dir = tmp_path / "data" |
| 27 | |
| 28 | # inv1 is seeded straight into the TSV (not via create_collection_record) |
| 29 | # so every test starts from the same draft invoice with no payments yet |
| 30 | # -- pin the row to the real schema's field order so a later schema |
| 31 | # edit can't silently shift these values into the wrong columns. |
| 32 | invoice_fields = schema_header("app-invoices", "invoices").strip("\n").split("\t") |
| 33 | invoice_values = {"id": "inv1", "number": "INV-1", "customer_name": "Acme", |
| 34 | "status": "draft", "issue_date": "2026-07-01", |
| 35 | "total_cents": "10000", "owner_id": "dan"} |
| 36 | invoice_row = "\t".join(invoice_values.get(f, "") for f in invoice_fields) + "\n" |
| 37 | stage_collection(data_dir, "app-invoices", "invoices", rows=invoice_row) |
| 38 | |
| 39 | stage_collection(data_dir, "app-payments", "payments") |
| 40 | stage_collection(data_dir, "app-payments", "refunds") |
| 41 | |
| 42 | settings = f"s0\tpayments.accounting_basis\t{basis}\t\n" |
| 43 | if configured: |
| 44 | settings += (f"s1\tpayments.journal.cash_account\t{CASH}\t\n" |
| 45 | f"s2\tpayments.journal.receivable_account\t{AR}\t\n" |
| 46 | f"s3\tpayments.journal.revenue_account\t{REV}\t\n") |
| 47 | stage_collection(data_dir, "app-settings", "app_settings", rows=settings) |
| 48 | |
| 49 | if books: |
| 50 | # CASH/AR/REV are likewise seeded straight into the TSV (a chart of |
| 51 | # accounts every test in this file can rely on existing already); |
| 52 | # same field-order pinning as the invoice row above. |
| 53 | account_fields = schema_header("app-finance", "fin_accounts").strip("\n").split("\t") |
| 54 | |
| 55 | def account_row(account_id, name, account_type): |
| 56 | values = {"id": account_id, "name": name, "account_type": account_type, |
| 57 | "owner_id": "dan"} |
| 58 | return "\t".join(values.get(f, "") for f in account_fields) + "\n" |
| 59 | |
| 60 | accounts = (account_row(CASH, "Cash", "asset") |
| 61 | + account_row(AR, "AR", "asset") |
| 62 | + account_row(REV, "Revenue", "income")) |
| 63 | stage_collection(data_dir, "app-finance", "fin_accounts", rows=accounts) |
| 64 | stage_collection(data_dir, "app-finance", "fin_journals") |
| 65 | stage_collection(data_dir, "app-finance", "fin_journal_lines") |
| 66 | stage_collection(data_dir, "app-finance", "fin_recurring") |
| 67 | |
| 68 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(data_dir)) |
| 69 | monkeypatch.setenv("DBBASIC_OBJECTS_DIR", str(tmp_path / "objects-unused")) |
| 70 | return data_dir |
| 71 | |
| 72 | |
| 73 | RUNTIME = python_object_runtime.PythonObjectRuntime() |
| 74 | |
| 75 | |
| 76 | def fire(collection, record_id, action): |
| 77 | # Mirror the REAL dispatcher payload: event name uses the participle, |
| 78 | # the action field carries the RAW verb ("create") -- the mismatch that |
| 79 | # slipped past the first version of these tests and skipped in prod. |
| 80 | raw = {"created": "create", "updated": "update", "deleted": "delete"}[action] |
| 81 | return object_execution.execute_object( |
| 82 | RUNTIME, |
| 83 | object_execution.ObjectExecutionRequest( |
| 84 | "system_books", method="EVENT", |
| 85 | payload={"event": f"{collection}.record.{action}", |
| 86 | "collection": collection, "record_id": record_id, |
| 87 | "action": raw}, |
| 88 | ), |
| 89 | roots=[PACKAGES / "app-payments" / "objects"], |
| 90 | ) |
| 91 | |
| 92 | |
| 93 | def run_action(object_id, payload, root): |
| 94 | return object_execution.execute_object( |
| 95 | RUNTIME, |
| 96 | object_execution.ObjectExecutionRequest(object_id, method="POST", payload=payload), |
| 97 | roots=[PACKAGES / "app-finance" / "objects" / ".."], # finance objects root |
| 98 | ) |
| 99 | |
| 100 | |
| 101 | def journals(data_dir): |
| 102 | return object_records.read_collection_records("fin_journals", base_dir=data_dir) |
| 103 | |
| 104 | |
| 105 | def lines_for(data_dir, journal_id): |
| 106 | return [l for l in object_records.read_collection_records("fin_journal_lines", base_dir=data_dir) |
| 107 | if l["journal_id"] == journal_id] |
| 108 | |
| 109 | |
| 110 | def make_payment(data_dir, pid="p1", cents="4000", status="received"): |
| 111 | return object_records.create_collection_record( |
| 112 | "payments", |
| 113 | {"id": pid, "invoice_id": "inv1", "amount_cents": cents, "method": "card", |
| 114 | "received_on": "2026-07-10", "reference": f"ref-{pid}", "status": status, |
| 115 | "owner_id": "dan"}, |
| 116 | base_dir=data_dir) |
| 117 | |
| 118 | |
| 119 | def test_cash_basis_payment_composes_posted_entry_idempotently(tmp_path, monkeypatch): |
| 120 | data_dir = setup_env(tmp_path, monkeypatch, basis="cash") |
| 121 | make_payment(data_dir) |
| 122 | result = fire("payments", "p1", "created") |
| 123 | assert result.ok, result.error |
| 124 | assert result.result.get("posted") is True |
| 125 | |
| 126 | js = journals(data_dir) |
| 127 | assert len(js) == 1 |
| 128 | j = js[0] |
| 129 | assert j["generated_from"] == "payments/p1" |
| 130 | assert j["status"] == "posted" |
| 131 | assert j["kind"] == "standard" |
| 132 | ls = {l["account_id"]: l for l in lines_for(data_dir, j["id"])} |
| 133 | assert ls[CASH]["debit_cents"] == "4000" and ls[CASH]["credit_cents"] == "0" |
| 134 | assert ls[REV]["credit_cents"] == "4000" and ls[REV]["debit_cents"] == "0" |
| 135 | |
| 136 | # Replay: composes nothing new. |
| 137 | replay = fire("payments", "p1", "created") |
| 138 | assert "already composed" in str(replay.result) |
| 139 | assert len(journals(data_dir)) == 1 |
| 140 | |
| 141 | |
| 142 | def test_accrual_full_chain_issue_payment_refund_bounce(tmp_path, monkeypatch): |
| 143 | data_dir = setup_env(tmp_path, monkeypatch, basis="accrual") |
| 144 | # issue: draft -> sent |
| 145 | object_records.update_collection_record("invoices", "inv1", {"status": "sent"}, |
| 146 | base_dir=data_dir) |
| 147 | fire("invoices", "inv1", "updated") |
| 148 | # pay + refund |
| 149 | make_payment(data_dir, "p1", "10000") |
| 150 | fire("payments", "p1", "created") |
| 151 | object_records.create_collection_record( |
| 152 | "refunds", {"id": "r1", "payment_id": "p1", "invoice_id": "inv1", |
| 153 | "amount_cents": "2500", "refunded_on": "2026-07-12", "owner_id": "dan"}, |
| 154 | base_dir=data_dir) |
| 155 | fire("refunds", "r1", "created") |
| 156 | |
| 157 | by_from = {j["generated_from"]: j for j in journals(data_dir)} |
| 158 | assert set(by_from) == {"invoices/inv1:issued", "payments/p1", "refunds/r1"} |
| 159 | issue = by_from["invoices/inv1:issued"] |
| 160 | ls = {l["account_id"]: l for l in lines_for(data_dir, issue["id"])} |
| 161 | assert ls[AR]["debit_cents"] == "10000" and ls[REV]["credit_cents"] == "10000" |
| 162 | pay = by_from["payments/p1"] |
| 163 | ls = {l["account_id"]: l for l in lines_for(data_dir, pay["id"])} |
| 164 | assert ls[CASH]["debit_cents"] == "10000" and ls[AR]["credit_cents"] == "10000" |
| 165 | ref = by_from["refunds/r1"] |
| 166 | ls = {l["account_id"]: l for l in lines_for(data_dir, ref["id"])} |
| 167 | assert ls[AR]["debit_cents"] == "2500" and ls[CASH]["credit_cents"] == "2500" |
| 168 | assert all(j["status"] == "posted" for j in by_from.values()) |
| 169 | |
| 170 | # bounce reverses the payment entry |
| 171 | object_records.update_collection_record("payments", "p1", {"status": "bounced"}, |
| 172 | base_dir=data_dir) |
| 173 | fire("payments", "p1", "updated") |
| 174 | by_from = {j["generated_from"]: j for j in journals(data_dir)} |
| 175 | assert "payments/p1:bounced" in by_from |
| 176 | bounce = by_from["payments/p1:bounced"] |
| 177 | assert bounce["kind"] == "reversing" |
| 178 | ls = {l["account_id"]: l for l in lines_for(data_dir, bounce["id"])} |
| 179 | assert ls[AR]["debit_cents"] == "10000" and ls[CASH]["credit_cents"] == "10000" |
| 180 | |
| 181 | |
| 182 | def test_unconfigured_accounts_and_missing_books_are_soft(tmp_path, monkeypatch): |
| 183 | data_dir = setup_env(tmp_path, monkeypatch, configured=False) |
| 184 | make_payment(data_dir) |
| 185 | result = fire("payments", "p1", "created") |
| 186 | assert "unconfigured" in str(result.result) |
| 187 | assert journals(data_dir) == [] |
| 188 | |
| 189 | |
| 190 | def test_missing_fin_journals_collection_noops(tmp_path, monkeypatch): |
| 191 | data_dir = setup_env(tmp_path, monkeypatch, books=False) |
| 192 | make_payment(data_dir) |
| 193 | result = fire("payments", "p1", "created") |
| 194 | assert result.ok |
| 195 | assert "books not installed" in str(result.result) |
| 196 | |
| 197 | |
| 198 | def make_posted_journal(data_dir, jid="j1", owner="dan"): |
| 199 | object_records.create_collection_record( |
| 200 | "fin_journals", |
| 201 | {"id": jid, "date": "2026-07-01", "description": "Manual entry", |
| 202 | "status": "draft", "kind": "standard", "owner_id": owner}, |
| 203 | base_dir=data_dir) |
| 204 | for lid, acct, dr, cr in ((f"{jid}-l1", CASH, "500", "0"), (f"{jid}-l2", REV, "0", "500")): |
| 205 | object_records.create_collection_record( |
| 206 | "fin_journal_lines", |
| 207 | {"id": lid, "journal_id": jid, "account_id": acct, |
| 208 | "debit_cents": dr, "credit_cents": cr, "owner_id": owner}, |
| 209 | base_dir=data_dir) |
| 210 | object_records.update_collection_record("fin_journals", jid, {"status": "posted"}, |
| 211 | base_dir=data_dir) |
| 212 | |
| 213 | |
| 214 | def reverse(payload): |
| 215 | return object_execution.execute_object( |
| 216 | RUNTIME, |
| 217 | object_execution.ObjectExecutionRequest( |
| 218 | "action_reverse_journal", method="POST", payload=payload), |
| 219 | roots=[PACKAGES / "app-finance" / "objects"], |
| 220 | ) |
| 221 | |
| 222 | |
| 223 | def test_reverse_action_composes_mirror_and_refuses_repeats(tmp_path, monkeypatch): |
| 224 | data_dir = setup_env(tmp_path, monkeypatch) |
| 225 | make_posted_journal(data_dir) |
| 226 | |
| 227 | ok = reverse({"journal_id": "j1", "_identity": {"user_id": "dan", "roles": []}}) |
| 228 | assert ok.ok and ok.result["status"] == 200 and ok.result["posted"] is True |
| 229 | mirror_id = ok.result["reversal_id"] |
| 230 | mirror = object_records.get_collection_record("fin_journals", mirror_id, base_dir=data_dir) |
| 231 | assert mirror["kind"] == "reversing" |
| 232 | assert mirror["generated_from"] == "reversal:j1" |
| 233 | ls = {l["account_id"]: l for l in lines_for(data_dir, mirror_id)} |
| 234 | assert ls[CASH]["credit_cents"] == "500" and ls[REV]["debit_cents"] == "500" # swapped |
| 235 | |
| 236 | again = reverse({"journal_id": "j1", "_identity": {"user_id": "dan", "roles": []}}) |
| 237 | assert again.result["status"] == 409 and "Already reversed" in again.result["error"] |
| 238 | |
| 239 | stranger = reverse({"journal_id": mirror_id, "_identity": {"user_id": "mallory", "roles": []}}) |
| 240 | assert stranger.result["status"] == 403 |
| 241 | |
| 242 | |
| 243 | def test_reverse_refuses_draft(tmp_path, monkeypatch): |
| 244 | data_dir = setup_env(tmp_path, monkeypatch) |
| 245 | object_records.create_collection_record( |
| 246 | "fin_journals", {"id": "jd", "date": "2026-07-01", "description": "draft", |
| 247 | "status": "draft", "owner_id": "dan"}, base_dir=data_dir) |
| 248 | result = reverse({"journal_id": "jd", "_identity": {"user_id": "dan", "roles": []}}) |
| 249 | assert result.result["status"] == 409 |
| 250 | |
| 251 | |
| 252 | def run_recurring(payload=None): |
| 253 | return object_execution.execute_object( |
| 254 | RUNTIME, |
| 255 | object_execution.ObjectExecutionRequest( |
| 256 | "system_fin_recurring_runner", method="POST", payload=payload or {}), |
| 257 | roots=[PACKAGES / "app-finance" / "objects"], |
| 258 | ) |
| 259 | |
| 260 | |
| 261 | def add_template(data_dir, tid="t1", lines=None, auto_post="true", next_run="2026-07-01", |
| 262 | frequency="monthly", active="true"): |
| 263 | tmpl = json.dumps(lines if lines is not None else [ |
| 264 | {"account_id": REV, "debit_cents": 100, "credit_cents": 0, "memo": "depr"}, |
| 265 | {"account_id": CASH, "debit_cents": 0, "credit_cents": 100}, |
| 266 | ]) |
| 267 | object_records.create_collection_record( |
| 268 | "fin_recurring", |
| 269 | {"id": tid, "name": "Monthly depreciation", "template_lines": tmpl, |
| 270 | "frequency": frequency, "next_run": next_run, "auto_post": auto_post, |
| 271 | "is_active": active, "owner_id": "dan"}, |
| 272 | base_dir=data_dir) |
| 273 | |
| 274 | |
| 275 | def test_recurring_runner_composes_advances_and_is_idempotent(tmp_path, monkeypatch): |
| 276 | data_dir = setup_env(tmp_path, monkeypatch) |
| 277 | add_template(data_dir) |
| 278 | |
| 279 | result = run_recurring({"today": "2026-07-24"}) |
| 280 | assert result.ok and result.result["ran"] == 1 |
| 281 | js = journals(data_dir) |
| 282 | assert len(js) == 1 |
| 283 | assert js[0]["generated_from"] == "fin_recurring/t1:2026-07-01" |
| 284 | assert js[0]["kind"] == "adjusting" and js[0]["status"] == "posted" |
| 285 | tpl = object_records.get_collection_record("fin_recurring", "t1", base_dir=data_dir) |
| 286 | assert tpl["next_run"] == "2026-08-01" and tpl["last_run"] == "2026-07-01" |
| 287 | |
| 288 | # Same pass again: next_run now 2026-08-01 > today -> nothing runs. |
| 289 | result = run_recurring({"today": "2026-07-24"}) |
| 290 | assert result.result["ran"] == 0 |
| 291 | assert len(journals(data_dir)) == 1 |
| 292 | |
| 293 | |
| 294 | def test_recurring_unbalanced_template_stays_draft(tmp_path, monkeypatch): |
| 295 | data_dir = setup_env(tmp_path, monkeypatch) |
| 296 | add_template(data_dir, tid="t2", lines=[ |
| 297 | {"account_id": REV, "debit_cents": 100, "credit_cents": 0}, |
| 298 | {"account_id": CASH, "debit_cents": 0, "credit_cents": 90}, |
| 299 | ]) |
| 300 | result = run_recurring({"today": "2026-07-24"}) |
| 301 | assert result.result["ran"] == 1 |
| 302 | j = journals(data_dir)[0] |
| 303 | assert j["status"] == "draft" |
| 304 | |
| 305 | |
| 306 | def test_recurring_inactive_and_future_skipped(tmp_path, monkeypatch): |
| 307 | data_dir = setup_env(tmp_path, monkeypatch) |
| 308 | add_template(data_dir, tid="t3", active="false") |
| 309 | add_template(data_dir, tid="t4", next_run="2027-01-01") |
| 310 | result = run_recurring({"today": "2026-07-24"}) |
| 311 | assert result.result["ran"] == 0 |
| 312 | assert journals(data_dir) == [] |