bmc_hub/docs/TEMPLATE_CREATION_FLOW.md

Perfect Template Creation Flow - BMC Hub

🎯 Workflow Overview

Upload Invoice
    ↓
No Template Match? → AI Extracts (10s)
    ↓
"Opret Template" knap vises
    ↓
Click → Auto-creates template
    ↓
Next invoice: 0.1s (100x faster!)

📋 Step-by-Step Guide

Method 1: From Upload (Recommended for First-Time)

1. Upload faktura via /billing/supplier-invoices
2. If no template matches:
   • AI extracts data (10s)
   • "🪄 Opret Template" knap vises
3. Click "Opret Template"
   • System AI-analyzes PDF
   • Converts to template format
   • Creates template automatically
4. Redirect to Template Builder for fine-tuning (optional)

Benefits:

• ✅ One-click from upload success
• ✅ Uses real invoice data
• ✅ Automatic field mapping
• ✅ Ready to use immediately

Method 2: Template Builder Manual

1. Go to /billing/template-builder
2. Step 1: Select PDF file
3. Step 2: Choose vendor + name template
4. Step 3: Click "🤖 AI Auto-generer Template"
   • AI analyzes PDF
   • Auto-fills all patterns
   • Shows detection confidence
5. Step 4: Test & Save

Benefits:

• ✅ More control
• ✅ Preview before saving
• ✅ Can edit patterns manually
• ✅ Test against PDF first

Method 3: Templates List (Batch)

1. Go to /billing/templates
2. View existing templates
3. Click "Test" to validate
4. Create new from scratch

🔄 Complete User Journey

First Invoice from New Vendor

User uploads ALSO invoice #1
    ↓
System: "Ingen template match"
    ↓
AI extracts in 10s
    ↓
Shows: "✅ Faktura uploadet!"
        "⚠️  Ingen template - næste gang vil være langsom"
        [🪄 Opret Template knap]
    ↓
User clicks "Opret Template"
    ↓
System creates template automatically
    ↓
"✅ Template oprettet! Næste faktura vil være 100x hurtigere"

Second Invoice from Same Vendor

User uploads ALSO invoice #2
    ↓
Template matches (0.1s) ⚡
    ↓
"✅ Faktura uploadet - auto-matched template!"
NO template creation button (already exists)

🎨 UI/UX Details

Upload Success Message (No Template Match)

✅ Faktura Uploadet & Analyseret!

AI Udtrækning: [Vendor Badge] [Confidence Badge]
  Leverandør: ALSO A/S
  CVR: 17630903
  Fakturanr: 974733485
  Beløb: 5.165,61 DKK

⚠️  Ingen template match - fremtidige uploads vil være langsomme
    
[👁️  Vis Faktura] [🪄 Opret Template] [✅ Luk]

After Template Creation

✅ Template Oprettet!

Næste gang en faktura fra denne leverandør uploades, vil den blive 
behandlet automatisk på 0.1 sekunder i stedet for 10 sekunder!

Template ID: 42
Fields: vendor_cvr, invoice_number, invoice_date, total_amount
Detection patterns: 3
    
[✏️  Rediger Template] [📋 Se Alle Templates] [✅ Luk]

🚀 Performance Metrics

Scenario	Processing Time	User Action
No Template	10s (AI)	Manual → "Opret Template"
Template Match	0.1s (Regex)	None - automatic
Template Creation	15s total	One-click

ROI Example:

• 100 invoices from same vendor
• Without template: 100 × 10s = 16.7 minutes
• With template: 1 × 15s + 99 × 0.1s = ~25 seconds
• Time saved: 16 minutes!

🧠 AI Auto-Generate Details

Input

{
  pdf_text: "ALSO A/S\nNummer 974733485\n...",
  vendor_id: 1
}

AI Output (qwen2.5:3b - 10s)

{
  "vendor_cvr": "17630903",
  "invoice_number": "974733485",
  "invoice_date": "30.06.2025",
  "total_amount": "5165.61",
  "detection_patterns": ["ALSO A/S", "Mårkærvej 2", "Faktura"],
  "lines_start": "Position Varenr. Beskrivelse",
  "lines_end": "Subtotal"
}

Converted to Template Format

{
  "vendor_id": 1,
  "template_name": "Auto-generated 2025-12-07",
  "detection_patterns": [
    {"type": "text", "pattern": "ALSO A/S", "weight": 0.5},
    {"type": "text", "pattern": "Mårkærvej 2", "weight": 0.3}
  ],
  "field_mappings": {
    "vendor_cvr": {"pattern": "DK\\s*(\\d{8})", "group": 1},
    "invoice_number": {"pattern": "Nummer\\s*(\\d+)", "group": 1},
    "invoice_date": {"pattern": "Dato\\s*(\\d{1,2}[\\/.-]\\d{1,2}[\\/.-]\\d{4})", "group": 1},
    "total_amount": {"pattern": "Total\\s*([\\d.,]+)", "group": 1},
    "lines_start": {"pattern": "Position Varenr\\. Beskrivelse"},
    "lines_end": {"pattern": "Subtotal"}
  }
}

✨ Smart Features

1. Auto-Detection of Template Need

if (!result.template_matched && result.vendor_id) {
  showButton("Opret Template"); // Only if vendor exists
}

2. One-Click Creation

• Fetches PDF text
• AI analyzes
• Converts format
• Saves template
• Shows success with edit link

3. Field Mapping Intelligence

// Handles both nested and flat AI responses
const cvrValue = aiData.vendor_cvr?.value || aiData.vendor_cvr || aiData.cvr;

4. Multi-line Item Support

• NO line_pattern in template
• Uses smart multi-line extraction
• Combines description + price lines automatically

🔧 Technical Implementation

Frontend Flow

async function createTemplateFromInvoice(invoiceId, vendorId) {
  // 1. Get PDF text
  const pdfData = await reprocess(invoiceId);
  
  // 2. AI analyze
  const aiData = await aiAnalyze(pdfData.pdf_text, vendorId);
  
  // 3. Convert to template format
  const template = convertAiToTemplate(aiData, vendorId);
  
  // 4. Save
  await createTemplate(template);
  
  // 5. Show success + edit link
  showSuccess(template.template_id);
}

Backend Endpoints

POST /api/v1/supplier-invoices/reprocess/{id}
  → Returns: {pdf_text, ...}

POST /api/v1/supplier-invoices/ai-analyze
  → Input: {pdf_text, vendor_id}
  → Returns: AI extracted fields

POST /api/v1/supplier-invoices/templates
  → Input: {vendor_id, template_name, detection_patterns, field_mappings}
  → Returns: {template_id, ...}

📊 Success Metrics

Track these in template_usage_log:

SELECT 
  template_id,
  COUNT(*) as uses,
  AVG(CASE WHEN matched THEN 1 ELSE 0 END) as success_rate,
  AVG(confidence) as avg_confidence
FROM template_usage_log
GROUP BY template_id

🎯 Best Practices

For Users

1. Always create template after first invoice from new vendor
2. Test template with 2-3 invoices before trusting
3. Edit patterns if confidence < 80%
4. Use descriptive names: "ALSO Standard", "ALSO Email Format"

For Admins

1. Review auto-generated templates weekly
2. Merge duplicate templates (same vendor, similar patterns)
3. Disable low-performing templates (success_rate < 0.7)
4. Keep AI model updated (qwen2.5:3b or better)

🚨 Edge Cases Handled

Vendor Not Found

• AI extracts CVR but vendor doesn't exist in DB
• Shows warning: "Du skal oprette leverandør først"
• No template creation button (needs vendor_id)

AI Returns Incomplete Data

• Template created with available fields only
• Missing fields can be added manually later
• Template still speeds up future processing

Duplicate Templates

• System allows multiple templates per vendor
• Each can target different invoice formats
• Detection patterns differentiate them

🎓 Training Users

Quick Start Tutorial

1. Upload en faktura
2. Klik "Opret Template" når den vises
3. Næste gang = automatisk!

Power User Tips

- Brug Template Builder for bedre kontrol
- Test templates før production
- Kombiner AI + manual editing
- Gennemgå templates månedligt

📈 Future Enhancements

1. Batch Template Creation: Upload 10 PDFs → Create 10 templates
2. Template Suggestions: "Found similar template - use this instead?"
3. Auto-Merge: Detect duplicate templates and suggest merge
4. Confidence Tracking: Dashboard showing template performance
5. A/B Testing: Test pattern variations automatically