Add EOI automation system with email processing and document management
- Implement automated EOI processing from sales emails - Add EOI document upload and management capabilities - Enhance email thread handling with better parsing and grouping - Add retry logic and error handling for file operations - Introduce Documeso integration for document processing - Create server tasks and plugins infrastructure - Update email composer with improved attachment handling
This commit is contained in:
235
docs/eoi-automation-system.md
Normal file
235
docs/eoi-automation-system.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user