From 7e71262ba4b5ffbec3cded250e64e90c009aa8a8 Mon Sep 17 00:00:00 2001
From: emkael <emkael@tlen.pl>
Date: Sat, 7 Oct 2023 23:49:02 +0200
Subject: Documentation updated

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index a82bcd7..69f677a 100644
--- a/README.md
+++ b/README.md
@@ -48,9 +48,12 @@ Wprowadza do zrzutów często potrzebne poprawki (jak np. uzupełnienie tabeli `
 
  * s3cmd
  * klient MySQL
+ * opcjonalnie: dbxcli
 
 Zrzuty baz danych muszą zostać niezależnie pozyskane od sędziów poszczególnych kotłów i wrzucone do jednego wiaderka S3, np. używając [Spedytora](https://github.com/emkael/spedytor/).
 
+Opcjonalnie, sędziowie mogą wrzucać zrzuty na Dropboksa, lub na FTP, do swojego katalogu wyników (pamiętaj o wyłączeniu publicznego dostępu do takich plików!).
+
 ### Wywołanie
 
 `make dumps`
@@ -61,12 +64,14 @@ Zmienne środowiskowe:
 
  * `LIGA_MYSQL_CONNECTION_OPTS`: komplet przełączników polecenia `mysql` pozwalający podłączyć się do docelowego (lokalnego) serwera MySQL
  * `LIGA_S3_BUCKET`: URI wiaderka S3, w którym trzymane są zrzuty - uwaga, obiekty z podkatalogów są ignorowane
+ * `LIGA_DROPBOX_DUMP_FOLDER`: (opcjonalnie) ścieżka w ramach konta Dropbox, z której kopiowane będą zrzuty
 
 Pliki konfiguracyjne:
 
  * `dumps/.s3config`: konfiguracja klienta `s3cmd`, można wygenerować ją poleceniem `s3cmd --configure -c dumps/.s3config`
  * `dumps/.mapping`: mapowanie nazw plików zrzutów na docelowe bazy danych, do których zrzuty są wgrywane, każdy wiersz to jeden turniej, w każdym wierszu najpierw pojawia się nazwa bazy danych, a następnie, po odstępie, nazwa pliku relatywna względem `./dumps/` (domyślnie zrzuty trafiają do katalogu `./dumps/sync/`)
  * `dumps/.queries`: spis poleceń SQL wykonywanych na każdej bazie danych po wgraniu jej do lokalnego serwera, po jednym poleceniu na wiersz
+ * w przypadku korzystania z Dropboksa, `dbxcli` musi zostać skonfigurowane niezależnie
 
 ## Kopie zapasowe lokalnych baz danych
 
@@ -92,6 +97,73 @@ Pliki konfiguracyjne:
 
  * `dumps/.backup`: spis baz danych do zrzucenia z lokalnego serwera, po jednej bazie na wiersz
 
+## Sprawdzenia przedsezonowe
+
+Moduł kontroli typowych błędów przy zakładaniu turniejów. Sprawdza:
+
+ * daty rozpoczęcia rund
+ * logohy
+ * kolorki
+ * tabele VP
+ * język strony z wynikami
+ * nazwy teamów i składy z Cezarem
+
+### Wymagania wstępne
+
+ * python, w wersji 3
+ * `requirements.txt` z katalogu modułu (`preseason`), w tym co najmniej requests i beautifulsoup z parserem lxml
+
+### Wywołanie
+
+`python3 checks.py PLIK_KONFIGURACJI SPRAWDZENIE SPRAWDZENIE SPRAWDZENIE...`
+
+`PLIK_KONFIGURACJI` to ścieżka do pliku JSON z konfiguracją dla danej grupy (patrz niżej), a kolejne argumenty to nazwy poszczególnych sprawdzeń do wykonania: `dates`, `logoh`, `vp_table`, `page_language`, `team_names`, `kolorki`.
+
+`make preseason`
+
+Przelatuje po wszystkich plikach `.json` z katalogu `preseason/config/` i wykonuje na każdym wszyskie sprawdzenia.
+
+### Konfiguracja
+
+Format pliku JSON:
+
+```
+{
+    "source": {
+        "path": "ŚCIEŻKA_DO_WYNIKÓW",
+        "prefix": "PREFIKS_TURNIEJU"
+    },
+    "language": "TŁUMACZENIE_FRAZY_MIEJSCE",
+    "vp_table": "PLIK_Z_TABELĄ_VP",
+    "logoh": {
+        "custom_file": "NAZWA_PLIKU_LOGOHA",
+        "template": "PLIK_SZABLONU",
+        "variables": {
+            ZMIENNE_DO_PODMIANY
+        }
+    },
+    "round_dates": [
+        DATY_RUND
+    ],
+    "team_names": "ID_TEAMÓW_Z_CEZARA",
+    "kolorki": "PLIK_KOLORKÓW"
+}
+```
+
+Sekcja `source` definiuje stronę z wynikami, którą sprawdzamy: `path` to ścieżka (bez nazwy pliku) do katalogu dostępnego po HTTP(S), a `prefix` to prefiks turnieju.
+
+Język strony sprawdzany jest na podstawie tego, jak brzmi fraza `"miejsce"` na stronie tabeli z wynikami (`PREFIXleaderb.html`).
+
+Tabela VPów pobierana jest z pliku w katalogu `config`, zawierającym wiersze formatu `IMPY - VP : VP`.
+
+Logoh turnieju porównywany jest do zawartości pliku szablonu w katalogu `config`. W szablonie podmieniane są zmienne, oznaczone w szablonie `%zmienna%`. Jeśli turniej ma logoh w pliku nazwanym inaczej niż po prefiksie, można podać tę nazwę w `custom_file`.
+
+Daty rund odczytywane są z nagłówków stron `PREFIXrundaN.html` - daty nie są parsowane, więc sprawdzany jest też ich format.
+
+Nazwy teamów porównywane są z Cezarem na podstawie mapowania między ID teamu w turnieju a ID drużyny w Cezarze - w konfiguracji podaje się plik mapowania, w formacie jak dla modułu bazy graczy.
+
+Kolorki poróénywane są z plikiem w katalogu `config`.
+
 ## Moduł butlera
 
 Zbija wiele turniejów w jeden, w celu wyliczenia wspólnego butlera.
-- 
cgit v1.2.3