musicCalendar/DOCUMENTATION.md

# 🎸 Denní Hudební Doporučení - Komplexní Dokumentace

## 📋 Obsah
- [🎯 Přehled projektu](#-přehled-projektu)
- [🏗️ Architektura projektu](#️-architektura-projektu)
- [📁 Struktura souborů](#-struktura-souborů)
- [🎨 Design a UX](#-design-a-ux)
- [⚙️ Technické detaily](#️-technické-detaily)
- [📊 Datová struktura](#-datová-struktura)
- [🔧 Funkčnost](#-funkčnost)
- [🧪 Testování](#-testování)
- [📦 Nasazení](#-nasazení)
- [🔒 Bezpečnost a GDPR](#-bezpečnost-a-gdpr)
- [📈 Budoucí vylepšení](#-budoucí-vylepšení)
- [🤝 Přispění](#-přispění)
- [📜 License](#-license)

---

## 🎯 Přehled projektu

**Denní Hudební Doporučení** je webová aplikace, která každý den nabízí jedno ikonické album z žánrů grunge a nu-metal. Projekt vznikl jako reakce na algoritmická doporučení hudebních streamovacích služeb, která uživatele uzavírají do bubliny známých skladeb.

### 🎵 Cíl projektu
- Poskytovat každodenní hudební doporučení formou celých alb
- Představit uživatelům méně známá, ale kvalitní alba z éry grunge a nu-metal
- Vytvořit jednoduchou, rychlou a vizuálně atraktivní webovou aplikaci
- Umožnit uživatelům objevovat novou hudbu bez nutnosti složitého vyhledávání

### 🎯 Cílová skupina
- Fanoušci grunge a nu-metal hudby
- Lidé, kteří chtějí objevovat novou hudbu
- Uživatelé, kteří preferují poslech celých alb před jednotlivými skladbami
- Milovníci 90. let a počátku 2000

---

## 🏗️ Architektura projektu

### 🌐 Technologický stack
- **Frontend**: Čistý HTML5, CSS3, JavaScript (ES6+)
- **Design**: Responsive design, CSS animace, temný režim
- **Hosting**: VPS (VPSfree.cz)
- **Analytics**: Vlastní analytický systém (analytics.lukan.cz)
- **Testování**: Playwright

### 🎨 Designové principy
- **Temný metalový vzhled** - inspirován grunge a nu-metal estetikou
- **Animace a efekty** - glitch efekty, pulzující prvky, hover animace
- **Responsive design** - optimalizováno pro mobilní i desktop zařízení
- **Minimalistický přístup** - zaměřeno na obsah, ne na zbytečné prvky

---

## 📁 Struktura souborů

```
musicCalendar/
├── .htaccess                    # HTTPS přesměrování
├── LICENSE                     # MIT License
├── README.md                   # Hlavní readme
├── DOCUMENTATION.md            # Tato dokumentace
├── web/                        # Hlavní webová aplikace
│   ├── index.html              # Hlavní stránka
│   ├── about.html              # Stránka "O projektu"
│   ├── gdpr.html               # GDPR a soukromí
│   ├── script.js               # Hlavní JavaScript logika
│   ├── scriptabout.js          # JavaScript pro about stránku
│   ├── musicData.js            # Databáze alb (4011 řádků)
│   ├── style.css               # Hlavní styly
│   └── img/                    # Obrázky
│       ├── 4525586.jpg         # Pozadí
│       ├── electric-guitar_12494348.png  # Favicon
│       ├── nu-metal-wallpapers.png
│       ├── so0naj17qrh91.jpg
│       └── vyzva-EDIT.jpg       # Logo
└── test/                       # Testovací složka
    ├── README.md
    ├── package.json
    ├── package-lock.json
    ├── playwright.config.ts
    ├── e2e/
    │   └── example.spec.ts
    ├── assets/
    │   └── pages/
    │       └── HomePage.ts      # Page Object Model
    └── tests/
        └── homePage.test.ts     # Testy hlavní stránky
```

---

## 🎨 Design a UX

### 🎭 Vizuální styl

#### Barevná paleta
- **Primární**: Tmavě červená (#8b0000, #cc0000, #ff1111)
- **Sekundární**: Tmavě fialová (#2a0033, #550066)
- **Pozadí**: Tmavě šedá s gradientem (rgba(0,0,0,0.6))
- **Text**: Světle šedá (#e0e0e0, #b0b0b0, #cccccc)
- **Akcenty**: Červená záře, azurové glitch efekty

#### Typografie
- **Font**: Sans-serif (systémový)
- **Hierarchie**:
  - H1: Bílá, glitch animace, 2.5em
  - H2: Světle šedá (#e0e0e0)
  - H3: Středně šedá (#cccccc)
  - P: Světle šedá (#b0b0b0)

### ✨ Animace a efekty

#### Globální efekty
1. **Scanlines overlay** - Jemné horizontální čáry přes celou stránku (starý TV efekt)
2. **Tmavý overlay** - Gradient rgba(0,0,0,0.6) přes pozadí

#### Nadpis (h1)
- **Glitch animace** - Každých 6 vteřin krátký glitch efekt:
  - Červeno-azurový text-shadow
  - SkewX transformace
  - Změna brightness

#### Karta alba (album-card)
- **Vstupní animace**: Pád z vrchu s rotací a blur efektem (0.7s)
- **Pulzující červená záře**: Border a box-shadow dýchají (3s cyklus)
- **Hover efekt**: Karta se zvedne, záře zesílí
- **Obálka alba**: Na hover se přiblíží a zvýší kontrast

#### Archivní kartičky (archiv-item)
- **Staggered fade-up**: Každá karta se vynoří o 60ms později než předchozí
- **Hover efekt**: Červený border, zvýšený shadow, mírné zvednutí

#### Tlačítka
- **Hlavní tlačítko (btn-main)**: Červený gradient, červená záře
- **Footer tlačítko (btn-footer)**: Fialový gradient
- **Streaming tlačítka**: Specifické styly pro Tidal, Spotify, About

#### Logo
- **Drop-shadow**: Červený stín
- **Hover**: Zvětšení a rotace

### 📱 Responsive design
- **Desktop**: Plná šířka, optimální zobrazení
- **Tablet**: Přizpůsobené rozložení
- **Mobile**: Zmenšené okraje, větší logo (20% šířky)

---

## ⚙️ Technické detaily

### 🔧 Hlavní funkce

#### 1. Zjištění aktuálního data
```javascript
const datum = new Date();
const rok = datum.getFullYear();
const mesic = String(datum.getMonth() + 1).padStart(2, "0");
const den = String(datum.getDate()).padStart(2, "0");
const dnes = `${rok}-${mesic}-${den}`;
```

#### 2. Hledání v databázi
```javascript
const dnesniAlbum = kalendarAlb.find((album) => album.datum === dnes);
```

#### 3. Zobrazení alba
- Dynamické generování HTML kódu pro kartu alba
- Zobrazení obálky, umělce, názvu, data vydání, recenze
- Odkazy na Tidal a Spotify

#### 4. Archiv alb
- Filtrování alb starších než dnešek
- Seřazení od nejnovějšího po nejstarší
- Dynamické generování archivních kartiček
- Toggle funkce pro otevření/zavření archivu

### 📡 API a externí služby
- **Tidal**: Odkazy na alba pro streamování
- **Spotify**: Odkazy na alba pro streamování
- **Analytics**: Vlastní analytický systém (analytics.lukan.cz)

### 🔗 Meta tagy a SEO
- Open Graph meta tagy pro sociální sítě
- Twitter Cards
- Popis stránky a klíčová slova
- Favicon: electric-guitar_12494348.png

---

## 📊 Datová struktura

### 🎵 Struktura alba
Každé album v databázi `kalendarAlb` má následující strukturu:

```javascript
{
  datum: "RRRR-MM-DD",      // Datum ve formátu YYYY-MM-DD
  umelec: "🎤 Název kapely", // Název umělce s emoji ikonou
  nazev: "💿 Název alba",   // Název alba s emoji ikonou
  img: "URL k obálce",      // URL k obrázku obálky alba
  vydano: "MM.RRRR",       // Datum vydání alba
  recenze: "Text recenze",   // Popis a recenze alba
  tidal: "URL na Tidal",    // Odkaz na album na Tidal
  spotify: "URL na Spotify" // Odkaz na album na Spotify
}
```

### 📅 Rozsah databáze
- **Počet alb**: 365 (pro celý rok 2026)
- **Datumové rozpětí**: 2026-01-01 až 2026-12-31
- **Soubor**: musicData.js (4011 řádků)

### 🎯 Žánry pokryté v databázi
- **Grunge**: Nirvana, Pearl Jam, Soundgarden, Alice in Chains, Stone Temple Pilots
- **Nu-Metal**: Korn, Limp Bizkit, Linkin Park, Slipknot, System of a Down
- **Alternativní metal**: Deftones, Tool, Primus, Helmet
- **Rap metal**: Rage Against the Machine, P.O.D.
- **Méně známé kapely**: World Eaters, Relative Ash, Factory 81, Shuvel, NO One, Sw1tched, Twisted Method, Spike 1000, Boy Hits Car

---

## 🔧 Funkčnost

### 🎯 Hlavní stránka (index.html)

#### Prvky stránky
1. **Nadpis** - "🎸 Denní Hudební Doporučení: 365 Alb na Celý Rok 💿"
2. **Úvodní text** - Krátký popis projektu
3. **Karta dnešního alba** - Zobrazení aktuálního alba
4. **Tlačítko archivu** - "📂 Zobrazit předchozí alba"
5. **Archivní mřížka** - Zobrazení minulých alb
6. **Footer** - Odkaz na GDPR a copyright
7. **Logo** - Obrázek "vyzva-EDIT.jpg"

#### Interaktivní prvky
- **Tlačítko archivu**: Toggle pro zobrazení/skryté archivu
- **Streaming odkazy**: Odkazy na Tidal a Spotify
- **Odkaz na About**: Tlačítko "O projektu"
- **Hover efekty**: Na všech interaktivních prvcích

### 📄 Stránka "O projektu" (about.html)

#### Obsah
1. **Úvod** - Popis projektu a jeho cíle
2. **Historie žánrů** - Vysvětlení spojitosti grunge a nu-metal
3. **Technická vsuvka** - Informace o vývoji
4. **Kontakt** - Odkazy na sociální sítě a podporu
5. **Hashtagy** - Seznam relevantních hashtagů
6. **Copyright** - Autorská práva

#### Design
- Tmavý kontejner s červeným borderem
- Červený nadpis
- Šedý text s dobrým kontrastem
- Tlačítko zpět na hlavní stránku

### 🔒 Stránka GDPR (gdpr.html)

#### Obsah
1. **Kdo jsem?** - Představení autora
2. **Sbírám Cookies?** - Negativní odpověď
3. **Co o tobě vím?** - Technické detaily
4. **Spotify, Tidal a ti druzí** - Informace o externích službách
5. **Kontakt** - Kontaktní informace

#### Zásady ochrany soukromí
- **Žádné cookies** - Aplikace neukládá žádná cookies
- **Žádné tracking** - Nepoužívá Google Analytics, Facebook Pixel
- **Lokální běh** - Aplikace běží ve prohlížeči uživatele
- **Minimální data** - Pouze základní serverové logy (IP adresa)

---

## 🧪 Testování

### 🔧 Testovací framework
- **Playwright** - Moderní framework pro testování webových aplikací
- **TypeScript** - Typově bezpečný kód
- **Page Object Model** - Strukturovaný přístup k testování

### 📁 Struktura testů
```
test/
├── assets/
│   └── pages/
│       └── HomePage.ts      # Page Object Model
├── tests/
│   └── homePage.test.ts     # Testy hlavní stránky
├── package.json
├── package-lock.json
└── playwright.config.ts
```

### 🧪 Existující testy
```typescript
// homePage.test.ts
test('has title', async ({ page }) => {
  await homePage.navigate('index.html');
  await expect(homePage.page).toHaveURL(⁄⁄index\.html$/);
  await expect(page).toHaveTitle('Zažij numetal a grunge každý den, po celý rok.');
});
```

### 🚀 Spuštění testů

#### Lokálně
```bash
cd test
npm install
npm test
```

#### Na produkci
```bash
cd test
BASE_URL=https://music.lukan.cz npm run test:prod
```

### 📊 Testovací scénáře (návrh)
1. **Zobrazení hlavní stránky** - Test titulu a URL
2. **Zobrazení alba** - Test, zda se zobrazí dnešní album
3. **Archiv alb** - Test otevření a zavření archivu
4. **Responsive design** - Test na různých rozlišeních
5. **Externí odkazy** - Test odkazů na Tidal a Spotify
6. **About stránka** - Test navigace a obsahu
7. **GDPR stránka** - Test navigace a obsahu

---

## 📦 Nasazení

### 🌐 Hosting
- **Poskytovatel**: VPSfree.cz
- **Doména**: music.lukan.cz
- **Protokol**: HTTPS (vynuceno přes .htaccess)

### 🔧 Konfigurace serveru

#### .htaccess
```apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    
    # Přesměrování na HTTPS
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
</IfModule>
```

### 📂 Struktura na serveru
```
/
├── .htaccess
├── index.html
├── about.html
├── gdpr.html
├── script.js
├── scriptabout.js
├── musicData.js
├── style.css
└── img/
    ├── 4525586.jpg
    ├── electric-guitar_12494348.png
    ├── nu-metal-wallpapers.png
    ├── so0naj17qrh91.jpg
    └── vyzva-EDIT.jpg
```

### 🚀 Deploy proces
1. **Vývoj**: Lokální úprava souborů
2. **Testování**: Spuštění Playwright testů
3. **Commit**: Uložení změn do Git repozitáře
4. **Push**: Odeslání změn na Codeberg
5. **Nasazení**: Ruční kopírování souborů na VPS

### 🔄 Automatizace (budoucí)
- CI/CD pipeline pro automatické nasazení
- Automatické spouštění testů před deployem
- Monitorování dostupnosti

---

## 🔒 Bezpečnost a GDPR

### 🛡️ Bezpečnostní opatření
1. **HTTPS** - Vynucené přes .htaccess
2. **Žádné cookies** - Aplikace neukládá žádná cookies
3. **Žádný tracking** - Nepoužívá externí analytické služby
4. **Lokální běh** - Všechny výpočty probíhají v prohlížeči
5. **Minimální data** - Pouze základní serverové logy

### 📜 GDPR compliance
- **Transparence** - Jasné informace o sběru dat
- **Minimalizace** - Sbírá se pouze nezbytná data
- **Souhlas** - Žádné skryté sbírání dat
- **Právo na zapomenutí** - Uživatelé mohou požádat o smazání dat

### 🔗 Externí služby
- **Tidal** - Externí odkazy, data sbírána Tidalem
- **Spotify** - Externí odkazy, data sbírána Spotify
- **Analytics** - Vlastní systém, minimální data

---

## 📈 Budoucí vylepšení

### 🎯 Krátkodobé cíle (1-3 měsíce)
- [ ] **Vylepšené testy** - Přidat testy pro archiv a about stránku
- [ ] **CI/CD pipeline** - Automatické testování a nasazení
- [ ] **Monitorování** - Sledování dostupnosti a výkonu
- [ ] **Optimalizace obrázků** - Komprese a lazy loading
- [ ] **PWA podpora** - Progressive Web App pro offline použití

### 🎯 Střednědobé cíle (3-6 měsíců)
- [ ] **Uživatelské účty** - Možnost uložit oblíbená alba
- [ ] **Hodnocení alb** - Systém pro hodnocení a komentáře
- [ ] **Vyhledávání** - Full-text vyhledávání v databázi
- [ ] **Filtrování** - Podle žánru, roku, umělce
- [ ] **API** - REST API pro přístup k datům

### 🎯 Dlouhodobé cíle (6-12 měsíců)
- [ ] **Mobilní aplikace** - Native aplikace pro iOS a Android
- [ ] **Integrace se streamovacími službami** - Přímé přehrávání
- [ ] **Komunita** - Diskuzní fórum a sdílení doporučení
- [ ] **Mezinárodní verze** - Překlady do dalších jazyků
- [ ] **Rozšíření databáze** - Další žánry a roky

### 💡 Nápady na vylepšení UX
- **Tmavý/ světlý režim** - Přepínání barevného schématu
- **Notifikace** - Upozornění na nové album
- **Historie poslechu** - Sledování poslechnutých alb
- **Náhodné album** - Tlačítko pro náhodné doporučení
- **Sdílení** - Snadné sdílení na sociálních sítích

---

## 🤝 Přispění

### 📝 Jak přispět
1. **Nahlásit chybu** - Vytvořit issue v repozitáři
2. **Navrhnout vylepšení** - Vytvořit feature request
3. **Přispět kódem** - Fork, změny, pull request
4. **Přidat album** - Navrhnout nové album do databáze
5. **Překlad** - Pomoci s překlady

### 🎯 Pravidla pro přispěvatele
1. **Kódový styl** - Dodržovat existující styl
2. **Testy** - Přidat testy pro nové funkce
3. **Dokumentace** - Aktualizovat dokumentaci
4. **Commit zprávy** - Jasné a popisné zprávy
5. **Pull requesty** - Malé, zaměřené změny

### 📦 Vývojové prostředí

#### Požadavky
- Node.js (pro testování)
- Git
- Textový editor (VS Code, Vim, atd.)

#### Nastavení
```bash
# Klonování repozitáře
git clone https://codeberg.org/Kankys/musicCalendar.git
cd musicCalendar

# Instalace závislostí pro testování
cd test
npm install
```

#### Spuštění testů
```bash
cd test
npm test
```

---

## 📜 License

### 📄 MIT License

```
MIT License

Copyright (c) 2025 Kankys

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

### 🎯 Povolené činnosti
- ✅ Použití pro osobní účely
- ✅ Komerční použití
- ✅ Úprava a distribuce
- ✅ Integrace do jiných projektů

### ❌ Zakázané činnosti
- ❌ Odstranění copyrightu
- ❌ Tvrdit, že jste autorem
- ❌ Porušování zákonů

---

## 📞 Kontakt

### 👤 Autor
- **Jméno**: Lukáš Kaňka (Kankys)
- **Web**: [lukaskanka.cz](https://lukaskanka.cz)
- **Bluesky**: [@kankys.bsky.social](https://bsky.app/profile/kankys.bsky.social)
- **Codeberg**: [@Kankys](https://codeberg.org/Kankys)
- **Email**: [Kontaktní formulář](https://lukaskanka.cz/index/about/index.html)

### 🌐 Projekt
- **Web**: [music.lukan.cz](https://music.lukan.cz)
- **Repozitář**: [Codeberg](https://codeberg.org/Kankys/musicCalendar)
- **Issue tracker**: [Codeberg Issues](https://codeberg.org/Kankys/musicCalendar/issues)

---

## 🏆 Poděkování

- Všem kapelám, které inspirovaly tento projekt
- Uživatelům, kteří podporují nezávislé projekty
- VPSfree.cz za bezplatné hostování
- Codeberg za open-source platformu

---

*Dokumentace vytvořena 5. srpna 2026. Poslední aktualizace: 5. srpna 2026.*