PSA/ee/docs/plans/2025-12-14-time-entry-work-date-plan.md

Time Entry “Work Date” Plan (Option A)

Date: December 14, 2025
Status: Proposed
Owner: Time Tracking / Billing

Decisions (Confirmed)

• work_date is not user-editable.
• work_date is computed in the user’s timezone (i.e., “the user’s calendar date”).
• We will store the timezone used for computation on each entry as work_timezone (for audit/debug).

Problem

Today, time entry → time sheet → time period mapping is effectively instant-based (start_time/end_time as timestamps) while time periods and the timesheet UX are calendar-based (“Apr 1–Apr 7”, “week of Apr 1”, etc.). Because instants are stored/compared in UTC-ish representations, users in non-UTC timezones can end up entering “Apr 1” locally while the system evaluates the entry against a different calendar day, creating confusing edge cases when determining the correct period_id/timesheet.

We want to keep the current architecture (persisted time_periods, time_sheets keyed by period_id, approvals, period CRUD, background period generation) while removing the conceptual mismatch between user-local calendar days and UTC instants.

Proposed Solution (Option A)

Introduce an explicit date-based bucketing field on time entries:

• Add work_date to time_entries as a date (no time).
• Define work_date as “the calendar date the work is attributed to” in the user’s timezone.
• Determine the time period / timesheet association using work_date vs time_periods.start_date/end_date (date-to-date comparisons), not using UTC instants.

We will still store start_time and end_time as instants for duration, auditability, ordering, and billing calculations, but grouping and period membership will use work_date.

Timezone Source of Truth

We need a stable source of truth for the user’s timezone at entry creation time.

Recommended resolution order:

1. users.timezone (preferred, already exists in schema)
2. Tenant default timezone (if we have one)
3. 'UTC' (last resort)

Note: even if we fall back to a non-user timezone, we still persist work_timezone so we can detect and remediate missing user timezone configuration.

Goals

• Preserve existing persisted time_periods behavior (listing, manual overrides, scheduled creation job).
• Make timesheet bucketing consistent with “calendar day” as the UI expresses it.
• Minimize schema/code churn and keep backwards compatibility.
• Avoid retroactively changing historical timesheet membership when settings/timezones change.

Non-Goals

• Eliminating time_periods records.
• Reworking the billing cycle subsystem.
• Changing approval semantics.

Data Model Changes

1) time_entries

Add:

• work_date DATE NOT NULL
• work_timezone TEXT NOT NULL
  • Stores the timezone used to compute work_date at create/update time (e.g., America/Los_Angeles).

Indexes (initial recommendation):

• (tenant, user_id, work_date)
• (tenant, work_date)

2) (Optional) time_sheets snapshot fields

Not strictly required for Option A, but consider adding:

• period_start_date DATE
• period_end_date DATE

This reduces join dependency for display and provides a historical snapshot even if periods are edited. If we keep period edit capability, we must decide whether edits should:

• update existing timesheets’ displayed boundaries, or
• be blocked once timesheets exist (current behavior blocks editing if sheets exist in server/src/lib/actions/timePeriodsActions.ts).

Behavior Changes

A) Saving a time entry

When creating/updating a time entry:

• Compute work_date from start_time using the resolved user timezone.
• Persist work_date and work_timezone.
• Ignore any incoming work_date/work_timezone fields from clients (not user-editable).

B) Choosing a timesheet / period for an entry

When an entry is created outside a timesheet context (API, quick-add):

• Find the time_periods row where:
  • start_date <= work_date and end_date > work_date (treat periods as half-open [start,end) dates)
• Then fetchOrCreateTimeSheet(user_id, period_id) and attach time_sheet_id.

When an entry is created from a specific timesheet UI:

• Continue attaching directly to that time_sheet_id/period_id.
• Still compute/persist work_date for consistency and reporting.

C) Validation rule

Replace “time entry must fall within a valid time period” checks that currently compare instants with checks that compare work_date with period date boundaries.

Migration / Backfill Plan

Existing rows in time_entries need a backfilled work_date.

Constraints:

• Historical user timezone at time of entry may not be available.

Backfill strategy options:

1. User timezone backfill (preferred): compute using users.timezone when present.
2. Fallback backfill: if a user has no timezone, fall back to tenant default (if any) else 'UTC'.

Backfill must also populate work_timezone with whatever timezone was used per row so we can identify entries computed with fallback logic.

Implementation Surface (What Changes Where)

Project-Specific Gotchas / Clarifications

• Time periods are date-based: migrate time_periods.start_date/end_date to DATE (timezone-agnostic), keeping half-open [start,end) semantics. This eliminates server-timezone and cast-related ambiguity and makes period membership comparisons explicitly date-to-date.
• Resolving users.timezone server-side: server actions that compute work_date (and “current period”) need a reliable way to fetch the current user and then read users.timezone.
  • For interactive flows: resolve timezone from the authenticated user record.
  • For non-interactive/system contexts (background jobs, service accounts): define an explicit fallback rule (tenant default or 'UTC') and persist that choice to work_timezone.
• Enterprise/Citus impact: EE has Citus distribution migrations that reference time/billing tables. Adding columns/indexes to time_entries should be verified against EE distributed table behavior (and include any EE-specific migration steps if required).
• Validation/test ripple: adding work_date/work_timezone will require updates across:
  • TypeScript interfaces (server/src/interfaces/timeEntry.interfaces.ts)
  • Zod schemas used by UI/server actions (server/src/lib/schemas/timeSheet.schemas.ts) and API schemas (server/src/lib/api/schemas/timeEntry.ts)
  • Test factories and fixtures that insert time_entries rows
• “Today” in UI: existing code uses UTC-derived strings (e.g. new Date().toISOString().slice(0, 10)) for “today/current period” checks. These must be replaced with browser-local date logic anywhere they influence “current” labeling or default date selection.

Screens (UI)

• server/src/components/time-management/time-entry/time-sheet/TimeEntryDialog.tsx
  • Ensure create/update calls do not send work_date; server computes it.
  • Validate the date/time pickers produce correct instants for start_time/end_time (avoid date-only parsing pitfalls).
• server/src/components/time-management/time-entry/time-sheet/TimeSheetTable.tsx
  • Any “quick add” path that constructs timestamps from a displayed date should construct instants in the user’s timezone (not via toISOString().slice(0,10) patterns).
• server/src/components/time-management/time-entry/TimePeriodList.tsx
  • The “Current” period highlight should use the user’s local date (not UTC derived from toISOString()).
• “Create time entry from elsewhere” entry points that call saveTimeEntry:
  • server/src/components/time-management/interval-tracking/IntervalManagement.tsx
  • server/src/components/tickets/ticket/TicketDetails.tsx
  • server/src/components/projects/TaskForm.tsx
  • server/src/components/interactions/InteractionDetails.tsx
  • server/src/components/tickets/TicketingDashboard.tsx
  • server/src/components/user-activities/ActivityDetailViewerDrawer.tsx
  • Confirm these flows still land in the expected timesheet/period after work_date becomes authoritative.

Server Actions (Next.js “use server”)

• server/src/lib/actions/timeEntryCrudActions.ts
  • Compute and persist work_date/work_timezone on create/update.
  • Ignore any client-supplied values for these fields.
• server/src/lib/actions/timePeriodsActions.ts
  • Update getCurrentTimePeriod() to compute “today” in the user’s timezone (not server timezone).
• server/src/lib/actions/timeSheetOperations.ts
  • Ensure any “current period” or “entry belongs to period” logic is date-based where applicable.

API Services (REST-ish)

• server/src/lib/api/services/TimeEntryService.ts
  • When creating entries (and when auto-creating timesheets), use work_date (computed via user timezone) to find the correct period and timesheet.
  • Update getTimePeriodForDate/getOrCreateTimeSheet logic to compare using date values, not Date objects interpreted in server timezone.
  • Update time-tracking session start/stop flows to persist work_date/work_timezone.
• server/src/lib/api/services/TimeSheetService.ts
  • If any endpoints derive “current period” or generate periods based on “today”, ensure “today” is user-local where needed (or explicitly tenant-local if it’s admin/system).

Billing / Background Jobs

• server/src/lib/billing/billingEngine.ts
  • rolloverUnapprovedTime(...) mutates start_time/end_time; it must recompute and persist work_date accordingly (using the entry’s work_timezone if available, otherwise resolve via user timezone).

Types / Schemas

• server/src/interfaces/timeEntry.interfaces.ts
  • Add work_date and work_timezone to the time entry interface(s) as appropriate.
• API Zod schemas in server/src/lib/api/schemas/timeEntry.ts
  • Ensure work_date/work_timezone are not client-writable; return them in responses if useful.

Phases & To-Dos

Phase 0 — Confirm invariants + timezone readiness

• Confirm users.timezone is populated in real environments; if not, define how it gets set (e.g., profile screen, onboarding, or a one-time “set timezone” prompt).
• Decide how strictly to enforce missing users.timezone (warn + fallback vs block time entry creation until set).
• Align on the definition of “user’s timezone” for service accounts/API clients (what timezone do we use when there is no interactive user?).

Phase 1 — Database migration + backfill

• Add work_date and work_timezone columns to time_entries (start nullable).
• Migrate time_periods.start_date/end_date to DATE (timezone-agnostic) and update any dependent code/queries accordingly.
• Backfill existing rows:
  • Join to users to compute work_date using users.timezone when present.
  • Use fallback timezone when missing, and persist the fallback into work_timezone.
• Add NOT NULL constraints after backfill.
• Add indexes for expected query patterns ((tenant, user_id, work_date), (tenant, work_date)).

Phase 2 — Server actions write-path

• Update saveTimeEntry flow to compute/persist work_date/work_timezone from start_time in the user timezone.
• Ensure updates that modify start_time also update work_date (and keep work_timezone consistent).
• Ensure client-supplied work_date/work_timezone are ignored/rejected.

Phase 3 — “Current period” and period membership logic

• Update getCurrentTimePeriod() to use the user’s local date (derived from users.timezone) when selecting a period.
• Audit any remaining “find period for date” logic to ensure it compares using date values and consistent half-open boundaries.

Phase 4 — REST API alignment

• Update TimeEntryService create/update paths to compute/persist work_date/work_timezone.
• Update time-tracking session start/stop to populate these fields.
• Update period lookup + auto-timesheet creation to use work_date rather than server-interpreted Date comparisons.
• Update API schemas to treat work_date/work_timezone as server-controlled fields.

Phase 5 — Frontend adjustments and regression fixes

• Update any UI “current period” indicator logic that uses UTC date strings to use the browser’s local date.
• Audit “quick add”/inline creation code paths that build timestamps from a displayed date and ensure they produce correct instants.
• Ensure all entry-creation entry points remain functional and land in the expected timesheet.

Phase 6 — Billing/job correctness

• Update BillingEngine.rolloverUnapprovedTime(...) to recompute work_date whenever it adjusts timestamps.
• Search for any other code paths that mutate time_entries.start_time/end_time and ensure they also maintain work_date.

Phase 7 — Tests, rollout, monitoring

• Add/extend tests covering timezone edge cases (entries around local midnight mapping to the expected period).
• Add a lightweight metric/log for “missing user timezone used fallback” to drive cleanup.
• Roll out behind a feature flag if desired, or deploy as a schema-first migration with dual-write then cutover.

Open Questions

• For API integrations (no browser context), what is the expected timezone rule for work_date?