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_escalation.py · 10.4 KB · 258 lines
| 1 | """system_bank_escalation -- turn a quietly-growing unreconciled tail into |
| 2 | work someone is accountable for (plan/bank-import-reconciliation-spec.md |
| 3 | section 5, "THE SIGNAL"). |
| 4 | |
| 5 | Matching (system_bank_matcher) and resolving (action_resolve_bank_line) both |
| 6 | depend on a human noticing an open item and acting on it. Nothing forces |
| 7 | that noticing to happen -- a bank line can sit at match_status=unmatched or |
| 8 | suggested forever, and a payment can sit recorded in the books with no bank |
| 9 | line ever confirming the cash actually arrived. Both are silent by default; |
| 10 | this runner is what makes them loud. |
| 11 | |
| 12 | Two directions of trouble, and the spec is explicit that BOTH matter: |
| 13 | |
| 14 | 1. **Bank lines the books cannot explain** -- a bank_line still |
| 15 | unmatched/suggested more than reconcile.escalate_after_days after |
| 16 | posted_on. Money moved and there is no book record saying why. |
| 17 | 2. **Book records the bank never confirmed** -- a payments row (status |
| 18 | received) older than the same window with no bank_line matched_to it. |
| 19 | This is the direction people forget, and the spec calls it the more |
| 20 | serious one: it can mean a payment was recorded that never actually |
| 21 | arrived, which is exactly the shape of a fraud loss or a bookkeeping |
| 22 | error that compounds every day it goes unnoticed. |
| 23 | |
| 24 | Each escalation becomes ONE row in the tasks collection, never two for the |
| 25 | same item. tasks.json (app-tasks) has no generated_from field the way |
| 26 | fin_journals does -- compose_posted_journal's idempotency-by-provenance |
| 27 | posture is mirrored here through the one free-form field the schema |
| 28 | offers: metadata is stamped with {"generated_from": "bank_lines/{id}"} (or |
| 29 | "payments/{id}"), and every run scans existing tasks for that marker before |
| 30 | creating another. Same posture as the composers, different field because |
| 31 | tasks was never built to be a composer target. |
| 32 | |
| 33 | Settings (app_settings, code-side defaults so an absent row is safe): |
| 34 | |
| 35 | reconcile.escalate_after_days how many days of silence before a line |
| 36 | or payment becomes a task (10) |
| 37 | reconcile.escalate_to user id to hold accountable; blank means |
| 38 | the item's own owner_id ("") |
| 39 | reconcile.escalation_enabled kill switch for the whole runner ("true") |
| 40 | |
| 41 | Best-effort like system_bank_matcher and system_invoice_aging: a single bad |
| 42 | row is skipped (recorded in results with an error) rather than aborting the |
| 43 | run, and the whole runner is a no-op -- not a crash -- on a server where |
| 44 | banking or tasks was never installed. Reconciliation must keep working (the |
| 45 | matcher, the resolution verbs) even where nothing is around to receive an |
| 46 | escalation. |
| 47 | """ |
| 48 | |
| 49 | import json |
| 50 | import os |
| 51 | from datetime import date, timedelta |
| 52 | |
| 53 | import object_ids |
| 54 | import object_records |
| 55 | |
| 56 | ACTOR = "system_bank_escalation" |
| 57 | |
| 58 | DEFAULT_AFTER_DAYS = 10 |
| 59 | DEFAULT_ENABLED = "true" |
| 60 | |
| 61 | |
| 62 | def _base_dir(): |
| 63 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 64 | |
| 65 | |
| 66 | def _setting(base, key, default): |
| 67 | try: |
| 68 | for row in object_records.read_collection_records("app_settings", base_dir=base): |
| 69 | if row.get("key") == key and str(row.get("value") or "").strip(): |
| 70 | return row["value"].strip() |
| 71 | except Exception: |
| 72 | pass |
| 73 | return default |
| 74 | |
| 75 | |
| 76 | def _int_setting(base, key, default): |
| 77 | try: |
| 78 | return int(_setting(base, key, default)) |
| 79 | except (TypeError, ValueError): |
| 80 | return default |
| 81 | |
| 82 | |
| 83 | def _bool_setting(base, key, default): |
| 84 | return str(_setting(base, key, default)).strip().lower() not in ("0", "false", "no", "off", "") |
| 85 | |
| 86 | |
| 87 | def _parse_date(value): |
| 88 | try: |
| 89 | y, m, d = (int(x) for x in str(value)[:10].split("-")) |
| 90 | return date(y, m, d) |
| 91 | except (ValueError, AttributeError): |
| 92 | return None |
| 93 | |
| 94 | |
| 95 | def _existing_markers(tasks): |
| 96 | """generated_from values already claimed by an escalation task. |
| 97 | |
| 98 | tasks.metadata is a free-form JSON string (same convention as |
| 99 | app-templates' schema/default_values); a row this runner did not write, |
| 100 | or wrote before this field existed, simply has nothing to parse and is |
| 101 | skipped rather than treated as a collision. |
| 102 | """ |
| 103 | markers = set() |
| 104 | for task in tasks: |
| 105 | raw = task.get("metadata") or "" |
| 106 | if not raw: |
| 107 | continue |
| 108 | try: |
| 109 | data = json.loads(raw) |
| 110 | except (TypeError, ValueError): |
| 111 | continue |
| 112 | marker = data.get("generated_from") if isinstance(data, dict) else None |
| 113 | if marker: |
| 114 | markers.add(marker) |
| 115 | return markers |
| 116 | |
| 117 | |
| 118 | def _confirmed_payment_refs(lines): |
| 119 | """Payment refs some bank line already claims via matched_to. |
| 120 | |
| 121 | matched_to is set on match (match_status=matched) and stays set through |
| 122 | resolution (e.g. action_resolve_bank_line's nsf path), so this is a |
| 123 | property of the line regardless of its current match_status. |
| 124 | """ |
| 125 | refs = set() |
| 126 | for line in lines: |
| 127 | target = (line.get("matched_to") or "").strip() |
| 128 | if target.startswith("payments/"): |
| 129 | refs.add(target) |
| 130 | return refs |
| 131 | |
| 132 | |
| 133 | def _create_task(base, *, marker, title, description, urgency, owner_id): |
| 134 | payload = { |
| 135 | "id": object_ids.new_uuid4(), |
| 136 | "title": title[:200], |
| 137 | "description": description, |
| 138 | "urgency": urgency, |
| 139 | "owner_id": owner_id or "", |
| 140 | "metadata": json.dumps({"generated_from": marker}), |
| 141 | } |
| 142 | return object_records.create_collection_record( |
| 143 | "tasks", payload, base_dir=base, actor=ACTOR) |
| 144 | |
| 145 | |
| 146 | def POST(request): |
| 147 | base = _base_dir() |
| 148 | today = _parse_date(request.get("today")) or date.today() |
| 149 | only_account = str(request.get("bank_account_id") or "").strip() |
| 150 | |
| 151 | if not _bool_setting(base, "reconcile.escalation_enabled", DEFAULT_ENABLED): |
| 152 | return {"ok": True, "skipped": "escalation disabled (reconcile.escalation_enabled)"} |
| 153 | |
| 154 | after_days = max(0, _int_setting(base, "reconcile.escalate_after_days", DEFAULT_AFTER_DAYS)) |
| 155 | escalate_to = _setting(base, "reconcile.escalate_to", "") |
| 156 | |
| 157 | try: |
| 158 | existing_tasks = object_records.read_collection_records("tasks", base_dir=base) |
| 159 | except Exception: |
| 160 | return {"ok": True, "skipped": "tasks not installed"} |
| 161 | already_escalated = _existing_markers(existing_tasks) |
| 162 | |
| 163 | try: |
| 164 | lines = object_records.read_collection_records("bank_lines", base_dir=base) |
| 165 | except Exception: |
| 166 | return {"ok": True, "skipped": "banking not installed (bank_lines absent)"} |
| 167 | |
| 168 | try: |
| 169 | payments = object_records.read_collection_records("payments", base_dir=base) |
| 170 | except Exception: |
| 171 | payments = [] |
| 172 | |
| 173 | confirmed = _confirmed_payment_refs(lines) |
| 174 | |
| 175 | scanned = escalated = already_open = 0 |
| 176 | results = [] |
| 177 | |
| 178 | # Direction 1: bank lines the books cannot explain. |
| 179 | for line in lines: |
| 180 | status = line.get("match_status") or "unmatched" |
| 181 | if status not in ("unmatched", "suggested"): |
| 182 | continue |
| 183 | if only_account and line.get("bank_account_id") != only_account: |
| 184 | continue |
| 185 | scanned += 1 |
| 186 | posted = _parse_date(line.get("posted_on")) |
| 187 | if posted is None or (today - posted).days < after_days: |
| 188 | continue |
| 189 | |
| 190 | marker = f"bank_lines/{line['id']}" |
| 191 | if marker in already_escalated: |
| 192 | already_open += 1 |
| 193 | results.append({"kind": "bank_line", "id": line["id"], "outcome": "already_open"}) |
| 194 | continue |
| 195 | |
| 196 | amount = line.get("amount_cents") or "0" |
| 197 | desc = line.get("description") or "(no description)" |
| 198 | title = f"Unexplained bank line: {desc} ({amount} cents, {line.get('posted_on')})" |
| 199 | body = ( |
| 200 | f"Bank line {line['id']} on account {line.get('bank_account_id')} posted " |
| 201 | f"{line.get('posted_on')} for {amount} cents (\"{desc}\") has been " |
| 202 | f"{status} for {(today - posted).days} days with no matching book record. " |
| 203 | "Confirm a match, or resolve it as a fee/interest/transfer/nsf/timing item." |
| 204 | ) |
| 205 | target_owner = escalate_to or line.get("owner_id") or "" |
| 206 | try: |
| 207 | _create_task(base, marker=marker, title=title, description=body, |
| 208 | urgency="high", owner_id=target_owner) |
| 209 | except Exception as exc: |
| 210 | results.append({"kind": "bank_line", "id": line["id"], "error": str(exc)[:160]}) |
| 211 | continue |
| 212 | escalated += 1 |
| 213 | results.append({"kind": "bank_line", "id": line["id"], "outcome": "escalated", |
| 214 | "days_old": (today - posted).days}) |
| 215 | |
| 216 | # Direction 2: book records the bank never confirmed -- the forgotten, |
| 217 | # more serious direction (a payment recorded that may never have landed). |
| 218 | for payment in payments: |
| 219 | if (payment.get("status") or "received") != "received": |
| 220 | continue |
| 221 | if f"payments/{payment['id']}" in confirmed: |
| 222 | continue |
| 223 | scanned += 1 |
| 224 | received = _parse_date(payment.get("received_on")) |
| 225 | if received is None or (today - received).days < after_days: |
| 226 | continue |
| 227 | |
| 228 | marker = f"payments/{payment['id']}" |
| 229 | if marker in already_escalated: |
| 230 | already_open += 1 |
| 231 | results.append({"kind": "payment", "id": payment["id"], "outcome": "already_open"}) |
| 232 | continue |
| 233 | |
| 234 | amount = payment.get("amount_cents") or "0" |
| 235 | title = (f"Unconfirmed payment: {amount} cents received " |
| 236 | f"{payment.get('received_on')} (invoice {payment.get('invoice_id') or '?'})") |
| 237 | body = ( |
| 238 | f"Payment {payment['id']} for {amount} cents against invoice " |
| 239 | f"{payment.get('invoice_id') or '?'} (method {payment.get('method') or '?'}, " |
| 240 | f"reference \"{payment.get('reference') or ''}\") was recorded as received on " |
| 241 | f"{payment.get('received_on')} -- {(today - received).days} days ago -- but no " |
| 242 | "bank line has confirmed the cash actually arrived. Verify against the bank " |
| 243 | "statement before trusting this balance." |
| 244 | ) |
| 245 | target_owner = escalate_to or payment.get("owner_id") or "" |
| 246 | try: |
| 247 | _create_task(base, marker=marker, title=title, description=body, |
| 248 | urgency="critical", owner_id=target_owner) |
| 249 | except Exception as exc: |
| 250 | results.append({"kind": "payment", "id": payment["id"], "error": str(exc)[:160]}) |
| 251 | continue |
| 252 | escalated += 1 |
| 253 | results.append({"kind": "payment", "id": payment["id"], "outcome": "escalated", |
| 254 | "days_old": (today - received).days}) |
| 255 | |
| 256 | return {"ok": True, "scanned": scanned, "escalated": escalated, |
| 257 | "already_open": already_open, "after_days": after_days, |
| 258 | "today": today.isoformat(), "results": results} |