port-nimara-client-portal/docs/comprehensive-fixes-implementation-plan.md

# Comprehensive Implementation Plan for Portal Fixes

## Overview
This document outlines the implementation plan for all requested fixes and improvements to the client portal system. Each section includes the problem, solution approach, and implementation details.

## 1. Hide Berth Recommendations

### Problem
Berth recommendations are shown across all instances and need to be hidden.

### Solution
- Remove or hide all UI elements related to berth recommendations
- Clean up related API calls
- Update the InterestDetailsModal and other components

### Implementation
```vue
<!-- Remove from InterestDetailsModal.vue -->
<!-- Remove the berth recommendations autocomplete field -->
<!-- Remove link-berth-recommendations-to-interest API calls -->
```

## 2. EOI Fixes

### 2.1 Hide Debug Console

#### Problem
Debug console is visible in production

#### Solution
- Remove all console.log statements from EOI-related components
- Add environment check for debug outputs

### 2.2 Slider Bubble Positioning

#### Problem
Slider bubble doesn't fit entirely within the slider bar

#### Solution
- Adjust CSS for the slider component to ensure bubble stays within bounds
- Calculate bubble position based on slider width

### 2.3 EOI Deletion Requires Multiple Clicks

#### Problem
EOI deletion fails unless clicked multiple times

#### Solution
- Add proper loading states and disable button during deletion
- Implement proper error handling and retry logic
- Use operation locks to prevent concurrent operations

### 2.4 Clean Database on EOI Deletion

#### Problem
Signature links and ID numbers remain in NocoDB after deletion

#### Solution
```typescript
// When deleting EOI:
// 1. Delete from Documenso
// 2. Clear all EOI-related fields in NocoDB:
//    - EOI Document
//    - EOI Client Link
//    - EOI Oscar Link
//    - EOI David Link
//    - EOI ID
//    - EOI Time Created
//    - EOI Time Sent
//    - EOI Status
// 3. Reset Sales Process Level if needed
```

### 2.5 EOI Regeneration Confirmation

#### Problem
No warning when regenerating EOI

#### Solution
- Add confirmation dialog with warning message
- Remind user to verify all information
- Delete old EOI data before regenerating

## 3. Email Refresh Button Styling

### Problem
Refresh button needs to be round and moved away from compose button

### Solution
```vue
<v-btn
  icon="mdi-refresh"
  size="small"
  variant="text"
  class="ml-2 rounded-circle"
  @click="loadEmails"
  :loading="loading"
>
```

## 4. Session Management

### Problem
Email credentials persist incorrectly between sessions

### Solution
- Clear sessionStorage on page load/unload
- Implement session validation on each API call
- Add session expiry timestamps
- Force re-authentication on page reload

## 5. Phone Input Country Issue

### Problem
USA selection switches to American Samoa

### Solution
- Fix country code sorting in PhoneInput component
- Ensure US (United States) appears before AS (American Samoa)
- Set explicit country code for USA (+1)

## 6. Email Attachments

### Problem
Attachments not displayed or downloadable

### Solution (Already Implemented)
- Added attachment display UI in EmailThreadView
- Created helper functions for icon display and file size formatting
- Implemented download functionality via proxy endpoint

## 7. IMAP Connection Reliability

### Problem
IMAP requires multiple connection attempts

### Solution (Already Implemented)
- Created email-sync service with exponential backoff retry
- Implemented MinIO-based caching for offline access
- Added connection pooling with health checks

## 8. Berth Assignment Concurrency

### Problem
Multiple berth selections cause errors

### Solution
- Implement operation locking for berth assignments
- Add debouncing to prevent rapid clicks
- Queue berth operations sequentially

## 9. 502 Gateway Errors

### Problem
Frequent 502 errors requiring multiple retries

### Root Causes
1. Connection pool exhaustion
2. Database connection limits
3. Memory/process issues
4. No retry logic in API calls

### Solutions
1. **Connection Pool Management**
   - Implement proper connection pooling for IMAP
   - Add connection recycling and health checks
   - Set maximum connection limits

2. **API Retry Logic**
   - Add exponential backoff retry to all API calls
   - Implement circuit breaker pattern
   - Cache responses where appropriate

3. **Resource Optimization**
   - Reduce concurrent database connections
   - Implement request queuing
   - Add memory monitoring

## 10. Performance Improvements

### Email System
- **MinIO-First Architecture**: Load cached emails instantly
- **Background Sync**: Update emails asynchronously
- **Incremental Updates**: Only fetch new emails
- **Connection Reuse**: Pool IMAP connections

### API Optimization
- **Request Batching**: Combine multiple API calls
- **Response Caching**: Cache frequently accessed data
- **Lazy Loading**: Load data only when needed
- **Debouncing**: Prevent excessive API calls

### Database Optimization
- **Connection Pooling**: Reuse database connections
- **Query Optimization**: Optimize NocoDB queries
- **Batch Operations**: Update multiple records at once

## Implementation Priority

### Phase 1: Critical Fixes (Immediate)
1. EOI deletion and database cleanup
2. Session management fixes
3. 502 error mitigation

### Phase 2: User Experience (This Week)
1. Hide berth recommendations
2. Fix phone input country selection
3. Email attachment display
4. UI improvements (buttons, sliders)

### Phase 3: Performance (Next Week)
1. Complete MinIO email implementation
2. API optimization
3. Connection pooling improvements

## Testing Requirements

### Unit Tests
- EOI deletion flow
- Email sync service
- Session management

### Integration Tests
- IMAP connection with retry
- MinIO caching
- Concurrent operations

### Performance Tests
- API response times
- Connection pool limits
- Memory usage under load

## Monitoring

### Metrics to Track
- 502 error frequency
- API response times
- IMAP connection success rate
- Memory/CPU usage
- Active connections count

### Alerts
- 502 errors above threshold
- Connection pool exhaustion
- High memory usage
- Failed email syncs

## Additional Recommendations

1. **Error Handling**
   - Implement global error handler
   - User-friendly error messages
   - Automatic error reporting

2. **Logging**
   - Structured logging for debugging
   - Request/response logging
   - Performance metrics logging

3. **Caching Strategy**
   - Redis for session management
   - MinIO for email caching
   - Memory cache for frequent queries

4. **Architecture Improvements**
   - Message queue for async operations
   - WebSocket for real-time updates
   - Service worker for offline support