# 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
2. **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
3. **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
4. **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
5. **Step 1: File Upload**
   - Reuse existing file upload functionality
   - Store file in blob storage
   - Return file ID for next step

6. **Step 2: Import Creation**
   - Create import record with:
     - Name: "Cintas Install Calendar Import"
     - Layout ID: Cintas Install Calendar layout
     - File ID: From step 1

7. **Step 3: Data Processing**
   - Read Excel file using ExcelJS
   - Process data using layout configuration
   - Bulk insert into `cintas_install_calendar` table

8. **Step 4: Summary Calculation**
   - Execute `cintas_calculate_summary` stored procedure
   - Display results in formatted table

## Technical Implementation Details

### Database Schema Updates
```sql
-- 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
```json
{
  "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
```typescript
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