38686-vm/docs/plans/2026-04-22-work-log-payroll-crosslink-design.md

Work Log → Payroll Cross-Link — Design (22 Apr 2026)

Goal

Let admins click a historic work log (anywhere it appears) and instantly see which workers on that log have been paid, which haven't, and for paid ones, which payslip paid them — with hyperlinks through to the existing Worker and Payslip detail pages.

Today the data exists (PayrollRecord.work_logs M2M, PayrollAdjustment.work_log FK) but is only reachable from the payroll dashboard by working backwards from a payment to its logs. This closes the loop: from a log you can reach its payments, not just the other way round.

Who it's for

• Admins (is_staff=True or is_superuser=True) — full click-through to payroll data
• Supervisors (Work Logger group) — unchanged behaviour. Payroll data stays hidden per the existing permission rule.

Entry points (three places, same modal)

Page	Row source
/history/ — Work History	each WorkLog in the paginated table
/teams/<id>/ — Recent Work Logs card	same logs, team-filtered
/projects/<id>/ — Recent Work Logs card	same logs, project-filtered

On each of these, the work-log row becomes clickable for admins: cursor: pointer, --bg-card-hover on hover, a small chevron icon at the right edge. For supervisors the rows keep their current non-interactive styling.

Interaction model — hybrid modal + full page

• Row click → Bootstrap modal fetches JSON and renders inline. Fast path for "did X get paid for this?". Same pattern as the existing Worker Lookup modal.
• [Open full page] button inside the modal → navigates to /history/<log_id>/, a dedicated bookmark-able page. Unlimited room for detail.

Both views share the same underlying data; the modal is a compact subset of the page.

What each view shows

Modal (compact)

1. Header strip — date, project (link), team (link), supervisor, worker count, OT-priced flag
2. Workers table — one row per log.workers.all():
   • Worker name → /workers/<id>/
   • Status: Paid · Priced, not paid · Unpaid
   • Earned from this log (net of adjustments on the same payroll record)
   • Payslip reference → /payroll/payslip/<pk>/ (or —)
   • Paid on date (or —)
3. Related adjustments — every PayrollAdjustment with adj.work_log == log. Worker and payslip as links.
4. Footer — total earned, total paid, total outstanding · [Open full page] · [Close]

Full page (/history/<log_id>/)

Everything the modal has, plus:

• Breadcrumb — History › {date} · {project} · {team}, each segment a link
• Attendance detail block — OT hours per worker (from log.overtime), supervisor, notes
• Pay-period context — uses get_pay_period(log.team) to show which period this log falls in and expected paydate if unpaid. Graceful "no schedule configured" fallback if the team has no pay_frequency.

Layout matches /workers/<id>/ — single-column card-paneled page, same typography and spacing.

Status logic (three states)

For each worker on the log:

record = PayrollRecord.objects.filter(work_logs=log, worker=worker).first()

if record:
    status = "Paid"           # show payslip + date
elif worker in log.priced_workers.all():
    status = "Priced, not paid"   # OT priced, no payroll cycle yet
else:
    status = "Unpaid"

Same per-worker checking CLAUDE.md documents for the dashboard's outstanding calculation. Handles partially-paid logs correctly.

Edge cases

• Brand-new log, never paid → all workers Unpaid, zero totals, no error
• Partially paid → mixed statuses per row (the whole reason per-worker checking exists)
• Overtime not yet priced (log.overtime > 0 and log.priced_workers empty) → amber banner at top of modal: "Overtime not yet priced · [Price now]" linking to the existing price_overtime flow
• Worker deactivated since → name struck through, grey Inactive pill, still shown
• Team/project deleted (SET_NULL) → header shows — for the missing reference, no crash
• Supervisor hits URL directly → 403 via is_admin(), same as every /payroll/* view
• Log with many workers → modal scrolls internally (max-height: 70vh); full page handles it natively

Implementation shape (no code yet)

New URLs

/history/<int:log_id>/              → work_log_payroll_detail    (HTML full page)
/history/<int:log_id>/payroll/ajax/ → work_log_payroll_ajax      (JSON for modal)

New views in core/views.py (both @login_required, both admin-gated)

• _build_work_log_payroll_context(log) — private helper. Returns a context dict with workers+status, adjustments, totals, pay-period info. One function, used by both endpoints so the JSON payload and the HTML page can never drift.
• work_log_payroll_ajax(request, log_id) — calls the helper, returns JSON for the modal
• work_log_payroll_detail(request, log_id) — calls the helper, renders the full-page template

New template

• core/templates/core/work_log_payroll.html — full-page view. Structure mirrors /workers/<id>/ so it feels like a sibling.

Small edits to existing templates

• core/templates/core/work_history.html — admin-gated data-log-id attribute on each row + JS click handler
• core/templates/core/teams/detail.html — same on the Recent Work Logs card rows
• core/templates/core/projects/detail.html — same

New JS (inline in base.html or work_log_modal.js)

• Single click handler, attached to [data-log-id] elements across any page
• fetch → inject HTML into a shared #work-log-payroll-modal defined once in base.html
• Same pattern as the existing Worker Lookup modal

What we DON'T need

• No model changes
• No migrations
• No new fields
• No changes to process_payment, add_adjustment, or any mutation path

Cross-links this adds to the app's graph

Before:

Payroll Dashboard → Payslip → [dead end]
Work History      → [dead end]

After:

Work History ↘                    Payslip ↗ Worker detail
Team detail → Work Log Payroll →
Project detail ↗                  Worker name ↘ Worker detail

Every work log becomes a first-class navigable node, reachable from three places, linking out to the two existing detail pages.

Rough scope

• ~150 lines new view code (helper + two endpoints)
• ~120 lines new full-page template
• ~40 lines JS for the modal
• ~30 lines CSS for hover and chevron states
• ~20 lines of edits across three existing templates

No third-party dependencies added.

Out of scope (deliberately)

• "Pay these workers now" action inside the modal/page — kept read-only for this pass; admins still use the payroll dashboard's Pay flow. Can add later if useful.
• "Add adjustment pre-filled for this log" shortcut — tempting but expands scope; revisit after the read-only version ships.
• Supervisor-visible attendance-only view of the same click-through — supervisors get no click affordance for now; if they later need a non-payroll drill-down, that's a separate design.

Next step

Hand off to superpowers:writing-plans to produce a task-by-task implementation plan with review checkpoints.

---

Shipped — 22 Apr 2026

Commits: 1c00ba2 (design) through the Task 10 "shipped" commit (this one). Plan: docs/plans/2026-04-22-work-log-payroll-crosslink-plan.md.

QA summary:

• 19 tests pass (python manage.py test core.tests)
• python manage.py check — no new issues
• No model changes, no migrations, no pushed-to-prod artefacts
• Three entry points clickable for admins; supervisors unchanged

Deferred for future passes (non-blocking):

• Admin-gate consistency: work_history uses {% if is_admin %}; teams/projects detail templates use {% if user.is_staff or user.is_superuser %}. Both semantically identical but stylistically inconsistent.
• Task 4 template branch tests: OT banner, adjustments table, Paid badge, Inactive worker — covered end-to-end via modal tests now, not via Django test client.
• Task 4 template: redundant |default:0 on log.overtime_amount (harmless, renders "0" instead of "0.00").
• Task 5 admin gate: user.is_authenticated and user.is_staff or user.is_superuser could be simplified to user.is_staff or user.is_superuser.
• background shorthand in Task 9 hover rule could be background-color for precision (pedantic).

"Pay these workers now" modal action and "Add adjustment pre-filled for this log" shortcut — explicitly out-of-scope per the design; revisit if users ask.