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

0 downloads

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
bank_escalation.py · 10.4 KB · 258 lines
1"""system_bank_escalation -- turn a quietly-growing unreconciled tail into
2work someone is accountable for (plan/bank-import-reconciliation-spec.md
3section 5, "THE SIGNAL").
4
5Matching (system_bank_matcher) and resolving (action_resolve_bank_line) both
6depend on a human noticing an open item and acting on it. Nothing forces
7that noticing to happen -- a bank line can sit at match_status=unmatched or
8suggested forever, and a payment can sit recorded in the books with no bank
9line ever confirming the cash actually arrived. Both are silent by default;
10this runner is what makes them loud.
11
12Two directions of trouble, and the spec is explicit that BOTH matter:
13
141. **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.
172. **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
24Each escalation becomes ONE row in the tasks collection, never two for the
25same item. tasks.json (app-tasks) has no generated_from field the way
26fin_journals does -- compose_posted_journal's idempotency-by-provenance
27posture is mirrored here through the one free-form field the schema
28offers: metadata is stamped with {"generated_from": "bank_lines/{id}"} (or
29"payments/{id}"), and every run scans existing tasks for that marker before
30creating another. Same posture as the composers, different field because
31tasks was never built to be a composer target.
32
33Settings (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
41Best-effort like system_bank_matcher and system_invoice_aging: a single bad
42row is skipped (recorded in results with an error) rather than aborting the
43run, and the whole runner is a no-op -- not a crash -- on a server where
44banking or tasks was never installed. Reconciliation must keep working (the
45matcher, the resolution verbs) even where nothing is around to receive an
46escalation.
47"""
48
49import json
50import os
51from datetime import date, timedelta
52
53import object_ids
54import object_records
55
56ACTOR = "system_bank_escalation"
57
58DEFAULT_AFTER_DAYS = 10
59DEFAULT_ENABLED = "true"
60
61
62def _base_dir():
63 return os.environ.get("DBBASIC_DATA_DIR", "data")
64
65
66def _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
76def _int_setting(base, key, default):
77 try:
78 return int(_setting(base, key, default))
79 except (TypeError, ValueError):
80 return default
81
82
83def _bool_setting(base, key, default):
84 return str(_setting(base, key, default)).strip().lower() not in ("0", "false", "no", "off", "")
85
86
87def _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
95def _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
118def _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
133def _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
146def 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}