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
fin_journals.py · 4.1 KB · 104 lines
| 1 | """Pre-write hook for fin_journals: balance before posting, and closed |
| 2 | periods stay closed. |
| 3 | |
| 4 | Two gates, both cross-record, both therefore hook territory |
| 5 | (plan/pre-write-hook-spec.md): |
| 6 | |
| 7 | 1. **A journal must balance before it posts.** The aggregate block on the |
| 8 | journal detail SHOWS debits vs credits, but nothing else stops an |
| 9 | unbalanced draft -> posted move -- the predecessor's own documented |
| 10 | weak spot. |
| 11 | |
| 12 | 2. **A closed period is closed.** Once a stretch of the books is settled |
| 13 | (fin_closed_periods), no journal may be created dated inside it, no |
| 14 | journal dated inside it may be edited, and none may be moved in or out |
| 15 | by changing its date. Without this, last year's "final" numbers stay |
| 16 | quietly editable forever -- the filed statements and the live books |
| 17 | drift apart with nobody deciding they should. Reopening is a deliberate |
| 18 | act (delete the period row, attributed in the change log), never a |
| 19 | side effect of an edit. |
| 20 | |
| 21 | Rejection-only; never transforms. Ordinary edits to a draft journal in an |
| 22 | open period pass untouched. Machine composers write at the storage level |
| 23 | and bypass hooks by design -- the period gate is for human hands; a |
| 24 | composer landing in a closed period is a case that should surface, not be |
| 25 | silently swallowed here (tracked in the package description). |
| 26 | """ |
| 27 | |
| 28 | import os |
| 29 | |
| 30 | import object_finance |
| 31 | import object_records |
| 32 | |
| 33 | |
| 34 | def _base_dir(): |
| 35 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 36 | |
| 37 | |
| 38 | def _period_error(period, date): |
| 39 | reason = str(period.get("reason") or "").strip() |
| 40 | label = f" ({reason})" if reason else "" |
| 41 | return { |
| 42 | "error": (f"The books from {period.get('start_date')} to {period.get('end_date')} " |
| 43 | f"are closed{label}; {date} falls inside. Corrections to a settled " |
| 44 | "period are new journals dated in the current period -- or, " |
| 45 | "deliberately, reopen the period by removing its fin_closed_periods " |
| 46 | "row (that act is attributed in the change log)."), |
| 47 | "status": 409, |
| 48 | } |
| 49 | |
| 50 | |
| 51 | def BEFORE_WRITE(request): |
| 52 | action = request.get("action") |
| 53 | record = request.get("record") or {} |
| 54 | existing = request.get("existing") or {} |
| 55 | changes = request.get("changes") or {} |
| 56 | base = _base_dir() |
| 57 | |
| 58 | # --- gate 2: closed periods ------------------------------------------ |
| 59 | owner = record.get("owner_id") or existing.get("owner_id") or "" |
| 60 | entity = record.get("entity_id") or existing.get("entity_id") or "" |
| 61 | |
| 62 | if action == "create": |
| 63 | period = object_finance.closed_period_for( |
| 64 | record.get("date"), base_dir=base, owner_id=owner, entity_id=entity) |
| 65 | if period is not None: |
| 66 | return _period_error(period, record.get("date")) |
| 67 | |
| 68 | if action == "update": |
| 69 | # Editing anything about a journal dated in a closed period is |
| 70 | # rewriting settled books; moving a date INTO one is backdating. |
| 71 | for date in (existing.get("date"), changes.get("date")): |
| 72 | if not date: |
| 73 | continue |
| 74 | period = object_finance.closed_period_for( |
| 75 | date, base_dir=base, owner_id=owner, entity_id=entity) |
| 76 | if period is not None: |
| 77 | return _period_error(period, date) |
| 78 | |
| 79 | # --- gate 1: balance before posting ----------------------------------- |
| 80 | if action != "update": |
| 81 | return None |
| 82 | if changes.get("status") != "posted" or existing.get("status") == "posted": |
| 83 | return None |
| 84 | |
| 85 | journal_id = record.get("id") or existing.get("id") |
| 86 | lines = [ |
| 87 | line |
| 88 | for line in object_records.read_collection_records("fin_journal_lines", base_dir=base) |
| 89 | if line.get("journal_id") == journal_id |
| 90 | ] |
| 91 | if not lines: |
| 92 | return {"error": "Cannot post an empty journal - add lines first.", "status": 409} |
| 93 | |
| 94 | debits = sum(object_finance.to_cents(line.get("debit_cents")) for line in lines) |
| 95 | credits = sum(object_finance.to_cents(line.get("credit_cents")) for line in lines) |
| 96 | if debits != credits: |
| 97 | return { |
| 98 | "error": ( |
| 99 | "Journal must balance before posting: " |
| 100 | f"debits {debits} != credits {credits} (cents)." |
| 101 | ), |
| 102 | "status": 409, |
| 103 | } |
| 104 | return None |