navidocs/FEATURE_SPEC_MAINTENANCE_SCHEDULER.md

Feature Spec: Maintenance Scheduler

Created: 2025-11-13 Priority: P1 (Core Feature) Estimated Time: 90-120 minutes Assignee: Cloud Session 7

---

Executive Summary

Add recurring maintenance scheduling and task management to NaviDocs. Boat owners need to track preventive maintenance schedules (oil changes, inspections, filter replacements) with automatic reminders and completion tracking.

Value Proposition:

• Never miss critical maintenance tasks
• Track recurring maintenance schedules
• Get alerts for overdue tasks
• Log maintenance completion with costs
• View maintenance history per task or equipment
• Prevent expensive breakdowns through preventive maintenance

---

User Story

As a boat owner I want to schedule and track recurring maintenance tasks So that I keep my boat in optimal condition and prevent costly repairs

Acceptance Criteria:

1. ✅ Create maintenance tasks (one-time or recurring)
2. ✅ Set recurrence patterns (days, hours, or miles)
3. ✅ Link tasks to specific equipment
4. ✅ Get alerts for due/overdue tasks
5. ✅ Mark tasks as complete with notes and costs
6. ✅ View maintenance calendar
7. ✅ Track maintenance history

---

Database Schema

Table: maintenance_tasks

CREATE TABLE maintenance_tasks (
  id TEXT PRIMARY KEY,
  organization_id TEXT NOT NULL,
  equipment_id TEXT,
  task_name TEXT NOT NULL,
  description TEXT,
  task_category TEXT NOT NULL,
  recurrence_type TEXT NOT NULL, -- 'one_time', 'recurring_days', 'recurring_hours', 'recurring_miles'
  recurrence_interval INTEGER, -- e.g., 30 for "every 30 days"
  last_completed_date INTEGER,
  next_due_date INTEGER,
  estimated_cost REAL,
  estimated_duration_minutes INTEGER,
  priority TEXT, -- 'low', 'medium', 'high', 'critical'
  status TEXT NOT NULL, -- 'pending', 'due', 'overdue', 'completed'
  alert_days_before INTEGER DEFAULT 7,
  notes TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
  FOREIGN KEY (equipment_id) REFERENCES equipment_inventory(id) ON DELETE SET NULL
);

CREATE INDEX idx_maintenance_org ON maintenance_tasks(organization_id);
CREATE INDEX idx_maintenance_equipment ON maintenance_tasks(equipment_id);
CREATE INDEX idx_maintenance_next_due ON maintenance_tasks(next_due_date);
CREATE INDEX idx_maintenance_status ON maintenance_tasks(status);

Table: maintenance_completions

CREATE TABLE maintenance_completions (
  id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  completed_date INTEGER NOT NULL,
  completed_by_user_id TEXT,
  actual_cost REAL,
  actual_duration_minutes INTEGER,
  service_provider TEXT,
  notes TEXT,
  meter_reading INTEGER, -- Hours or miles at completion
  created_at INTEGER NOT NULL,
  FOREIGN KEY (task_id) REFERENCES maintenance_tasks(id) ON DELETE CASCADE,
  FOREIGN KEY (completed_by_user_id) REFERENCES users(id) ON DELETE SET NULL
);

CREATE INDEX idx_completions_task ON maintenance_completions(task_id);
CREATE INDEX idx_completions_date ON maintenance_completions(completed_date);

---

Task Categories

Predefined Categories:

• Engine Service
• Oil & Filters
• Electrical System
• Plumbing & Pumps
• Hull & Bottom
• Rigging & Sails
• Safety Equipment
• Electronics
• HVAC & Heating
• Winterization
• Annual Inspection
• Other

---

API Endpoints

1. List Maintenance Tasks

GET /api/organizations/:orgId/maintenance/tasks

Query Params:

• status (optional) - 'pending', 'due', 'overdue', 'completed'
• equipment_id (optional) - Filter by equipment
• category (optional) - Filter by category
• view (optional) - 'calendar', 'list', 'upcoming'

Response:

{
  "tasks": [
    {
      "id": "mt_123",
      "task_name": "Engine Oil Change",
      "description": "Replace engine oil and filter",
      "task_category": "Engine Service",
      "recurrence_type": "recurring_hours",
      "recurrence_interval": 100,
      "last_completed_date": 1699920000000,
      "next_due_date": 1735689600000,
      "days_until_due": 15,
      "status": "due",
      "priority": "high",
      "estimated_cost": 250.00,
      "equipment": {
        "id": "eq_123",
        "name": "Main Engine - Yanmar 4JH5E"
      },
      "completions_count": 5
    }
  ],
  "stats": {
    "total": 23,
    "due_soon": 5,
    "overdue": 2,
    "completed_this_month": 8
  }
}

2. Create Maintenance Task

POST /api/organizations/:orgId/maintenance/tasks

Body:

{
  "equipment_id": "eq_123",
  "task_name": "Engine Oil Change",
  "description": "Replace engine oil and filter",
  "task_category": "Engine Service",
  "recurrence_type": "recurring_hours",
  "recurrence_interval": 100,
  "next_due_date": 1735689600000,
  "estimated_cost": 250.00,
  "estimated_duration_minutes": 60,
  "priority": "high",
  "alert_days_before": 7
}

3. Complete Maintenance Task

POST /api/organizations/:orgId/maintenance/tasks/:taskId/complete

Body:

{
  "completed_date": 1699920000000,
  "actual_cost": 265.50,
  "actual_duration_minutes": 75,
  "service_provider": "ABC Marine Services",
  "notes": "Used synthetic oil. Replaced oil filter.",
  "meter_reading": 1250
}

Response:

{
  "completion": {
    "id": "comp_456",
    "task_id": "mt_123",
    "completed_date": 1699920000000,
    "actual_cost": 265.50
  },
  "updated_task": {
    "id": "mt_123",
    "last_completed_date": 1699920000000,
    "next_due_date": 1735689600000,
    "status": "pending"
  }
}

4. Get Task Details & History

GET /api/organizations/:orgId/maintenance/tasks/:taskId

Response:

{
  "task": {
    "id": "mt_123",
    "task_name": "Engine Oil Change",
    "description": "Replace engine oil and filter",
    "task_category": "Engine Service",
    "recurrence_type": "recurring_hours",
    "recurrence_interval": 100,
    "last_completed_date": 1699920000000,
    "next_due_date": 1735689600000,
    "status": "pending",
    "priority": "high",
    "equipment": {
      "id": "eq_123",
      "name": "Main Engine - Yanmar 4JH5E"
    }
  },
  "completion_history": [
    {
      "id": "comp_456",
      "completed_date": 1699920000000,
      "actual_cost": 265.50,
      "service_provider": "ABC Marine Services",
      "notes": "Used synthetic oil"
    }
  ],
  "stats": {
    "total_completions": 5,
    "total_cost": 1275.00,
    "avg_cost": 255.00,
    "avg_duration_minutes": 68
  }
}

5. Get Due/Overdue Alerts

GET /api/organizations/:orgId/maintenance/alerts

Response:

{
  "alerts": [
    {
      "task_id": "mt_123",
      "task_name": "Engine Oil Change",
      "equipment_name": "Main Engine - Yanmar 4JH5E",
      "next_due_date": 1735689600000,
      "days_until_due": 5,
      "alert_level": "urgent", // 'overdue', 'urgent', 'warning', 'info'
      "priority": "high"
    }
  ]
}

6. Update Task

PUT /api/organizations/:orgId/maintenance/tasks/:taskId

7. Delete Task

DELETE /api/organizations/:orgId/maintenance/tasks/:taskId

8. Get Maintenance Calendar

GET /api/organizations/:orgId/maintenance/calendar

Query Params:

• start_date (required) - Unix timestamp
• end_date (required) - Unix timestamp

Response:

{
  "events": [
    {
      "date": "2025-12-15",
      "tasks": [
        {
          "id": "mt_123",
          "task_name": "Engine Oil Change",
          "equipment_name": "Main Engine",
          "status": "due",
          "priority": "high"
        }
      ]
    }
  ]
}

---

Frontend Components

1. Maintenance Dashboard (client/src/views/Maintenance.vue)

Features:

• Alert banner for overdue/due soon tasks
• Filter by status, category, equipment
• Sortable task list
• Quick actions (Mark Complete, View Details, Edit)
• Visual priority indicators (🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low)
• "Add Task" button

Columns:

• Task Name
• Equipment
• Category
• Next Due Date
• Days Until Due
• Status
• Priority
• Est. Cost
• Actions

2. Add Maintenance Task Modal (client/src/components/AddMaintenanceTaskModal.vue)

Form Fields:

• Task Name* (required)
• Category* (dropdown)
• Equipment (dropdown - optional)
• Description (textarea)
• Recurrence Type* (dropdown: One-time, Every N days, Every N hours, Every N miles)
• Recurrence Interval (number - if recurring)
• Next Due Date* (date picker)
• Estimated Cost
• Estimated Duration (minutes)
• Priority* (dropdown: Low, Medium, High, Critical)
• Alert Days Before (default: 7)
• Notes

3. Complete Task Modal (client/src/components/CompleteMaintenanceTaskModal.vue)

Form Fields:

• Completion Date* (date picker - default: today)
• Actual Cost
• Actual Duration (minutes)
• Service Provider
• Meter Reading (hours or miles)
• Notes (textarea)
• "Mark Complete" button

4. Maintenance Alert Banner (client/src/components/MaintenanceAlertBanner.vue)

Display at top of dashboard:

⚠️ 2 overdue tasks | 3 due within 7 days
└─ Engine Oil Change: 5 days overdue
└─ Bilge Pump Inspection: Due today
[View All Maintenance]

5. Maintenance Calendar View (client/src/components/MaintenanceCalendar.vue)

Features:

• Month view calendar
• Tasks displayed on due dates
• Color-coded by priority
• Click task to view details
• Navigate months

---

Status Logic

function calculateMaintenanceStatus(task) {
  if (task.status === 'completed') return 'completed';

  const now = Date.now();
  const nextDue = task.next_due_date;

  if (!nextDue) return 'pending';

  const daysUntilDue = Math.floor((nextDue - now) / (1000 * 60 * 60 * 24));

  if (daysUntilDue < 0) return 'overdue';
  if (daysUntilDue <= task.alert_days_before) return 'due';
  return 'pending';
}

function calculateNextDueDate(task, completion) {
  const completedDate = completion.completed_date;

  switch (task.recurrence_type) {
    case 'one_time':
      return null; // Task doesn't repeat

    case 'recurring_days':
      return completedDate + (task.recurrence_interval * 24 * 60 * 60 * 1000);

    case 'recurring_hours':
      // Calculate based on meter reading
      const nextMeterReading = completion.meter_reading + task.recurrence_interval;
      // Estimate date based on average usage (would need usage tracking)
      return completedDate + (task.recurrence_interval * 60 * 60 * 1000); // Simplified

    case 'recurring_miles':
      // Similar to hours
      const nextMiles = completion.meter_reading + task.recurrence_interval;
      return completedDate + (task.recurrence_interval * 60 * 60 * 1000); // Simplified

    default:
      return null;
  }
}

---

Implementation Steps

Phase 1: Database (15 min)

1. Create migration: server/migrations/012_maintenance_scheduler.sql
2. Run migration: node server/run-migration.js 012_maintenance_scheduler.sql
3. Verify tables created

Phase 2: Backend Service (30 min)

1. Create: server/services/maintenance-service.js

   • CRUD for tasks
   • Complete task logic (auto-calculate next due date)
   • Status calculation
   • Alert generation

2. Implement recurrence logic

Phase 3: Backend Routes (20 min)

1. Create: server/routes/maintenance.js
2. Implement 8 endpoints
3. Register route in server/index.js

Phase 4: Frontend (50 min)

1. Create views/Maintenance.vue (dashboard)
2. Create components/AddMaintenanceTaskModal.vue
3. Create components/CompleteMaintenanceTaskModal.vue
4. Create components/MaintenanceAlertBanner.vue
5. Update router: Add /maintenance route
6. Update navigation: Add "Maintenance" link

Phase 5: Integration (15 min)

1. Add maintenance alert banner to HomeView
2. Link equipment to maintenance tasks
3. Log maintenance completions to activity timeline

Phase 6: Demo Data (10 min)

Create 10-15 sample maintenance tasks:

• 2 overdue tasks
• 3 due within 7 days
• 5 pending tasks
• 5 completed tasks with history

---

Demo Data

Sample Tasks for Riviera Plaisance Demo:

1. Engine Oil Change (recurring every 100 hours) - DUE IN 5 DAYS
2. Fuel Filter Replacement (recurring every 200 hours) - DUE TODAY
3. Bilge Pump Inspection (recurring every 30 days) - OVERDUE 3 DAYS
4. Battery Water Check (recurring every 14 days) - OVERDUE 1 DAY
5. Transmission Fluid Check (recurring every 150 hours) - Due in 15 days
6. Impeller Replacement (recurring every 2 years) - Due in 45 days
7. Zincs Replacement (recurring every 6 months) - Due in 30 days
8. Fire Extinguisher Inspection (recurring every 1 year) - Due in 60 days
9. Life Jacket Inspection (recurring every 1 year) - Due in 90 days
10. Hull Cleaning (recurring every 60 days) - Due in 20 days

---

Success Criteria

✅ Database migration creates 2 tables ✅ All 8 API endpoints working ✅ Can create tasks (one-time and recurring) ✅ Can mark tasks complete ✅ Next due date auto-calculated for recurring tasks ✅ Alert banner shows overdue/due tasks ✅ Can filter by status, category, equipment ✅ Completion history tracked per task ✅ Activity timeline shows maintenance events ✅ Demo data loads successfully

---

Integration Points

With Inventory:

• Link maintenance tasks to equipment
• Show maintenance schedule on equipment detail page
• Track service history per equipment

With Timeline:

• Log task creation events
• Log task completion events
• Show maintenance history in timeline

With Dashboard:

• Display maintenance alerts banner
• Show upcoming tasks widget
• Display monthly maintenance summary

---

Duration: 90-120 minutes Dependencies: Equipment Inventory (for linking tasks to equipment) Branch: feature/maintenance-scheduler