Payroll Time Review Workflow

Summary

Payroll time review is the operator workflow for inspecting weekly time, opening day detail, understanding blockers, making pay-type or entry repairs, and preserving audit context before sync. The concept page Payroll Time Review explains the primitive; this thread explains the UI-to-service workflow.

Reader Question

How does the payroll UI make time evidence reviewable and repairable before sync is allowed?

Surface Or Workflow

Operators enter through the weekly grid, mobile review list, day detail modal, planned entries, repair panels, status legend, audit trail, and deferred dialogs. API routes adapt time-review requests into service calls.

Lifecycle

The service builds read models from source refresh state, payroll review rows, blocker rules, cell rules, and pay-type override state. The UI renders the review grid and day detail. Operators repair fields or overrides, then the service persists mutations and updates state used by sync eligibility.

Child Threads

Payroll Sync And Exceptions Workflow: what happens after review state is safe enough to sync.
Review Workflow Foundations: shared repair and audit pattern.

Implementation Boundaries

UI lives under app/web/app/payroll/time-review; API routes under app/api/payroll/time_review; read models, blockers, pay-type overrides, mutations, and service behavior under services/payroll/time_review; tests under tests/payroll.

Tradeoffs

The weekly grid is a dense operational surface. Keeping state in services rather than UI components makes it easier to reuse review logic for sync, exceptions, tests, and future diagnostics.

Visual

The current visual is a graph neighborhood. The intended visual is a review screen map from weekly grid to day detail, blocker, repair action, audit trail, and sync eligibility.

Source Evidence

docs/engineering/concepts/payroll-time-review.md
app/web/app/payroll/time-review
app/api/payroll/time_review
services/payroll/time_review/read_models.py
services/payroll/time_review/service.py
services/payroll/time_review/blockers.py
services/payroll/time_review/pay_type_overrides.py
docs/runbooks/payroll-time-review.md
tests/payroll/test_time_review_grid_contracts.py
tests/payroll/test_time_review_mutation_contracts.py