AKT MAMUT – Challenges Manual

1. Overview

System challenges działa w modelu:

Google Sheets → Python generator → JSON → Frontend HTML/JS

Źródło danych Google Sheets zawiera zakładkę CONFIG oraz osobne zakładki dla regionów.

Efekt końcowy Frontend korzysta z wygenerowanych plików JSON i pokazuje kafelki oraz stronę pojedynczego challenge.

2. Struktura projektu

AKT-MAMUT/
├─ data/
│  └─ generate_challenges.py
└─ site/
   ├─ index.html
   └─ challenges/
      ├─ list.html
      ├─ index.html
      ├─ manual.html
      └─ data/
         ├─ challenges-index.json
         ├─ challenges-ro.json
         ├─ challenges-sk.json
         ├─ challenges-cz.json
         └─ ...

Najważniejsze katalogi to data/ i site/challenges/data/.

3. CONFIG w Google Sheets

Zakładka CONFIG steruje tym, jakie challenge są aktywne i jak są prezentowane.

kolumna	opis
`key`	unikalny identyfikator challenge
`sheet`	nazwa zakładki z danymi regionu
`name`	nazwa challenge wyświetlana w UI
`icon`	emoji albo ścieżka do obrazka, np. `/assets/img/ro.svg`
`active`	`1` = aktywny, `0` = wyłączony
`order`	kolejność wyświetlania

Przykład

key       sheet     name                           icon                   active   order
ro        RO        Romanian Peak Challenge        /assets/img/ro.svg    1        1
sk        SK        Slovak Peak Challenge          /assets/img/sk.svg    1        2
cz        CZ        Czech Peak Challenge           /assets/img/cz.svg    1        3
kampinos  Kampinos  Kampinos Hills Challenge       🌲                    1        6
raba      Raba      Beskid Myślenicki Challenge                          0        8

4. Dane regionów

Każdy challenge ma własną zakładkę w Google Sheets. Generator oczekuje kolumn:

NR
PEAK
REGION
SUBREGION
HEIGHT
EXPEDITION
DATE
LAT
LON

Status jest obliczany automatycznie:

DATE != ""  → done
DATE == ""  → todo

5. Generator Python

Plik generatora:

data/generate_challenges.py

Uruchamianie:

python generate_challenges.py

1. Wczytaj CONFIG z Google Sheets

2. Dla każdego aktywnego challenge pobierz dane z odpowiedniej zakładki

3. Wygeneruj plik challenges-<key>.json

4. Zaktualizuj menu w site/index.html

5. Wygeneruj challenges-index.json dla strony kafelków

6. JSON output

Plik indeksu

[
  {
    "key": "ro",
    "name": "Romanian Peak Challenge",
    "icon": "/assets/img/ro.svg"
  },
  {
    "key": "sk",
    "name": "Slovak Peak Challenge",
    "icon": "/assets/img/sk.svg"
  }
]

Plik pojedynczego challenge

[
  {
    "number": 1,
    "peak": "Moldoveanu",
    "region": "Făgăraș",
    "subregion": "",
    "height": 2544,
    "expedition": "AKT Mamut",
    "date": "2024-08-15",
    "lat": 45.599,
    "lon": 24.736,
    "status": "done"
  }
]

7. Strony frontendowe

`list.html`

Strona z kafelkami. Wczytuje challenges-index.json, a potem dla każdego challenge pobiera jego JSON i liczy:

liczbę wszystkich szczytów,
liczbę ukończonych,
procent progresu.

`index.html`

Strona pojedynczego challenge, otwierana jako:

/challenges/index.html?region=ro

Parametr region musi odpowiadać polu key z CONFIG.

8. Workflow

1. Edycja danych w Google Sheets
2. python generate_challenges.py
3. commit
4. push
5. Netlify deploy

Jeśli dodajesz lub zmieniasz challenge, nie trzeba ręcznie edytować menu, jeżeli generator poprawnie aktualizuje site/index.html.

9. Dodanie nowego challenge

Dodaj nową zakładkę w Google Sheets z danymi szczytów.
Dodaj nowy wiersz w CONFIG.
Uruchom generator.
Sprawdź, czy powstał nowy plik challenges-<key>.json.
Sprawdź, czy challenge pojawił się w menu i na stronie kafelków.

Przykład wpisu w CONFIG

tatry   Tatry   Tatra Peak Challenge   /assets/img/tatry.svg   1   9

Challenges System Manual