Client Care Dashboard: Date Type filter (Inspection vs Booked)

Objective

• Add a Date Type filter to the Admin Client Care Dashboard so users can choose whether metrics are calculated by Inspection Date or Booked Date, instead of mixing appointment-date top KPIs with booking-date scheduler table semantics.
• Make regional coaching, weekly booking visibility, and finance review trustworthy: the same date basis applies everywhere on the page for a given filter selection.
• Surface Online Scheduler bookings (scheduledBy null) in their own section with the same metrics as employee performance for apples-to-apples comparison.

Background

• The Client Care dashboard (CCDashboardClient.tsx) loads two endpoints today with different date attribution and no user-visible control:
• GET /cc-dashboard/metrics — top KPI grid uses inspection datetime (appointment / inspection date).
• GET /cc-dashboard/scheduler-metrics — employee table uses scheduledTs (booking moment).
• Users reviewing “what we booked this week” see Total Revenue and Average Fee on appointment date while the scheduler table below uses booked date — misleading for coaching.
• KPI tooltips say “in the selected date range” but do not state which date field is used.
• Employee performance requires scheduledBy: { $ne: null }; online self-booked Attik jobs often have scheduledBy null and therefore never appear in the employee table despite contributing to regional totals.
• Attik is the job-creation path going forward; Spectora booking is no longer in scope for this bucket.

Product decisions

1. Date Type filter (no duplicate KPI tile rows)

• Add a filter alongside Companies, Time Period, and Date Range:
  • Inspection Date — filter/range on inspection datetime
  • Booked Date — filter/range on scheduledTs (timestamp set when the order is saved at booking time, whether the job is confirmed or unconfirmed at creation)
• Default: Booked Date
• Applies consistently across all three surfaces:
  • Top KPI tiles
  • Employee performance table
  • Online Scheduler section (unassigned)

1. Keep existing KPI set and employee columns

• Retain all current KPI cards (Revenue, Close Rate, Upsell Rate, Leads Created, Jobs Confirmed, Average Fee) and employee-table columns (orders created, cancel rate, one-call close, etc.) — same layout users see today.
• Date Type changes the date field used for range matching, not which metrics are shown. Pipeline KPIs (Leads, Close Rate) stay for now; can revisit later if users want simplification.

1. Online Scheduler section

• Jobs with scheduledBy: null appear in a separate Online Scheduler section (not mixed into employee rows).
• Same metrics and columns as employee performance, calculated the same way, so internal team vs online self-book is a clear comparison.
• Label: Online Scheduler (not Spectora — no new Spectora bookings).

1. Confirmed jobs for revenue / avg fee KPIs

• Revenue and Average Fee (and aligned confirmed-job counts where applicable) use confirmed inspections only — same confirmed-only revenue semantics as today’s KPI revenue path.
• Employee table retains existing columns including cancel rate and orders created (unchanged column set).

1. Saved views

• Date Type persists on saved Client Care dashboard views (ccDashboardSavedViews.ts) with companies, timeframe, date range, add-on categories, and scheduler selections so users do not re-select filters each visit.

1. Date field mapping

• Inspection Date → match on inspection datetime
• Booked Date → match on scheduledTs (booking save time), not quote createdAt
• Per-company timezone boundaries via existing buildCompanyTzRanges / TZDayjs patterns in ccDashboard.ts

Scope

Backend

• attik-backend/src/routes/ccDashboard.ts — accept dateType=inspection|booked (name TBD) on /metrics and /scheduler-metrics; drive $match on datetime vs scheduledTs consistently.
• attik-backend/src/routes/ccDashboardSavedViews.ts + saved view schema — persist dateType on create/update/read.
• Online Scheduler aggregation — same facet as scheduler metrics but scheduledBy: null, exposed in scheduler-metrics response (e.g. dedicated row/section) or parallel structure.
• Update file-header comments that document date attribution so they match the filter model.

Frontend

• attik-frontend/src/app/admin/client-care-dashboard/_components/DashboardHeader.tsx / shared DashboardHeader — Date Type control.
• CCDashboardClient.tsx — pass dateType to KPI and scheduler fetches; include in save-view payload.
• KPIStatsGrid.tsx — tooltip copy should state active date type (Inspection Date vs Booked Date).
• EmployeeTable.tsx — render Online Scheduler section with identical columns/metrics.
• _types.ts — extend saved view DTO and API params.

Acceptance criteria

• [ ] Date Type filter: Inspection Date and Booked Date; default Booked Date.
• [ ] Same Date Type drives KPI grid, employee table, and Online Scheduler section for the selected range.
• [ ] Inspection Date uses datetime; Booked Date uses scheduledTs.
• [ ] Online Scheduler section shows scheduledBy: null jobs with same metrics/columns as employees.
• [ ] Revenue / avg fee KPI paths remain confirmed-job-based.
• [ ] All existing KPI cards and employee columns remain visible (no layout regression).
• [ ] Date Type saves and restores on saved views.
• [ ] KPI tooltips mention which date type is active.

References

• attik-backend/src/routes/ccDashboard.ts
• attik-backend/src/routes/ccDashboardSavedViews.ts
• attik-backend/scripts/createCcDashboardViews.ts (scheduledTs, scheduledBy, datetime)
• attik-frontend/src/app/admin/client-care-dashboard/CCDashboardClient.tsx
• attik-frontend/src/app/admin/client-care-dashboard/_components/KPIStatsGrid.tsx
• attik-frontend/src/app/admin/client-care-dashboard/_components/EmployeeTable.tsx
• attik-backend/src/util/functions/inspection/createInspection.ts (scheduledTs at booking save)

Transcript Context

The team said the top regional dashboard numbers on the client care dashboard in admin attik were pulling revenue based on what was scheduled in that week instead of what schedulers had actually booked during the week. That made the view less useful for coaching and weekly booking visibility. They also called out that average fee was being derived from the scheduled-date basis, which made the metric misleading for the use case they had in mind. They suggested either making the date basis selectable or showing separate booked vs scheduled sections; product decision: single Date Type filter instead of duplicate metric tiles. They also noted that online scheduler and admin-created orders should be represented in the aggregate view; Online Scheduler section covers self-booked jobs with null scheduledBy.