# Feature Spec: Tasks and Scheduling

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

---

## Overview

The Tasks and Scheduling module enables cultivation teams to create, assign, and track recurring and one-off tasks across different room types (veg, flower, dry, facility). It provides room-based task templates, calendar and list views, and a simplified "Today / This Week" view optimized for on-shift workers.

---

## User Stories

### As a Head Grower

- I want to create task templates for each room type (veg, flower, dry, facility) so that recurring operations are standardized
- I want to schedule tasks on a calendar so I can visualize the workload across the week
- I want to assign tasks to specific staff members so accountability is clear
- I want to see task completion status so I can track progress and identify blockers

### As a Staff Member

- I want to see my tasks for today in a simple list so I can complete them efficiently
- I want to mark tasks as complete with notes and photos so the team has a record
- I want to see upcoming tasks for the week so I can plan my time
- I want to filter tasks by room or batch so I can focus on specific areas

### As a Compliance Manager

- I want to see a history of completed tasks with timestamps and assignees so I can demonstrate SOP compliance
- I want to export task logs for audit purposes

---

## Requirements

### Functional Requirements

#### Task Templates

- **Room-based templates** for:
  - **Veg Room**: clones, up-potting, watering schedule, IPM schedule, tagging, move-to-flower
  - **Flower Room**: feed schedule, IPM plan, day-21 pruning, pre-harvest deleaf, harvest and weights
  - **Dry/Cure**: hang, burp, transfer, packaging
  - **Facility**: cleaning, maintenance, "fix it" items, materials checks
- Templates include:
  - Task name and description
  - Estimated duration
  - Required materials/tools
  - Instructions or SOP links
  - Recurrence pattern (daily, weekly, custom)

#### Task Scheduling

- **Calendar view** (month, week, day)
- **List view** with filters:
  - By room
  - By batch
  - By assignee
  - By status (pending, in progress, complete, overdue)
- **Drag-and-drop** rescheduling (calendar view)
- **Bulk actions** (assign, reschedule, mark complete)

#### Task Execution

- **Today / This Week view** optimized for mobile/tablet:
  - Large tap targets
  - Minimal clutter
  - Quick complete/defer actions
- **Task detail view**:
  - Instructions and materials
  - Batch/room context
  - Add notes and photos
  - Mark complete with timestamp
- **Notifications** for:
  - Tasks due today
  - Overdue tasks
  - Newly assigned tasks

#### Task History & Audit Trail

- **Immutable log** of all task completions
- **Metadata**: assignee, completion time, notes, photos
- **Export** to CSV/JSON for compliance

### Non-Functional Requirements

- **Performance**: Task list loads in < 500ms
- **Offline support**: Tasks viewable offline; completion syncs when online
- **Accessibility**: WCAG 2.1 AA compliant
- **Mobile-first**: All workflows completable on tablet

---

## Out of Scope (v1)

- Advanced project management features (dependencies, Gantt charts)
- Time tracking per task (handled by Labor module)
- External calendar integrations (Google Calendar, Outlook)
- AI-powered task suggestions

---

## Acceptance Criteria

### Template Management

- [ ] Head Grower can create a task template for each room type
- [ ] Templates can be edited and versioned
- [ ] Templates can be duplicated for customization

### Task Scheduling

- [ ] Tasks can be created from templates or from scratch
- [ ] Tasks can be assigned to specific users or roles
- [ ] Calendar view displays all scheduled tasks
- [ ] List view supports filtering by room, batch, assignee, status

### Task Execution

- [ ] Staff can view their tasks for today in a simplified view
- [ ] Staff can mark tasks complete with notes and photos
- [ ] Completed tasks are logged with timestamp and assignee
- [ ] Overdue tasks are highlighted

### Notifications

- [ ] Users receive daily digest of tasks due today
- [ ] Users receive alerts for overdue tasks
- [ ] Notifications are configurable per user

### Audit & Export

- [ ] Task history is immutable and timestamped
- [ ] Task logs can be exported to CSV
- [ ] Export includes all metadata (assignee, notes, photos)

---

## Technical Notes

### Data Model (Prisma Schema)

```prisma
model TaskTemplate {
  id          String   @id @default(cuid())
  name        String
  description String?
  roomType    RoomType
  estimatedDuration Int? // minutes
  materials   String[] // array of material names
  instructions String?
  recurrence  Json?    // cron-like pattern
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  tasks       Task[]
}

model Task {
  id          String   @id @default(cuid())
  templateId  String?
  template    TaskTemplate? @relation(fields: [templateId], references: [id])
  name        String
  description String?
  roomId      String?
  room        Room?    @relation(fields: [roomId], references: [id])
  batchId     String?
  batch       Batch?   @relation(fields: [batchId], references: [id])
  assigneeId  String?
  assignee    User?    @relation(fields: [assigneeId], references: [id])
  status      TaskStatus @default(PENDING)
  dueDate     DateTime
  completedAt DateTime?
  notes       String?
  photos      String[] // URLs
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

enum TaskStatus {
  PENDING
  IN_PROGRESS
  COMPLETE
  OVERDUE
}

enum RoomType {
  VEG
  FLOWER
  DRY
  FACILITY
}
```

### API Endpoints

- `GET /api/tasks` - List tasks with filters
- `GET /api/tasks/:id` - Get task detail
- `POST /api/tasks` - Create task
- `PATCH /api/tasks/:id` - Update task
- `DELETE /api/tasks/:id` - Delete task
- `POST /api/tasks/:id/complete` - Mark task complete
- `GET /api/tasks/templates` - List task templates
- `POST /api/tasks/templates` - Create task template
- `GET /api/tasks/export` - Export task history

### UI Components

- `TaskCalendar` - Calendar view with drag-and-drop
- `TaskList` - Filterable list view
- `TaskCard` - Task summary card
- `TaskDetail` - Full task view with completion form
- `TodayView` - Simplified mobile-optimized view
- `TaskTemplateForm` - Template creation/editing

---

## Dependencies

- **Batches and Rooms** module (for task context)
- **Labor** module (for assignee data)
- **Authentication** (for user assignment and audit trail)

---

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Template complexity overwhelms users | High | Start with simple templates; iterate based on feedback |
| Offline sync conflicts | Medium | Use optimistic UI updates; clear conflict resolution UX |
| Notification fatigue | Medium | Make notifications configurable; use smart batching |

---

## Future Enhancements (Post-v1)

- Task dependencies and workflows
- Recurring task auto-generation
- Integration with external calendars
- Voice-to-text for task notes
- AI-powered task duration estimates