bogdan Remove stale RPI unattended prototype

1115ed9 3 weeks ago History

# Agent README

## Scope

Acest fisier este pentru agentii si toolurile care folosesc acest repository ca baza pentru importuri media automate, inclusiv rulari unattended din udev, systemd, cron, pipeline-uri NAS sau wrapper-e generate.

Scriptul principal validat este:

```text
media-importer.sh
```

Prototipurile Raspberry Pi / unattended wrapper au fost eliminate din repository deoarece erau bazate pe o versiune invechita si netestata a importerului. Nu le recreati si nu le folositi ca reference design fara o decizie explicita de reluare a acelei directii.

## Context critic: incidente de pierdere de date

Au existat pierderi reale de date in mediul nostru cu versiuni anterioare ale importerului. Incidentul documentat in `INCIDENTS.md` a fost declansat de fisiere GoPro chapter care au ajuns sa fie mapate la acelasi nume destinatie. Scriptul vechi a continuat dupa conflict, copia/mutarea a suprascris destinatia existenta, verificarea a validat fisierul suprascris, iar sursele au fost sterse.

Orice agent care copiaza, deriva, rescrie sau integreaza acest script intr-un tool unattended trebuie sa verifice explicit ca nu reintroduce bugurile care au dus la acea pierdere de date.

## Reguli obligatorii pentru import unattended

- Nu folositi variante vechi, copii locale sau scripturi derivate fara comparatie cu protectiile curente din `media-importer.sh`.
- Nu folositi `cp`, `mv`, `rsync` sau alte unelte lasate sa rezolve singure conflictele de destinatie. Conflictele trebuie rezolvate in cod inainte de operatie.
- Nu suprascrieti niciodata o destinatie existenta.
- Nu stergeti sursa pana cand destinatia nu exista si verificarea a trecut.
- In move mode, fluxul sigur este `copy -> verify -> delete source`; nu inlocuiti acest flux cu `mv` direct in scripturi unattended.
- Destinatiile planificate in aceeasi rulare trebuie rezervate in memorie, ca doua surse sa nu poata ajunge la acelasi path chiar daca fisierul destinatie nu exista inca.
- Pentru conflicte unattended, comportamentul acceptat este suffix numeric unic (`_1`, `_2`, ...), skip explicit sau abort. Nu este acceptat overwrite silentios.
- Daca destinatia este in interiorul sursei, destinatia trebuie exclusa din scanare, iar orice fisier aflat deja in destinatie trebuie refuzat inainte de procesare.
- Pentru camere GoPro/Garmin/Varia sau fisiere QuickTime, nu modificati logica de data/timp fara teste de regresie; timestampurile identice sunt un caz normal, nu o eroare de intrare.

## Checklist pentru copii sau scripturi derivate

Inainte ca o copie sau derivare sa fie folosita unattended, verificati ca include echivalentul acestor protectii:

- `safe_cp` si `safe_mv` refuza destinatii existente.
- Copierea se face intr-un fisier temporar, se verifica temporarul, apoi se muta in destinatia finala doar daca destinatia finala nu exista.
- `VERIFY_MODE=size` este default; `strict` este disponibil pentru comparatie byte-to-byte.
- Stergerea sursei are loc doar dupa verificarea destinatiei.
- Conflictele de destinatie sunt rezolvate prin `resolve_destination_conflict` / `ensure_unique_destination_path` sau logica echivalenta.
- Path-urile destinatie deja planificate sunt rezervate, nu doar cele existente pe disk.
- Testul `timestamp-collision` trece.
- Dry-run-ul pentru camere noi arata destinatii distincte pentru fiecare fisier.

## Teste minime inainte de automatizare

Pentru orice schimbare care atinge importul, copierea, mutarea, verificarea, stergerea sursei, generarea numelor sau extragerea datelor, rulati cel putin:

```bash
./test_runner.sh timestamp-collision
./test_runner.sh verify-mode
./test_runner.sh dest-in-source
```

Pentru schimbari legate de GoPro sau metadata sidecar, rulati si:

```bash
./test_runner.sh gopro-sidecar-sync
./test_runner.sh gopro-no-sidecar-reimport
```

Daca aceste teste nu pot fi rulate, agentul trebuie sa marcheze integrarea ca nevalidata si sa nu recomande unattended move mode.

## Recomandari operationale

Pentru camere sau destinatii noi, prima rulare trebuie sa fie dry-run:

```bash
./media-importer.sh -s "/path/to/camera" -d "/path/to/destination" --dry-run -v
```

Verificati in output ca:

- fiecare fisier sursa are o destinatie distincta;
- nu exista mesaje de overwrite;
- conflictele sunt suffixate, sarite explicit sau duc la abort;
- pentru GoPro, sursa datei este cea asteptata, inclusiv sidecar `THM`/`LRV` cand exista.

Pentru date cu valoare mare sau cand sursa poate fi pastrata, preferati temporar:

```bash
./media-importer.sh -s "/path/to/camera" -d "/path/to/destination" --verify-mode strict --keep-originals -v
```

## Regula de oprire

Daca un agent gaseste o copie a scriptului care:

- foloseste `mv` direct in move mode;
- permite overwrite;
- sterge sursa fara verificare;
- nu rezerva destinatii planificate;
- sau nu poate demonstra ca trece testul `timestamp-collision`;

atunci agentul trebuie sa opreasca integrarea unattended si sa raporteze riscul ca posibil bug de pierdere de date.