# Automatiseerimine

# Avalduste automatiseerimine

Jaotis **Kursused → Seaded → Automatiseerimine** võimaldab automatiseerida kolme põhiprotsessi avaldustega töötamisel:

1. **Automaatsaatmine** — avalduste automaatne saatmine allkirjastamiseks
2. **Meeldetuletused** — meeldetuletuste saatmine allkirjastamata avalduste kohta (e-post või SMS)
3. **Automaatne tühistamine** — avalduste automaatne tühistamine, mida ei allkirjastatud tähtajaks

> **Märkus:** Automatiseerimine töötab iga organisatsiooni jaoks eraldi. Ühe organisatsiooni seaded ei mõjuta teisi.

---

## Kuidas avada automatiseerimise seaded

1. Minge külgmenüüs **Kursused → Seaded**.
2. Valige navigatsioonipaneelis vaheleht **Automatiseerimine**.

> **Juurdepääsuõigus:** Vaatamiseks on vajalik õigus `course.setting.view`, muutmiseks — `course.setting.edit`.

---

## Automaatsaatmine

Automaatsaatmine saadab avalduse maksjale automaatselt allkirjastamiseks pärast seadistatavat viivitust.

### Kuidas see töötab

Kui õpilane (või administraator) loob avalduse kursusele, saab see staatuse **Loodud**. Ilma automatiseerimiseta peab administraator iga avalduse puhul käsitsi vajutama „Saada". Automaatsaatmine teeb seda automaatselt.

**Protsess:**
1. Avaldus luuakse → staatus **Loodud**
2. Möödub määratud arv päevi
3. Süsteem automaatselt:
   - Genereerib avalduse PDF-dokumendi (kursuse malli järgi)
   - Muudab staatuse **Saadetud**
   - Saadab maksjale teavituse (kursuse teavitusmalli järgi)

### Seadistamine

1. Lülitage lüliti **„Automaatsaatmine sisse lülitatud"** sisse.
2. Märkige **viivitus päevades** — mitu päeva oodata pärast avalduse loomist enne automaatset saatmist.
3. Vajutage **Salvesta**.

| Viivituse väärtus | Käitumine |
|:-----------------:|-----------|
| **0** | Avaldus saadetakse järgmisel töötlemisel (tunni jooksul pärast loomist) |
| **1** | Saatmine 1 päev pärast loomist |
| **3** | Saatmine 3 päeva pärast loomist |

> **Tähtis:** Automaatsaatmise korrektseks toimimiseks peab kursusel olema seadistatud **avalduse mall** (vaheleht „Mall" kursuse lehel). Kui mall puudub, jäetakse selle kursuse automaatsaatmine logi kirjega vahele.

### Millal automaatsaatmine EI toimi

- Avaldusel on juba teine staatus (mitte „Loodud") — näiteks administraator saatis selle varem käsitsi
- Kursusel pole seadistatud avalduse malli
- Toimus PDF-i genereerimise viga (kirjutatakse logi)

---

## Meeldetuletused

Meeldetuletused võimaldavad automaatselt teavitada maksjaid avaldustest, mis on saadetud allkirjastamiseks, kuid mida pole veel allkirjastatud. Saab seadistada mitu reeglit erinevate viivituste ja kohaletoimetamiskanalitega.

### Kuidas see töötab

1. Avaldus saadetud → staatus **Saadetud**
2. Möödub määratud arv päevi (saatmiskuupäevast)
3. Süsteem saadab meeldetuletuse valitud kanali kaudu (e-post või SMS)
4. Iga konkreetne meeldetuletus saadetakse iga avalduse puhul **üks kord**

### Näitestsenaarium

Seadistasite kolm meeldetuletust:

| Meeldetuletus | Päeva pärast saatmist | Kanal |
|:-------------:|:---------------------:|:-----:|
| 1 | 3 | E-post |
| 2 | 7 | E-post |
| 3 | 10 | SMS |

**Mis juhtub:**
- **Päev 3:** Maksja saab e-posti meeldetuletuse
- **Päev 7:** Teine e-posti meeldetuletus
- **Päev 10:** SMS-meeldetuletus
- Kui maksja allkirjastas avalduse **päeval 5** — teist ja kolmandat meeldetuletust EI saadeta (staatus muutus)

### Meeldetuletuse seadistamine

1. Vajutage nuppu **„Lisa meeldetuletus"**.
2. Täitke väljad:

| Väli | Kirjeldus |
|------|-----------|
| **Päeva pärast saatmist** | Mitu päeva pärast avalduse saatmist meeldetuletus töötab (vähemalt 1) |
| **Kanal** | Kohaletoimetamisviis: **E-post** või **SMS** |
| **Teema** (ainult e-post) | Kirja teema igas süsteemi keeles (eesti, vene) |
| **Sisu** | Meeldetuletuse tekst igas keeles. Toetab muutujaid `[[KEY]]` |

3. Vajutage **Salvesta**.

### Meeldetuletuse kustutamine

- Vajutage meeldetuletuse kõrval nuppu **„Kustuta"**.
- Meeldetuletus desaktiveeritakse. Juba saadetud meeldetuletusi tagasi ei kutsuta.

### Mallide muutujad

Meeldetuletuse tekstis (ja e-posti teemas) saab kasutada muutujaid topelt nurksulgudes. Saatmisel asendatakse need automaatselt tegelike andmetega.

| Muutuja | Kirjeldus | Näide |
|---------|-----------|:-----:|
| `[[STUDENT_FIRST_NAME]]` | Õpilase eesnimi | Maria |
| `[[STUDENT_LAST_NAME]]` | Õpilase perekonnanimi | Ivanova |
| `[[PARENT_FIRST_NAME]]` | Maksja eesnimi | Ivan |
| `[[PARENT_LAST_NAME]]` | Maksja perekonnanimi | Ivanov |
| `[[COURSE_NAME]]` | Kursuse nimi | Matemaatika — rühm A |
| `[[APPLICATION_DATE]]` | Avalduse loomise kuupäev | 15.03.2026 |
| `[[CANCELLATION_DATE]]` | Automaatse tühistamise kuupäev | 29.03.2026 |

> **Tõstutundlikkust pole:** `[[STUDENT_FIRST_NAME]]` ja `[[student_first_name]]` töötavad ühtemoodi.

> **CANCELLATION_DATE:** Arvutatakse kui saatmiskuupäev + päevad automaatse tühistamiseni. Kui automaatne tühistamine on välja lülitatud — on tühi string.

### Meeldetuletuse teksti näide

**Eesti keeles:**
```
Lugupeetud [[PARENT_FIRST_NAME]] [[PARENT_LAST_NAME]],

tuletame meelde, et õpilase [[STUDENT_FIRST_NAME]] [[STUDENT_LAST_NAME]]
avaldus kursusele [[COURSE_NAME]] ootab allkirjastamist.

Avaldus loodi [[APPLICATION_DATE]].
Palun allkirjastage enne [[CANCELLATION_DATE]], vastasel juhul avaldus tühistatakse.
```

### Kanalite eripärad

#### E-post
- Saaja: maksja e-post (Party profiilist või Payer kirjest)
- Kui e-post puudub — meeldetuletus jäetakse vahele
- Teema on iga keele jaoks kohustuslik

#### SMS
- Saaja: maksja telefon → kui puudub, õpilase telefon
- Kui telefon puudub — meeldetuletus jäetakse vahele
- **Tähemärgi piirang:**
  - Ladina tähestik: 160 tähemärki = 1 SMS
  - Kirillitsa: 70 tähemärki = 1 SMS
  - Limiidi ületamisel jagatakse sõnum mitmeks SMS-iks
- Tähemärgi loendur kuvatakse tekstivälja all reaalajas
- Teemat SMS-is ei kasutata

### Meeldetuletuse keel

Teksti keel määratakse maksja `lang` välja järgi. Kui keel pole määratud — kasutatakse süsteemi vaikekeelt. Seetõttu on oluline täita meeldetuletuse tekst **kõigis saadaolevates keeltes**.

---

## Automaatne tühistamine

Automaatne tühistamine tühistab automaatselt avaldused, mis on saadetud allkirjastamiseks, kuid mida pole määratud aja jooksul allkirjastatud.

### Kuidas see töötab

1. Avaldus staatuses **Saadetud**
2. Möödub määratud arv päevi (saatmiskuupäevast)
3. Süsteem automaatselt:
   - Muudab staatuse **Tühistatud**
   - Saadab maksjale teavituse **standardse tühistamismalli** järgi (kursuse seadetest)

### Seadistamine

1. Lülitage lüliti **„Automaatne tühistamine sisse lülitatud"** sisse.
2. Märkige **päevade arv pärast saatmist** — mitu päeva pärast avalduse saatmist see tühistatakse (vähemalt 1).
3. Vajutage **Salvesta**.

| Väärtus | Käitumine |
|:-------:|-----------|
| **7** | Tühistamine 7 päeva pärast saatmist |
| **14** | Tühistamine 14 päeva pärast (vaikimisi) |
| **30** | Tühistamine 30 päeva pärast |

> **Tähtis:** Tühistamise teavitus saadetakse **standardse tühistamismalli** järgi, mis on seadistatud **Kursused → [Kursus] → vaheleht „Mall"** (mall staatuse „Tühistatud" jaoks). Meeldetuletuste teksti EI kasutata.

### Koostoime meeldetuletustega

Automaatne tühistamine ja meeldetuletused töötavad sõltumatult. Soovitatud seadistus — meeldetuletused peaksid olema **enne** tühistamist:

| Toiming | Päeva pärast saatmist |
|---------|:---------------------:|
| 1. meeldetuletus (e-post) | 3 |
| 2. meeldetuletus (e-post) | 7 |
| 3. meeldetuletus (SMS) | 10 |
| Automaatne tühistamine | 14 |

Nii saab maksja kolm meeldetuletust enne avalduse tühistamist.

---

## Töötlemise ajakava

Automatiseerimist töödeldakse **iga tund**. See tähendab:

- Pärast avalduse loomist võib mööduda kuni 1 tund enne automaatset saatmist (viivitusega 0 päeva)
- Meeldetuletusi ja tühistamist kontrollitakse igatunniselt
- Kõik toimingud sooritatakse **üks kord** — korduv töötlemine ei loo duplikaate

> **Tehniline detail:** Käsk `automation:process-applications` käivitatakse iga tund kaitsega paralleelse käivituse eest (withoutOverlapping). Töötlemise aeg sõltub organisatsioonide ja avalduste arvust.

---

## Logid ja seire

Kõik automatiseerimise toimingud salvestatakse kohta **Seaded → Logid**. Saate jälgida:

- **Edukad saatmised:** kirje tüübiga `AUTOMATION_AUTO_SEND`
- **Saadetud meeldetuletused:** kirje tüübiga `AUTOMATION_REMINDER`
- **Tühistamised:** kirje tüübiga `AUTOMATION_AUTO_CANCEL`
- **Vead:** kirje tüübiga `AUTOMATION_FAILED` — sisaldab vea kirjeldust

Probleemide korral (näiteks meeldetuletusi ei saadeta) kontrollige logisid `AUTOMATION_FAILED` kirjete olemasolu suhtes.

### Tüüpilised vigade põhjused

| Viga | Põhjus | Lahendus |
|------|--------|----------|
| `template missing` | Kursusel pole seadistatud avalduse malli | Minge Kursused → [Kursus] → Mall ja valige mall |
| `PDF generation failed` | Dokumendi genereerimise viga | Kontrollige malli (.docx) õigsust |
| `payer notification failed` | E-posti saatmise viga | Kontrollige maksja e-posti ja postiserveri seadeid |
| `not found or status changed` | Avaldus töödeldi käsitsi enne automatiseerimise töötamist | Normaalne olukord, tegevusi ei nõua |

---

## Seadistamise soovitused

### Põhiseadistus

Enamiku organisatsioonide jaoks on soovitatav:

1. **Automaatsaatmine:** sisse lülitatud, viivitus **0 päeva** (kohene saatmine)
2. **1. meeldetuletus:** e-post **3 päeva** pärast saatmist
3. **2. meeldetuletus:** e-post **7 päeva** pärast saatmist
4. **3. meeldetuletus:** SMS **12 päeva** pärast saatmist
5. **Automaatne tühistamine:** sisse lülitatud, **14 päeva** pärast saatmist

### Viivitusega kontrolliks

Kui administraator soovib avaldusi enne saatmist kontrollida:

1. **Automaatsaatmine:** sisse lülitatud, viivitus **1 päev** (annab aega kontrollimiseks)
2. **Meeldetuletused ja tühistamine:** nagu põhiseadistuses

### Ainult meeldetuletused (ilma automaatsaatmiseta)

Kui saatmine peab jääma käsitsi tehtavaks:

1. **Automaatsaatmine:** välja lülitatud
2. **Meeldetuletused:** seadistatud (töötavad käsitsi saadetud avalduste jaoks)
3. **Automaatne tühistamine:** soovi korral

---

## Korduma kippuvad küsimused

### Mis juhtub, kui ma lülitan sisse automaatsaatmise — kas ka vanad avaldused saadetakse?

Jah. Järgmisel töötlemise käivitamisel saadetakse kõik „Loodud" staatuses avaldused, mille vanus ületab viivituse. Kui te ei soovi vanu avaldusi saata — töödelge need kõigepealt käsitsi.

### Kas meeldetuletust saab saata korraga nii e-posti kui ka SMS-i teel?

Jah. Looge kaks meeldetuletuse reeglit sama viivitusega, kuid erinevate kanalitega.

### Mis juhtub, kui maksja allkirjastab avalduse meeldetuletuste vahel?

Meeldetuletust ei saadeta, kuna avalduse staatus muutub „Saadetud"-st „Allkirjastatud"-uks. Süsteem kontrollib staatust iga käivitamise ajal.

### Kas konkreetse avalduse automaatset tühistamist saab tühistada?

Spetsiaalset mehhanismi tühistamiseks pole. Kuid kui administraator muudab avalduse staatust käsitsi (näiteks sulgeb selle) enne tühistamise töötamist — automaatset tühistamist ei toimu.

### Kui sageli automatiseerimist kontrollitakse?

Iga tund. Täpne aeg sõltub Laraveli ajakava seadistusest.

### Muutuja [[CANCELLATION_DATE]] näitab tühja väärtust — miks?

Veenduge, et **automaatne tühistamine on sisse lülitatud** ja on määratud päevade arv. Tühistamise kuupäev arvutatakse kui: saatmiskuupäev + päevad tühistamiseni. Kui automaatne tühistamine on välja lülitatud, on muutuja tühi.

### Kas seadete muutmine mõjutab juba saadetud meeldetuletusi?

Ei. Juba saadetud meeldetuletusi ja tehtud tühistamisi tagasi ei kutsuta. Muudatused mõjutavad ainult tulevasi toiminguid.