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
object_books_status.py · 17.5 KB · 432 lines
| 1 | """Readiness check for the books spine's silent-skip posture. |
| 2 | |
| 3 | system_books (packages/app-payments/objects/system/books.py), |
| 4 | system_stock_books (packages/app-catalog/objects/system/stock_books.py), and |
| 5 | action_resolve_bank_line (packages/app-banking/objects/action/ |
| 6 | resolve_bank_line.py) each compose real double-entry journals as a SOFT |
| 7 | dependency: if fin_journals/fin_journal_lines/fin_accounts aren't installed, |
| 8 | or the app_settings account mapping they need is blank, they return |
| 9 | {"ok": True, "skipped": "..."} and move on. That posture is deliberate -- |
| 10 | payments, stock keeping, and reconciliation all work without a chart of |
| 11 | accounts, per docs/logic-decisions.md #6 (reactions never block the source |
| 12 | write). But the skip reason lives only in a dispatcher return value nobody |
| 13 | reads. On a demo box that's harmless: no books, no problem. The day real |
| 14 | money and real books show up, an unconfigured or half-configured mapping |
| 15 | means payments get recorded and simply never reach the ledger -- forever, |
| 16 | with 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 | |
| 19 | This module does not change any of that behavior. It is a PURE, read-only |
| 20 | readiness check: given a data directory, would any installed composer |
| 21 | above silently skip right now, and specifically why? It mirrors each |
| 22 | composer's own soft-dependency logic (same app_settings keys, same "is the |
| 23 | collection even installed" gate) so its answer matches what the composer |
| 24 | would actually do, and adds one distinction the composers don't bother |
| 25 | making because it doesn't change their behavior but matters enormously to |
| 26 | a 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 | |
| 38 | Only areas that are actually installed are reported: a server with no |
| 39 | inventory package should never see an "inventory accounts unconfigured" |
| 40 | problem, because system_stock_books can never fire there in the first |
| 41 | place -- that would be noise, not signal. Nothing here writes, posts, or |
| 42 | mutates; it only reads app_settings, fin_accounts, and the presence of a |
| 43 | handful of collections, the same way object_permission_status.py reads |
| 44 | identity/policy state to answer "is enforcement safe to turn on" without |
| 45 | touching either. |
| 46 | """ |
| 47 | |
| 48 | from __future__ import annotations |
| 49 | |
| 50 | from pathlib import Path |
| 51 | from typing import Any |
| 52 | |
| 53 | import 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 | |
| 73 | def _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 | |
| 89 | def _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 | |
| 111 | def _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 | |
| 119 | def _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 | |
| 167 | def _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 | |
| 220 | def _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 | |
| 268 | def _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 | |
| 292 | def _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 | |
| 331 | def _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 | |
| 352 | def 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 | |
| 430 | def 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"] |