diff --git a/CLAUDE.md b/CLAUDE.md index 9d76848..01e173d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,13 @@ # FoxFitt LabourPay v5 +## What's mid-flight — read this first +**Parked / deferred work:** see `docs/plans/parked-work.md` for the +short list of features that are designed, half-built, or blocked on +Konrad's input. The active next-up brainstorm topic is **worker +absence records** (leave / sick / AWOL tracking). Phase A.2 (manual +JournalEntry UI) and Phase B (Letterly inbound webhook) from the +Site Work Logging design are parked pending Q5 / Q7 answers. + ## Coding Style - Always add clear section header comments using the format: # === SECTION NAME === - Add plain English comments explaining what complex logic does diff --git a/docs/plans/parked-work.md b/docs/plans/parked-work.md new file mode 100644 index 0000000..6d8a568 --- /dev/null +++ b/docs/plans/parked-work.md @@ -0,0 +1,139 @@ +# Parked / deferred work + +> Updated 14 May 2026. A small index of features that are designed, +> half-built, or blocked on input — but **not** the active priority. +> When a fresh session opens, glance here first to see what's +> already on the workbench. + +--- + +## Active queue + +### Worker absence records (NEW — to brainstorm) + +**Status:** Not yet brainstormed. Requested by Konrad in the +session that shipped Site Report Phase A.1. + +**One-line description:** Per-worker leave / sick / AWOL records, +separate from the implicit "not in a WorkLog" state. Likely mirrors +the `WorkerWarning` / `WorkerCertificate` pattern (per-worker, dated, +reason, optional document upload). + +**Recommended next action:** New session → run +`/superpowers:brainstorm` with the prompt: + +> "Worker absence records — should mirror the WorkerWarning pattern +> (per-worker, dated, optional doc). Need to define absence TYPES +> (paid leave / sick / AWOL / family responsibility / unpaid leave / +> public holiday / suspension), how absences show on +> /history/ and worker detail pages, and whether each type affects +> payroll calculations (paid leave should still generate a daily-rate +> amount; AWOL should not)." + +**Things to consider in the brainstorm:** +- **Type taxonomy.** Paid leave, sick leave, AWOL, family + responsibility, unpaid leave, public holiday, suspension. Each + has different payroll implications. +- **Payroll integration.** Does a "paid leave" absence auto-generate + a PayrollAdjustment (bonus-style, equal to one daily rate) on the + worker for that day? AWOL should NOT. Public holidays — depends + on SA labour law / FoxFitt policy. +- **UI placement.** Worker detail page tab (sibling to Certifications + and Warnings)? A tab/filter on `/history/`? A standalone + `/absences/` list? +- **Bulk entry.** Mark a whole team absent for a public holiday in + one form submission. Save a click per worker. +- **Document upload.** Doctor's notes / leave-form scans. Re-use + `validate_max_5mb()` from `core/forms.py`. +- **Admin / supervisor scoping.** Supervisors can mark absent + workers on their team; admins see everything. +- **Reporting.** Per-worker annual leave-day totals on the worker + batch report. + +**Models to learn from in `core/models.py`:** +- `WorkerWarning` — per-worker, severity choices, dated, optional + document, ordered `-date`. Good shape match. +- `WorkerCertificate` — per-worker, type choices with `unique_together`, + `valid_until` expiry, `is_expired` / `expires_soon` properties. + +--- + +## Blocked on Konrad's input + +### Phase A.2 — Manual JournalEntry web UI + +**Status:** Designed in the Site Work Logging brainstorm. Model +class drafted in the design doc (not yet in `core/models.py`). +Not yet built. + +**Blocked on:** Q7 from the original brainstorm — "Who is Vi?" The +answer drives whether `JournalEntry` needs a `recipient` or +`audience` field (i.e. is this a public log, or does it have +specific addressees like a client). **Default if unanswered:** no +recipient field — entries are all-admin-readable. + +**Scope when unblocked:** ~1 hour of work. Manual entry form at +`/journal/new/`, list at `/journal/`, edit at `/journal//edit/`. +Admin-only views. Lives on `ai-dev` (no webhook involvement). + +### Phase B — Letterly inbound webhook (`integrations` branch) + +**Status:** Designed in the Site Work Logging brainstorm. Belongs +on the `integrations` branch, **not** `ai-dev`. + +**Blocked on:** Q5 from the original brainstorm — Konrad needs to +share a sample Letterly webhook payload. Need to know: +- Does it include the recording user (so we can map to a Django User)? +- Does it include project / location metadata, or just the transcript? +- Does it include an audio URL for link-back? +- Does Letterly support custom fields (so a deep-link from + `/site-report//edit/` could embed a `work_log_id` that the + webhook reads back)? + +**Scope when unblocked:** ~3-4 hours including tests + one-off +Letterly account setup. Adds a `@csrf_exempt` view at +`/webhooks/letterly/`, `JournalEntry` row creation, HMAC body +verification, shared-secret URL token. + +--- + +## Defaulted (not blocking — flag if you disagree) + +From Q9, Q4 of the Site Work Logging brainstorm: + +- **Q9 — photos on site reports.** Deferred to v2 of SiteReport. + Construction supervisors often want to attach a phone photo of + "plinths cast today" but it adds ~50 LOC + storage handling + + thumbnail rendering. v1 ships without. +- **Q4 — per-project metric templates.** Same metric set for all + projects in v1. If/when a non-solar-farm project lands and the + metrics diverge wildly, we add a `MetricTemplate` model. YAGNI + for now — `core/site_report_schema.py` is one Python file edit. + +--- + +## Recently shipped (for context, so a fresh session knows what just landed) + +- **Phase A.1 — SiteReport** (commit `864ae72`, 14 May 2026): + Model, migration `0013_add_site_report.py`, form, two-step flow + from attendance log, 16 new tests. All 85 / 85 tests passing. + `CLAUDE.md` updated with model summary + `site_report_schema.py` + pattern section. +- **Pastel soft-fill payroll action buttons** (commit `6c6ade9`, + 24 Apr 2026): unified Worker Lookup / Batch Pay / Add Adjustment + / Price Overtime treatment. +- **Path A display-only rename** (UX Polish Pass, Apr 2026): + "New Loan" / "Advance Payment" / "Advance Repayment" display as + "Loan" / "Advance" / "Advance Repaid" — but **DB values are + unchanged**. See "UI-vs-DB naming drift" section in `CLAUDE.md` + before writing any filter/comparison on `PayrollAdjustment.type`. + +--- + +## Original Site Work Logging brainstorm + +The full Q1-Q13 question list and design rationale lives in +`~/.claude/plans/prancy-painting-brook.md` (local — deliberately +not committed to the repo, since the parts that matter have been +absorbed into `CLAUDE.md` and this file). If Konrad answers Q5 or +Q7 later, refer back to that file for the original framing.