ca-grow-ops-manager/specs/labor-and-hours.md

Feature Spec: Labor and Hours

Domain: Labor
Status: Draft
Version: 0.1.0
Last Updated: 2025-12-08

---

Overview

The Labor and Hours module provides a web/mobile timeclock for staff to track their hours, associate time to specific rooms and batches for cost visibility, and generate reports for payroll and batch profitability analysis. It does NOT process payroll but provides CSV exports suitable for external payroll systems.

---

User Stories

As a Staff Member

• I want to clock in and out quickly on a tablet so I can start working without friction
• I want to select which room or batch I'm working on so my time is attributed correctly
• I want to add notes about what I did during my shift so there's a record

As a Head Grower

• I want to see which staff are currently clocked in and where they're working so I can coordinate tasks
• I want to see labor hours per batch so I can identify which batches are labor-intensive

As an Owner

• I want to see labor costs per batch so I can calculate profitability
• I want to export hours data for payroll processing
• I want to see labor cost trends over time

As an Accountant

• I want to export hours data in a format compatible with our payroll system (CSV)
• I want to see labor hours broken down by user, period, and cost center (room/batch)

---

Requirements

Functional Requirements

Timeclock

• Clock in:
  • Select room or batch (optional but encouraged)
  • Add start-of-shift notes (optional)
  • Timestamp recorded
• Clock out:
  • Add end-of-shift notes (optional)
  • Timestamp recorded
  • Duration calculated automatically
• Break tracking (optional for v1)
• Edit time entries (with audit trail, manager approval required)
• Mobile-optimized: Large buttons, minimal steps

Roles and Wage Rates

• User roles:
  • Owner
  • Compliance Manager
  • Head Grower
  • Grower
  • Trimmer
  • Maintenance
• Wage rates:
  • Hourly rate per role
  • Effective date for rate changes
  • Historical rate tracking
• Cost calculations:
  • Hours × wage rate = labor cost
  • Aggregated by user, room, batch, period

Reporting

• Hours per user, per period:
  • Daily, weekly, bi-weekly, monthly
  • Total hours and estimated cost
• Labor hours and cost per room/batch:
  • Breakdown by user
  • Percentage of total labor
• CSV exports:
  • User, date, clock in, clock out, duration, room, batch, notes
  • Compatible with common payroll systems (ADP, Gusto, QuickBooks)

Who's Working Now

• Live dashboard:
  • Currently clocked-in staff
  • Room/batch assignment
  • Duration of current shift
• Manager view: See all active shifts

Non-Functional Requirements

• Performance: Clock in/out completes in < 1 second
• Data integrity: Time entries are immutable once saved (edits create new records with audit trail)
• Accessibility: WCAG 2.1 AA compliant
• Mobile-first: Timeclock optimized for tablet use

---

Out of Scope (v1)

• Payroll processing (taxes, deductions, direct deposit)
• PTO/vacation tracking
• Shift scheduling (handled by Tasks module)
• Biometric clock-in (fingerprint, facial recognition)
• GPS-based clock-in verification

---

Acceptance Criteria

Timeclock

• Staff can clock in with room/batch selection in ≤ 3 taps
• Staff can clock out with notes in ≤ 2 taps
• Clock in/out timestamps are accurate to the second
• Duration is calculated automatically
• Time entries are immutable once saved

Roles and Wage Rates

• Roles can be created and assigned to users
• Wage rates can be set per role with effective dates
• Historical wage rates are preserved
• Labor cost is calculated correctly (hours × rate)

Reporting

• Hours per user report displays total hours and cost
• Labor cost per room/batch report displays breakdown by user
• CSV export includes all required fields for payroll
• Reports can be filtered by date range

Who's Working Now

• Dashboard displays currently clocked-in staff
• Room/batch assignments are visible
• Shift duration updates in real-time

Audit Trail

• Time entry edits create new records with original preserved
• Edits require manager approval
• Audit log displays all changes with user and timestamp

---

Technical Notes

Data Model (Prisma Schema)

model TimeEntry {
  id          String   @id @default(cuid())
  userId      String
  user        User     @relation(fields: [userId], references: [id])
  clockIn     DateTime
  clockOut    DateTime?
  duration    Int?     // minutes, calculated on clock out
  roomId      String?
  room        Room?    @relation(fields: [roomId], references: [id])
  batchId     String?
  batch       Batch?   @relation(fields: [batchId], references: [id])
  notes       String?
  editedBy    String?
  editedAt    DateTime?
  originalId  String?  // if this is an edit, reference to original
  original    TimeEntry? @relation("TimeEntryEdits", fields: [originalId], references: [id])
  edits       TimeEntry[] @relation("TimeEntryEdits")
  approved    Boolean  @default(false)
  approvedBy  String?
  approvedAt  DateTime?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model Role {
  id          String   @id @default(cuid())
  name        String   @unique
  description String?
  users       User[]
  wageRates   WageRate[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model WageRate {
  id          String   @id @default(cuid())
  roleId      String
  role        Role     @relation(fields: [roleId], references: [id])
  hourlyRate  Float
  effectiveDate DateTime
  endDate     DateTime?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model User {
  id          String   @id @default(cuid())
  email       String   @unique
  name        String
  roleId      String?
  role        Role?    @relation(fields: [roleId], references: [id])
  timeEntries TimeEntry[]
  // ... other user fields
}

API Endpoints

• POST /api/labor/clock-in - Clock in
• POST /api/labor/clock-out - Clock out
• GET /api/labor/current-shift - Get current shift for user
• GET /api/labor/time-entries - List time entries with filters
• PATCH /api/labor/time-entries/:id - Edit time entry (creates new record)
• POST /api/labor/time-entries/:id/approve - Approve time entry edit
• GET /api/labor/whos-working - Get currently clocked-in staff
• GET /api/labor/reports/hours-per-user - Hours per user report
• GET /api/labor/reports/cost-per-batch - Labor cost per batch
• GET /api/labor/reports/cost-per-room - Labor cost per room
• GET /api/labor/export - Export time entries to CSV
• GET /api/labor/roles - List roles
• POST /api/labor/roles - Create role
• GET /api/labor/wage-rates - List wage rates
• POST /api/labor/wage-rates - Create wage rate

UI Components

• TimeclockWidget - Clock in/out interface (mobile-optimized)
• WhosWorkingDashboard - Live view of clocked-in staff
• TimeEntryList - List of time entries with filters
• TimeEntryEditForm - Edit time entry (manager only)
• HoursReport - Hours per user report
• LaborCostReport - Labor cost per batch/room
• RoleManagement - Role and wage rate management
• PayrollExport - CSV export interface

---

Dependencies

• Batches and Rooms module (for time attribution)
• Authentication (for user identification and RBAC)

---

Risks & Mitigations

Risk	Impact	Mitigation
Users forget to clock out	High	Auto-clock-out after configurable duration; daily reminders
Time entry fraud (buddy punching)	Medium	Audit trail; manager review; future: biometric verification
Wage rate errors	Medium	Historical rate tracking; approval workflow for changes
Export format incompatibility	Medium	Support multiple export formats; customizable field mapping

---

Future Enhancements (Post-v1)

• Break tracking
• Shift scheduling integration
• PTO/vacation tracking
• Biometric clock-in (fingerprint, facial recognition)
• GPS-based clock-in verification
• Overtime calculations and alerts
• Integration with payroll systems (ADP, Gusto, QuickBooks)