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
time_logs.json · 5.4 KB · 151 lines
| 1 | { |
| 2 | "name": "time_logs", |
| 3 | "title": "Time Logs", |
| 4 | "version": 4, |
| 5 | "description": "Work time against tasks. A running timer is a row with is_running true and no ended_at. Server-enforced by /timers/start, /timers/stop, /timers/running (62 - Timer, plan/vocabulary/62-timer-spec.md) -- see packages/app-timers/objects/site/timer_actions.py. v4 makes an entry billable: consulting hours are a usage metric with an APPROVAL GATE, and that gate is the only structural difference between time-and-materials billing and metered cloud billing -- both then run the same meter -> rate -> line -> invoice spine. status walks draft -> submitted -> approved -> billed, and the rate is STAMPED at approval from rate_cards (docs/logic-decisions.md #1), so a rate change next quarter can never reprice work somebody already approved. An approved or billed entry is frozen: correcting it is a compensating entry or a credit on the invoice, never an edit to the evidence of what happened (#5, #8).", |
| 6 | "fields": [ |
| 7 | { |
| 8 | "name": "id" |
| 9 | }, |
| 10 | { |
| 11 | "name": "task_id", |
| 12 | "label": "Task", |
| 13 | "relation": { |
| 14 | "collection": "tasks", |
| 15 | "display_field": "title" |
| 16 | } |
| 17 | }, |
| 18 | { |
| 19 | "name": "project_id", |
| 20 | "label": "Project", |
| 21 | "relation": { |
| 22 | "collection": "projects", |
| 23 | "display_field": "name" |
| 24 | }, |
| 25 | "help": "What the hours are billed against. Also half of the rate-card lookup: a rate scoped to this project beats the house default." |
| 26 | }, |
| 27 | { |
| 28 | "name": "started_at", |
| 29 | "type": "datetime", |
| 30 | "required": true, |
| 31 | "label": "Started" |
| 32 | }, |
| 33 | { |
| 34 | "name": "ended_at", |
| 35 | "type": "datetime", |
| 36 | "label": "Ended" |
| 37 | }, |
| 38 | { |
| 39 | "name": "is_running", |
| 40 | "type": "boolean", |
| 41 | "label": "Running", |
| 42 | "default": "false" |
| 43 | }, |
| 44 | { |
| 45 | "name": "notes", |
| 46 | "type": "text", |
| 47 | "label": "Notes" |
| 48 | }, |
| 49 | { |
| 50 | "name": "billable", |
| 51 | "type": "boolean", |
| 52 | "default": "true", |
| 53 | "label": "Billable", |
| 54 | "help": "Time worth recording is not always time worth charging for. Unbillable hours still count toward a project's cost -- they are simply never rated." |
| 55 | }, |
| 56 | { |
| 57 | "name": "status", |
| 58 | "type": "enum", |
| 59 | "default": "draft", |
| 60 | "label": "Status", |
| 61 | "enum": ["draft", "submitted", "approved", "rejected", "billed"], |
| 62 | "transitions": { |
| 63 | "draft": [{"to": "submitted", "when": {"owner_id": "$user_id"}}], |
| 64 | "submitted": ["approved", "rejected"], |
| 65 | "rejected": [{"to": "draft", "when": {"owner_id": "$user_id"}}], |
| 66 | "approved": ["billed", "rejected"], |
| 67 | "billed": [] |
| 68 | }, |
| 69 | "help": "Only the person who logged the time may submit it, and only somebody else's hand moves it to approved -- an approval you can grant yourself is not an approval. rejected returns to draft so the hours can be corrected and resubmitted rather than lost. approved -> billed is machine-advanced by the invoice generator; billed is terminal, because a disputed hour is a credit on the invoice, not a rewind." |
| 70 | }, |
| 71 | { |
| 72 | "name": "hourly_rate_cents", |
| 73 | "type": "integer", |
| 74 | "default": "0", |
| 75 | "label": "Rate", |
| 76 | "help": "Stamped at approval from the rate card in force on the day the work happened. Once stamped it belongs to this entry -- later rate changes never reprice approved work." |
| 77 | }, |
| 78 | { |
| 79 | "name": "amount_cents", |
| 80 | "type": "integer", |
| 81 | "default": "0", |
| 82 | "label": "Amount", |
| 83 | "help": "Stamped alongside the rate: round(billable seconds / 3600 * rate), half-up, once. The entry is what a client disputes, so it is the thing whose arithmetic they can reproduce." |
| 84 | }, |
| 85 | { |
| 86 | "name": "rate_card_id", |
| 87 | "label": "Rate Card", |
| 88 | "relation": {"collection": "rate_cards", "display_field": "label"}, |
| 89 | "help": "Which card was chosen. Keeps 'why am I being charged this?' answerable years later." |
| 90 | }, |
| 91 | { |
| 92 | "name": "invoice_id", |
| 93 | "label": "Invoice", |
| 94 | "relation": {"collection": "invoices", "display_field": "number"}, |
| 95 | "help": "Stamped when the entry is billed. An entry already carrying one is never billed again -- that is what makes re-running the generator safe." |
| 96 | }, |
| 97 | { |
| 98 | "name": "approved_by", |
| 99 | "type": "text", |
| 100 | "label": "Approved By" |
| 101 | }, |
| 102 | { |
| 103 | "name": "approved_at", |
| 104 | "type": "datetime", |
| 105 | "label": "Approved" |
| 106 | }, |
| 107 | { |
| 108 | "name": "created_at", |
| 109 | "type": "datetime", |
| 110 | "read_only": true, |
| 111 | "label": "Created" |
| 112 | }, |
| 113 | { |
| 114 | "name": "owner_id", |
| 115 | "type": "text", |
| 116 | "label": "Owner" |
| 117 | }, |
| 118 | { |
| 119 | "name": "duration_seconds", |
| 120 | "type": "integer", |
| 121 | "label": "Duration (seconds)", |
| 122 | "help": "Stamped by the stop verb: floor(ended_at - started_at). Never client-writable in practice -- omitted from forms.default, not schema read_only (update_collection_record has no preserve_read_only escape hatch; see packages/app-invoices/objects/system/invoice_totals.py for the same finding and the same workaround)." |
| 123 | } |
| 124 | ], |
| 125 | "hooks": {"before_write": "hook_time_logs"}, |
| 126 | "forms": { |
| 127 | "default": { |
| 128 | "fields": [ |
| 129 | "task_id", |
| 130 | "project_id", |
| 131 | "started_at", |
| 132 | "ended_at", |
| 133 | "is_running", |
| 134 | "billable", |
| 135 | "notes" |
| 136 | ] |
| 137 | } |
| 138 | }, |
| 139 | "views": { |
| 140 | "list_mode": "table", |
| 141 | "list_fields": [ |
| 142 | "task_id", |
| 143 | "project_id", |
| 144 | "started_at", |
| 145 | "duration_seconds", |
| 146 | "status", |
| 147 | "amount_cents" |
| 148 | ], |
| 149 | "filter_fields": ["status", "billable", "project_id"] |
| 150 | } |
| 151 | } |