telvero_whatson_talpa/plans/transmission-sync-update-plan.md

# Plan: Transmission Synchronisatie met Talpa Updates

## Probleem Beschrijving

Wanneer infomercials in de planning worden verplaatst, moeten de transmissions in Talpa ook worden bijgewerkt. Dit geldt voor:
- De verplaatste infomercial zelf
- Alle andere infomercials in hetzelfde uitzendblok (omdat hun starttijden verschuiven)

Momenteel wordt alleen bij de eerste synchronisatie een transmission aangemaakt in Talpa, maar er is geen mechanisme om bestaande transmissions te updaten wanneer de planning wijzigt.

## Huidige Situatie

### Database Schema
De `transmissions` tabel heeft:
- `id` - lokale database ID
- `api_status` - status: 'pending', 'synced', 'error'
- `api_response` - JSON response van Talpa API
- **GEEN** dedicated kolom voor Talpa transmission ID

### Huidige Flow
1. **Aanmaken**: [`create_transmission.php`](api/create_transmission.php) maakt lokale transmission aan met status 'pending'
2. **Sync**: [`sync_block.php`](api/sync_block.php) synchroniseert naar Talpa en zet status op 'synced'
3. **Update**: [`update_transmission.php`](api/update_transmission.php) update lokale data en zet status terug naar 'pending'
4. **Probleem**: Er is geen mechanisme om Talpa te updaten na wijzigingen

### Talpa API
- `POST /linearSchedule/v1/transmissions` - Aanmaken (retourneert `id` in response)
- `PUT /linearSchedule/v1/transmissions/{id}` - Update (nog niet geïmplementeerd)

## Oplossing Architectuur

### 1. Database Wijzigingen

Voeg nieuwe kolom toe aan `transmissions` tabel:
```sql
ALTER TABLE transmissions 
ADD COLUMN talpa_transmission_id VARCHAR(100) NULL 
COMMENT 'Talpa API transmission ID voor updates';
```

**Rationale**: 
- Dedicated kolom is beter dan JSON parsing uit `api_response`
- Makkelijker te indexeren en queryen
- Duidelijker in code

### 2. TalpaAPI Uitbreiding

Voeg nieuwe methode toe aan [`TalpaAPI.php`](TalpaAPI.php):
```php
public function updateTransmission($transmissionId, $data) {
    return $this->request('PUT', '/linearSchedule/v1/transmissions/' . $transmissionId, [
        "startDate" => $data['startDate'],
        "startTime" => $data['startTime'],
        "duration" => $data['duration']
    ]);
}
```

### 3. Sync Block Wijzigingen

Update [`sync_block.php`](api/sync_block.php):
- Bij succesvolle sync: extract `id` uit response en sla op in `talpa_transmission_id`
- Ondersteun zowel nieuwe transmissions (POST) als bestaande (PUT)

**Logica**:
```
IF talpa_transmission_id IS NULL:
    → POST nieuwe transmission
    → Sla transmission_id op
ELSE:
    → PUT update bestaande transmission
```

### 4. Update Transmission Wijzigingen

Update [`update_transmission.php`](api/update_transmission.php):
- Na lokale update: check of `talpa_transmission_id` bestaat
- Zo ja: direct Talpa updaten (niet wachten op sync)
- Update ook andere transmissions in hetzelfde blok

**Cascade Update Logica**:
```
1. Bepaal welk blok de transmission behoort
2. Haal alle transmissions in dat blok op (gesorteerd op tijd)
3. Herbereken starttijden vanaf de gewijzigde transmission
4. Update alle affected transmissions:
   - Lokaal: nieuwe start_time
   - Talpa: PUT update (als talpa_transmission_id bestaat)
```

### 5. Insert at Position Wijzigingen

Update [`insert_transmission_at_position.php`](api/insert_transmission_at_position.php):
- Na insert: herbereken alle volgende transmissions in blok
- Update Talpa voor alle transmissions met `talpa_transmission_id`

## Implementatie Details

### Scenario 1: Nieuwe Transmission
```mermaid
graph LR
    A[Create Transmission] --> B[Status: pending]
    B --> C[Sync Block]
    C --> D[POST to Talpa]
    D --> E[Save talpa_transmission_id]
    E --> F[Status: synced]
```

### Scenario 2: Update Bestaande Transmission
```mermaid
graph LR
    A[Update Transmission] --> B[Check talpa_transmission_id]
    B -->|Exists| C[PUT to Talpa]
    B -->|NULL| D[Status: pending]
    C --> E[Update Cascade]
    E --> F[Update Other Transmissions in Block]
    F --> G[PUT each to Talpa]
```

### Scenario 3: Insert at Position
```mermaid
graph LR
    A[Insert at Position] --> B[Create New Transmission]
    B --> C[Recalculate Block Times]
    C --> D[Update All Following Transmissions]
    D --> E[POST new to Talpa]
    E --> F[PUT updates to Talpa]
```

## Benodigde Functies

### Helper Function: updateBlockTransmissions()
```php
function updateBlockTransmissions($db, $api, $blockId, $date, $channel) {
    // 1. Get all transmissions in block (ordered by time)
    // 2. Recalculate start times
    // 3. Update local database
    // 4. Update Talpa (if talpa_transmission_id exists)
    // 5. Return results
}
```

### Helper Function: syncTransmissionToTalpa()
```php
function syncTransmissionToTalpa($api, $transmission) {
    if ($transmission['talpa_transmission_id']) {
        // PUT update
        return $api->updateTransmission($transmission['talpa_transmission_id'], $data);
    } else {
        // POST create
        $result = $api->createTransmission($data);
        return $result['id'];
    }
}
```

## API Status Flow

```
pending → synced → pending → synced
   ↓         ↓         ↓         ↓
 CREATE    SYNC    UPDATE    RE-SYNC
```

**Status Betekenis**:
- `pending`: Lokale wijziging, nog niet gesynchroniseerd
- `synced`: In sync met Talpa
- `error`: Synchronisatie gefaald

## Edge Cases

### 1. Talpa Transmission ID Ontbreekt
**Situatie**: Oude data zonder `talpa_transmission_id`
**Oplossing**: Behandel als nieuwe transmission (POST)

### 2. Talpa Update Faalt
**Situatie**: PUT request faalt (transmission bestaat niet meer in Talpa)
**Oplossing**: 
- Zet `talpa_transmission_id` op NULL
- Zet status op 'pending'
- Bij volgende sync: POST nieuwe transmission

### 3. Blok Overlap
**Situatie**: Transmission verplaatsen veroorzaakt overlap
**Oplossing**: Validatie blijft zoals nu (reject met error)

### 4. Overnight Blocks
**Situatie**: Blok loopt over middernacht (bijv. 23:30 - 02:00)
**Oplossing**: Bestaande logica blijft werken (al geïmplementeerd)

## Testing Scenario's

### Test 1: Nieuwe Transmission Sync
1. Maak nieuwe transmission aan
2. Sync block
3. Verify: `talpa_transmission_id` is gevuld
4. Verify: `api_status` = 'synced'

### Test 2: Update Transmission
1. Maak en sync transmission
2. Verplaats transmission naar andere tijd
3. Verify: Talpa is geüpdatet (PUT call)
4. Verify: Andere transmissions in blok zijn ook geüpdatet

### Test 3: Insert at Position
1. Maak blok met 3 transmissions (alle synced)
2. Insert nieuwe transmission op positie 2
3. Verify: Nieuwe transmission is aangemaakt in Talpa
4. Verify: Transmissions 2 en 3 zijn geüpdatet in Talpa

### Test 4: Cascade Update
1. Maak blok met 5 transmissions
2. Verplaats transmission 2 naar latere tijd
3. Verify: Transmissions 3, 4, 5 hebben nieuwe starttijden
4. Verify: Alle updates zijn naar Talpa gestuurd

### Test 5: Error Recovery
1. Maak transmission met talpa_transmission_id
2. Simuleer Talpa error (transmission bestaat niet)
3. Verify: `talpa_transmission_id` wordt NULL
4. Verify: Status wordt 'pending'
5. Re-sync: nieuwe transmission wordt aangemaakt

## Migratie Strategie

### Voor Bestaande Data
```sql
-- Optioneel: Probeer transmission_id uit api_response te extracten
UPDATE transmissions 
SET talpa_transmission_id = JSON_EXTRACT(api_response, '$.id')
WHERE api_status = 'synced' 
AND api_response IS NOT NULL
AND JSON_VALID(api_response);
```

**Note**: Dit werkt alleen als `api_response` het `id` veld bevat.

## Voordelen van Deze Aanpak

1. **Incrementeel**: Werkt met bestaande data
2. **Robuust**: Fallback naar POST als PUT faalt
3. **Efficiënt**: Direct updaten ipv wachten op sync
4. **Consistent**: Talpa blijft in sync met lokale planning
5. **Traceerbaar**: Duidelijke status en logging

## Risico's en Mitigatie

| Risico | Impact | Mitigatie |
|--------|--------|-----------|
| Talpa API rate limiting | Medium | Batch updates, retry logic |
| Netwerk failures | Medium | Error handling, status tracking |
| Data inconsistentie | Hoog | Transaction wrapping, rollback |
| Oude data zonder ID | Laag | Behandel als nieuwe transmission |

## Implementatie Volgorde

1. ✅ Database migratie (nieuwe kolom)
2. ✅ TalpaAPI uitbreiding (updateTransmission)
3. ✅ sync_block.php update (save transmission_id)
4. ✅ Helper functions (updateBlockTransmissions, syncTransmissionToTalpa)
5. ✅ update_transmission.php update (cascade updates)
6. ✅ insert_transmission_at_position.php update
7. ✅ Testing en validatie
8. ✅ Documentatie

## Vragen voor Gebruiker

1. **Moet er een retry mechanisme komen** voor gefaalde Talpa updates?
2. **Moeten we een audit log bijhouden** van alle Talpa synchronisaties?
3. **Wat gebeurt er als een transmission in Talpa is verwijderd** maar lokaal nog bestaat?
4. **Moeten we batch updates ondersteunen** (meerdere transmissions in één API call)?