Add shared card schemas layouts and renderer

2026-07-15 08:41:20 +02:00
commit 65299458ed
19 changed files with 7786 additions and 0 deletions
@@ -0,0 +1,81 @@
+# 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.
+
+### 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.
+
+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.
+
+### 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.
+
+## 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ń i odwołań, a dopiero potem zapisuje oba formaty.