# Mapa importu CSV — instrukcja dla Google Sheets

Nie tworzymy pliku CSV ręcznie. Źródłem prawdy jest jeden arkusz Google Sheets,
a do GUI pobieramy jego eksport CSV. Jeden CSV opisuje wszystkie kursy Dxx,
które mają być importowane.

## Arkusz Google Sheets

Utwórz kartę, na przykład `MAPA_IMPORTU`. W pierwszym wierszu wpisz dokładnie:

```text
kurs | sekcja | tytuł | lesson_id
```

Alternatywnie ostatnią kolumną może być `url` albo można mieć obie kolumny:

```text
kurs | sekcja | tytuł | url | lesson_id
```

Rekomendowany przykład:

| kurs | sekcja | tytuł | lesson_id |
| --- | ---: | --- | ---: |
| D22 | 1 | Wprowadzenie do kursu | 12345 |
| D22 | 2 | Budowa układu | 12346 |
| D22 | 3 | Bezpieczeństwo pracy | 12347 |
| D23 | 1 | Wprowadzenie | 12401 |

`lesson_id` to liczba z adresu lekcji EdTool. Dla adresu
`https://.../uco-lessons/12345/` ID wynosi `12345`. Można wkleić cały adres do
kolumny `url` zamiast przepisywać ID. Jeżeli są obie kolumny, muszą wskazywać
to samo ID.

## Znaczenie kolumn

- `kurs` — kod kursu Moodle, np. `D01`, `D22`, `D48`.
- `sekcja` — oznaczenie lekcji w programie kursu. Dla zwykłych kursów jest to
  numer docelowej sekcji Moodle, np. `1`, `2`, `17`. Historyczne oznaczenia
  BCU typu `4A` i `4B` są także poprawne: importer zachowuje kolejność CSV i
  mapuje je na kolejne rzeczywiste sekcje Moodle (po `4` są to `5` i `6`).
- `tytuł` — pełny tytuł lekcji; jest porównywany kontrolnie z EdTool oraz
  Moodle, ale nie służy do wyszukiwania lekcji.
- `lesson_id` — zalecany, trwały identyfikator lekcji EdTool.
- `url` — alternatywa dla `lesson_id`; pełny link EdTool zawierający
  `/uco-lessons/<id>`.

## Reguły, które blokują import

1. Każdy wiersz lekcji ma kurs, dodatni numer sekcji, tytuł i `lesson_id` albo
   poprawny URL EdTool.
2. Oznaczenia typu `4A`, `6B` są obsługiwane dla historycznej mapy BCU.
   Pusta sekcja nadal wymaga poprawy — nie da się ustalić kolejności lekcji.
3. Nie powtarzaj pary `kurs + sekcja` ani `lesson_id` w dwóch wierszach.
4. Nie sortuj tylko fragmentu tabeli. Najbezpieczniej powtarzać kod `Dxx` w
   każdym wierszu, nawet że parser toleruje puste komórki po pierwszym kursie.
5. Wiersze `TEST` i `EXTRA` bez numerycznej sekcji nie są importowane.
   Wiersz techniczny `BRAKUJE MATERIAŁÓW` z eksportu BCU także jest pomijany.

## Eksport i użycie w GUI

1. W Google Sheets wybierz kartę `MAPA_IMPORTU`.
2. `Plik` → `Pobierz` → `Wartości rozdzielane przecinkami (.csv, bieżący arkusz)`.
3. W GUI otwórz **Mapa CSV**, wybierz plik i kliknij **Sprawdź i dodaj CSV**.
4. Przeczytaj wynik walidacji. Popraw błędne kursy w Sheets i wyeksportuj
   ponownie, jeśli są błędy.
5. Kliknij **Użyj tej mapy**. Dopiero od tej chwili nowe preflighty i joby
   używają jej danych.

Istniejący job zachowuje kopię ścieżki do mapy, z którą został utworzony;
zmiana aktywnego CSV nie zmienia jego planu w trakcie pracy.