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
bank_lines.py · 3.9 KB · 94 lines
| 1 | """Pre-write hook for bank_lines: evidence stays evidence. |
| 2 | |
| 3 | Two jobs. On CREATE, the duplicate gate. On UPDATE, the rule that makes |
| 4 | this collection an anti-fraud control rather than just another table: |
| 5 | **the bank's words are immutable.** posted_on, amount_cents, description, |
| 6 | raw and the identity fields can never be edited -- a correction comes from |
| 7 | re-importing a corrected statement, never from reshaping the evidence to |
| 8 | agree with the books. What an operator MAY change is their own |
| 9 | reconciliation work: match_status, matched_to, resolved_as, suggestions. |
| 10 | |
| 11 | Also gated: claiming a line is `matched` without saying what it matched is |
| 12 | a status with no substance, so matched_to must be present and well-formed. |
| 13 | |
| 14 | A statement line must land exactly once per bank account. The bank's own |
| 15 | transaction id (OFX FITID) is the strongest key; CSV exports rarely carry |
| 16 | one, so we fall back to a content hash that is ordinal-disambiguated -- |
| 17 | two identical $4.50 coffees on the same day are both real and both land, |
| 18 | but re-importing last month's file adds nothing (plan/bank-import- |
| 19 | reconciliation-spec.md section 2). |
| 20 | |
| 21 | Gates only, per docs/business-logic-patterns.md: this rejects, it never |
| 22 | reacts. The importer action performs the same check itself (it writes at |
| 23 | the storage level, which never reaches this hook) -- this hook is what |
| 24 | protects the public HTTP write surface, so a client or agent POSTing lines |
| 25 | directly gets the same guarantee. |
| 26 | """ |
| 27 | |
| 28 | import os |
| 29 | |
| 30 | import object_banking |
| 31 | |
| 32 | |
| 33 | def _base_dir(): |
| 34 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 35 | |
| 36 | |
| 37 | def _check_update(request): |
| 38 | existing = request.get("existing") or {} |
| 39 | changes = request.get("changes") or {} |
| 40 | |
| 41 | touched = object_banking.evidence_changes(existing, changes) |
| 42 | if touched: |
| 43 | return { |
| 44 | "error": ("A bank line records what the bank said and cannot be edited " |
| 45 | f"({', '.join(touched)}). Import a corrected statement instead -- " |
| 46 | "reconciliation means explaining the difference between the bank " |
| 47 | "and the books, never editing one to match the other."), |
| 48 | "status": 409, |
| 49 | } |
| 50 | |
| 51 | if changes.get("match_status") == "matched": |
| 52 | target = str(changes.get("matched_to") or existing.get("matched_to") or "").strip() |
| 53 | if not target: |
| 54 | return {"error": "Set matched_to (e.g. payments/<id>) when marking a line matched.", |
| 55 | "status": 400} |
| 56 | if target.count("/") != 1 or not all(part.strip() for part in target.split("/")): |
| 57 | return {"error": f"matched_to must look like collection/record_id, got {target!r}.", |
| 58 | "status": 400} |
| 59 | return None |
| 60 | |
| 61 | |
| 62 | def BEFORE_WRITE(request): |
| 63 | action = request.get("action") |
| 64 | if action == "update": |
| 65 | return _check_update(request) |
| 66 | if action != "create": |
| 67 | return None |
| 68 | record = request.get("record") or {} |
| 69 | |
| 70 | if not str(record.get("bank_account_id") or "").strip(): |
| 71 | return None # required-field validation owns this |
| 72 | |
| 73 | stamped = dict(record) |
| 74 | if not str(stamped.get("line_hash") or "").strip(): |
| 75 | try: |
| 76 | amount = int(stamped.get("amount_cents") or 0) |
| 77 | except (TypeError, ValueError): |
| 78 | return None # schema validation reports the type error properly |
| 79 | stamped["line_hash"] = object_banking.line_hash( |
| 80 | str(stamped.get("posted_on") or ""), amount, |
| 81 | str(stamped.get("description") or "")) |
| 82 | |
| 83 | if object_banking.is_duplicate_line(stamped, base_dir=_base_dir()): |
| 84 | which = "transaction id" if stamped.get("external_id") else "date/amount/description" |
| 85 | return { |
| 86 | "error": (f"This statement line is already on file for this bank account " |
| 87 | f"(matched on {which}). Bank lines are append-only evidence: " |
| 88 | f"re-importing a statement never duplicates it."), |
| 89 | "status": 409, |
| 90 | } |
| 91 | |
| 92 | if stamped.get("line_hash") != record.get("line_hash"): |
| 93 | return {"record": stamped} |
| 94 | return None |