Documentation

2 files changed, 410 insertions, 0 deletions

diff --git a/CONFIG b/CONFIG
new file mode 100644
index 0000000..c1e6e32
--- /dev/null
+++ b/CONFIG
@@ -0,0 +1,337 @@
+JFR Teamy - play-off - plik konfiguracyjny
+==========================================
+
+Przykładowy plik konfiguracyjny, który służył do wygenerowania [przykładów](https://emkael.info/brydz/playoff/), umieszczono w całości u dołu tego pliku.
+
+Ogólny format
+-------------
+
+Plik konfiguracyjny jest formatu JSON - a to oznacza na przykład, że trzeba pilnować backslashów wewnątrz łańcuchów znaków.
+Na przykład - backslashe w konfiguracji logo nagłówka są podwojone. Szczególnie należy na to uważać przy podawaniu ścieżek do pliku wyjściowego.
+
+Opcje ogólne
+------------
+
+Konfiguracja składa się, po kolei, z:
+ - pola `"output"`: ścieżki do pliku, do którego będzie generowana drabinka.
+   Polecam ścieżkę bezwzględną do katalogu WWW turnieju.
+   W ścieżce musi znajdować katalog `sklady/`, do którego kopiowany jest JavaScript `playoff.js`
+ - sekcji `"page"`: ustawień strony
+   + `"title"` - tytuł (`<title>` HTMLa)
+   + `"logoh"` - nagłówek, jak w tabeli admin bazy turnieju
+   + `"refresh"` - parametr odświeżania strony drabinki: `0` = wyłączone, liczba naturalna = interwał odświeżania, w sekundach
+   + `"width"` i `"height"` - wymiary (w pikselach) miejsca rezerwowanego dla każdego meczu w widoku drabinki (`"width"` bezpośrednio wpływa na rozmieszczanie kolumn, wewnątrz każdej z kolumn mecze rozmieszczane są równomiernie, w zależnie od ich liczby)
+   + `"margin"` - odstęp między w/w miejscem (minimalny - jak widać, w przypadku mniejszej liczby meczów w fazie, odstępy się dopasują)
+ - sekcji `"database"`, zawierającej ustawienia połączenia bazy danych
+ - sekcji `"goniec"`, zawierającej ustawienia Gońca (`"enabled"` przyjmuje wartości `0`/`1`)
+
+Ustawienia teamów
+-----------------
+
+Dalej mamy sekcję `"teams"`, która jest pierwsza do przebudowy (albo do odstrzału, w ogóle), więc zbytnio nie przyzwyczajałbym się do jej struktury.
+
+W niej definiujemy teamy w kolejności, wg której mają być rozdzielane miejsca (w sytuacjach "przegrani zajmują miejsca...").
+
+Każdy team to tablica, kolejno: pełnej nazwy (tej, która MUSI się zgadzać z nazwami we wszystkich turniejach), skróconej nazwy, pliku flagi (opcjonalnie).
+
+Jako czwarty element każdej tablicy można wpisać liczbę naturalną, która oznacza pozycję, jaką team ma zająć w końcowej klasyfikacji (tj. wpisanie tam liczby oznacza, że team od samego początku umieszczany jest na tej pozycji w klasyfikacji końcowej - np. jeśli nie uczestniczy w ogóle w play-off).
+
+Co zrobić, gdy jest taki team, a turniej nie ma ustawionych obrazków z flagami - nie wiem, będę się martwił kiedy indziej.
+
+Ustawienia drabinki
+-------------------
+
+Sekcja `"phases"` definiuje już samą drabinkę.
+
+Jest to tablica obiektów - każdy obiekt to kolejna faza (kolumna) drabinki.
+
+Faza ma następujące pola:
+ - `"title"` - etykieta fazy, wyświetlana u góry jako link do wyników szczegółowych danej fazy
+ - `"link"` - w/w link (ale linki do poszczególnych meczów generują się na podstawie informacji pobranych z bazy, dopóki wszystkie turnieje, których mecze wchodzą w skład danej fazy, są wysyłane do jednej ścieżki)
+ - tablicę `"matches"`, definiującej mecze w fazie
+
+Ustawienia kozy (co meczy)
+--------------------------
+
+Mecz ma następujące pola:
+ - `"id"` - identyfikator meczu (liczbowy, musi być unikatowy)
+ - `"database"`, `"round"` i `"table"` - określają, skąd brać dane meczu
+ - `"teams"` określa, co ma się wyświetlić w przypadku, gdy z powyższego
+zestawu pól nie da się pobrać informacji o meczu
+  Jest to tablica dwóch elementów, które mogą być:
+   + łańcuchem tekstowym - wówczas musi to być pełna nazwa teamu
+   + obiektem, z możliwymi polami tablicowymi `"winner"` lub `"loser"` - oznacza to, że dane miejsce drabinki jest przeznaczone dla zwycięzców/przegranych w meczach o ID podanych w polu
+ - opcjonalne, pola `"winner"` i `"loser"` - które z kolei w tym kontekście oznaczają, miejsca, które zajmują zwycięzcy/przegrani danego meczu w końcowej klasyfikacji
+
+Na przykładach, pierwszy i ostatni mecz z poniższego pliku:
+
+```
+{
+  "id": 1,
+  "database": "iiild_po_1",
+  "round": 1,
+  "table": 1,
+  "teams": [
+    "CKM Łódź",
+    "MKS Bzura I Ozorków"
+  ],
+  "loser": [7, 8]
+}
+```
+
+Mecz nr 1, pobierany z turnieju `iiild_po_1`, ze stołu nr 1 w pierwszej rundzie.
+
+Gdyby turniej nie był gotowy i rozstawiony, i tak wiadomo, że w meczu gra CKM z Bzurą.
+
+W końcu, przegrany tego meczu zajmie jedno z miejsc 7-8.
+Tu uwaga: jeśli okaże się, że żaden inny mecz nie ma dokładnie tego samego warunku - miejsc 7-8 - klasyfikacja prawdopodobnie nie wypełni się, tj. nie można określić, że przegrany jednego meczu zajmie miejsca 7-8, drugiego 8-9, a trzeciego 9-10 i liczyć, że program sam rozwiąże zagadkę.
+
+```
+{
+  "id": 14,
+  "database": "iiild_po_4",
+  "round": 1,
+  "table": 2,
+  "teams": [
+    { "loser": [11, 12] },
+    { "loser": [11, 12] }
+  ],
+  "winner": [15],
+  "loser": [16]
+}
+```
+
+Mecz nr 14 to mecz z drugiego stołu pierwszej rundy turnieju `iiild_po_4`.
+
+Miejsca w tym meczu zajmują przegrani meczów o ID 11 i 12 (przy czym gospodarze/goście są nieznani dopóki turniej nie zostanie rozstawiony w bazie).
+
+Zwycięzca zajmie 15. miejsce w lidze, a przegrany - 16.
+
+Pełen plik konfiguracyjny
+-------------------------
+
+```
+{
+    "output": "D:/Brydz/Teamy/www/liga_playoff_12.html",
+    "page": {
+        "title": "III liga 2016/17, WZBS Łódź, play-off",
+        "logoh": "<span id=\"logo\"></span><script type=\"text/javascript\">loadIt('liga_logo.html','logo');</script>",
+        "refresh": 0,
+        "width": 200,
+        "height": 80,
+        "margin": 70
+    },
+    "database": {
+        "host": "localhost",
+        "port": 3306,
+        "user": "UŻYTKOWNIK BAZY",
+        "pass": "HASŁO BAZY"
+    },
+    "goniec": {
+        "enabled": 1,
+        "host": "localhost",
+        "port": 8090
+    },
+    "teams": [
+        ["Mazowia Płock", "Mazowia", "herby/wp.png"],
+        ["Jagielloński Ośrodek Kultury Łódź", "JOK", "herby/el.png"],
+        ["KDK II Kutno", "KDK II", "herby/eku.png"],
+        ["BINŻ Bełchatów", "BINŻ", "herby/ebe.png"],
+        ["CKM Łódź", "CKM", "herby/el.png"],
+        ["PTC - PAFANA I Pabianice", "PTC", "herby/epa.png"],
+        ["Intra Łódź", "Intra", "herby/el.png"],
+        ["BOK Rondo Łódź", "Rondo", "herby/el.png"],
+        ["MKS Bzura I Ozorków", "Bzura", "herby/ezgozo.png"],
+        ["Zdrowie Piast Sieradz", "Piast", "herby/esi.png"],
+        ["Olimpia Chąśno", "Olimpia", "herby/elc.png"],
+        ["Brydż Quartet Lechia Tomaszów Mazowiecki", "Lechia", "herby/etm.png"],
+        ["Veolia Energia Łódź", "Veolia", "herby/el.png"],
+        ["Ekolog Łódź", "Ekolog", "herby/el.png"],
+        ["KDK III Kutno", "KDK III", "herby/eku.png"],
+        ["Pomiar - Ceemka Opoczno", "Ceemka", "herby/eop.png"]
+    ],
+    "phases": [
+        {
+            "title": "25.02.2017",
+            "link": "http://arturwasiak.republika.pl/brydz/sedzia/3liga_2016_17/faza_3/liga_runda1.html",
+            "matches": [
+                {
+                    "id": 1,
+                    "database": "iiild_po_1",
+                    "round": 1,
+                    "table": 1,
+                    "teams": [
+                        "CKM Łódź",
+                        "MKS Bzura I Ozorków"
+                    ],
+                    "loser": [7, 8]
+                },
+                {
+                    "id": 2,
+                    "database": "iiild_po_1",
+                    "round": 1,
+                    "table": 2,
+                    "teams": [
+                        "PTC - PAFANA I Pabianice",
+                        "Intra Łódź"
+                    ],
+                    "loser": [7, 8]
+                },
+                {
+                    "id": 3,
+                    "database": "iiild_po_1",
+                    "round": 1,
+                    "table": 3,
+                    "teams": [
+                        "BOK Rondo Łódź",
+                        "KDK III Kutno"
+                    ],
+                    "winner": [9, 10]
+                },
+                {
+                    "id": 4,
+                    "database": "iiild_po_1",
+                    "round": 1,
+                    "table": 4,
+                    "teams": [
+                        "Zdrowie Piast Sieradz",
+                        "Ekolog Łódź"
+                    ],
+                    "winner": [9, 10]
+                }
+            ]
+        },
+        {
+            "title": "26.02.2017",
+            "link": "http://arturwasiak.republika.pl/brydz/sedzia/3liga_2016_17/faza_4/liga_runda1.html",
+            "matches": [
+                {
+                    "id": 5,
+                    "database": "iiild_po_2",
+                    "round": 1,
+                    "table": 1,
+                    "teams": [
+                        "BINŻ Bełchatów",
+                        { "winner": [1, 2] }
+                    ],
+                    "loser": [5, 6]
+                },
+                {
+                    "id": 6,
+                    "database": "iiild_po_2",
+                    "round": 1,
+                    "table": 2,
+                    "teams": [
+                        "KDK II Kutno",
+                        { "winner": [1, 2] }
+                    ],
+                    "loser": [5, 6]
+                },
+                {
+                    "id": 7,
+                    "database": "iiild_po_2",
+                    "round": 1,
+                    "table": 3,
+                    "teams": [
+                        "Pomiar - Ceemka Opoczno",
+                        { "loser": [3, 4] }
+                    ],
+                    "winner": [11, 12]
+                },
+                {
+                    "id": 8,
+                    "database": "iiild_po_2",
+                    "round": 1,
+                    "table": 4,
+                    "teams": [
+                        "Olimpia Chąśno",
+                        { "loser": [3, 4] }
+                    ],
+                    "winner": [11, 12]
+                }
+            ]
+        },
+        {
+            "title": "08.04.2017",
+            "link": "http://arturwasiak.republika.pl/brydz/sedzia/3liga_2016_17/faza_5/liga_runda1.html",
+            "matches": [
+                {
+                    "id": 9,
+                    "database": "iiild_po_3",
+                    "round": 1,
+                    "table": 1,
+                    "teams": [
+                        "Mazowia Płock",
+                        { "winner": [5, 6] }
+                    ],
+                    "loser": [3, 4]
+                },
+                {
+                    "id": 10,
+                    "database": "iiild_po_3",
+                    "round": 1,
+                    "table": 2,
+                    "teams": [
+                        "Jagielloński Ośrodek Kultury Łódź",
+                        { "winner": [5, 6] }
+                    ],
+                    "loser": [3, 4]
+                },
+                {
+                    "id": 11,
+                    "database": "iiild_po_3",
+                    "round": 1,
+                    "table": 3,
+                    "teams": [
+                        "Veolia Energia Łódź",
+                        { "loser": [7, 8] }
+                    ],
+                    "winner": [13, 14]
+                },
+                {
+                    "id": 12,
+                    "database": "iiild_po_3",
+                    "round": 1,
+                    "table": 4,
+                    "teams": [
+                        "Brydż Quartet Lechia Tomaszów Mazowiecki",
+                        { "loser": [7, 8] }
+                    ],
+                    "winner": [13, 14]
+                }
+            ]
+        },
+        {
+            "title": "09.04.2017",
+            "link": "http://arturwasiak.republika.pl/brydz/sedzia/3liga_2016_17/faza_6/liga_runda1.html",
+            "matches": [
+                {
+                    "id": 13,
+                    "database": "iiild_po_4",
+                    "round": 1,
+                    "table": 1,
+                    "teams": [
+                        { "winner": [9, 10] },
+                        { "winner": [9, 10] }
+
+                    ],
+                    "winner": [1],
+                    "loser": [2]
+                },
+                {
+                    "id": 14,
+                    "database": "iiild_po_4",
+                    "round": 1,
+                    "table": 2,
+                    "teams": [
+                        { "loser": [11, 12] },
+                        { "loser": [11, 12] }
+                    ],
+                    "winner": [15],
+                    "loser": [16]
+                }
+            ]
+        }
+    ]
+}
+```
diff --git a/README b/README
new file mode 100644
index 0000000..272a976
--- /dev/null
+++ b/README
@@ -0,0 +1,73 @@
+JFR Teamy - play-off
+====================
+
+Generator drabinek wizualizacji play-off dla turniejów prowadzonych przy użyciu JFR Teamy.
+
+Przykład wizualizacji: [III liga LD, sezon 2016/17](https://emkael.info/brydz/playoff/).
+
+Wymagania systemowe
+-------------------
+
+Dla wersji skompilowanej: jakiś współczesny system rodziny MS Windows.
+
+Dla wersji skryptowej:
+ * Python 2.x ze standardowym zestawem bibliotek
+ * MySQL connector dla Pythona
+
+Instalacja
+----------
+
+Dla wersji skompilowanej: ściągnąć, rozpakować, upewnić się, że [`playoff.js`](playoff.js) jest w katalogu pliku wykonywalnego.
+
+Dla wersji skryptowej: sklonować to repozytorium.
+
+Użycie
+------
+
+Niezależnie od wersji, należy wykonać w linii poleceń polecenie:
+
+```
+playoff.exe PLIK_USTAWIEŃ_JSON
+```
+
+lub
+
+```
+python playoff.py PLIK_USTAWIEŃ_JSON
+```
+
+`PLIK_USTAWIEŃ_JSON` jest plikiem konfiguracyjnym, dostarczającym wszelkich danych niezbędnych do pracy programu.
+
+Jego strukturę opisuje dokument [CONFIG](CONFIG).
+
+Znane ograniczenia
+------------------
+
+ *  wszystkie mecze danej fazy muszą lądować na FTP w tej samej ścieżce:
+linki generowane są na podstawie URL całej fazy (linki z datami u góry),
+prefiksów turniejów oraz numerów rund
+ * brak obsługi "ręczników" - trzeba wypełnić zręcznikowany segment
+średnimi, żeby pokazało, że mecz się skończył
+ * fazy powinny być określone raczej chronologicznie (czytaj: nie
+testowano, co się stanie, jeśli określimy np., że w meczu fazy 2 ma zagrać
+zwycięzca z fazy 4), ale nie powinno być problemu z "przeskakiwaniem"
+faz (czyli awansem zwycięzcy z fazy 1 od razu do fazy 3), przy czym
+takiej sytuacji też nie testowano (rysować się powinno, ale ubytki estetyczne są prawie pewne)
+ * program wymaga działania Webmastera (wyniki czytane są z takiego
+miejsca bazy, do którego pisze Webmaster, a z jakichś powodów nie pisze
+Admin przy zamykaniu rundy/segmentu), więc nawet w przypadku grania
+"off-line" (Kolektor+statyczne po każdym segmencie), może być potrzeba
+przejechania segmentu Webmasterem
+ * przez cały czas trwania play-off pełne nazwy teamów (w bazach i te
+określone w JSONie) muszą się zgadzać - teamy są rozróżniane po nich właśnie
+ * skorzystanie z funkcjonalności umieszczenia drużyny na określonym miejscu klasyfikacji końcowej (przed rozegraniem play-off) wymaga obecności flag teamów
+
+Autor
+-----
+
+Michał Klichowicz (mkl)
+
+Licencja
+--------
+
+[Uproszczona licencja BSD](LICENSE)