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
invoice_totals.py · 12.5 KB · 284 lines
1"""invoice_totals -- HANDLES invoice_lines writes; recomputes invoice totals.
2
3Registered as a Phase-5a event handler (object_handlers.py,
4docs/event-hooks-decisions.md, docs/upgrade-and-customization.md Rule 4).
5The platform's post-commit dispatcher (object_server.py's
6_dispatch_event_handlers) executes this object's EVENT method whenever a
7client-facing write to invoice_lines commits, but only when the operator
8has DBBASIC_ENABLE_EVENT_HANDLERS set. With the flag unset (the default),
9invoice_lines/invoices writes still succeed -- they just stop getting
10fresher totals until a line is touched again after the flag is turned on.
11Same posture plan/vocabulary/20-invoice-spec.md documents for itself.
12
13Integer-cents arithmetic only, per 00-doctrine-and-contract.md /
1420-invoice-spec.md: money is always a whole number of cents. quantity is
15the one deliberate exception to "never a float" in this package, because
16it is a count/measure (e.g. 2.5 hours), not currency. Line/tax math uses
17Decimal (never a bare Python float) so a fractional quantity can never
18introduce binary-float rounding error, then floors to an integer number
19of cents -- never rounds up ("exact arithmetic, floor not round").
20
21Why these fields are NOT schema `read_only` despite the task brief asking
22for it: verified against object_records.py before writing this file.
23`update_collection_record` has no `preserve_read_only` escape hatch at
24all (only `create_collection_record` does, and even there defaults are
25never stamped onto a read_only field -- see `_apply_schema_defaults`), so
26a genuinely `read_only` field can never be written again after creation,
27by ANY caller, including this handler's own follow-up write. Marking
28subtotal_cents/tax_cents/total_cents/balance_due_cents/line_total_cents/
29line_tax_cents read_only would therefore let this handler compute the
30correct value once and then permanently fail to ever write it again.
31Instead this package follows plan/vocabulary/20-invoice-spec.md's own
32already-reasoned fallback posture for exactly this situation ("Permissions
33Posture"): these stay ordinary owner-writable fields, simply omitted from
34forms.default so the generated form never renders them as editable
35inputs (confirmed against packages/app-theme/objects/site/form.py's own
36`skip()`, which also independently omits any read_only field --
37belt-and-suspenders, not the primary protection); any actual tamper is
38fully visible in record_changes (before/after, actor, timestamp)
39regardless. Detection, not prevention -- the same backstop the platform
40already relies on elsewhere.
41
42Idempotence: every write below is compared against the already-stored
43value first and skipped if unchanged. This platform's dispatch lives in
44object_server.py's HTTP request handlers, not inside object_records.py
45itself (checked: object_records.py has zero references to event
46dispatch), so a handler calling object_records directly -- as this one
47does -- does not currently re-enter the dispatcher and cannot recurse.
48The guard is kept anyway: it is cheap, it avoids a pointless no-op write
49and record_change entry on every re-run, and it is the correct discipline
50regardless of whether a future refactor moves dispatch closer to the
51write path (plan/vocabulary/20-invoice-spec.md calls this out as an open
52question worth a shared helper one day).
53"""
54from __future__ import annotations
55
56import os
57from decimal import ROUND_FLOOR, Decimal
58
59import object_record_changes
60import object_finance
61import object_lines
62import object_records
63
64HANDLES = [
65 "invoice_lines.record.created",
66 "invoice_lines.record.updated",
67 "invoice_lines.record.deleted",
68]
69
70ACTOR = "invoice_totals"
71DATA_DIR_ENV = "DBBASIC_DATA_DIR"
72
73
74def _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
80def _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
91def _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
104def _line_discount(line: dict) -> int:
105 return object_lines.line_amounts(line)["discount_cents"]
106
107
108def _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
140def _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
179def _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
256def 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}