# Opis repozytorium pojedynczej karty Każda karta jest osobnym repozytorium lub samodzielnym katalogiem. Jej źródłem prawdy jest `json/card_source.json`; pliki TeX i HTML są artefaktami generowanymi. ## Minimalne drzewo ```text moja-karta/ ├── README.md ├── json/card_source.json ├── doc/ ├── web/ └── src/ ``` ## Obowiązkowe warstwy danych ### Metadane Obiekt `card` identyfikuje serię, numer, wersję, UUID, autora i status. Obiekt `generated` wskazuje ścieżki wyjściowe TeX/HTML/CSS. Pole `template` wybiera layout. Opcjonalny obiekt `title_block` włącza tabliczkę zasobu o wysokości dokładnie 3 cm na każdej stronie, także pierwszej, bibliografii, słownika i stronach kontynuacji. Tabliczka zastępuje dużą tabelę metadanych strony tytułowej. Zawiera kategorię, tytuł, metadane karty, numer strony oraz widoczny, kanoniczny URL. Ten sam URL jest kodowany lokalnie w QR: jako SVG w HTML i przez pakiet `qrcode` w TeX. Opcjonalny `repository_url` dodaje drugi QR do repozytorium. Przy dwóch kodach komórki mają po 27 mm: Gitea znajduje się po lewej, a wyrenderowany zasób po prawej. Jedna zamknięta ramka biegnie dokładnie między marginesami strony. W HTML widok ekranowy ma rozmiar A4 (210 × 297 mm) i nagłówek na każdej logicznej karcie, a wydruk używa `@page { size: A4; }` oraz pól marginesu, dlatego nagłówek powtarza się również po automatycznym podziale długiej sekcji. Pola `height_cm: 3`, `repeat_on_every_page: true` i `replace_front_matter: true` dokumentują ten kontrakt. `show_qr: true` wymaga kanonicznego adresu HTTP(S) w `url` albo pary `url_host_uuid`/`doc_uuid`, z której powstaje `https:///`. `show_repository_qr: true` wymaga `repository_url`. Adres podglądu `localhost` nie powinien być publikowany na karcie. ### Efekty i kryteria - `educational_requirements` — wymagania `WE`; - `learning_effects` — efekty `EN` lub `EK`; - `assessment_criteria` — mierzalne kryteria `KW`; - `educational_requirements.*.learning_tree` — połączenia renderowane na marginesach. Każdy wpis `learning_tree.ogolne[]` lub `learning_tree.zawodowe[]` ma stabilne `tree_id`, odwołanie `effect_ref`, etykietę `display` oraz co najmniej jedno powiązane `KW`. ### Sekcje i kroki Pole `sections[]` porządkuje treść. Kroki `sections[].steps[]` mają: - `id` i `title`; - `tree_refs` wskazujące drzewka z marginesów; - opcjonalne odwołania do wymagań, efektów, kryteriów, równań i figur. ### Referencje zewnętrzne bez kopiowania treści Karta może ładować kanoniczne rejestry współdzielonych strategii, kart, treści i wzorów. Lokalny plik JSON służy do walidacji oraz deterministycznego buildu: ```json { "reference_registries": [ { "uuid": "03403a8a-e20d-5b17-9004-26d9fe6c3003", "source": "../../../tools/debugging-strategies/json/reference_registry.json" } ] } ``` Krok przechowuje tylko rodzaj, UUID rejestru i UUID wpisu: ```json { "references": [ { "kind": "strategy", "registry_uuid": "03403a8a-e20d-5b17-9004-26d9fe6c3003", "uuid": "1ecfc474-4fbd-5a56-8ef1-80ae557761d0" } ] } ``` Generator pobiera z rejestru etykietę, tytuł, ścieżkę i publiczny adres. Strategię pokazuje jako kod `Mxx`, kartę jako jej nazwę, a treść lub wzór jako kanoniczną etykietę. W TeX/PDF i HTML etykieta jest hiperłączem. Nazw ani URL-i nie kopiujemy do `card_source.json`; brak rejestru, UUID albo lokalnego pliku przerywa generowanie. Layouty 5a/5b obsługują również: - `model_block.steps` — kroki modelowania; - `code_block.blocks[].web_steps` — interaktywne kroki HTML; - `hardware_procedure[]` — tabela `step/action/condition` w TeX i HTML. `code_block.blocks[]` jest rzeczywistym podziałem na bloki: każdy wpis jest renderowany jako osobna, opisana ramka w sekcji implementacyjnej, a jego `web_steps` zasila niezależną checklistę HTML. Kolejność głównych bloków strony jest opisana przez `block_map` wybranego szablonu. ### Zrzuty ekranu i inne assety sekcji Zrzutów nie wpisujemy jako ręcznego `\\includegraphics` w wygenerowanym TeX. Sekcja może deklarować listę `assets`, a generator umieszcza każdy element w TeX/PDF i HTML, kopiuje plik do `figures/` strony oraz dodaje link do pełnego rozmiaru: ```json { "title": "Pomiar w debuggerze", "content_tex": "Zatrzymaj program przed pierwszą alokacją.", "assets": [ { "path": "assets/task04-first-allocation-annotated.png", "caption": "Task04 przed pierwszym przydziałem pamięci.", "label": "fig:task04-first-allocation", "alt": "Termdebug: kod C, listing, rejestry i allocbuf", "kind": "screenshot", "width": 1.0 } ] } ``` - `path` jest liczony względem katalogu `doc/` karty; standardem jest `doc/assets/`; - obsługiwane są PNG, JPG/JPEG i PDF; - `width` jest ułamkiem szerokości kolumny od `0.1` do `1.0`; - `label` jest stabilnym identyfikatorem używanym przez `figure_refs`; - `full_size_link` domyślnie włącza otwieranie zrzutu HTML w pełnym rozmiarze. ### Zadania `tasks` jest słownikiem zadań, a `tasks_order` określa ich kolejność. Każde zadanie posiada polecenie `prompt_tex`, kryterium zaliczenia i odwołania do modelu edukacyjnego. Rozbudowane zadanie przechowuje przebieg dydaktyczny w uporządkowanym `tasks..flow[]`: - `kind: "block"` grupuje jedną część objaśnienia lub demonstracji; - opcjonalne `block.steps[]` zachowują kolejność czynności wewnątrz bloku; - `kind: "exercise"` jest samodzielną pracą ucznia należącą bezpośrednio do zadania i podaje `prompt_tex`, `evidence_tex` oraz `criterion`; - `exercise.based_on[]` może wskazać wcześniejsze bloki lub ich kroki. Bloki i ćwiczenia są rodzeństwem w jednym `flow`, dzięki czemu renderer nie gubi kolejności nauczania. `steps` nie może występować bezpośrednio w obiekcie zadania. Dawne `prompt_tex` i `criterion` pozostają wymagane dla zgodności ze starszymi konsumentami; gdy istnieje `flow`, renderer używa jego treści. ## Zalecany README karty README konkretnej karty powinien zawierać: 1. nazwę, numer i miejsce w serii; 2. cel oraz rezultat obserwowalny; 3. mapowanie do źródeł i efektów nauczania; 4. listę kroków/zadań; 5. polecenia generowania i testowania; 6. warunek `PASS`; 7. informację, które pliki są źródłowe, a które generowane. Gotowy przykład znajduje się w `examples/card/README.md`. ## Generowanie Z katalogu repozytorium `card-layouts`: ```bash python3 tools/render_card.py /sciezka/do/mojej-karty ``` Generator najpierw sprawdza spójność identyfikatorów WE/EN/EK/KW, kroków, zadań, rejestrów UUID i odwołań, a dopiero potem zapisuje oba formaty.