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
expense_books.py · 4.7 KB · 134 lines
| 1 | """system_expense_books -- HANDLES expenses writes; posts the journal. |
| 2 | |
| 3 | An approved expense composes one balanced entry: |
| 4 | |
| 5 | DR the expense account (what it was for) |
| 6 | CR the clearing account (company card or cash), OR |
| 7 | CR the reimbursable liability (when a person paid personally) |
| 8 | |
| 9 | That second credit is the whole reason paid_by exists as a field. An |
| 10 | employee's own card creates a DEBT the business owes them; booking it |
| 11 | against the company's cash account claims money left an account it never |
| 12 | left, and the person is left chasing a reimbursement the ledger has no |
| 13 | record of. Most expense tools model this as a flag on a report; here it |
| 14 | is the account the credit lands in, which is the only place it can |
| 15 | actually be true. |
| 16 | |
| 17 | Placement follows docs/logic-decisions.md #6: this is a REACTION |
| 18 | (post-commit, best-effort, never blocks the write), so it lives in an |
| 19 | event handler rather than the hook. Somebody recording that they bought a |
| 20 | plane ticket must not be stopped because nobody has mapped a chart of |
| 21 | accounts yet -- an unconfigured books mapping skips with a reason and the |
| 22 | expense stands. |
| 23 | |
| 24 | Configuration (app_settings): |
| 25 | expenses.journal.expense_account default DR when an expense names none |
| 26 | expenses.journal.paid_account CR for company-paid spend |
| 27 | expenses.journal.reimbursable_account CR for personally-paid spend |
| 28 | |
| 29 | Idempotency by provenance: generated_from "expenses/{id}", so a replayed |
| 30 | event composes nothing (doctrine #7). |
| 31 | """ |
| 32 | |
| 33 | import os |
| 34 | |
| 35 | import object_finance |
| 36 | import object_records |
| 37 | |
| 38 | HANDLES = [ |
| 39 | "expenses.record.created", |
| 40 | "expenses.record.updated", |
| 41 | ] |
| 42 | |
| 43 | ACTOR = "system_expense_books" |
| 44 | |
| 45 | |
| 46 | def _base_dir(): |
| 47 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 48 | |
| 49 | |
| 50 | def _setting(base, key, default=""): |
| 51 | try: |
| 52 | for row in object_records.read_collection_records("app_settings", base_dir=base): |
| 53 | if row.get("key") == key and str(row.get("value") or "").strip(): |
| 54 | return row["value"].strip() |
| 55 | except Exception: |
| 56 | pass |
| 57 | return default |
| 58 | |
| 59 | |
| 60 | def _int(value): |
| 61 | try: |
| 62 | return int(str(value or "0").strip() or 0) |
| 63 | except (TypeError, ValueError): |
| 64 | return 0 |
| 65 | |
| 66 | |
| 67 | def _text(value): |
| 68 | return str(value if value is not None else "").strip() |
| 69 | |
| 70 | |
| 71 | def _record_for(request, base): |
| 72 | record = request.get("record") |
| 73 | if isinstance(record, dict) and record.get("id"): |
| 74 | return record |
| 75 | record_id = _text(request.get("record_id") or request.get("id")) |
| 76 | if not record_id: |
| 77 | return None |
| 78 | try: |
| 79 | return object_records.get_collection_record("expenses", record_id, base_dir=base) |
| 80 | except Exception: |
| 81 | return None |
| 82 | |
| 83 | |
| 84 | def EVENT(request): |
| 85 | base = _base_dir() |
| 86 | expense = _record_for(request, base) |
| 87 | if not expense: |
| 88 | return {"ok": True, "skipped": "no expense in the event"} |
| 89 | if _text(expense.get("status")) not in ("approved", "billed"): |
| 90 | # Nothing is owed and nothing was authorised until somebody |
| 91 | # approved it; a draft expense is a note to self. |
| 92 | return {"ok": True, "skipped": "not approved"} |
| 93 | |
| 94 | amount = _int(expense.get("amount_cents")) |
| 95 | if amount <= 0: |
| 96 | return {"ok": True, "skipped": "zero amount"} |
| 97 | |
| 98 | debit = (_text(expense.get("account_id")) |
| 99 | or _setting(base, "expenses.journal.expense_account")) |
| 100 | personal = _text(expense.get("paid_by")) == "personal" |
| 101 | credit = _setting( |
| 102 | base, |
| 103 | "expenses.journal.reimbursable_account" if personal |
| 104 | else "expenses.journal.paid_account") |
| 105 | if not debit or not credit: |
| 106 | return {"ok": True, "skipped": "accounts unconfigured", |
| 107 | "needs": ["expenses.journal.expense_account", |
| 108 | "expenses.journal.reimbursable_account" if personal |
| 109 | else "expenses.journal.paid_account"]} |
| 110 | |
| 111 | memo = ("reimbursable to " + _text(expense.get("owner_id")) if personal |
| 112 | else "paid by the company") |
| 113 | return object_finance.compose_posted_journal( |
| 114 | base, |
| 115 | generated_from=f"expenses/{expense['id']}", |
| 116 | date=_text(expense.get("incurred_on")), |
| 117 | description=f"Expense: {_text(expense.get('description')) or expense['id']}", |
| 118 | lines=[ |
| 119 | {"account_id": debit, "debit_cents": amount, "credit_cents": 0, |
| 120 | "memo": _text(expense.get("description"))}, |
| 121 | {"account_id": credit, "debit_cents": 0, "credit_cents": amount, |
| 122 | "memo": memo}, |
| 123 | ], |
| 124 | owner_id=_text(expense.get("owner_id")), |
| 125 | entity_id=_text(expense.get("entity_id")), |
| 126 | actor=ACTOR, |
| 127 | ) |
| 128 | |
| 129 | |
| 130 | # EVENT is the verb the change dispatcher calls handlers with (see |
| 131 | # object_change_dispatch); the same POST-instead-of-EVENT slip as |
| 132 | # system_shop_fulfillment, fixed the same day. POST stays as an alias so |
| 133 | # an operator can poke the handler by hand over HTTP. |
| 134 | POST = EVENT |