telvero_whatson_talpa/README.md

# Telvero Talpa Planning System

Een geavanceerd TV-planning systeem voor het beheren en plannen van homeshopping uitzendingen op Talpa zenders (SBS9, Net5, Veronica).

## 🎯 Functionaliteiten

### ✅ Kalender Planning
- **Drag-and-drop interface** voor eenvoudige planning
- **Timeline view** met meerdere zenders tegelijk
- **Automatische tijdberekening** voor opeenvolgende uitzendingen
- **Kleurgecodeerde uitzendingen** voor overzichtelijkheid
- **Conflict detectie** bij overlappende uitzendingen

### 📺 Commercial Management
- Registratie van commercials via Talpa API
- Automatische media asset aanmaak
- Kleurcode toewijzing per commercial
- Series code voor groepering
- Upload status tracking

### 🕐 Blok Templates
- Definieer terugkerende tijdblokken per zender
- Dagelijkse aanpassing van starttijden mogelijk
- Automatische generatie van dagelijkse blokken
- Ondersteuning voor dag-specifieke templates

### 🔄 Talpa API Integratie
- Episode registratie
- Media asset management
- Transmission scheduling
- Sync status monitoring

## 📋 Vereisten

- PHP 7.4 of hoger
- MySQL 5.7 of hoger
- Composer
- Webserver (Apache/Nginx)

## 🚀 Installatie

### 1. Clone het project

```bash
cd /path/to/your/project
```

### 2. Installeer dependencies

```bash
composer install
```

### 3. Configureer environment

Kopieer `.env.example` naar `.env` en vul de gegevens in:

```env
# Database
DB_HOST=localhost
DB_NAME=talpa_planning
DB_USER=your_username
DB_PASS=your_password

# Talpa API
TALPA_API_BASE=https://api.talpa.tv
TALPA_TOKEN=your_api_token
TALPA_MOCK_MODE=false

# TV Settings
TV_SEASON_ID=your_season_id
```

### 4. Database Setup

Voer de migratie uit:

```bash
mysql -u your_username -p talpa_planning < migrations/001_add_blocks_and_colors.sql
```

Of via phpMyAdmin:
1. Open phpMyAdmin
2. Selecteer de database
3. Ga naar "Import"
4. Upload `migrations/001_add_blocks_and_colors.sql`

### 5. Bestandspermissies

Zorg dat de webserver schrijfrechten heeft:

```bash
chmod 755 api/
chmod 755 assets/
chmod 644 api/*.php
```

## 📁 Projectstructuur

```
/
├── index.php                 # Dashboard
├── calendar.php              # Kalender planning view
├── blocks.php                # Blok template management
├── commercials.php           # Commercial management
├── helpers.php               # Helper functies
├── TalpaAPI.php             # API wrapper
├── /api                      # API endpoints
│   ├── get_transmissions.php
│   ├── create_transmission.php
│   ├── update_transmission.php
│   ├── delete_transmission.php
│   ├── update_block_time.php
│   ├── get_block_time.php
│   └── assign_color.php
├── /assets
│   ├── /css
│   │   └── custom.css       # Custom styling
│   └── /js
│       └── calendar-init.js # Calendar JavaScript
├── /migrations
│   └── 001_add_blocks_and_colors.sql
└── README.md
```

## 🎨 Gebruik

### 1. Blok Templates Instellen

1. Ga naar **Blokken** in het menu
2. Klik op "Nieuw Template"
3. Vul de gegevens in:
   - Zender (SBS9, NET5, VERONICA)
   - Template naam (bijv. "SBS9 Dagblok")
   - Dag van de week
   - Standaard starttijd
   - Optioneel: eindtijd

**Voorbeelden:**
- SBS9 Dagblok: Ma-Zo, 07:00-15:00
- SBS9 Nachtblok: Ma-Zo, 23:30-02:00
- Net5 Ochtend: Ma-Vr, 07:30-11:30
- Net5 Middag: Ma-Vr, 13:20-13:50

### 2. Commercials Registreren

1. Ga naar **Commercials** in het menu
2. Vul het formulier in:
   - Product naam
   - Duur (HH:MM:SS formaat)
   - Optioneel: Series code (bijv. 006a)
3. Klik op "Registreren bij Talpa"
4. Het systeem:
   - Maakt een episode aan via API
   - Genereert een media asset
   - Wijst automatisch een unieke kleur toe
5. Update de upload status naar "Uploaded" wanneer de video is geüpload

### 3. Planning Maken

1. Ga naar **Kalender** in het menu
2. Selecteer de gewenste week/dag view
3. **Optioneel:** Pas blok starttijd aan:
   - Klik op een tijdslot
   - Wijzig de starttijd
   - Kies of je alle uitzendingen wilt herberekenen
4. **Plan uitzendingen:**
   - Sleep een commercial uit de sidebar
   - Drop deze op het gewenste tijdslot
   - Het systeem berekent automatisch de volgende starttijd
5. **Bewerk uitzendingen:**
   - Klik op een uitzending voor details
   - Sleep om te verplaatsen
   - Verwijder indien nodig

### 4. Synchroniseren met Talpa

1. Klik op een uitzending in de kalender
2. Klik op "Sync naar Talpa"
3. Monitor de status:
   - 🟡 **Pending:** Nog niet gesynchroniseerd
   - 🟢 **Synced:** Succesvol gesynchroniseerd
   - 🔴 **Error:** Fout opgetreden

## 🎨 Kleurcode Systeem

Het systeem wijst automatisch unieke kleuren toe aan commercials voor visuele identificatie:

- Kleuren worden automatisch gegenereerd met voldoende contrast
- Elke commercial krijgt een unieke kleur
- Series codes kunnen dezelfde kleur delen
- Kleuren zijn handmatig aanpasbaar in Commercial Management

## 🔧 Geavanceerde Functies

### Automatische Tijdberekening

Het systeem berekent automatisch de starttijd van de volgende uitzending:

```
Volgende starttijd = Huidige starttijd + Duur huidige uitzending
```

### Conflict Detectie

Bij het plannen controleert het systeem op:
- Overlappende uitzendingen op dezelfde zender
- Uitzendingen buiten blok tijden
- Dubbele bookings

### Blok Herberekening

Wanneer je een blok starttijd aanpast:
1. Optie 1: Alleen de starttijd wijzigen
2. Optie 2: Alle uitzendingen in het blok herberekenen vanaf de nieuwe starttijd

## 🐛 Troubleshooting

### Kalender laadt niet

**Probleem:** Kalender toont geen events

**Oplossing:**
1. Check browser console voor JavaScript errors
2. Controleer of API endpoints bereikbaar zijn:
   ```bash
   curl http://your-domain/api/get_transmissions.php?start=2026-01-01&end=2026-01-31
   ```
3. Controleer database connectie in `.env`

### Drag-and-drop werkt niet

**Probleem:** Commercials zijn niet sleepbaar

**Oplossing:**
1. Controleer of FullCalendar correct is geladen
2. Check browser console voor errors
3. Zorg dat commercials status "uploaded" hebben

### API Sync Errors

**Probleem:** Synchronisatie met Talpa faalt

**Oplossing:**
1. Controleer API credentials in `.env`
2. Check `api_log.txt` voor details
3. Verifieer dat content_id en media_asset_id correct zijn
4. Test met `TALPA_MOCK_MODE=true` voor debugging

### Database Errors

**Probleem:** SQL errors bij gebruik

**Oplossing:**
1. Controleer of migratie correct is uitgevoerd:
   ```sql
   SHOW TABLES;
   DESCRIBE block_templates;
   DESCRIBE daily_blocks;
   ```
2. Controleer of alle kolommen bestaan:
   ```sql
   SHOW COLUMNS FROM commercials LIKE 'color_code';
   ```

## 📊 Database Schema

### Nieuwe Tabellen

**block_templates**
- Definieert terugkerende tijdblokken
- Per zender en dag van de week
- Standaard start- en eindtijden

**daily_blocks**
- Dagelijkse instanties van templates
- Mogelijkheid tot aanpassing per dag
- Gekoppeld aan template_id

### Uitgebreide Kolommen

**commercials**
- `color_code` (VARCHAR(7)): Hex kleurcode
- `series_code` (VARCHAR(20)): Series identifier

## 🔐 Beveiliging

- Gebruik prepared statements voor alle database queries
- Valideer alle input (datum, tijd, kleuren)
- Sanitize output met `htmlspecialchars()`
- Gebruik HTTPS in productie
- Bewaar `.env` buiten webroot
- Voeg `.env` toe aan `.gitignore`

## 📈 Performance Tips

1. **Database Indexen:** Reeds toegevoegd in migratie
2. **Caching:** Overweeg Redis voor API responses
3. **Lazy Loading:** Kalender laadt alleen zichtbare periode
4. **Batch Operations:** Sync meerdere uitzendingen tegelijk

## 🔄 Updates & Migraties

Bij toekomstige updates:

1. Maak nieuwe migratie file: `002_description.sql`
2. Voer uit in volgorde
3. Update deze README met wijzigingen

## 📞 Support

Voor vragen of problemen:
- Check de troubleshooting sectie
- Bekijk `api_log.txt` voor API details
- Controleer browser console voor JavaScript errors

## 📝 Changelog

### Versie 1.0.0 (2026-01-13)
- ✅ Kalender planning met drag-and-drop
- ✅ Blok template management
- ✅ Commercial management met kleurcodes
- ✅ Automatische tijdberekening
- ✅ Talpa API integratie
- ✅ Conflict detectie
- ✅ Responsive design

## 🎯 Roadmap

Toekomstige features:
- [ ] Bulk import van commercials
- [ ] Excel export van planning
- [ ] Email notificaties bij sync errors
- [ ] Gebruikersbeheer en rechten
- [ ] Planning templates (kopieer week)
- [ ] Statistieken en rapportages
- [ ] Mobile app

## 📄 Licentie

Proprietary - Telvero © 2026

---

**Gemaakt met ❤️ voor Telvero Talpa Planning**