AI-Powered Sales Order Automation - Implementation Plan¶

Date: December 31, 2024
Status: Planning Phase
Estimated Total Effort: 10-14 hours

Overview¶

Implement AI-powered automation for Sales Order creation through two complementary features: 1. Manual Upload: Upload customer PO documents with AI extraction 2. Email Integration: Automated processing of orders sent to soentry@company.com

Both features leverage the existing AI document scanning engine from the Employee module.

User Review Required¶

[!IMPORTANT] Email Service Decision Required - Option A: Gmail API (recommended for Gmail users) - Option B: Microsoft Graph API (for Outlook/Office 365) - Option C: Generic IMAP (works with any email provider)

Please confirm which email service your company uses for soentry@company.com

[!WARNING] Breaking Changes - Adds new source_document field to SalesOrder model (requires migration) - Adds new ai_confidence and requires_review fields - New Celery task for email polling (requires Celery setup if not already configured)

Proposed Changes¶

Phase 1: Manual Upload + AI Extraction (4-6 hours)¶

Backend Changes¶

[NEW] `sales/services/document_extractor.py`¶

Purpose: AI extraction service for customer PO documents

Features: - Reuse existing AI engine from hrms/services/document_scanner.py - Extract: customer name, products, quantities, prices, delivery date - Return structured data with confidence scores - Handle multiple document formats (PDF, images, Excel)

Key Functions:

def extract_sales_order_data(document_path: str) -> dict:
    """
    Extract SO data from uploaded document
    Returns: {
        'customer_name': str,
        'customer_email': str,
        'products': [{'name': str, 'qty': float, 'price': float}],
        'delivery_date': str,
        'currency': str,
        'confidence': float,
        'missing_fields': [str]
    }
    """

[MODIFY] `sales/models.py`¶

Changes: - Add source_document field to SalesOrder (FileField) - Add ai_confidence field (DecimalField, 0-100%) - Add requires_review flag (BooleanField) - Add extraction_metadata (JSONField for audit trail)

New Fields:

class SalesOrder(models.Model):
    # ... existing fields ...
    source_document = models.FileField(upload_to='sales_orders/uploads/', null=True, blank=True)
    ai_confidence = models.DecimalField(max_digits=5, decimal_places=2, null=True, blank=True)
    requires_review = models.BooleanField(default=False)
    extraction_metadata = models.JSONField(null=True, blank=True)

[MODIFY] `sales/views.py`¶

Add Endpoint: POST /sales/sales-orders/upload_document/

Features: - Accept file upload (PDF, PNG, JPG, XLSX) - Call AI extraction service - Validate extracted data - Return extracted data + missing fields list - Save document temporarily

Response:

{
  "extracted_data": {
    "customer_name": "ABC Corp",
    "products": [...],
    "total": 15000
  },
  "missing_fields": ["customer_id", "warehouse"],
  "confidence": 85.5,
  "document_id": "temp_uuid"
}

Frontend Changes¶

[MODIFY] `CreateSalesOrder.tsx`¶

Add Features: - File upload button with drag-and-drop - AI extraction progress indicator - Smart validation modal for missing fields - Preview extracted data before saving

New Components: 1. Upload Button: Trigger file selection 2. Progress Modal: Show AI extraction progress 3. Validation Modal: Fill missing required fields 4. Preview Panel: Show extracted data with edit capability

Workflow:

User Uploads → Show Progress → AI Extracts → 
  ├─ All Required → Auto-populate form
  └─ Missing Data → Show Modal → User Fills → Populate form

[NEW] `components/SmartValidationModal.tsx`¶

Purpose: Modal to fill missing required fields

Features: - Show extracted data preview - Highlight missing required fields - Pre-fill with defaults (warehouse, currency) - Customer dropdown or "Create New" option - Confidence score indicator

Phase 2: Email Integration (6-8 hours)¶

Backend Changes¶

[NEW] `sales/services/email_processor.py`¶

Purpose: Email monitoring and processing service

Features: - Connect to email inbox (soentry@company.com) - Poll for new emails with attachments - Download attachments - Call AI extraction service - Create draft Sales Orders - Send confirmation emails

Key Functions:

def poll_inbox():
    """Poll inbox every 5 minutes for new emails"""

def process_email(email_id: str):
    """Process single email with attachments"""

def create_draft_from_email(extracted_data: dict, email_from: str):
    """Create draft SO from extracted data"""

def send_confirmation_email(customer_email: str, so_reference: str):
    """Notify customer of order receipt"""

[NEW] `sales/tasks.py`¶

Purpose: Celery tasks for background processing

Tasks:

@shared_task
def poll_sales_order_inbox():
    """Celery task to poll email inbox every 5 minutes"""

@shared_task
def process_sales_order_email(email_id: str):
    """Process individual email asynchronously"""

[MODIFY] `sales/views.py`¶

Add Endpoint: GET /sales/sales-orders/email_queue/

Purpose: List draft SOs created from emails for review

Response:

{
  "pending_review": [
    {
      "id": "uuid",
      "reference": "SO-2024-001",
      "customer_email": "customer@example.com",
      "confidence": 92.5,
      "requires_review": true,
      "created_at": "2024-12-31T10:00:00Z"
    }
  ]
}

[NEW] `core/email_service.py`¶

Purpose: Generic email service (reusable across modules)

Features: - Gmail API integration - Microsoft Graph API integration - IMAP fallback - Email sending (SMTP) - Attachment handling

Configuration:

# settings.py
EMAIL_SERVICE = 'gmail'  # or 'microsoft' or 'imap'
SALES_ORDER_EMAIL = 'soentry@company.com'
EMAIL_POLL_INTERVAL = 300  # 5 minutes

Frontend Changes¶

[NEW] `pages/EmailOrderQueue.tsx`¶

Purpose: Dashboard for reviewing email-generated orders

Features: - List of draft SOs from emails - Confidence score badges - Quick review and approve - Edit before confirming - Bulk actions (approve all, delete)

Access: Link from Sales Orders page or dashboard

[MODIFY] `Dashboard.tsx`¶

Add Widget: "Pending Email Orders" count with link to queue

Technical Architecture¶

AI Extraction Flow¶

Document Upload → 
  AI Engine (Gemini/GPT) → 
    Extract Structured Data → 
      Validate Required Fields → 
        Return to Frontend

Email Processing Flow¶

Email Arrives at soentry@company.com → 
  Celery Task Polls Inbox → 
    Download Attachment → 
      AI Extraction → 
        Create Draft SO → 
          Notify Sales Team → 
            User Reviews & Confirms

Error Handling¶

Extraction Fails: Email sales team for manual entry
Customer Not Found: Create lead in CRM + notify
Products Not Found: Flag for review with suggestions
Low Confidence (<70%): Mark for manual review

Database Migrations¶

Migration 1: Add AI Fields to SalesOrder¶

# sales/migrations/00XX_add_ai_fields.py
operations = [
    migrations.AddField(
        model_name='salesorder',
        name='source_document',
        field=models.FileField(upload_to='sales_orders/uploads/', null=True, blank=True),
    ),
    migrations.AddField(
        model_name='salesorder',
        name='ai_confidence',
        field=models.DecimalField(max_digits=5, decimal_places=2, null=True, blank=True),
    ),
    migrations.AddField(
        model_name='salesorder',
        name='requires_review',
        field=models.BooleanField(default=False),
    ),
    migrations.AddField(
        model_name='salesorder',
        name='extraction_metadata',
        field=models.JSONField(null=True, blank=True),
    ),
]

Environment Variables¶

# Email Service Configuration
EMAIL_SERVICE=gmail  # or microsoft, imap
SALES_ORDER_EMAIL=soentry@company.com
EMAIL_POLL_INTERVAL=300

# Gmail API (if using Gmail)
GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
GMAIL_REFRESH_TOKEN=your_refresh_token

# Microsoft Graph (if using Outlook)
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_TENANT_ID=your_tenant_id

# IMAP (generic)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USERNAME=soentry@company.com
IMAP_PASSWORD=your_app_password

# AI Service (already configured)
GEMINI_API_KEY=existing_key

Verification Plan¶

Phase 1 Testing¶

Manual Upload:
Upload sample customer PO (PDF)
Verify AI extraction accuracy
Test validation modal for missing fields
Confirm draft SO creation
Test with various document formats
Edge Cases:
Corrupted/unreadable documents
Documents in different languages
Handwritten POs (scanned images)
Excel spreadsheets

Phase 2 Testing¶

Email Integration:
Send test email to soentry@company.com
Verify attachment download
Confirm draft SO creation
Test notification emails
Verify error handling
Performance:
Test with multiple concurrent emails
Verify polling doesn't impact performance
Test with large attachments (>10MB)

Rollout Plan¶

Week 1: Phase 1 (Manual Upload)¶

Day 1-2: Backend AI extraction service
Day 2-3: Frontend upload UI + validation modal
Day 3: Testing and refinement
Day 4: Deploy to staging, user acceptance testing

Week 2: Phase 2 (Email Integration)¶

Day 1-2: Email service + Celery tasks
Day 2-3: Email queue dashboard
Day 3: Testing and refinement
Day 4: Deploy to staging
Day 5: Production deployment with monitoring

Success Metrics¶

Phase 1: - AI extraction accuracy >85% - Time to create SO reduced by 70% - User satisfaction with validation modal

Phase 2: - 24/7 order processing capability - Email-to-SO conversion rate >90% - Average processing time <2 minutes - Zero missed emails

Risks & Mitigation¶

Risk	Impact	Mitigation
Low AI accuracy	High	Manual review for confidence <70%
Email service downtime	Medium	Fallback to manual upload
Large attachment processing	Medium	Async processing, size limits
Customer data privacy	High	Encrypted storage, audit logs
Email spam/phishing	Medium	Sender whitelist, validation

Next Steps¶

✅ Get user approval on email service choice
✅ Confirm environment setup (Celery, email credentials)
✅ Start Phase 1 implementation
✅ User testing and feedback
✅ Phase 2 implementation
✅ Production deployment

AI-Powered Sales Order Automation - Implementation Plan¶

Overview¶

User Review Required¶

Proposed Changes¶

Phase 1: Manual Upload + AI Extraction (4-6 hours)¶

Backend Changes¶

[NEW] sales/services/document_extractor.py¶

[MODIFY] sales/models.py¶

[MODIFY] sales/views.py¶

Frontend Changes¶

[MODIFY] CreateSalesOrder.tsx¶

[NEW] components/SmartValidationModal.tsx¶

Phase 2: Email Integration (6-8 hours)¶

Backend Changes¶

[NEW] sales/services/email_processor.py¶

[NEW] sales/tasks.py¶

[MODIFY] sales/views.py¶

[NEW] core/email_service.py¶

Frontend Changes¶

[NEW] pages/EmailOrderQueue.tsx¶

[MODIFY] Dashboard.tsx¶

Technical Architecture¶

AI Extraction Flow¶

Email Processing Flow¶

Error Handling¶

Database Migrations¶

Migration 1: Add AI Fields to SalesOrder¶

Environment Variables¶

Verification Plan¶

Phase 1 Testing¶

Phase 2 Testing¶

Rollout Plan¶

Week 1: Phase 1 (Manual Upload)¶

Week 2: Phase 2 (Email Integration)¶

Success Metrics¶

Risks & Mitigation¶

Next Steps¶

[NEW] `sales/services/document_extractor.py`¶

[MODIFY] `sales/models.py`¶

[MODIFY] `sales/views.py`¶

[MODIFY] `CreateSalesOrder.tsx`¶

[NEW] `components/SmartValidationModal.tsx`¶

[NEW] `sales/services/email_processor.py`¶

[NEW] `sales/tasks.py`¶

[MODIFY] `sales/views.py`¶

[NEW] `core/email_service.py`¶

[NEW] `pages/EmailOrderQueue.tsx`¶

[MODIFY] `Dashboard.tsx`¶