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

0 downloads

dbbasic-object-server/object_books_status.py
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
object_books_status.py · 17.5 KB · 432 lines
1"""Readiness check for the books spine's silent-skip posture.
2
3system_books (packages/app-payments/objects/system/books.py),
4system_stock_books (packages/app-catalog/objects/system/stock_books.py), and
5action_resolve_bank_line (packages/app-banking/objects/action/
6resolve_bank_line.py) each compose real double-entry journals as a SOFT
7dependency: if fin_journals/fin_journal_lines/fin_accounts aren't installed,
8or the app_settings account mapping they need is blank, they return
9{"ok": True, "skipped": "..."} and move on. That posture is deliberate --
10payments, stock keeping, and reconciliation all work without a chart of
11accounts, per docs/logic-decisions.md #6 (reactions never block the source
12write). But the skip reason lives only in a dispatcher return value nobody
13reads. On a demo box that's harmless: no books, no problem. The day real
14money and real books show up, an unconfigured or half-configured mapping
15means payments get recorded and simply never reach the ledger -- forever,
16with no error, no log line a human would ever see, and no way to tell
17"nothing to book yet" apart from "the books are broken."
18
19This module does not change any of that behavior. It is a PURE, read-only
20readiness check: given a data directory, would any installed composer
21above silently skip right now, and specifically why? It mirrors each
22composer's own soft-dependency logic (same app_settings keys, same "is the
23collection even installed" gate) so its answer matches what the composer
24would actually do, and adds one distinction the composers don't bother
25making because it doesn't change their behavior but matters enormously to
26a human auditing the setup:
27
28 missing -- the app_settings key is absent or blank. Obviously
29 unconfigured; an operator glancing at settings would notice.
30 dangling -- the key has a value, but that value does not name a real
31 fin_accounts row. This is WORSE than missing: app_settings
32 *looks* configured, a casual read of the settings screen
33 looks fine, and the composer still skips every single time
34 (compose_posted_journal never gets there -- the composer's
35 own "not cash or not counter" check only tests for blank,
36 not for existence, per its docstring/comments).
37
38Only areas that are actually installed are reported: a server with no
39inventory package should never see an "inventory accounts unconfigured"
40problem, because system_stock_books can never fire there in the first
41place -- that would be noise, not signal. Nothing here writes, posts, or
42mutates; it only reads app_settings, fin_accounts, and the presence of a
43handful of collections, the same way object_permission_status.py reads
44identity/policy state to answer "is enforcement safe to turn on" without
45touching either.
46"""
47
48from __future__ import annotations
49
50from pathlib import Path
51from typing import Any
52
53import object_records
54
55# The books spine itself: without all three, every composer's own
56# _books_ready()-style gate trips and nothing composes at all, regardless
57# of app_settings. fin_accounts is included here (not just journals/lines)
58# because "dangling" is meaningless without a chart of accounts to check
59# against -- no fin_accounts collection means every configured id is
60# unverifiable, which this module treats as "books not installed" rather
61# than guessing.
62_BOOKS_COLLECTIONS = ("fin_journals", "fin_journal_lines", "fin_accounts")
63
64# One entry per composer above. "collection" is what gates whether the
65# composer (and therefore this check) applies at all; "keys" list the
66# checks in the order system_books/system_stock_books/resolve_bank_line
67# read them (see each module's docstring for the exact app_settings names).
68_PAYMENTS_COLLECTION = "payments"
69_INVENTORY_COLLECTION = "stock_moves"
70_BANKING_COLLECTION = "bank_lines"
71
72
73def _collection_present(base_dir: Path | str, name: str) -> bool:
74 """True if `name` is an installed, readable collection.
75
76 Same posture as system_books._books_ready() / system_stock_books.
77 _books_ready(): a package that was never installed (unknown schema)
78 or a collection that can't be read for any other reason is treated
79 as absent, never as an error -- this module must never raise just
80 because a package is missing.
81 """
82 try:
83 object_records.read_collection_records(name, base_dir=base_dir)
84 except Exception:
85 return False
86 return True
87
88
89def _load_settings(base_dir: Path | str) -> dict[str, str]:
90 """Return {key: value} for every non-blank app_settings row.
91
92 First match wins on a duplicate key, mirroring the composers' own
93 _setting() helpers (they return on the first row that matches and has
94 a value). An unreadable or absent app_settings collection folds to an
95 empty map -- every setting then reads as "missing", which is exactly
96 the state the composers would see too.
97 """
98 settings: dict[str, str] = {}
99 try:
100 rows = object_records.read_collection_records("app_settings", base_dir=base_dir)
101 except Exception:
102 return settings
103 for row in rows:
104 key = row.get("key")
105 value = str(row.get("value") or "").strip()
106 if key and value and key not in settings:
107 settings[key] = value
108 return settings
109
110
111def _account_ids(base_dir: Path | str) -> set[str]:
112 try:
113 rows = object_records.read_collection_records("fin_accounts", base_dir=base_dir)
114 except Exception:
115 return set()
116 return {row.get("id") for row in rows if row.get("id")}
117
118
119def _check(
120 *,
121 check_id: str,
122 area: str,
123 setting_key: str,
124 settings: dict[str, str],
125 account_ids: set[str],
126 impact: str,
127) -> dict[str, Any]:
128 """One setting -> one verdict, matching what its composer would do.
129
130 status="ok" only when the setting has a value AND that value names a
131 fin_accounts row that actually exists -- either half of that failing
132 is exactly the condition under which the real composer returns
133 {"skipped": "accounts unconfigured"} and posts nothing.
134 """
135 value = settings.get(setting_key, "")
136 if not value:
137 return {
138 "id": check_id,
139 "area": area,
140 "setting": setting_key,
141 "status": "missing",
142 "detail": f"app_settings has no value for '{setting_key}'.",
143 "impact": impact,
144 }
145 if value not in account_ids:
146 return {
147 "id": check_id,
148 "area": area,
149 "setting": setting_key,
150 "status": "dangling",
151 "detail": (
152 f"'{setting_key}' is set to '{value}', but no fin_accounts "
153 f"row with that id exists."
154 ),
155 "impact": impact,
156 }
157 return {
158 "id": check_id,
159 "area": area,
160 "setting": setting_key,
161 "status": "ok",
162 "detail": f"'{setting_key}' -> '{value}' (fin_accounts row exists).",
163 "impact": "",
164 }
165
166
167def _payments_checks(base_dir, settings, account_ids) -> list[dict[str, Any]]:
168 """Mirrors system_books.py's account reads exactly.
169
170 cash_account and revenue_account are read on EVERY basis (revenue is
171 the cash-basis counter account and also one side of the accrual
172 issue entry); receivable_account is only read -- and only required --
173 on accrual basis, per system_books.py's `basis == "accrual"` branch.
174 """
175 basis = settings.get("payments.accounting_basis", "cash") or "cash"
176 checks = [
177 _check(
178 check_id="payments.cash_account",
179 area="payments",
180 setting_key="payments.journal.cash_account",
181 settings=settings,
182 account_ids=account_ids,
183 impact=(
184 "payments and refunds are recorded but never reach the "
185 "ledger: system_books skips every payment, refund, and "
186 "bounce-reversal entry silently."
187 ),
188 ),
189 _check(
190 check_id="payments.revenue_account",
191 area="payments",
192 setting_key="payments.journal.revenue_account",
193 settings=settings,
194 account_ids=account_ids,
195 impact=(
196 "payments have no revenue side to post against, so "
197 "system_books skips the entry instead of posting an "
198 "unbalanced one"
199 + ("; accrual invoice-issue entries skip too" if basis == "accrual" else "")
200 + "."
201 ),
202 ),
203 ]
204 if basis == "accrual":
205 checks.append(_check(
206 check_id="payments.receivable_account",
207 area="payments",
208 setting_key="payments.journal.receivable_account",
209 settings=settings,
210 account_ids=account_ids,
211 impact=(
212 "on accrual basis, invoice issuance, payment, and refund "
213 "entries all need the receivable account: system_books "
214 "skips all three silently until it exists."
215 ),
216 ))
217 return checks
218
219
220def _inventory_checks(settings, account_ids) -> list[dict[str, Any]]:
221 """Mirrors system_stock_books.py's two required account reads.
222
223 Per-reason overrides (inventory.journal.{reason}_account) are
224 optional -- they fall back to shrinkage_account when unset, so an
225 absent override is not a problem. A CONFIGURED override that points
226 at a nonexistent account is exactly the dangling trap this module
227 exists to catch, so those are checked too, but only when set.
228 """
229 checks = [
230 _check(
231 check_id="inventory.inventory_account",
232 area="inventory",
233 setting_key="inventory.journal.inventory_account",
234 settings=settings,
235 account_ids=account_ids,
236 impact=(
237 "inventory losses and count variances are recorded in "
238 "stock_moves but never reach the ledger: "
239 "system_stock_books skips every loss and variance entry "
240 "silently."
241 ),
242 ),
243 _check(
244 check_id="inventory.shrinkage_account",
245 area="inventory",
246 setting_key="inventory.journal.shrinkage_account",
247 settings=settings,
248 account_ids=account_ids,
249 impact=(
250 "loss and count-variance entries have no expense/mirror "
251 "side to post against, so system_stock_books skips them "
252 "silently instead of posting an unbalanced entry."
253 ),
254 ),
255 ]
256 return checks
257
258
259# LOSS_REASONS is duplicated from system_stock_books.py rather than
260# imported: this module must stay importable (and correct) even on a
261# server where packages/app-catalog was never installed, and importing a
262# package object module for one constant would tie this pure status
263# module's import-time behavior to package install state. If that list
264# ever changes there, it should change here too.
265_LOSS_REASONS = ("waste", "breakage", "theft", "expiry", "damage", "disaster")
266
267
268def _inventory_reason_overrides(settings, account_ids) -> list[dict[str, Any]]:
269 checks = []
270 for reason in _LOSS_REASONS:
271 setting_key = f"inventory.journal.{reason}_account"
272 value = settings.get(setting_key, "")
273 if not value:
274 continue # unset -> falls back to shrinkage_account; not a problem
275 checks.append(_check(
276 check_id=f"inventory.{reason}_account",
277 area="inventory",
278 setting_key=setting_key,
279 settings=settings,
280 account_ids=account_ids,
281 impact=(
282 f"'{reason}' losses are meant to route to their own "
283 f"account (e.g. for an insurance claim) but the "
284 f"configured account does not exist, so "
285 f"system_stock_books skips those entries silently "
286 f"instead of falling back."
287 ),
288 ))
289 return checks
290
291
292def _banking_checks(settings, account_ids) -> list[dict[str, Any]]:
293 """Mirrors action_resolve_bank_line.py's two account_settings reads.
294
295 Unlike the two event-handler composers, resolve_bank_line is a
296 user-facing action: today it returns a 409 error at the moment
297 someone tries to resolve a fee/interest line, rather than skipping
298 silently. That is louder than the other two, but it is still a
299 surprise sprung at the worst possible time (mid-reconciliation)
300 instead of a known gap surfaced ahead of time -- which is the gap
301 this readiness check closes.
302 """
303 return [
304 _check(
305 check_id="banking.fees_account",
306 area="banking",
307 setting_key="reconcile.journal.fees_account",
308 settings=settings,
309 account_ids=account_ids,
310 impact=(
311 "resolving a bank line as a fee fails at the moment a "
312 "user tries it (a 409 error), instead of the account "
313 "being ready before anyone hits reconciliation."
314 ),
315 ),
316 _check(
317 check_id="banking.interest_account",
318 area="banking",
319 setting_key="reconcile.journal.interest_account",
320 settings=settings,
321 account_ids=account_ids,
322 impact=(
323 "resolving a bank line as interest earned fails at the "
324 "moment a user tries it (a 409 error), instead of the "
325 "account being ready before anyone hits reconciliation."
326 ),
327 ),
328 ]
329
330
331def _not_installed_status(base_dir: Path | str, missing: list[str]) -> dict[str, Any]:
332 return {
333 "ready": False,
334 "collections": {
335 "fin_journals": _collection_present(base_dir, "fin_journals"),
336 "fin_journal_lines": _collection_present(base_dir, "fin_journal_lines"),
337 "fin_accounts": _collection_present(base_dir, "fin_accounts"),
338 "app_settings": _collection_present(base_dir, "app_settings"),
339 },
340 "checks": [],
341 "problems": [],
342 "summary": (
343 "No accounting books are installed (missing: "
344 + ", ".join(missing)
345 + "); every composer that tries to post a journal "
346 "(system_books, system_stock_books, action_resolve_bank_line) "
347 "will skip silently and nothing will reach the ledger."
348 ),
349 }
350
351
352def books_status(*, base_dir: Path | str) -> dict[str, Any]:
353 """Would any installed composer silently skip its journal right now?
354
355 Returns a dict shaped for both a human report and a machine gate:
356 ready -- True only when every check for every INSTALLED area
357 came back "ok". A server with no payments/
358 inventory/banking apps installed is vacuously
359 ready (nothing composes journals, so nothing can
360 silently skip).
361 collections -- presence of the four collections every check below
362 depends on.
363 checks -- every check that was evaluated (installed areas
364 only), "ok" included.
365 problems -- the subset of checks that is not "ok" -- the
366 actionable list.
367 summary -- one sentence a human can read without opening the
368 dict.
369
370 Never raises: every read goes through _collection_present /
371 _load_settings / _account_ids, which fold any failure (unknown
372 collection, unreadable file, missing package) to an empty/absent
373 result rather than an exception, the same defensive posture every
374 composer this module inspects already uses.
375 """
376 collections = {
377 name: _collection_present(base_dir, name) for name in _BOOKS_COLLECTIONS
378 }
379 collections["app_settings"] = _collection_present(base_dir, "app_settings")
380
381 books_installed = all(collections[name] for name in _BOOKS_COLLECTIONS)
382 if not books_installed:
383 missing = [name for name in _BOOKS_COLLECTIONS if not collections[name]]
384 return _not_installed_status(base_dir, missing)
385
386 settings = _load_settings(base_dir)
387 account_ids = _account_ids(base_dir)
388
389 checks: list[dict[str, Any]] = []
390 if _collection_present(base_dir, _PAYMENTS_COLLECTION):
391 checks.extend(_payments_checks(base_dir, settings, account_ids))
392 if _collection_present(base_dir, _INVENTORY_COLLECTION):
393 checks.extend(_inventory_checks(settings, account_ids))
394 checks.extend(_inventory_reason_overrides(settings, account_ids))
395 if _collection_present(base_dir, _BANKING_COLLECTION):
396 checks.extend(_banking_checks(settings, account_ids))
397
398 problems = [c for c in checks if c["status"] != "ok"]
399 ready = not problems
400
401 if not checks:
402 summary = (
403 "Books are installed but no app that posts journals "
404 "(payments, inventory, banking) is installed; nothing "
405 "composes entries yet, so nothing can silently skip."
406 )
407 elif ready:
408 summary = (
409 f"Books are ready: all {len(checks)} checked ledger account "
410 f"setting(s) across the installed areas are configured and "
411 f"point at real accounts."
412 )
413 else:
414 named = "; ".join(f"{p['id']} ({p['status']})" for p in problems)
415 summary = (
416 f"Books are NOT ready: {len(problems)} of {len(checks)} "
417 f"checked ledger account setting(s) will cause silent gaps "
418 f"({named})."
419 )
420
421 return {
422 "ready": ready,
423 "collections": collections,
424 "checks": checks,
425 "problems": problems,
426 "summary": summary,
427 }
428
429
430def is_ready(*, base_dir: Path | str) -> bool:
431 """Convenience: books_status(base_dir=base_dir)["ready"]."""
432 return books_status(base_dir=base_dir)["ready"]