telvero_whatson_talpa/docs/IMPLEMENTATION_SUMMARY.md

# Transmission Synchronisatie - Implementatie Samenvatting

## Overzicht

Deze implementatie zorgt ervoor dat transmissions in de planning automatisch worden bijgewerkt in Talpa wanneer ze worden verplaatst. Dit geldt voor zowel de verplaatste transmission als alle andere transmissions in hetzelfde uitzendblok.

## Geïmplementeerde Wijzigingen

### 1. Database Migratie
**Bestand**: [`migrations/002_add_talpa_transmission_id.sql`](../migrations/002_add_talpa_transmission_id.sql)

- Nieuwe kolom `talpa_transmission_id` toegevoegd aan `transmissions` tabel
- Index toegevoegd voor snellere lookups
- Automatische migratie van bestaande data uit `api_response` JSON

**Uitvoeren**:
```bash
mysql -u [user] -p [database] < migrations/002_add_talpa_transmission_id.sql
```

### 2. TalpaAPI Uitbreiding
**Bestand**: [`TalpaAPI.php`](../TalpaAPI.php)

**Nieuwe methode**:
```php
public function updateTransmission($transmissionId, $data)
```

**Functionaliteit**:
- PUT request naar `/linearSchedule/v1/transmissions/{id}`
- Update startDate, startTime en duration
- Mock response voor testing

### 3. Sync Block Update
**Bestand**: [`api/sync_block.php`](../api/sync_block.php)

**Wijzigingen**:
- Detecteert of transmission nieuw is (POST) of bestaand (PUT)
- Slaat `talpa_transmission_id` op na succesvolle sync
- Ondersteunt zowel create als update operaties
- Uitgebreide debug logging

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

### 4. Helper Functies
**Bestand**: [`helpers.php`](../helpers.php)

**Nieuwe functies**:

#### `updateBlockTransmissionsToTalpa($db, $api, $date, $channel, $blockId)`
- Herberekent starttijden van alle transmissions in een blok
- Update lokale database
- Synchroniseert naar Talpa (PUT requests)
- Retourneert resultaat met success/failure counts

#### `syncTransmissionToTalpa($db, $api, $transmission)`
- Sync één transmission naar Talpa
- Automatische detectie van create vs update
- Error handling en status updates
- Retourneert talpa_transmission_id

### 5. Update Transmission
**Bestand**: [`api/update_transmission.php`](../api/update_transmission.php)

**Nieuwe functionaliteit**:
- Direct sync naar Talpa na lokale update
- Cascade update van alle transmissions in hetzelfde blok
- Bepaalt automatisch welk blok de transmission behoort
- Retourneert sync resultaten in response

**Flow**:
1. Update lokale transmission
2. Sync transmission naar Talpa (als talpa_transmission_id bestaat)
3. Bepaal block_id
4. Update alle andere transmissions in blok
5. Return resultaten

### 6. Insert at Position
**Bestand**: [`api/insert_transmission_at_position.php`](../api/insert_transmission_at_position.php)

**Nieuwe functionaliteit**:
- Herberekent starttijden na insert
- Synchroniseert hele blok naar Talpa
- Retourneert block update resultaten

**Flow**:
1. Insert nieuwe transmission op positie
2. Herbereken alle starttijden in blok
3. Update lokale database
4. Sync hele blok naar Talpa
5. Return resultaten

## API Response Wijzigingen

### sync_block.php Response
```json
{
  "success": true,
  "message": "Synchronisatie voltooid: 3 geslaagd, 0 mislukt",
  "synced": 3,
  "failed": 0,
  "errors": [],
  "api_calls": [
    {
      "transmission_id": 1,
      "action": "update",
      "talpa_transmission_id": "MOCK_TX_123",
      "determined_status": "synced"
    }
  ]
}
```

### update_transmission.php Response
```json
{
  "success": true,
  "message": "Transmission updated successfully",
  "transmission": { ... },
  "talpa_sync": {
    "success": true,
    "talpa_transmission_id": "MOCK_TX_123"
  },
  "block_update": {
    "success": true,
    "updated": 2,
    "failed": 0
  }
}
```

### insert_transmission_at_position.php Response
```json
{
  "success": true,
  "message": "Transmission inserted successfully",
  "new_transmission_id": 456,
  "block_update": {
    "success": true,
    "updated": 3,
    "failed": 0
  }
}
```

## Gebruik Scenario's

### Scenario 1: Eerste Sync
```
1. Maak transmissions aan in planning
2. Klik "Sync Block"
3. Transmissions krijgen talpa_transmission_id
4. Status wordt 'synced'
```

### Scenario 2: Transmission Verplaatsen
```
1. Drag transmission naar nieuwe tijd
2. API update wordt getriggerd
3. Transmission wordt geüpdatet in Talpa (PUT)
4. Alle volgende transmissions in blok worden ook geüpdatet
5. Status blijft 'synced'
```

### Scenario 3: Insert at Position
```
1. Insert nieuwe transmission op positie 2
2. Nieuwe transmission wordt aangemaakt (lokaal)
3. Transmissions 2, 3, 4... worden verschoven
4. Alle bestaande transmissions worden geüpdatet in Talpa
5. Nieuwe transmission krijgt status 'pending' (nog geen talpa_transmission_id)
6. Bij volgende sync: nieuwe transmission wordt aangemaakt in Talpa
```

## Error Handling

### Talpa Transmission Niet Gevonden
```
1. PUT request faalt (404)
2. talpa_transmission_id wordt NULL
3. api_status wordt 'error' of 'pending'
4. Bij volgende sync: POST create nieuwe transmission
```

### Netwerk Failure
```
1. API call faalt
2. Status blijft 'pending'
3. Error wordt gelogd in api_response
4. Bij volgende sync: retry
```

### Validation Errors
```
1. Lokale validatie faalt (overlap, buiten blok)
2. Update wordt geweigerd
3. Error response naar client
4. Geen Talpa call
```

## Logging

Alle API calls worden gelogd in `api_log.txt`:
```
[2026-01-16 10:20:15] REQUEST: PUT /linearSchedule/v1/transmissions/MOCK_TX_123 | Data: {"startDate":"2026-01-20","startTime":"08:15:00","duration":"00:30:00"}
[2026-01-16 10:20:15] RESPONSE (HTTP 200): {"statusCode":"200","message":"Transmission updated"}
```

## Testing

Zie [`docs/TRANSMISSION_SYNC_TESTING.md`](TRANSMISSION_SYNC_TESTING.md) voor:
- 7 gedetailleerde test scenario's
- Database verificatie queries
- API endpoint voorbeelden
- Troubleshooting guide

## Configuratie

### .env Settings
```env
# Talpa API
TALPA_API_BASE=https://api.talpa.nl
TALPA_TOKEN=your_token_here

# Mock mode voor testing (geen echte API calls)
TALPA_MOCK_MODE=true
```

### Mock Mode
Wanneer `TALPA_MOCK_MODE=true`:
- Geen echte API calls naar Talpa
- Gesimuleerde responses met delays
- Transmission IDs: `MOCK_TX_[timestamp]`
- Altijd success responses

## Performance

### Overwegingen
- Elke transmission update triggert meerdere PUT requests
- Bij grote blokken (>10 transmissions): meerdere seconden
- Overweeg rate limiting bij productie gebruik

### Optimalisaties
- Batch updates mogelijk in toekomst
- Async processing voor grote blokken
- Caching van block data

## Rollback Plan

Bij problemen:
```sql
-- Verwijder nieuwe kolom
ALTER TABLE transmissions DROP COLUMN talpa_transmission_id;

-- Restore oude code files
git checkout HEAD~1 TalpaAPI.php api/sync_block.php api/update_transmission.php api/insert_transmission_at_position.php helpers.php
```

## Volgende Stappen

### Optionele Verbeteringen
1. **Audit Log**: Bijhouden van alle sync operaties
2. **Retry Mechanisme**: Automatische retry bij failures
3. **Batch Updates**: Meerdere transmissions in één API call
4. **Webhooks**: Talpa notificaties bij wijzigingen
5. **Conflict Resolution**: Wat als Talpa data afwijkt van lokaal?

### Monitoring
- Check `api_log.txt` regelmatig
- Monitor failed syncs in database
- Alert bij hoge failure rate
- Performance metrics voor API calls

## Support

Bij vragen of problemen:
1. Check [`plans/transmission-sync-update-plan.md`](../plans/transmission-sync-update-plan.md) voor architectuur
2. Check [`docs/TRANSMISSION_SYNC_TESTING.md`](TRANSMISSION_SYNC_TESTING.md) voor testing
3. Review `api_log.txt` voor API call details
4. Check database `api_response` kolom voor error details

## Bestanden Overzicht

| Bestand | Wijziging | Beschrijving |
|---------|-----------|--------------|
| [`migrations/002_add_talpa_transmission_id.sql`](../migrations/002_add_talpa_transmission_id.sql) | Nieuw | Database migratie |
| [`TalpaAPI.php`](../TalpaAPI.php) | Gewijzigd | updateTransmission() methode |
| [`api/sync_block.php`](../api/sync_block.php) | Gewijzigd | Create/Update logica |
| [`api/update_transmission.php`](../api/update_transmission.php) | Gewijzigd | Cascade updates |
| [`api/insert_transmission_at_position.php`](../api/insert_transmission_at_position.php) | Gewijzigd | Block sync |
| [`helpers.php`](../helpers.php) | Gewijzigd | Nieuwe helper functies |
| [`plans/transmission-sync-update-plan.md`](../plans/transmission-sync-update-plan.md) | Nieuw | Architectuur plan |
| [`docs/TRANSMISSION_SYNC_TESTING.md`](TRANSMISSION_SYNC_TESTING.md) | Nieuw | Testing guide |
| [`docs/IMPLEMENTATION_SUMMARY.md`](IMPLEMENTATION_SUMMARY.md) | Nieuw | Dit document |

## Versie Informatie

- **Implementatie Datum**: 2026-01-16
- **Versie**: 1.0
- **Status**: Klaar voor testing