port-nimara-client-portal/docs/eoi-automation-system.md

# EOI Automation System Documentation

## Overview

The EOI (Expression of Interest) automation system provides comprehensive management of EOI documents, including:
- Manual EOI upload capability
- Automated signature status tracking via Documeso API
- Automated reminder emails for unsigned documents
- Automated processing of EOI attachments from sales@portnimara.com

## Components

### 1. EOI Section Component (`components/EOISection.vue`)

**Features:**
- Display EOI documents associated with an interest
- Generate new EOI documents via Documeso
- Upload signed EOI documents manually
- Display signature links for all parties (Client, CC, Developer)
- Track EOI status and signing time

**Key Functions:**
- `generateEOI()` - Creates new EOI document via Documeso API
- `uploadEOI()` - Uploads PDF documents to MinIO
- `copyLink()` - Copies signature link and tracks when sent

### 2. Documeso API Integration (`server/utils/documeso.ts`)

**Configuration:**
- API URL: https://signatures.portnimara.dev/api/v1
- API Key: Bearer api_malptg62zqyb0wrp

**Key Functions:**
- `getDocumesoDocument()` - Fetch document by ID
- `getDocumesoDocumentByExternalId()` - Find document by external ID (e.g., 'loi-94')
- `checkDocumentSignatureStatus()` - Check signature status of all recipients
- `getRecipientsToRemind()` - Get recipients who need reminders (after client has signed)

### 3. Reminder System

#### API Endpoints:
- `/api/eoi/check-signature-status` - Check signature status of an EOI
- `/api/eoi/send-reminders` - Send reminder emails

#### Scheduled Tasks (`server/tasks/eoi-reminders.ts`):
- Runs at 9am and 4pm daily (Europe/Paris timezone)
- Checks all interests with EOI documents
- Sends reminders based on rules:
  - 4pm only: Reminder to sales if client hasn't signed
  - 9am & 4pm: Reminders to CC/Developer if client has signed but they haven't
  - Maximum one reminder per 12 hours per interest

#### Email Templates:
- **Sales Reminder**: Notifies sales team when client hasn't signed
- **Recipient Reminder**: Personalized reminder for CC/Developer to sign

### 4. Sales Email Processing (`server/api/email/process-sales-eois.ts`)

**Features:**
- Monitors sales@portnimara.com inbox every 30 minutes
- Processes unread emails with PDF attachments
- Automatically extracts client name from filename or subject
- Uploads EOI documents to MinIO
- Updates interest record with EOI document and status

**Client Name Extraction Patterns:**
- Filename: "John_Doe_EOI_signed.pdf", "EOI_John_Doe.pdf", "John Doe - EOI.pdf"
- Subject: "EOI for John Doe signed", "Signed EOI - John Doe"

## Database Schema Updates

### Interest Table Fields:

```typescript
// EOI Document storage
'EOI Document': EOIDocument[] // Array of uploaded EOI documents

// Signature tracking
'Signature Link Client': string
'Signature Link CC': string  
'Signature Link Developer': string
'documeso_document_id': string // Documeso document ID

// Reminder tracking
'reminder_enabled': boolean // Enable/disable reminders
'last_reminder_sent': string // ISO timestamp of last reminder

// Status tracking
'EOI Status': 'Waiting for Signatures' | 'Signed'
'EOI Time Sent': string // When EOI was first sent
```

### EOIDocument Type:

```typescript
interface EOIDocument {
  title: string
  filename: string
  url: string
  size: number
  mimetype: string
  icon: string
  uploadedAt?: string
  source?: 'email' | 'manual'
  from?: string // Email sender if from email
}
```

## API Endpoints

### Generate EOI Document
```http
POST /api/email/generate-eoi-document
Headers: x-tag: 094ut234
Body: { interestId: string }
```

### Upload EOI Document
```http
POST /api/eoi/upload-document?interestId=123
Headers: x-tag: 094ut234
Body: FormData with 'file' field
```

### Check Signature Status
```http
GET /api/eoi/check-signature-status?interestId=123
Headers: x-tag: 094ut234
```

### Send Reminders
```http
POST /api/eoi/send-reminders
Headers: x-tag: 094ut234
Body: { interestId: string, documentId: string }
```

### Process Sales Emails
```http
POST /api/email/process-sales-eois
Headers: x-tag: 094ut234
```

## Email Configuration

### Reminder Emails (noreply@portnimara.com)
- Host: mail.portnimara.com
- Port: 465
- Secure: true
- User: noreply@portnimara.com
- Pass: sJw6GW5G5bCI1EtBIq3J2hVm8xCOMw1kQs1puS6g0yABqkrwj

### Sales Email Monitoring (sales@portnimara.com)
- Host: mail.portnimara.com
- Port: 993 (IMAP)
- TLS: true
- User: sales@portnimara.com
- Pass: MDze7cSClQok8qWOf23X8Mb6lArdk0i42YnwJ1FskdtO2NCc9

## Testing

### Manual Testing Commands

1. **Generate EOI for Interest #94:**
```javascript
await $fetch('/api/email/generate-eoi-document', {
  method: 'POST',
  headers: { 'x-tag': '094ut234' },
  body: { interestId: '94' }
})
```

2. **Check Signature Status:**
```javascript
await $fetch('/api/eoi/check-signature-status?interestId=94', {
  headers: { 'x-tag': '094ut234' }
})
```

3. **Trigger Reminder Processing:**
```javascript
// In server console
import { triggerReminders } from '~/server/tasks/eoi-reminders'
await triggerReminders()
```

4. **Trigger Email Processing:**
```javascript
// In server console
import { triggerEmailProcessing } from '~/server/tasks/process-sales-emails'
await triggerEmailProcessing()
```

## Troubleshooting

### Common Issues:

1. **EOI Generation Fails**
   - Check Documeso API credentials
   - Verify interest has required fields (Full Name, Email, etc.)
   - Check API rate limits

2. **Reminders Not Sending**
   - Verify SMTP credentials
   - Check reminder_enabled field is not false
   - Ensure documeso_document_id is set
   - Check last_reminder_sent timestamp

3. **Email Processing Not Working**
   - Verify IMAP credentials
   - Check sales@portnimara.com inbox access
   - Ensure emails have PDF attachments
   - Verify client name extraction patterns

4. **Signature Status Not Updating**
   - Check Documeso API connectivity
   - Verify document exists in Documeso
   - Check external ID format (loi-{interestId})

## Security Considerations

1. All API endpoints require x-tag authentication
2. Email credentials are stored securely
3. Uploaded files are stored in MinIO with access control
4. Signature links are unique and time-limited
5. Reminder emails are sent to verified addresses only

## Future Enhancements

1. Add webhook support for real-time signature updates
2. Implement customizable reminder schedules
3. Add email template customization
4. Support for multiple document types beyond EOI
5. Add audit logging for all EOI operations
6. Implement retry queue for failed email processing