6.4 KiB

Raw Permalink Blame History

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:

// 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:

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

POST /api/email/generate-eoi-document
Headers: x-tag: 094ut234
Body: { interestId: string }

Upload EOI Document

POST /api/eoi/upload-document?interestId=123
Headers: x-tag: 094ut234
Body: FormData with 'file' field

Check Signature Status

GET /api/eoi/check-signature-status?interestId=123
Headers: x-tag: 094ut234

Send Reminders

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

Process Sales Emails

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

Generate EOI for Interest #94:

await $fetch('/api/email/generate-eoi-document', {
  method: 'POST',
  headers: { 'x-tag': '094ut234' },
  body: { interestId: '94' }
})

Check Signature Status:

await $fetch('/api/eoi/check-signature-status?interestId=94', {
  headers: { 'x-tag': '094ut234' }
})

Trigger Reminder Processing:

// In server console
import { triggerReminders } from '~/server/tasks/eoi-reminders'
await triggerReminders()

Trigger Email Processing:

// In server console
import { triggerEmailProcessing } from '~/server/tasks/process-sales-emails'
await triggerEmailProcessing()

Troubleshooting

Common Issues:

EOI Generation Fails
- Check Documeso API credentials
- Verify interest has required fields (Full Name, Email, etc.)
- Check API rate limits
Reminders Not Sending
- Verify SMTP credentials
- Check reminder_enabled field is not false
- Ensure documeso_document_id is set
- Check last_reminder_sent timestamp
Email Processing Not Working
- Verify IMAP credentials
- Check sales@portnimara.com inbox access
- Ensure emails have PDF attachments
- Verify client name extraction patterns
Signature Status Not Updating
- Check Documeso API connectivity
- Verify document exists in Documeso
- Check external ID format (loi-{interestId})

Security Considerations

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

Future Enhancements

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

6.4 KiB Raw Permalink Blame History