Compare commits
2 Commits
af4eb5bb88
...
5ac84e3690
| Author | SHA1 | Date | |
|---|---|---|---|
5ac84e3690
|
|||
|
c37a114a78
|
210
web/content/posts/api/lib/index.md
Normal file
210
web/content/posts/api/lib/index.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
title: "Oficiální knihovna"
|
||||
date: 2026-02-11
|
||||
tags: ["api", "docs"]
|
||||
hiddenInHomelist: true
|
||||
TocOpen: true
|
||||
---
|
||||
|
||||
Ječná Rozvrh API má svoji Rust knihovnu pro komunikaci s API. Obsahuje mappings pro Kotlin. Pro další jazyky budou mappingy v budoucnu.
|
||||
|
||||
## Usage
|
||||
|
||||
### `JecnaSuplClient` struct
|
||||
|
||||
Knihovna používá `JecnaSuplClient` struct. Vytvoříte instanci pomocí `new`.
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
let client = JecnaSuplClient::new();
|
||||
}
|
||||
```
|
||||
|
||||
### `set_provider(url: String)`
|
||||
|
||||
Pokud nenastavíte vlastní provider path API použije hosted `https://jecnarozvrh.jzitnik.dev`
|
||||
|
||||
Example usage:
|
||||
|
||||
```rust
|
||||
client.set_provider("https://jecnarozvrh.example.com");
|
||||
```
|
||||
|
||||
### `get_schedule(class_name: String) -> Result<SuplResult, SuplError>`
|
||||
|
||||
Example usage:
|
||||
|
||||
```rust
|
||||
let class = String::from("C2c");
|
||||
match client.get_schedule(class) {
|
||||
Ok(result) => {
|
||||
println!("Last update: {}", result.status.last_updated);
|
||||
}
|
||||
Err(error) => {
|
||||
panic!("Error: {}", error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `get_teacher_absence() -> Result<TeacherAbsenceResult, SuplError>`
|
||||
|
||||
Example usage:
|
||||
|
||||
```rust
|
||||
match client.get_teacher_absence() {
|
||||
Ok(result) => {
|
||||
/* Code */
|
||||
}
|
||||
Err(error) => {
|
||||
panic!("Error: {}", error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `get_all() -> Result<ApiResponse, SuplError>`
|
||||
|
||||
Example usage:
|
||||
|
||||
```rust
|
||||
match client.get_all() {
|
||||
Ok(result) => {
|
||||
/* Code */
|
||||
}
|
||||
Err(error) => {
|
||||
panic!("Error: {}", error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `report(content: String, class: String, report_location: ReportLocation) -> Result<(), SuplError>`
|
||||
|
||||
Report function for reporting errors of the parser to the provider.
|
||||
|
||||
Example usage:
|
||||
|
||||
```rust
|
||||
let content = String::from("Detailni popis chyby");
|
||||
let class = String::from("C2c");
|
||||
let report_location = ReportLocation::Timetable;
|
||||
|
||||
match client.report(content, class, report_location) {
|
||||
Ok(result) => {
|
||||
println!("Success");
|
||||
}
|
||||
Err(error) => {
|
||||
panic!("Error: {}", error)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Datové struktury
|
||||
|
||||
```rust
|
||||
#[derive(Debug, thiserror::Error, uniffi::Error)]
|
||||
pub enum SuplError {
|
||||
#[error("Network error: {reason}")]
|
||||
NetworkError { reason: String },
|
||||
#[error("Parse error: {reason}")]
|
||||
ParseError { reason: String },
|
||||
#[error("Invalid date format: {reason}")]
|
||||
DateFormatError { reason: String },
|
||||
#[error("Internal runtime error: {reason}")]
|
||||
RuntimeError { reason: String },
|
||||
}
|
||||
|
||||
pub enum AbsenceEntry {
|
||||
WholeDay {
|
||||
teacher: Option<String>,
|
||||
teacher_code: String,
|
||||
},
|
||||
Single {
|
||||
teacher: Option<String>,
|
||||
teacher_code: String,
|
||||
hours: u16,
|
||||
},
|
||||
Range {
|
||||
teacher: Option<String>,
|
||||
teacher_code: String,
|
||||
hours: AbsenceRange,
|
||||
},
|
||||
Exkurze {
|
||||
teacher: Option<String>,
|
||||
teacher_code: String,
|
||||
},
|
||||
Zastoupen {
|
||||
teacher: Option<String>,
|
||||
teacher_code: String,
|
||||
zastupuje: SubstituteInfo,
|
||||
},
|
||||
Invalid { original: String },
|
||||
}
|
||||
|
||||
pub struct AbsenceRange {
|
||||
pub from: u16,
|
||||
pub to: u16,
|
||||
}
|
||||
|
||||
pub struct SubstituteInfo {
|
||||
pub teacher: Option<String>,
|
||||
pub teacher_code: String,
|
||||
}
|
||||
|
||||
pub struct ChangeEntry {
|
||||
pub text: String,
|
||||
pub background_color: Option<String>,
|
||||
pub foreground_color: Option<String>,
|
||||
pub will_be_specified: Option<bool>,
|
||||
}
|
||||
|
||||
pub struct ApiResponse {
|
||||
pub status: Status,
|
||||
pub schedule: HashMap<String, DailyData>,
|
||||
}
|
||||
|
||||
pub struct DailyData {
|
||||
pub info: DayInfo,
|
||||
pub changes: HashMap<String, Vec<Option<ChangeEntry>>>,
|
||||
pub absence: Vec<AbsenceEntry>,
|
||||
pub takes_place: String,
|
||||
pub reserved_rooms: Vec<Option<String>>,
|
||||
}
|
||||
|
||||
pub struct DayInfo {
|
||||
pub in_work: bool,
|
||||
}
|
||||
|
||||
pub struct Status {
|
||||
pub last_updated: String,
|
||||
pub current_update_schedule: u16,
|
||||
}
|
||||
|
||||
pub struct SuplResult {
|
||||
pub status: Status,
|
||||
pub schedule: HashMap<String, DailySchedule>,
|
||||
}
|
||||
|
||||
pub struct DailySchedule {
|
||||
pub info: DayInfo,
|
||||
pub changes: Vec<Option<ChangeEntry>>,
|
||||
pub absence: Vec<AbsenceEntry>,
|
||||
pub takes_place: String,
|
||||
}
|
||||
|
||||
pub struct TeacherAbsenceResult {
|
||||
pub absences: HashMap<String, Vec<AbsenceEntry>>,
|
||||
}
|
||||
```
|
||||
|
||||
## Mappings do jiných jazyků
|
||||
|
||||
### Kotlin
|
||||
|
||||
- [Mappings (required)](https://mvnrepository.com/artifact/cz.jzitnik/jecna-supl-client)
|
||||
|
||||
Jednotlivé buildy:
|
||||
|
||||
- [Android](https://mvnrepository.com/artifact/cz.jzitnik/jecna-supl-client-android)
|
||||
- [Linux X64](https://mvnrepository.com/artifact/cz.jzitnik/jecna-supl-client-linux-x64)
|
||||
- [Windows X64](https://mvnrepository.com/artifact/cz.jzitnik/jecna-supl-client-windows-x64)
|
||||
|
||||
Všechny funkce jsou mappovány do `camelCase`. **Nejedná se o suspend funkce!**
|
||||
@@ -6,6 +6,10 @@ tags: ["api", "docs"]
|
||||
|
||||
Vítejte v dokumentaci pro API systému Ječná Rozvrh. Toto API poskytuje programový přístup k rozvrhům, suplování a dalším informacím.
|
||||
|
||||
## Oficiální knihovna
|
||||
|
||||
[Oficiální knihovna pro komunikaci s Ječná Rozvrh API](../lib)
|
||||
|
||||
## Základní Informace
|
||||
|
||||
### URL
|
||||
@@ -26,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
|
||||
|
||||
@@ -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á.
|
||||
|
||||
<details>
|
||||
|
||||
@@ -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á.
|
||||
|
||||
<details>
|
||||
|
||||
193
web/content/posts/api/v3/index.md
Normal file
193
web/content/posts/api/v3/index.md
Normal file
@@ -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`.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad struktury odpovědi</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule": { /* objekt denních rozvrhů */ },
|
||||
"status": { /* objekt stavu */ }
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
}
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad rozvrhu pro třídu A1</summary>
|
||||
|
||||
```json
|
||||
"A1": [
|
||||
{
|
||||
"text": "M 5 Kp(Ng)"
|
||||
},
|
||||
null,
|
||||
null,
|
||||
{
|
||||
"text": "M 5 odpadá",
|
||||
"backgroundColor": "#DCEDD5",
|
||||
"foregroundColor": "#FF000000"
|
||||
},
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null
|
||||
]
|
||||
```
|
||||
</details>
|
||||
|
||||
##### `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.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklady absencí</summary>
|
||||
|
||||
**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"
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
##### `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).
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad status</summary>
|
||||
|
||||
```json
|
||||
"status": {
|
||||
"lastUpdated": "08:30",
|
||||
"currentUpdateSchedule": 5
|
||||
}
|
||||
```
|
||||
</details>
|
||||
@@ -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.
|
||||
|
||||
78
web/layouts/shortcodes/admonition.html
Normal file
78
web/layouts/shortcodes/admonition.html
Normal file
@@ -0,0 +1,78 @@
|
||||
{{ $type := .Get "type" | default "note" }}
|
||||
{{ $title := .Get "title" | default (print (title $type)) }}
|
||||
|
||||
<div class="alert alert-{{ $type }}">
|
||||
<div class="alert-title">
|
||||
{{ $title }}
|
||||
</div>
|
||||
|
||||
<div class="alert-content">
|
||||
{{ .Inner | markdownify }}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<style>
|
||||
.alert {
|
||||
margin: 1.5rem 0;
|
||||
padding: 1rem;
|
||||
border-left: 4px solid;
|
||||
border-radius: 0.5rem;
|
||||
background-color: #2e2e33;
|
||||
color: #ebebeb;
|
||||
}
|
||||
|
||||
/* Title */
|
||||
.alert-title {
|
||||
font-weight: 600;
|
||||
margin-bottom: 0.5rem;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
font-size: 2rem;
|
||||
}
|
||||
|
||||
.alert-content {
|
||||
font-size: 1.1rem;
|
||||
line-height: 1.6;
|
||||
max-width: 100%;
|
||||
}
|
||||
|
||||
.alert-content p {
|
||||
margin: 0.5em 0;
|
||||
}
|
||||
|
||||
.alert-content a {
|
||||
color: #7dd3fc;
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.alert-content code {
|
||||
background: #2a2a2a;
|
||||
padding: 0.15em 0.35em;
|
||||
border-radius: 4px;
|
||||
font-size: 0.85em;
|
||||
}
|
||||
|
||||
.alert-content pre {
|
||||
background: #111;
|
||||
padding: 0.75rem;
|
||||
border-radius: 6px;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.alert-note {
|
||||
border-color: #31929A;
|
||||
}
|
||||
|
||||
.alert-warning {
|
||||
border-color: #eab308;
|
||||
}
|
||||
|
||||
.alert-danger {
|
||||
border-color: #ef4444;
|
||||
}
|
||||
|
||||
.alert-success {
|
||||
border-color: #22c55e;
|
||||
}
|
||||
</style>
|
||||
Reference in New Issue
Block a user