# 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)

```prisma
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)