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)

```html
✅ 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

```html
✅ 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
```javascript
{
  pdf_text: "ALSO A/S\nNummer 974733485\n...",
  vendor_id: 1
}
```

### AI Output (qwen2.5:3b - 10s)
```json
{
  "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
```json
{
  "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
```javascript
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
```javascript
// 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
```javascript
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:

```sql
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