diff --git a/web/content/posts/api/lib/index.md b/web/content/posts/api/lib/index.md index 90d4d71..08c4c06 100644 --- a/web/content/posts/api/lib/index.md +++ b/web/content/posts/api/lib/index.md @@ -1,6 +1,6 @@ --- title: "Oficiální knihovna" -date: 2025-12-20 +date: 2026-02-11 tags: ["api", "docs"] hiddenInHomelist: true TocOpen: true diff --git a/web/content/posts/api/usage/index.md b/web/content/posts/api/usage/index.md index 19e512b..163dc4b 100644 --- a/web/content/posts/api/usage/index.md +++ b/web/content/posts/api/usage/index.md @@ -30,16 +30,22 @@ Ačkoliv v současnosti vrací stejná data jako `/versioned/v1`, jeho podpora m API je verzované, aby byla zajištěna zpětná kompatibilita. Zde je seznam dostupných verzí: +- ### [Verze 3 (v2)](../v3) + **Status:** Stabilní + **Endpoint:** `/versioned/v3` + + Toto je aktuální a doporučená verze API. Obsahuje velké změny oproti V2 a obsahuje nové data. + - ### [Verze 2 (v2)](../v2) **Status:** Stabilní **Endpoint:** `/versioned/v2` - - Toto je aktuální a doporučená verze API. Klikněte na odkaz pro zobrazení kompletní dokumentace pro v2. -- ### [Verze 1 (v1)](../v1) - **Status:** Stabilní +- ### [~Verze 1 (v1)~](../v1) + **Status:** Deprecated **Endpoint:** `/versioned/v1` + Verze 1 bude v budoucnu odstaněna. Migrujte na novější verze + --- ## Nezařazené Endpointy diff --git a/web/content/posts/api/v1/index.md b/web/content/posts/api/v1/index.md index 262b9e2..75f5da8 100644 --- a/web/content/posts/api/v1/index.md +++ b/web/content/posts/api/v1/index.md @@ -5,6 +5,10 @@ tags: ["api", "docs", "v1"] hiddenInHomelist: true --- +{{< admonition type="warning" title="Deprecated" >}} +Tato verze je **deprecated**. Prosím nepoužívejte ji, bude brzy odstraněna. +{{< /admonition >}} + Tato stránka detailně popisuje **Verzi 1 (v1)** API Ječná Rozvrh. ## Endpoint: `GET /versioned/v1` @@ -39,7 +43,7 @@ Tato sekce je pole, kde každý prvek představuje jeden den. Každý den je obj - **Klíč:** Název třídy (např. `"A1"`) - **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin. - `string`: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně. - - `null`: Pokud hodina odpadá nebo pro ni není záznam. + - `null`: Pokud pro ni není záznam. - Text `(bude upřesněno)` může být připojen k předmětu, pokud je změna nejistá.
diff --git a/web/content/posts/api/v2/index.md b/web/content/posts/api/v2/index.md index f52ed9f..1415959 100644 --- a/web/content/posts/api/v2/index.md +++ b/web/content/posts/api/v2/index.md @@ -39,7 +39,7 @@ Tato sekce je pole, kde každý prvek představuje jeden den. Každý den je obj - **Klíč:** Název třídy (např. `"A1"`) - **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin. - `string`: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně. - - `null`: Pokud hodina odpadá nebo pro ni není záznam. + - `null`: Pokud pro ni není záznam. - Text `(bude upřesněno)` může být připojen k předmětu, pokud je změna nejistá.
diff --git a/web/content/posts/api/v3/index.md b/web/content/posts/api/v3/index.md new file mode 100644 index 0000000..9d75f4f --- /dev/null +++ b/web/content/posts/api/v3/index.md @@ -0,0 +1,193 @@ +--- +title: "API Dokumentace - Verze 2" +date: 2026-01-28 +tags: ["api", "docs", "v2"] +hiddenInHomelist: true +--- + +Tato stránka detailně popisuje **Verzi 2 (v2)** API Ječná Rozvrh. + +## Endpoint: `GET /versioned/v3` + +Toto je hlavní endpoint, který poskytuje veškerá data o rozvrhu pro v2. + +### Struktura Odpovědi + +Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `status`. + +
+Zobrazit příklad struktury odpovědi + +```json +{ + "schedule": { /* objekt denních rozvrhů */ }, + "status": { /* objekt stavu */ } +} +``` +
+ +--- + +### Datové Struktury + +#### Sekce: `schedule` + +Tato sekce je objekt, kde každý klíč představuje datum ve formátu `YYYY-MM-DD` a prvek představuje jeden den. Každý den je objekt, jehož klíče jsou `info`, `changes`, `absence`, `takesPlace` a `reservedRooms` + +##### `changes` +- Objekt +- **Klíč:** Název třídy (např. `"A1"`) +- **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin. + - Objekt: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně. + - `null`: Pokud pro ni není záznam. + +Hodnota je následující objekt + +```ts +{ + text: string, + backgroundColor?: string, + foregroundColor?: string, + willBeSpecified?: boolean +} +``` + +
+Zobrazit příklad rozvrhu pro třídu A1 + +```json +"A1": [ + { + "text": "M 5 Kp(Ng)" + }, + null, + null, + { + "text": "M 5 odpadá", + "backgroundColor": "#DCEDD5", + "foregroundColor": "#FF000000" + }, + null, + null, + null, + null, + null, + null +] +``` +
+ +##### `absence` +- Pole objektů, kde každý objekt specifikuje jednu absenci. Struktura objektu je následující: + - `teacher` (string | null): Celé jméno učitele, pokud je známé. + - `teacherCode` (string | null): Zkratka jména učitele (např. "me", "ad"). + - `type` (string): Typ absence. Může nabývat následujících hodnot: + - `"wholeDay"`: Učitel chybí celý den. + - `"single"`: Učitel chybí jednu vyučovací hodinu. + - `"range"`: Učitel chybí v rozmezí několika hodin. + - `"exkurze"`: Učitel je na exkurzi. + - `"invalid"`: Záznam o absenci se nepodařilo zpracovat. + - `hours` (object | number | null): Specifikuje hodiny absence. + - `null`: Pro typy `wholeDay`, `exkurze`, a `invalid`. + - `number` (např. `3`): Pro typ `single`. + - `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range`. + - `original` (string | null): Pouze pro typ `invalid`, obsahuje původní nezpracovaný text. + +
+Zobrazit příklady absencí + +**Celý den:** +```json +{ + "teacher": "Jan Novák", + "teacherCode": "no", + "type": "wholeDay", + "hours": null +} +``` + +**Jedna hodina:** +```json +{ + "teacher": "Jan Novák", + "teacherCode": "no", + "type": "single", + "hours": 1 +} +``` + +**Rozsah hodin:** +```json +{ + "teacher": "Jan Novák", + "teacherCode": "no", + "type": "range", + "hours": { "from": 2, "to": 4 } +} +``` + +**Exkurze:** +```json +{ + "teacher": "Jan Novák", + "teacherCode": "no", + "type": "exkurze", + "hours": null +} +``` + +**Zastupuje:** +```json +{ + "teacher": "Ing. Zdeněk Vondra", + "teacherCode": "vn", + "type": "zastoupen", + "hours": null, + "zastupuje": { + "teacher": "David Janoušek", + "teacherCode": "jk", + }, +}, +``` + +**Neplatný záznam:** +```json +{ + "type": "invalid", + "teacher": null, + "teacherCode": null, + "hours": null, + "original": "Nezpracovatelný text" +} +``` +
+ +##### `takesPlace` + +String obsahující aktuálně probíhající akce ten den. + +#### `reservedRooms` + +Pole 10 prvků (string | null) pro jakou hodinu jsou rezervované jaké místnosti. + +#### `info.inWork` + +Boolean jestli je daná tabulka in work (příprava). + +#### Sekce: `status` - Stav a Metadata + +Objekt poskytující informace o aktuálnosti dat. + +- `lastUpdated` (string): Čas poslední úspěšné aktualizace dat ve formátu `HH:MM`. +- `currentUpdateSchedule` (number): Interval v **minutách**, ve kterém scraper interně kontroluje a stahuje novou verzi rozvrhu. Tento interval se dynamicky mění v závislosti na denní době (kratší během vyučování, delší v noci). + +
+Zobrazit příklad status + +```json +"status": { + "lastUpdated": "08:30", + "currentUpdateSchedule": 5 +} +``` +
diff --git a/web/content/posts/self-hosting/index.md b/web/content/posts/self-hosting/index.md index 5fb2d32..ac929e7 100644 --- a/web/content/posts/self-hosting/index.md +++ b/web/content/posts/self-hosting/index.md @@ -10,7 +10,7 @@ Tento projekt je možné hostovat vlastním způsobem, ať už pomocí Dockeru n Před začátkem se ujistěte, že máte připravené následující: -- **Účet SPŠ Ječná**: Projekt vyžaduje platný školní e-mail a heslo pro přístup k tabulce na SharePointu. +- **Účet SPŠE Ječná**: Projekt vyžaduje platný školní e-mail a heslo pro přístup k tabulce na SharePointu. - **Node.js 22+**: Pokud hostujete nativně. - **Hugo**: Pro sestavení a provoz webového rozhraní. - **Chromium/Puppeteer**: Pro automatizované stahování dat. diff --git a/web/layouts/shortcodes/admonition.html b/web/layouts/shortcodes/admonition.html new file mode 100644 index 0000000..963c29e --- /dev/null +++ b/web/layouts/shortcodes/admonition.html @@ -0,0 +1,78 @@ +{{ $type := .Get "type" | default "note" }} +{{ $title := .Get "title" | default (print (title $type)) }} + +
+
+ {{ $title }} +
+ +
+ {{ .Inner | markdownify }} +
+
+ +