Skip to main content
Crew clock in and out of a gig on the mobile app. Managers review, fix, and approve the hours on web or mobile, and approved hours change hourly crew pay. Read the QA testing guide before you start.

At a glance

Before you start

  • An org with the flag on. Ask the QA lead which test org has time-clock on.
  • Clock-in turned on. An owner or admin opens web Settings → Organization → Gig workflow → Time clock and turns on Crew clock in and out.
  • A gig dated today in a known time zone, published (not a draft), with:
    • one crew member on an accepted hourly crew offer day, with a rate and call times,
    • one crew member on an accepted invitation,
    • one crew member on an accepted fixed-rate crew offer.
  • Accounts for each role: crew, gig lead, org coordinator, finance, and admin or owner.
A gig with clocked hours cannot be deleted. Archive it when you finish, and list it in your report.

In scope

Settings (web)

Crew clock in and out (mobile)

Offline clock (mobile)

Crew hours review (web)

Crew hours (mobile, managers)

Timesheets and export (web)

Pay from approved hours

Who sees what

Out of scope

Do not file these as bugs. They are not built yet.
  • Weekly overtime, meal penalties, turnaround and minimum calls. Only daily overtime and double time apply to time clock pay.
  • Hourly invitations. An invitation punch is always fixed rate.
  • Clock in or out for crew on the web app.
  • Manager clock in or out buttons. The API exists, the screens do not.
  • Time clock settings on mobile, and a read-only settings view for finance.
  • The No rate badge and deleted-gig rows on mobile.
  • A live worked total on web.
  • Reminder and alert pushes, until ENG-2037 applies the scheduled job in that environment. See Needs a real device.
  • iOS location permission wording (ENG-2027, needs a native build).

Known limitations

  • Mobile shows four counts, web shows five. Mobile Crew hours has no Clocked out count.
  • Hours panel from Timesheets has no Edit history. Open the panel from the gig’s Crew hours to see it.
  • A gig with hours cannot be deleted. The error says to cancel or archive the gig instead.
  • A clock-out within 5 minutes of the last one succeeds silently. The server treats it as a repeat, not an error.
  • Clocking in twice within 5 minutes of a manager entry marks the entry Duplicate for review instead of failing.
  • Turning the flag off mid-shift still lets crew clock out or set a stop time. The meal stepper hides, and the card disappears after clock-out.
  • A new entry on an already approved day does not change pay until a manager reviews it.

Needs a real device

TC-49 to TC-51 need a phone that receives pushes and the scheduled job from ENG-2037. Until that job runs in the environment, mark them BLOCKED. TC-52 needs a real location fix, from a phone or a simulator set to a custom location.

Edge cases worth a run

  • An overnight shift that crosses midnight in the gig’s zone.
  • A gig in a different time zone from the org and from the phone.
  • A multi-day crew offer. Each accepted day has its own clock.
  • Clocked in on one gig, then clock in on another: the second fails with a “clocked in elsewhere” message.
  • A fast double tap on Clock in.

For agents

  • API routes live under /events/{eventId}/time-clock for crew and /me/time-punches for My hours. List them with npm run api -- ops time.
  • Exception codes to expect: WINDOW_NOT_OPEN, WINDOW_CLOSED, NOT_WORKING_TODAY, NOT_CREW, FIXED_RATE, ALREADY_CLOCKED_IN, NOT_CLOCKED_IN, CLOCKED_IN_ELSEWHERE, PUNCH_OVERLAPS, OWN_HOURS.
  • Review exceptions the list can show: Missing clock-out, Over 16 hours, Duplicate (these block approval), and Early, Late, Hours differ from schedule, Device time mismatch, New device, Self-reported, Outside venue, Edited after approval.
  • Analytics (PostHog, from PR 5102): server events time_punch_created, time_punch_completed, time_punch_updated, time_punch_reviewed. Mobile events time_clock_viewed, time_clock_blocked_shown, time_punch_failed, time_clock_queue_synced, crew_hours_viewed, my_hours_viewed. Web sends no time clock events. Event properties are in docs/engineering/reference/analytics-taxonomy.mdx in the repository.
  • No seeded gig with punches exists on dev (ENG-2039). Create one per the setup above, and archive it at the end.