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
invoice_totals.py · 12.5 KB · 284 lines
| 1 | """invoice_totals -- HANDLES invoice_lines writes; recomputes invoice totals. |
| 2 | |
| 3 | Registered as a Phase-5a event handler (object_handlers.py, |
| 4 | docs/event-hooks-decisions.md, docs/upgrade-and-customization.md Rule 4). |
| 5 | The platform's post-commit dispatcher (object_server.py's |
| 6 | _dispatch_event_handlers) executes this object's EVENT method whenever a |
| 7 | client-facing write to invoice_lines commits, but only when the operator |
| 8 | has DBBASIC_ENABLE_EVENT_HANDLERS set. With the flag unset (the default), |
| 9 | invoice_lines/invoices writes still succeed -- they just stop getting |
| 10 | fresher totals until a line is touched again after the flag is turned on. |
| 11 | Same posture plan/vocabulary/20-invoice-spec.md documents for itself. |
| 12 | |
| 13 | Integer-cents arithmetic only, per 00-doctrine-and-contract.md / |
| 14 | 20-invoice-spec.md: money is always a whole number of cents. quantity is |
| 15 | the one deliberate exception to "never a float" in this package, because |
| 16 | it is a count/measure (e.g. 2.5 hours), not currency. Line/tax math uses |
| 17 | Decimal (never a bare Python float) so a fractional quantity can never |
| 18 | introduce binary-float rounding error, then floors to an integer number |
| 19 | of cents -- never rounds up ("exact arithmetic, floor not round"). |
| 20 | |
| 21 | Why these fields are NOT schema `read_only` despite the task brief asking |
| 22 | for it: verified against object_records.py before writing this file. |
| 23 | `update_collection_record` has no `preserve_read_only` escape hatch at |
| 24 | all (only `create_collection_record` does, and even there defaults are |
| 25 | never stamped onto a read_only field -- see `_apply_schema_defaults`), so |
| 26 | a genuinely `read_only` field can never be written again after creation, |
| 27 | by ANY caller, including this handler's own follow-up write. Marking |
| 28 | subtotal_cents/tax_cents/total_cents/balance_due_cents/line_total_cents/ |
| 29 | line_tax_cents read_only would therefore let this handler compute the |
| 30 | correct value once and then permanently fail to ever write it again. |
| 31 | Instead this package follows plan/vocabulary/20-invoice-spec.md's own |
| 32 | already-reasoned fallback posture for exactly this situation ("Permissions |
| 33 | Posture"): these stay ordinary owner-writable fields, simply omitted from |
| 34 | forms.default so the generated form never renders them as editable |
| 35 | inputs (confirmed against packages/app-theme/objects/site/form.py's own |
| 36 | `skip()`, which also independently omits any read_only field -- |
| 37 | belt-and-suspenders, not the primary protection); any actual tamper is |
| 38 | fully visible in record_changes (before/after, actor, timestamp) |
| 39 | regardless. Detection, not prevention -- the same backstop the platform |
| 40 | already relies on elsewhere. |
| 41 | |
| 42 | Idempotence: every write below is compared against the already-stored |
| 43 | value first and skipped if unchanged. This platform's dispatch lives in |
| 44 | object_server.py's HTTP request handlers, not inside object_records.py |
| 45 | itself (checked: object_records.py has zero references to event |
| 46 | dispatch), so a handler calling object_records directly -- as this one |
| 47 | does -- does not currently re-enter the dispatcher and cannot recurse. |
| 48 | The guard is kept anyway: it is cheap, it avoids a pointless no-op write |
| 49 | and record_change entry on every re-run, and it is the correct discipline |
| 50 | regardless of whether a future refactor moves dispatch closer to the |
| 51 | write path (plan/vocabulary/20-invoice-spec.md calls this out as an open |
| 52 | question worth a shared helper one day). |
| 53 | """ |
| 54 | from __future__ import annotations |
| 55 | |
| 56 | import os |
| 57 | from decimal import ROUND_FLOOR, Decimal |
| 58 | |
| 59 | import object_record_changes |
| 60 | import object_finance |
| 61 | import object_lines |
| 62 | import object_records |
| 63 | |
| 64 | HANDLES = [ |
| 65 | "invoice_lines.record.created", |
| 66 | "invoice_lines.record.updated", |
| 67 | "invoice_lines.record.deleted", |
| 68 | ] |
| 69 | |
| 70 | ACTOR = "invoice_totals" |
| 71 | DATA_DIR_ENV = "DBBASIC_DATA_DIR" |
| 72 | |
| 73 | |
| 74 | def _data_dir() -> str: |
| 75 | # Mirrors object_handlers.handlers_enabled()'s own note: standalone, |
| 76 | # reads os.environ directly rather than depending on object_server. |
| 77 | return os.environ.get(DATA_DIR_ENV, object_records.DEFAULT_DATA_DIR) |
| 78 | |
| 79 | |
| 80 | def _to_int(value): |
| 81 | """The shared defensive ledger parser (object_finance.to_cents). |
| 82 | |
| 83 | This was a byte-identical private copy in three modules. One |
| 84 | shared floor-parser is one place to be right about rounding, and |
| 85 | a *_cents field left blank by a half-filled draft still reads 0 |
| 86 | rather than raising. |
| 87 | """ |
| 88 | return object_finance.to_cents(value) |
| 89 | |
| 90 | |
| 91 | def _line_amounts(line: dict) -> tuple[int, int]: |
| 92 | """Return (line_total_cents, line_tax_cents) for one invoice_lines row. |
| 93 | |
| 94 | The arithmetic lives in object_lines, shared with app-orders: the two |
| 95 | copies were near enough identical that one was the other plus |
| 96 | modifier_cents, and both now subtract a line discount. See that |
| 97 | module for the order of operations and why tax is charged on the |
| 98 | discounted amount. |
| 99 | """ |
| 100 | amounts = object_lines.line_amounts(line) |
| 101 | return amounts["line_total_cents"], amounts["line_tax_cents"] |
| 102 | |
| 103 | |
| 104 | def _line_discount(line: dict) -> int: |
| 105 | return object_lines.line_amounts(line)["discount_cents"] |
| 106 | |
| 107 | |
| 108 | def _resolve_invoice_id(record_id: str, action: str, base_dir: str) -> str | None: |
| 109 | """Return the invoice_id an invoice_lines write belongs to, or None. |
| 110 | |
| 111 | create/update: the line record still exists -- read it directly. |
| 112 | delete: the line is already gone by the time this fires (post-commit |
| 113 | dispatch runs after the write), so recover its last known invoice_id |
| 114 | from record_changes' own "before" snapshot -- the same "read the |
| 115 | change log directly" shape object_server.py's own |
| 116 | _record_change_for_publish already uses to recover a just-committed |
| 117 | write for its own downstream publish step. |
| 118 | """ |
| 119 | if action == "deleted": |
| 120 | try: |
| 121 | payload = object_record_changes.list_record_changes( |
| 122 | "invoice_lines", record_id=record_id, limit=1, base_dir=base_dir |
| 123 | ) |
| 124 | except (OSError, ValueError): |
| 125 | return None |
| 126 | changes = payload.get("changes") or [] |
| 127 | if not changes: |
| 128 | return None |
| 129 | before = changes[0].get("before") or {} |
| 130 | invoice_id = before.get("invoice_id") |
| 131 | return invoice_id or None |
| 132 | |
| 133 | try: |
| 134 | line = object_records.get_collection_record("invoice_lines", record_id, base_dir=base_dir) |
| 135 | except (object_records.RecordNotFoundError, object_records.InvalidRecordIdError): |
| 136 | return None |
| 137 | return line.get("invoice_id") or None |
| 138 | |
| 139 | |
| 140 | def _sync_triggering_line(record_id: str, action: str, base_dir: str) -> None: |
| 141 | """Recompute + write back the one line that triggered this dispatch. |
| 142 | |
| 143 | No-op for delete (nothing left to write) and for a line already |
| 144 | carrying the correct stamped values (the idempotence guard). |
| 145 | """ |
| 146 | if action == "deleted": |
| 147 | return |
| 148 | try: |
| 149 | line = object_records.get_collection_record("invoice_lines", record_id, base_dir=base_dir) |
| 150 | except (object_records.RecordNotFoundError, object_records.InvalidRecordIdError): |
| 151 | return |
| 152 | |
| 153 | line_total_cents, line_tax_cents = _line_amounts(line) |
| 154 | line_discount_cents = _line_discount(line) |
| 155 | # The discount is STORED beside the total it produced, not left to be |
| 156 | # re-derived: an invoice has to be able to print "10% off -2.00" |
| 157 | # next to the line, and a reader who only has the net total cannot |
| 158 | # say what was taken off or whether anything was. |
| 159 | if line_total_cents == _to_int(line.get("line_total_cents")) and \ |
| 160 | line_tax_cents == _to_int(line.get("line_tax_cents")) and \ |
| 161 | line_discount_cents == _to_int(line.get("line_discount_cents")): |
| 162 | return |
| 163 | |
| 164 | try: |
| 165 | object_records.update_collection_record( |
| 166 | "invoice_lines", |
| 167 | record_id, |
| 168 | {"line_total_cents": str(line_total_cents), |
| 169 | "line_tax_cents": str(line_tax_cents), |
| 170 | "line_discount_cents": str(line_discount_cents)}, |
| 171 | base_dir=base_dir, |
| 172 | actor=ACTOR, |
| 173 | ) |
| 174 | except (object_records.RecordNotFoundError, object_records.InvalidRecordPayloadError, |
| 175 | object_records.InvalidRecordIdError): |
| 176 | pass |
| 177 | |
| 178 | |
| 179 | def _recompute_invoice(invoice_id: str, base_dir: str) -> bool: |
| 180 | """Re-sum every line on invoice_id and stamp the parent invoice. |
| 181 | |
| 182 | Returns True if the invoice row actually changed. A full scan of |
| 183 | invoice_lines is the right cost/complexity trade at this collection's |
| 184 | expected scale (a handful of lines per invoice, per |
| 185 | plan/vocabulary/20-invoice-spec.md) -- no index needed. |
| 186 | """ |
| 187 | try: |
| 188 | invoice = object_records.get_collection_record("invoices", invoice_id, base_dir=base_dir) |
| 189 | except (object_records.RecordNotFoundError, object_records.InvalidRecordIdError): |
| 190 | return False |
| 191 | |
| 192 | lines = object_records.read_collection_records("invoice_lines", base_dir=base_dir) |
| 193 | |
| 194 | subtotal_cents = 0 |
| 195 | line_tax_cents_total = 0 |
| 196 | any_line_states_a_rate = False |
| 197 | for line in lines: |
| 198 | if line.get("invoice_id") != invoice_id: |
| 199 | continue |
| 200 | line_total_cents, line_tax_cents = _line_amounts(line) |
| 201 | subtotal_cents += line_total_cents |
| 202 | line_tax_cents_total += line_tax_cents |
| 203 | if _to_int(line.get("tax_rate_bps")): |
| 204 | any_line_states_a_rate = True |
| 205 | |
| 206 | # A fold must not replace a value it cannot reproduce. |
| 207 | # |
| 208 | # Tax can legitimately live in either of two places: on the LINES (a |
| 209 | # rate per line, summed here) or on the DOCUMENT (computed once over |
| 210 | # the whole taxable sale, which is how action_checkout does it, so that |
| 211 | # four fifty-cent lines at 5% owe 10c rather than the 12c four |
| 212 | # separately-rounded lines come to). This handler can only see the |
| 213 | # first. When no line states a rate, a recomputed tax of zero is not a |
| 214 | # finding -- it is this object looking in the wrong place -- and |
| 215 | # writing it destroys real money. |
| 216 | # |
| 217 | # It did. On the live shop a customer was quoted 2116 at checkout |
| 218 | # (1400 goods + 600 postage + 116 tax), and by the time the invoice |
| 219 | # lines had been written this pass had restated the invoice to 2000 |
| 220 | # with tax 0. The tests did not catch it because they never ran with |
| 221 | # event handlers enabled; the shop did, and the invoice disagreed with |
| 222 | # the price the customer had already agreed to. |
| 223 | if any_line_states_a_rate: |
| 224 | tax_cents = line_tax_cents_total |
| 225 | else: |
| 226 | tax_cents = _to_int(invoice.get("tax_cents")) |
| 227 | |
| 228 | total_cents = subtotal_cents + tax_cents |
| 229 | # balance_due_cents / amount_paid_cents are formula fields now (invoices |
| 230 | # v2, app-payments): the storage layer derives them from total and the |
| 231 | # payments/refunds rollups on every write. Writing them here would be |
| 232 | # rejected as a computed-field submission -- this object owns only the |
| 233 | # line-derived totals until those, too, graduate to rollups. |
| 234 | |
| 235 | changes = {} |
| 236 | if _to_int(invoice.get("subtotal_cents")) != subtotal_cents: |
| 237 | changes["subtotal_cents"] = str(subtotal_cents) |
| 238 | if _to_int(invoice.get("tax_cents")) != tax_cents: |
| 239 | changes["tax_cents"] = str(tax_cents) |
| 240 | if _to_int(invoice.get("total_cents")) != total_cents: |
| 241 | changes["total_cents"] = str(total_cents) |
| 242 | |
| 243 | if not changes: |
| 244 | return False |
| 245 | |
| 246 | try: |
| 247 | object_records.update_collection_record( |
| 248 | "invoices", invoice_id, changes, base_dir=base_dir, actor=ACTOR |
| 249 | ) |
| 250 | except (object_records.RecordNotFoundError, object_records.InvalidRecordPayloadError, |
| 251 | object_records.InvalidRecordIdError): |
| 252 | return False |
| 253 | return True |
| 254 | |
| 255 | |
| 256 | def EVENT(request): |
| 257 | """Dispatch entry point. request = {"event","collection","record_id","action"}. |
| 258 | |
| 259 | Post-commit, best-effort: every exception is caught here so a bad row |
| 260 | or a race with a concurrent delete never surfaces as a failed write. |
| 261 | object_server.py's own dispatcher already wraps this call in a |
| 262 | try/except for the same reason -- this is defense in depth, not |
| 263 | redundant. |
| 264 | """ |
| 265 | collection = str(request.get("collection") or "") |
| 266 | record_id = str(request.get("record_id") or "") |
| 267 | action = str(request.get("action") or "") |
| 268 | if collection != "invoice_lines" or not record_id: |
| 269 | return {"ok": True, "skipped": "not an invoice_lines event"} |
| 270 | |
| 271 | base_dir = _data_dir() |
| 272 | try: |
| 273 | invoice_id = _resolve_invoice_id(record_id, action, base_dir) |
| 274 | if not invoice_id: |
| 275 | _logger.info("invoice_totals: no invoice_id resolved", record_id=record_id, action=action) |
| 276 | return {"ok": True, "skipped": "no invoice_id"} |
| 277 | _sync_triggering_line(record_id, action, base_dir) |
| 278 | changed = _recompute_invoice(invoice_id, base_dir) |
| 279 | except Exception as exc: # never break the triggering write |
| 280 | _logger.warning("invoice_totals recompute failed", error=str(exc)) |
| 281 | return {"ok": False, "error": str(exc)} |
| 282 | |
| 283 | _logger.info("invoice_totals recomputed", invoice_id=invoice_id, changed=changed) |
| 284 | return {"ok": True, "invoice_id": invoice_id, "changed": changed} |