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_matcher.py · 6.1 KB · 159 lines
| 1 | """system_bank_matcher -- propose book-side records for unmatched bank lines. |
| 2 | |
| 3 | POST {bank_account_id?, today?} -- runs over unmatched lines and writes what |
| 4 | it found onto each: match_status=suggested plus a `suggestions` JSON block |
| 5 | saying which records, at which tier, and WHY. Schedulable daily like any |
| 6 | other runner (the scheduler board shows its results). |
| 7 | |
| 8 | The important restraint: **the matcher suggests, a person confirms.** Only |
| 9 | tier 1 (the record's reference appears in the statement text AND the amount |
| 10 | agrees -- two independent signals) is auto-confirmable, and even that is |
| 11 | configurable down to nothing: |
| 12 | |
| 13 | reconcile.auto_match_tier 0 = never auto-match, 1 = tier 1 (default) |
| 14 | reconcile.date_window_days how far apart a line and a record may be (5) |
| 15 | |
| 16 | Confirming a match is deliberately NOT an action object -- it is an |
| 17 | ordinary attributed record update, so the change log names who reconciled |
| 18 | what and when. Reconciliation done invisibly by the same hands that move |
| 19 | the money is the classic fraud hole; making confirmation a normal write |
| 20 | closes it with machinery that already exists. |
| 21 | |
| 22 | Candidates are payments (money in) and refunds (money out), each converted |
| 23 | to the statement's sign convention before comparison. Journals and bills |
| 24 | join the candidate pool when those flows exist. |
| 25 | """ |
| 26 | |
| 27 | import json |
| 28 | import os |
| 29 | |
| 30 | import object_banking |
| 31 | import object_records |
| 32 | |
| 33 | ACTOR = "system_bank_matcher" |
| 34 | |
| 35 | DEFAULT_WINDOW_DAYS = 5 |
| 36 | DEFAULT_AUTO_TIER = 1 |
| 37 | |
| 38 | |
| 39 | def _base_dir(): |
| 40 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 41 | |
| 42 | |
| 43 | def _setting(base, key, default): |
| 44 | try: |
| 45 | for row in object_records.read_collection_records("app_settings", base_dir=base): |
| 46 | if row.get("key") == key and str(row.get("value") or "").strip(): |
| 47 | return row["value"].strip() |
| 48 | except Exception: |
| 49 | pass |
| 50 | return default |
| 51 | |
| 52 | |
| 53 | def _int_setting(base, key, default): |
| 54 | try: |
| 55 | return int(_setting(base, key, default)) |
| 56 | except (TypeError, ValueError): |
| 57 | return default |
| 58 | |
| 59 | |
| 60 | def _candidates(base, owner_id): |
| 61 | """Book-side records this line could be, in the statement's signs.""" |
| 62 | out = [] |
| 63 | try: |
| 64 | for payment in object_records.read_collection_records("payments", base_dir=base): |
| 65 | if owner_id and payment.get("owner_id") and payment["owner_id"] != owner_id: |
| 66 | continue |
| 67 | if (payment.get("status") or "received") != "received": |
| 68 | continue |
| 69 | out.append({ |
| 70 | "ref": f"payments/{payment['id']}", |
| 71 | "amount_cents": int(payment.get("amount_cents") or 0), # money in: positive |
| 72 | "date": payment.get("received_on") or payment.get("created_at", "")[:10], |
| 73 | "reference": payment.get("reference") or "", |
| 74 | }) |
| 75 | except Exception: |
| 76 | pass |
| 77 | try: |
| 78 | for refund in object_records.read_collection_records("refunds", base_dir=base): |
| 79 | if owner_id and refund.get("owner_id") and refund["owner_id"] != owner_id: |
| 80 | continue |
| 81 | out.append({ |
| 82 | "ref": f"refunds/{refund['id']}", |
| 83 | "amount_cents": -abs(int(refund.get("amount_cents") or 0)), # money out |
| 84 | "date": refund.get("refunded_on") or refund.get("created_at", "")[:10], |
| 85 | "reference": refund.get("payment_id") or "", |
| 86 | }) |
| 87 | except Exception: |
| 88 | pass |
| 89 | return out |
| 90 | |
| 91 | |
| 92 | def _already_matched(base): |
| 93 | """Refs already claimed by another line -- one book record, one line.""" |
| 94 | claimed = set() |
| 95 | try: |
| 96 | for row in object_records.read_collection_records("bank_lines", base_dir=base): |
| 97 | if row.get("matched_to"): |
| 98 | claimed.add(row["matched_to"]) |
| 99 | except Exception: |
| 100 | pass |
| 101 | return claimed |
| 102 | |
| 103 | |
| 104 | def POST(request): |
| 105 | base = _base_dir() |
| 106 | identity = request.get("_identity") or {} |
| 107 | owner_id = identity.get("user_id") or "" |
| 108 | only_account = str(request.get("bank_account_id") or "").strip() |
| 109 | |
| 110 | window = _int_setting(base, "reconcile.date_window_days", DEFAULT_WINDOW_DAYS) |
| 111 | auto_tier = _int_setting(base, "reconcile.auto_match_tier", DEFAULT_AUTO_TIER) |
| 112 | |
| 113 | try: |
| 114 | lines = object_records.read_collection_records("bank_lines", base_dir=base) |
| 115 | except Exception: |
| 116 | return {"ok": True, "skipped": "banking not installed (bank_lines absent)"} |
| 117 | |
| 118 | open_lines = [l for l in lines |
| 119 | if (l.get("match_status") or "unmatched") in ("unmatched", "suggested") |
| 120 | and not (only_account and l.get("bank_account_id") != only_account) |
| 121 | and not (owner_id and l.get("owner_id") and l["owner_id"] != owner_id)] |
| 122 | if not open_lines: |
| 123 | return {"ok": True, "scanned": 0, "suggested": 0, "auto_matched": 0, "results": []} |
| 124 | |
| 125 | pool = _candidates(base, owner_id) |
| 126 | claimed = _already_matched(base) |
| 127 | available = [c for c in pool if c["ref"] not in claimed] |
| 128 | |
| 129 | suggested = auto_matched = 0 |
| 130 | results = [] |
| 131 | for line in open_lines: |
| 132 | proposals = object_banking.candidate_matches( |
| 133 | line, [c for c in available if c["ref"] not in claimed], window_days=window) |
| 134 | if not proposals: |
| 135 | continue |
| 136 | best = proposals[0] |
| 137 | changes = {"suggestions": json.dumps(proposals[:5])} |
| 138 | outcome = "suggested" |
| 139 | if best["tier"] <= auto_tier and len(best["refs"]) == 1: |
| 140 | changes["match_status"] = "matched" |
| 141 | changes["matched_to"] = best["refs"][0] |
| 142 | claimed.add(best["refs"][0]) |
| 143 | auto_matched += 1 |
| 144 | outcome = "auto_matched" |
| 145 | else: |
| 146 | changes["match_status"] = "suggested" |
| 147 | suggested += 1 |
| 148 | try: |
| 149 | object_records.update_collection_record( |
| 150 | "bank_lines", line["id"], changes, base_dir=base, actor=ACTOR) |
| 151 | except Exception as exc: |
| 152 | results.append({"line": line["id"], "error": str(exc)[:160]}) |
| 153 | continue |
| 154 | results.append({"line": line["id"], "outcome": outcome, "tier": best["tier"], |
| 155 | "refs": best["refs"], "why": best["why"]}) |
| 156 | |
| 157 | return {"ok": True, "scanned": len(open_lines), "suggested": suggested, |
| 158 | "auto_matched": auto_matched, "auto_match_tier": auto_tier, |
| 159 | "window_days": window, "results": results} |