Scheduler – propagace změn šablon

Tato stránka slouží jako checklist pro testery přepracované logiky synchronizace šablon (větev refactoring/scheduler-fix). Cíle: ověřit, že změny na šabloně se správně promítnou do budoucích eventů, ručně upravené eventy jsou chráněny před přepsáním a moderátoři dostávají upozornění.

Popis chování (referenční dokument) je v Správa a plánování kvízů. Zde najdete co se změnilo, jak to otestovat a jaké podmínky očekávat.

---

Co se v tomto kole změnilo

Nové joby

Job	Účel
App\Jobs\QuizzBlueprint\SyncDayOfWeek	Přesune budoucí neručně-upravené eventy na nový den v týdnu
App\Jobs\QuizzBlueprint\SyncTimes	Aktualizuje čas konání budoucích neručně-upravených eventů
App\Jobs\QuizzBlueprint\SyncFrequency	Zruší eventy nezapadající do nové frekvence, případně dogeneruje nové
App\Jobs\QuizzBlueprint\PostUpdateBrief	Odešle moderátorům shrnutí změn (mail + Slack) po dokončení synchronizace

Nové / upravené chování

1. Změny šablony se propagují na budoucí eventy – dříve se změny šablony (den v týdnu, čas, frekvence) nepromítaly do již vygenerovaných eventů. Nyní se do fronty dispatche příslušný job, který eventy asynchronně aktualizuje.
2. Ochrana ručně upravených eventů – eventy, u nichž byl čas nebo den změněn přímo (nikoli přes šablonu), mají vyplněný sloupec manually_changed_at a synchronizace je přeskočí.
3. Notifikace moderátorům – po každé změně šablony (den v týdnu, čas nebo frekvence) dostanou moderátoři e-mail a Slack zprávu se souhrnem: původní doba konání, nová doba konání, seznam dotčených eventů.
4. Kontrola duplicit v scheduleru – scheduler nyní kontroluje existenci eventu podle čísla týdne (week), nikoli přesného data. V rámci jednoho týdne se event pro daný blueprint nevygeneruje dvakrát.

Nový sloupec

Tabulka	Sloupec	Účel
chk_quizz_events	manually_changed_at	Timestamp posledního ručního zásahu do data/času eventu; NULL = neměněno

---

Příprava testovacího prostředí

• Admin: https://admin.beta.chytrykviz.cz
• Mailhog (odchozí e-maily): http://159.89.0.170:8025/
• Slack: kanál odpovídající testovacímu prostředí

Beta prostředí

Z BETA neodejdou e-maily na reálné adresy – vše je odchyceno v Mailhogu výše.

Před testováním ověřte, že:

• Horizon nebo Sync queue driver je spuštěný (joby musí proběhnout)
• Šablona, na které testujete, má alespoň 4 budoucí eventy
• Alespoň jeden z eventů má ručně upravený čas (manually_changed_at není NULL)

---

1 · Synchronizace dne v týdnu

1.1 Změna dne – budoucí eventy se přesunou

1. Otevřete šablonu s frekvencí weekly, která má budoucí eventy na středu.
2. Změňte den v týdnu na pátek a uložte.
3. Očekávání:
   • Job SyncDayOfWeek se dispatchne na frontu.
   • Po zpracování jobu mají všechny budoucí eventy (bez manually_changed_at) start_time přesunutý na pátek téhož týdne.
   • Eventy, jejichž páteční datum by padlo do minulosti, se nepřesunou (zůstanou na středu nebo jsou přeskočeny).

1.2 Ručně upravený event je přeskočen

1. Na jednom z budoucích eventů šablony změňte datum/čas přímo v detailu eventu.
2. Změňte den v týdnu šablony.
3. Očekávání: event, který byl ručně upraven, zůstane na původním datu. Ostatní eventy se přesunou.

---

2 · Synchronizace času konání

2.1 Změna času – budoucí eventy se aktualizují

1. Šablona s časem konání 19:00. Budoucí eventy mají start_time s hodinou 19.
2. Změňte čas na 20:00 a uložte.
3. Očekávání:
   • Job SyncTimes se dispatchne.
   • Po zpracování mají všechny budoucí eventy (bez manually_changed_at) start_time s hodinou 20.
   • Datum eventů zůstane nezměněné.

2.2 Ručně upravený event je přeskočen

1. Ručně upravte čas jednoho eventu v detailu (vyplní se manually_changed_at).
2. Změňte čas šablony.
3. Očekávání: ručně upravený event zachová svůj čas. Ostatní se aktualizují.

---

3 · Synchronizace frekvence

3.1 Zvýšení frekvence (méně časté → více časté)

1. Šablona s frekvencí biweekly (sudé nebo liché týdny).
2. Změňte na weekly.
3. Očekávání:
   • Job SyncFrequency se dispatchne.
   • Scheduler dogeneruje chybějící eventy (týdny bez eventu) do 4 týdnů dopředu.

3.2 Snížení frekvence (více časté → méně časté)

1. Šablona s frekvencí weekly.
2. Změňte na biweekly (sudé týdny).
3. Očekávání:
   • Eventy v lichých týdnech se zruší (status = canceled, soft-deleted).
   • Scheduler dogeneruje chybějící sudé-týdnové eventy do 4 týdnů dopředu.

3.3 Přepnutí sudé ↔ liché týdny

1. Šablona na lichý týden.
2. Změňte na sudý týden.
3. Očekávání: všechny budoucí eventy se zruší a scheduler vygeneruje nové na sudé týdny.

3.4 Frekvence na monthly

1. Šablona s weekly, změňte na monthly (3. středa v měsíci, day_order = 3).
2. Očekávání: eventy, které nejsou 3. středou svého měsíce, se zruší. Chybějící eventy se dogenerují.

---

4 · Notifikace moderátorům (PostUpdateBrief)

4.1 E-mail po změně šablony

1. Změňte čas, den nebo frekvenci šablony.
2. Po zpracování jobu PostUpdateBrief otevřete Mailhog.
3. Očekávání:
   • Moderátoři šablony obdrželi e-mail s předmětem Aktualizace doby konání předpisu {název}.
   • E-mail obsahuje: původní a novou dobu konání, seznam dotčených eventů se stavem.

4.2 Slack zpráva po změně šablony

1. Stejný postup jako 4.1.
2. Očekávání:
   • Slack kanál obdržel zprávu s nadpisem 📝 Aktualizace doby konání předpisu {název}.
   • Zpráva obsahuje sekce: původní doba konání (pokud dostupná), nová doba konání, seznam eventů.
   • V zápatí zprávy je upozornění: Automaticky neměníme události, které byly změněny ručně.

4.3 Ručně upravené eventy nejsou v notifikaci přeskočeny bez zmínky

1. Šablona má ručně upravený event.
2. Změňte čas šablony.
3. Očekávání: notifikace přijde. Ručně upravený event v ní figuruje s původním stavem (přeskočen při synchronizaci, ale stále zahrnut v přehledu).

---

5 · Scheduler – kontrola duplicit

5.1 Scheduler nevygeneruje event dvakrát ve stejném týdnu

1. Spusťte scheduler (php artisan schedule:run nebo manuálně) dvakrát po sobě ve stejný den.
2. Očekávání: druhý běh nevytvoří žádné nové eventy pro šablony, které již v daném týdnu event mají. Sloupec week se nesmí duplikovat pro stejný blueprint.

5.2 Přesunutý event neblokuje vygenerování nového

1. Přesuňte event na jiný týden (ručně změňte start_time přes admin).
2. Spusťte scheduler.
3. Očekávání: scheduler vygeneruje nový event pro původní týden (ten je nyní volný), protože kontroluje week hodnotu a přesunutý event má nové číslo týdne.

---

6 · Regresní checklist

Po nasazení ověřit, že nic dalšího nepraskne:

• Změna moderátora na šabloně nevyvolá žádný sync job (jen změna dne, času nebo frekvence má joby).
• Změna stavu šablony (active → on_hold) změní stav na všech budoucích eventech bez dispatchování sync jobů.
• Šablona s manually_changed_at eventy na více budoucích eventech – ověřit, že jsou všechny přeskočeny, ne jen první.
• Scheduler generující 8 týdnů dopředu nevygeneruje duplicitní eventy při opakovaném spuštění.
• Po změně frekvence a jejím opětovném navrácení na původní hodnotu (např. weekly → monthly → weekly) jsou eventy konzistentní.

---

7 · Automatizované testy

docker-compose exec fpm php artisan test tests/Feature/SchedulerTest.php --compact

Pokryté scénáře:

• Generování správného počtu eventů pro každou frekvenci (weekly, biweekly, monthly, irregular) a každý QuizzMode
• Respektování start_date a end_date šablony
• Kontrola duplicit – scheduler nezdvojí event v rámci stejného týdne
• Respektování stavu šablony (active, on_hold, canceled, completed)
• Generování pro každý den v týdnu
• Přesunutý event neblokuje vygenerování nového