bmc_hub/docs/EMAIL_RULES_TO_WORKFLOWS_MIGRATION.md

# Email Rules → Workflows Migration Guide

## 🎯 Formål

BMC Hub er ved at phase out det gamle **Rules** system til fordel for det nyere og mere kraftfulde **Workflows** system.

**Status:** 
- ✅ Workflows er default aktiveret (`EMAIL_WORKFLOWS_ENABLED=true`)
- ⚠️ Rules er nu disabled by default (`EMAIL_RULES_ENABLED=false`)

## 🔄 Hvad Er Ændret?

### I koden:
1. **Koordinering tilføjet**: Workflows kører først, rules kun hvis workflow ikke har processed emailen
2. **Deduplication**: Samme action køres ikke 2 gange
3. **Config ændring**: `EMAIL_RULES_ENABLED` er nu `false` by default
4. **Silent failures fixet**: extract_invoice_data fejler nu synligt hvis fil mangler

### I `.env`:
```bash
# Gammelt (deprecated):
EMAIL_RULES_ENABLED=true
EMAIL_RULES_AUTO_PROCESS=false

# Nyt (anbefalet):
EMAIL_WORKFLOWS_ENABLED=true
EMAIL_RULES_ENABLED=false
```

## 📋 Migration Steps

### Trin 1: Identificer Aktive Rules

```sql
-- Se alle aktive rules
SELECT id, name, action_type, conditions, priority, match_count 
FROM email_rules 
WHERE enabled = true 
ORDER BY priority ASC;
```

### Trin 2: Opret Tilsvarende Workflows

For hver rule, opret en workflow:

**Eksempel: Rule → Workflow**

**Gammel Rule:**
```json
{
  "name": "Link Supplier Invoices",
  "conditions": {
    "classification": "invoice",
    "sender_domain": ["example.com", "vendor.dk"]
  },
  "action_type": "link_supplier",
  "priority": 10
}
```

**Ny Workflow:**
```sql
INSERT INTO email_workflows (
  name, 
  description,
  classification_trigger,
  sender_pattern,
  confidence_threshold,
  workflow_steps,
  priority,
  enabled
) VALUES (
  'Link Supplier Invoices',
  'Automatically link invoice emails from known suppliers',
  'invoice',
  '(example\\.com|vendor\\.dk)$',  -- Regex pattern
  0.70,
  '[
    {"action": "link_to_vendor", "params": {"match_by": "email"}},
    {"action": "extract_invoice_data", "params": {}},
    {"action": "mark_as_processed", "params": {}}
  ]'::jsonb,
  10,
  true
);
```

### Trin 3: Test Workflows

1. Send test email der matcher classification
2. Check `email_workflow_executions` tabel for results
3. Verificer at email blev processed korrekt

```sql
-- Se workflow executions
SELECT 
  e.id,
  w.name as workflow_name,
  em.subject,
  e.status,
  e.steps_completed,
  e.execution_time_ms,
  e.started_at
FROM email_workflow_executions e
JOIN email_workflows w ON w.id = e.workflow_id
JOIN email_messages em ON em.id = e.email_id
ORDER BY e.started_at DESC
LIMIT 20;
```

### Trin 4: Disable Rules

```sql
-- Disable alle rules
UPDATE email_rules SET enabled = false;
```

Eller i `.env`:
```bash
EMAIL_RULES_ENABLED=false
```

### Trin 5: Monitor

I de første dage efter migration:
- Check logs for fejl
- Verificer at workflows kører som forventet
- Check at ingen emails falder igennem

## 🗂️ Mapping: Rules → Workflows

### Action Mapping

| Rule Action | Workflow Action | Notes |
|-------------|-----------------|-------|
| `link_supplier` | `link_to_vendor` | ✅ Direct replacement |
| `link_customer` | `link_to_customer` | ⚠️ Not fully implemented yet |
| `link_case` | `create_ticket` | ✅ Creates ticket from email |
| `mark_spam` | *(none)* | ⚠️ Needs workflow action |
| `create_purchase` | *(none)* | ⚠️ Not implemented |

### Condition Mapping

| Rule Condition | Workflow Equivalent |
|----------------|---------------------|
| `classification` | `classification_trigger` |
| `sender_email` | `sender_pattern` (exact match regex) |
| `sender_domain` | `sender_pattern` (domain regex) |
| `subject_contains` | `subject_pattern` (contains regex) |
| `subject_regex` | `subject_pattern` (direct) |
| `confidence_score` | `confidence_threshold` |

## 🆕 Workflow-Only Features

Workflows kan mere end rules:

1. **Multi-step execution**: Chain multiple actions
2. **Better error handling**: Each step tracked separately
3. **Execution history**: Full audit trail
4. **Regex patterns**: More flexible matching
5. **Stop on match**: Control workflow chaining
6. **Statistics**: Success/failure rates

## ⚠️ Backward Compatibility

**Hvis du MÅ beholde rules:**

Set i `.env`:
```bash
EMAIL_RULES_ENABLED=true
EMAIL_WORKFLOWS_ENABLED=true
```

**Systemet vil:**
- Køre workflows først
- Kun køre rules hvis workflow ikke processede emailen
- Undgå duplicate actions

**Men dette er ikke anbefalet** - rules vil blive fjernet i fremtiden.

## 📊 Status Dashboard

Tilføj til admin UI:

```sql
-- Workflow statistics
SELECT 
  w.name,
  w.classification_trigger,
  w.execution_count,
  w.success_count,
  w.failure_count,
  ROUND(100.0 * w.success_count / NULLIF(w.execution_count, 0), 1) as success_rate,
  w.last_executed_at
FROM email_workflows w
WHERE w.enabled = true
ORDER BY w.execution_count DESC;
```

## 🐛 Troubleshooting

### "Workflow ikke executed"

**Check:**
1. Er `EMAIL_WORKFLOWS_ENABLED=true` i .env?
2. Er workflow enabled i database?
3. Matcher classification_trigger?
4. Er confidence over threshold?
5. Matcher sender/subject patterns?

**Debug:**
```python
# I logs se:
# "🔄 Finding workflows for classification: invoice (confidence: 0.95)"
# "📋 Found X matching workflow(s)"
```

### "Email processed 2 gange"

**Check:**
1. Er både workflows OG rules enabled?
2. Har de samme actions?

**Fix:**
Disable rules: `EMAIL_RULES_ENABLED=false`

### "Workflow fejler stille"

**Efter fix:**
- extract_invoice_data raiser nu FileNotFoundError hvis PDF mangler
- Check `email_workflow_executions.status = 'failed'`
- Check `error_message` column

## ✅ Success Criteria

Migration er komplet når:

1. ✅ Alle rules er migrated til workflows
2. ✅ Workflows tested og virker
3. ✅ `EMAIL_RULES_ENABLED=false` i produktion
4. ✅ Ingen emails falder igennem
5. ✅ email_workflow_executions viser success

## 📞 Support

Hvis problemer:
1. Check logs: `docker-compose logs -f api | grep "🔄\|❌\|✅"`
2. Check database: `SELECT * FROM email_workflow_executions ORDER BY started_at DESC LIMIT 10;`
3. Revert: Set `EMAIL_RULES_ENABLED=true` midlertidigt

---

**Tidslinje:**
- ✅ Nu: Workflows aktiveret, rules disabled by default
- 🔜 Næste sprint: Fjern rule UI fra admin
- 🔜 Om 1 måned: Drop email_rules tabel helt

**Anbefaling:** Migrer nu, imens begge systemer er tilgængelige som fallback.