vtorio/IMPLEMENTATION_PLAN.md

Cintas Install Calendar Summary - Implementation Plan

Overview

This document outlines the complete implementation plan for creating a new page called "Cintas Install Calendar Summary" with a workflow-based interface for processing Cintas install calendar data.

Architecture Analysis

Current System Structure

• File Storage: PostgreSQL ByteA type for blob storage
• Import System: Uses Import model with LayoutConfiguration for data mapping
• Excel Processing: Uses exceljs with streaming for large files
• Database Models:
  • cintas_install_calendar - stores raw calendar data
  • cintas_intall_calendar_summary - stores calculated summaries
• Stored Procedure: cintas_calculate_summary for summary calculations

Implementation Steps

Phase 1: Database Schema Updates

1. Add Stored Procedure to Prisma Schema
   • Add the cintas_calculate_summary stored procedure definition
   • Update Prisma schema with proper model definitions

Phase 2: Layout Configuration

1. Create "Cintas Install Calendar" Layout Configuration
   • Create layout configuration with appropriate sections and fields
   • Map Excel columns to database fields
   • Configure table mapping to cintas_install_calendar

Phase 3: Page Creation

1. Create New Page Component
   • Create app/cintas-install-calendar-summary/page.tsx
   • Implement workflow-based UI with 4 steps:
     1. File Upload
     2. Import Creation
     3. Data Processing
     4. Results Display

Phase 4: Dashboard Integration

1. Add to Dashboard
   • Update app/dashboard/page.tsx to include new tile
   • Use cintas-blue.svg icon with circular motif
   • Add navigation link

Phase 5: Workflow Implementation

1. Step 1: File Upload

   • Reuse existing file upload functionality
   • Store file in blob storage
   • Return file ID for next step

2. Step 2: Import Creation

   • Create import record with:
     • Name: "Cintas Install Calendar Import"
     • Layout ID: Cintas Install Calendar layout
     • File ID: From step 1

3. Step 3: Data Processing

   • Read Excel file using ExcelJS
   • Process data using layout configuration
   • Bulk insert into cintas_install_calendar table

4. Step 4: Summary Calculation

   • Execute cintas_calculate_summary stored procedure
   • Display results in formatted table

Technical Implementation Details

Database Schema Updates

-- Add stored procedure (will be added via migration)
CREATE PROCEDURE cintas_calculate_summary(IN provided_import_id bigint)
LANGUAGE plpgsql
AS $$
-- [Stored procedure definition from task]
$$;

Layout Configuration Structure

{
  "name": "Cintas Install Calendar",
  "sections": [
    {
      "name": "Install Calendar Data",
      "type": "excel_import",
      "sheetName": "Sheet1",
      "tableName": "cintas_install_calendar",
      "fields": [
        {"name": "opportunity_status", "cellPosition": "A", "dataType": "string"},
        {"name": "week", "cellPosition": "B", "dataType": "string"},
        {"name": "qtr", "cellPosition": "C", "dataType": "string"},
        {"name": "install_date", "cellPosition": "D", "dataType": "string"},
        {"name": "account_name", "cellPosition": "E", "dataType": "string"},
        {"name": "zip_code", "cellPosition": "F", "dataType": "string"},
        {"name": "sold_to_number", "cellPosition": "G", "dataType": "string"},
        {"name": "sort_number", "cellPosition": "H", "dataType": "string"},
        {"name": "type", "cellPosition": "I", "dataType": "string"},
        {"name": "route", "cellPosition": "J", "dataType": "string"},
        {"name": "day", "cellPosition": "K", "dataType": "string"},
        {"name": "trr", "cellPosition": "L", "dataType": "decimal"},
        {"name": "paper_chem_wk1", "cellPosition": "M", "dataType": "decimal"},
        {"name": "paper_chem_wk2", "cellPosition": "N", "dataType": "decimal"},
        {"name": "paper_chem_wk3", "cellPosition": "O", "dataType": "decimal"},
        {"name": "paper_chem_wk4", "cellPosition": "P", "dataType": "decimal"},
        {"name": "sanis", "cellPosition": "Q", "dataType": "decimal"},
        {"name": "power_add", "cellPosition": "R", "dataType": "decimal"}
      ]
    }
  ]
}

Page Structure

app/
├── cintas-install-calendar-summary/
│   ├── page.tsx                    # Main page component
│   ├── components/
│   │   ├── FileUploadStep.tsx      # Step 1: File upload
│   │   ├── ImportCreationStep.tsx  # Step 2: Import creation
│   │   ├── ProcessingStep.tsx      # Step 3: Data processing
│   │   ├── ResultsStep.tsx         # Step 4: Results display
│   │   └── WorkflowProgress.tsx    # Progress indicator
│   └── actions/
│       └── cintas-actions.ts       # Server actions

API Endpoints

• POST /api/cintas/upload - File upload
• POST /api/cintas/create-import - Create import record
• POST /api/cintas/process-import - Process data
• GET /api/cintas/summary/:importId - Get summary results

Workflow States

enum WorkflowStep {
  UPLOAD = 1,
  CREATE_IMPORT = 2,
  PROCESS = 3,
  RESULTS = 4
}

interface WorkflowState {
  currentStep: WorkflowStep;
  fileId?: string;
  importId?: number;
  processingStatus?: 'idle' | 'processing' | 'completed' | 'error';
  results?: CintasSummary[];
}

Implementation Order

1. Database Migration - Add stored procedure
2. Layout Configuration - Create "Cintas Install Calendar" layout
3. Page Components - Create React components for each step
4. Server Actions - Implement backend functionality
5. Dashboard Integration - Add to main dashboard
6. Testing - End-to-end workflow testing

Dependencies

• exceljs - Excel file processing
• @prisma/client - Database access
• lucide-react - Icons
• react-hook-form - Form handling
• react-dropzone - File upload

Next Steps

1. Switch to Code mode to begin implementation
2. Create database migration for stored procedure
3. Implement layout configuration
4. Build page components
5. Integrate with dashboard

Success Criteria

• New page accessible from dashboard
• Complete 4-step workflow functional
• File upload working with blob storage
• Data import processing correctly
• Summary calculations accurate
• Results displayed in formatted table
• Error handling throughout workflow