---

O nás

Think different Academy je organizace zabývající se volnočasovými a vzdělávacími aktivitami pro děti a mládež.

Kromě našich skvělých prezenčních aktivit a publikací do časopisů s logickými úlohami se chceme zkusit znovu rozšířit i do online prostoru. Naším momentálním projektem je platforma, díky které si budou moci mladí lidé potrénovat své logické a taktické myšlení na piškvorkových úlohách.

Náš cíl

Protože nám na platformě velmi záleží, hledáme tým vývojářů, který nám pomůže našeho snu dosáhnout. Věříme, že právě díky spolupráci se soutěží Tour de App budeme schopni najít ten nejlepší tým mladých talentů, který nám pomůže zrealizovat náš sen.

Během tří výběrových kol si ověříme nejen vaše dovednosti, ale i kreativitu a schopnost komunikace s našimi zástupci.

Naší představou je, aby všichni uživatelé naší platformy měli možnost vytvářet a řešit úlohy všech obtížností. Ty si můžete představit jako rozehrané partie piškvorek, které jsou v nějaké zajímavé situaci. Na tohle budete mít v rámci prvního kola zhruba 3 měsíce.

Jelikož víme, že se zadání může na první pohled tvářit komplexně, rozdělili jsme jej pro vás na 4 menší fáze a připravili jsme sadu automatizovaných testů, díky kterým budete znát svůj postup ve vývoji.

---

Fáze 1: How does it work?

V první fázi si potřebujeme ověřit, zda jste schopni něco odevzdat (viz Odevzdání aplikace) a následně to něco otestovat (Testování aplikace). Nic složitého, že?

• Založte si GitHub repozitář s názvem ve tvaru TdA25 IdealneNazevTymu a zprovozněte GitHub akci s Dockerem
• Publikujte aplikaci, která bude na http://server-url.cz (u vás poběží na http://localhost, server-url vám bude přiděleno po odevzdání – pracujte tedy jen s relativními cestami) obsahovat HTML stránku s textem „Hello TdA“ (kdekoliv v obsahu stránky).
• Aplikace bude také poskytovat první primitivní API^[?] na http://server-url.cz/api, které bude obsahovat JSON^[?] objekt ve tvaru {"organization": "Student Cyber Games"}.
• Přihlaste se do testovacího frameworku a spusťte testy pro první fázi.
• Tuto fázi je (jako jedinou) nutno odevzdat a otestovat do 20. 12.

---

Fáze 2: Bare minimum

Přichází chvíle, kdy je na čase si vzít do rukou klávesnice a začít psát první řádky kódu. Nezapomeňte, že už jde do tuhého a musíte přemýšlet nad celou podobou vaší aplikace, protože chyby v počátcích se opravují nejhůře. Abychom vám toto nějak ulehčili, připravili jsme pro vás sadu hodnocených automatických testů, které vám ukážou, zda jste na správné cestě.

Mockupy

Abychom vám a vašemu týmu ulehčili práci a nemuseli jste na sebe zbytečně čekat, máme pro vás připravené mockup aplikace: Mockfish a Mockbush.

Avšak chceme upozornit, že tyhle nástroje máte jen pro testovací potřeby. Takže nadále prosíme, nezapomeňte ve finální aplikaci propojit váš frontend s vaším backendem.

Při poslední fázi testování na to budeme brát zřetel a budeme tyto nástroje vypínat.

Mockfish

Testovací frontend, skrz něj můžete otestovat backend. Nabízí jednoduché grafické rozhraní, kde uvidíte, jaká data se vracejí z vašeho backendu.

Mockfish naleznete na této URL adrese: https://odevzdavani.tourdeapp.cz/mockfish.

Mockbush

Testovací backend, který vám pomůže postavit váš frontend s reálnými daty, která máme pro Vás připravena. Tento backend se plně shoduje s naší API specifikací. Dejte si pozor, náš backend není schopen zpracovat stav hry a vždy bude vracet ‘unknown’.

Mockbush naleznete na této URL adrese: https://odevzdavani.tourdeapp.cz/mockbush.

Backend

Potřebujeme vytvořit funkční logiku celé aplikace. Z funkčních požadavků vyplývá, že je nutné někam ukládat úlohy a nějakým způsobem je pak i číst, případně je i aktualizovat a mazat.

• Implementujte veřejné REST API pro správu piškvorkových her
• Kompletní specifikaci API (veškeré endpointy včetně formátu očekávaných dat a HTTP kódů) naleznete zde.

Tipy pro vývoj:

• Specifikaci API vám dodáváme ve formátu OpenAPI (Swagger), takže ho můžete využít v řadě různých nástrojů, jako je třeba https://editor.swagger.io, nebo mnoho automatizovaných generátorů kódu.
• Pro ukládání dat budete pravděpodobně muset vaši aplikaci napojit na nějaký databázový systém. Volba konkrétní technologie je čistě na vás, ale musí splňovat požadavky pro odevzdání. Pro začátečníky doporučujeme jednodušší databáze, jako je například SQLite.
• V modelu uložené hry je i pole gameState. To je jako jediné vypočítané na backendu, zbytek ovlivňuje samotný uživatel. Prozatím mu můžete udělit výchozí hodnotu unknown.

Frontend

Hrát piškvorky jen přes API není to pravé ořechové. Další částí této fáze je frontend, který bude reprezentovat vaši aplikaci, jak vzhledově tak i funkcionálně pro uživatele. Připravte si rychlý návrh a vytvořte super webovku!

Úvodní stránka

• Titulní (kořenová http://server-url.cz) stránka je na vás, ale měla by být jednoduchá a měla by uživateli umožnit rychle se dostat na všechny potřebné části aplikace.

Herní plocha

• Měla by být na http://server-url.cz/game. Skládá se z mřížky 15x15 polí a je dominantním prvkem celé stránky.
• Herní plocha by měla být interaktivní a při kliknutí na pole umožňovat střídavě umisťovat křížky ✖️ a kolečka ⭕ (křížky začínají).
• Aplikace by měla být schopna vyhodnotit, jestli některý z hráčů umístil 5 a více symbolů vedle sebe (kolmo či diagonálně) a pokud se tak stane, hra je ukončena a vítěz je oznámen.

Ovládací prvky

Celá aplikace by nám měla nabídnout možnost, přes grafické rozhraní přívětivé ovládání, nechat uživatele s aplikací interagovat.

V této fázi tyto věci nutně nepotřebujeme, ale sepíšeme je už teď, abyste měli představu, co si v následující fázi přejeme, aby vaše aplikace obsahovala.

• Vytvoření a uložení piškvorkové úlohy (Nezapomeňte, každá úloha má své jméno)
• Načtení dané piškvorkové úlohy
• Možnost upravit piškvorkovou úlohu
• Smazání piškvorkové úlohy

Důležitý aspekt je i to, že v případě, kdy není vybraná žádná konkrétní úloha, zapne se „klasická“ nová hra piškvorek s čistým herním polem.

Vizuální stránka celé aplikace

S naším týmem grafiků jsme si pro vás připravili brandmanuál, kterým se prosím řiďte. Jde o naši brand identitu, kterou se chceme prezentovat.

Brandmanuál naleznete zde.

---

Fáze 3: Optimal solution

Základní aplikaci máme, a tak se můžeme posunout dál. Až doteď jsme ignorovali dva podstatné body: možnost plnit uložené úlohy bez toho, abychom měli jistotu, že všichni plní úlohy, jak mají. Tím pádem potřebujeme nějakým způsobem ověřit, v jakém stavu jsou hry a jestli hry jsou v platném stavu.

Rozšíření backendu

Pomocí algoritmů určete a přiřaďte správný stav hry:

• Zahájení - hra s 5 a méně koly
• Middle game - stav hry od 6. kola
• Koncovka - hráč má šanci svým dalším tahem propojit 5 v řadě a vyhrát hru

Pozor! Ne všechny 4 znaky v řadě jsou výherní, dejte si pozor na tyto případy:

• Čtyřka je z jedné strany zablokovaná zdí, nebo soupeřovým symbolem a hráč, který je na tahu, může soupeřovu čtyřku zablokovat
• Čtyřka je z obou stran zablokovaná zdí, nebo soupeřovým symbolem

Občas může být hra jednoznačná a hráč se zvládne dostat do koncovky už v zahájení, v takovém případě se hra klasifikuje jako Koncovka.

Určete, zda je hra platná:

• Piškvorky se hrají s kolečky a křížky, cokoliv jiného do herní plochy nepatří.
• Kromě symbolů je potřeba mít validní i samotné pole. Jeho rozměry jsou pokaždé 15x15 políček.
• Pro zjednodušení hry křížek vždy začíná. To znamená, že kontrolujeme zda je stejný počet znaků, nebo křížek má o jeden víc.

Všechny chybové hlášky musí splňovat výše zmíněné schéma.

Rozšíření frontendu

V aplikaci se nějakým způsobem pohybujeme. Ale přesto to není všechno a stále tu dost věcí chybí. Proto si připravte čajíček a jdeme po přidávat kritické věci, případně QoL věci.

• Potřebujeme, abyste propojili frontend s backendem. Prozatím můžete využít váš nebo jestli potřebujete tak i náš Mockbush.

Práce s piškvorkovými úlohami

Jestli jste splnili tyto podmínky již v druhé fázi, tak i přesto doporučujeme, abyste si je znovu prošli a zkontrolovali, jestli máte vše splněno.

Vytvoření a uložení piškvorkové úlohy:

• Nezapomeňte, každá úloha má své jméno.
• Možnost přiřadit ke hře jméno a obtížnost.
• Když uložíte úlohu, automaticky přejde z adresy http://server-url.cz/game na http://server-url.cz/game/{uuid}.

Načtení dané piškvorkové úlohy:

• Načtená hra bude na http://server-url.cz/game/{uuid}
• Možnost upravit již vytvořené piškvorkové úlohy.
• Možnost smazat už vytvořenou piškvorkovou úlohu.

Seznam úloh

Jedna z posledních věcí, co si přejeme je, abychom mohli přívětivě procházet vytvořené úlohy. Přejeme se mít seznam úloh. Každá úloha bude mít vlastní kartičku, která bude obsahovat:

• Název úlohy
• Obtížnost úlohy
• Tlačítko pro spuštění úlohy
• Tlačítka pro přejití na úpravu úlohy

V samotném seznamu úloh je těžké najít určitou úlohu. Proto si přejeme mít možnost filtrovat na základě:

• Obtížnosti (začátečník, jednoduchá, pokročilá, těžká, nejtěžší)
• Názvu
• A datum poslední úpravy (za poslední 24 hodin, 7 dní, 1 měsíc, 3 měsíce)

V případě více filtrů hledáme průnik zadaných vlastností.

---

Fáze 4: Fullstack

Propojit imaginární kablíky s vaším backendem a frontendem, k tomu případně doladit detaily, učesat vlásky a máte skoro hotovo!

K vámi dodané aplikaci potřebujeme také základní readme, které nám o vaší aplikaci řekne něco víc. Tento soubor by měl být (dle konvencí) v kořenové složce vašeho repozitáře.

Za nás by bylo ideální kdybyste uvedli následující informace:

• Název a členové týmu
• Jaké technologie používá
• Jak se aplikace spouští
• Další informace, které uznáte za vhodné

Ujistěte se, že vaše aplikace nepoužívá Mockbush!

Tato část již nebude hodnocena automaticky, ale bude posuzována naším expertním týmem.

---

Odevzdání aplikace

K úspěšnému odevzdání vaší aplikace musíte provést následující:

• Kód vaší aplikace nahrát do repozitáře na platformě github.com a přidat jako spolupracovníka (‘collaborator’) uživatele “Tour-de-App-user”.
• využít GitHub akci, která se postará o nasazení na náš server. Jako parametry musíte této akci předat:
• Název a cestu k Docker image^[?] vaší aplikace, která bude mít jeden libovolný otevřený port. Tento port musí být zpřístupněný příkazem EXPOSE ČÍSLO_PORTU
• Identifikační token (TEAM_TOKEN), který získáte v našem testovacím systému (https://odevzdavani.tourdeapp.cz), kde se přihlásíte za pomocí e-mailu, který jste zadali při registraci, a hesla, co jste zadali při ověřování vašeho účtu

Pokud jste se s Dockerem či GitHubem ještě nesetkali, doporučujeme využít jednu z námi připravených šablon, které se postarají o vytvoření Docker image a spuštění GitHub akce. Dále vám doporučujeme navštívit webináře od Tour de App, kde tento proces projdete společně.

Testování aplikace

Běží vaše aplikace na našem serveru jak má? Skvěle! Teď to ale musíme zjistit i my.

V našem testovacím systému https://odevzdavani.tourdeapp.cz, uvidíte několik sad automatických testů, které se budou postupně odemykat v průběhu soutěže.

• Testy můžete spouštět vícekrát, ale uchovávat se bude jen nejlepší výsledek, vyjádřený v % úspěšně prošlých testů.
• S výjimkou 1. testu nebudou jednotlivé testy časově omezeny. První test bude z kapacitních důvodů uzamčen 20. 12. a je z něj potřeba získat alespoň 50% bodů (= pokud do té doby neodevzdáte alespoň 1. fázi, máte smůlu).

Závěrem

Ještě než se s vámi rozloučíme, tak chceme zmínit, že se tu skrývá flag{NĚCO-VELKÉHO}, co vám může otevřít nové možnosti, jak na vše pohlížet.

Mockrát vám jménem Think different Academy děkujeme, že se podílíte na šíření našich aktivit online. V případě nejasností prosím využijte primárně komunity (a případně členů TdA) na soutěžním Discordu. Hodně štěstí!