MediaImporter
/
AGENTS.md
Newer
■
■
■
■
■
■
■
■
■
■
Older
96 lines
|
4.984kb
| 1 |
# Agent README |
|
| 2 | ||
| 3 |
## Scope |
|
| 4 | ||
| 5 |
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. |
|
| 6 | ||
| 7 |
Scriptul principal validat este: |
|
| 8 | ||
| 9 |
```text |
|
| 10 |
media-importer.sh |
|
| 11 |
``` |
|
| 12 | ||
| 13 |
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. |
|
| 14 | ||
| 15 |
## Context critic: incidente de pierdere de date |
|
| 16 | ||
| 17 |
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. |
|
| 18 | ||
| 19 |
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. |
|
| 20 | ||
| 21 |
## Reguli obligatorii pentru import unattended |
|
| 22 | ||
| 23 |
- Nu folositi variante vechi, copii locale sau scripturi derivate fara comparatie cu protectiile curente din `media-importer.sh`. |
|
| 24 |
- Nu folositi `cp`, `mv`, `rsync` sau alte unelte lasate sa rezolve singure conflictele de destinatie. Conflictele trebuie rezolvate in cod inainte de operatie. |
|
| 25 |
- Nu suprascrieti niciodata o destinatie existenta. |
|
| 26 |
- Nu stergeti sursa pana cand destinatia nu exista si verificarea a trecut. |
|
| 27 |
- In move mode, fluxul sigur este `copy -> verify -> delete source`; nu inlocuiti acest flux cu `mv` direct in scripturi unattended. |
|
| 28 |
- 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. |
|
| 29 |
- Pentru conflicte unattended, comportamentul acceptat este suffix numeric unic (`_1`, `_2`, ...), skip explicit sau abort. Nu este acceptat overwrite silentios. |
|
| 30 |
- Daca destinatia este in interiorul sursei, destinatia trebuie exclusa din scanare, iar orice fisier aflat deja in destinatie trebuie refuzat inainte de procesare. |
|
| 31 |
- 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. |
|
| 32 | ||
| 33 |
## Checklist pentru copii sau scripturi derivate |
|
| 34 | ||
| 35 |
Inainte ca o copie sau derivare sa fie folosita unattended, verificati ca include echivalentul acestor protectii: |
|
| 36 | ||
| 37 |
- `safe_cp` si `safe_mv` refuza destinatii existente. |
|
| 38 |
- Copierea se face intr-un fisier temporar, se verifica temporarul, apoi se muta in destinatia finala doar daca destinatia finala nu exista. |
|
| 39 |
- `VERIFY_MODE=size` este default; `strict` este disponibil pentru comparatie byte-to-byte. |
|
| 40 |
- Stergerea sursei are loc doar dupa verificarea destinatiei. |
|
| 41 |
- Conflictele de destinatie sunt rezolvate prin `resolve_destination_conflict` / `ensure_unique_destination_path` sau logica echivalenta. |
|
| 42 |
- Path-urile destinatie deja planificate sunt rezervate, nu doar cele existente pe disk. |
|
| 43 |
- Testul `timestamp-collision` trece. |
|
| 44 |
- Dry-run-ul pentru camere noi arata destinatii distincte pentru fiecare fisier. |
|
| 45 | ||
| 46 |
## Teste minime inainte de automatizare |
|
| 47 | ||
| 48 |
Pentru orice schimbare care atinge importul, copierea, mutarea, verificarea, stergerea sursei, generarea numelor sau extragerea datelor, rulati cel putin: |
|
| 49 | ||
| 50 |
```bash |
|
| 51 |
./test_runner.sh timestamp-collision |
|
| 52 |
./test_runner.sh verify-mode |
|
| 53 |
./test_runner.sh dest-in-source |
|
| 54 |
``` |
|
| 55 | ||
| 56 |
Pentru schimbari legate de GoPro sau metadata sidecar, rulati si: |
|
| 57 | ||
| 58 |
```bash |
|
| 59 |
./test_runner.sh gopro-sidecar-sync |
|
| 60 |
./test_runner.sh gopro-no-sidecar-reimport |
|
| 61 |
``` |
|
| 62 | ||
| 63 |
Daca aceste teste nu pot fi rulate, agentul trebuie sa marcheze integrarea ca nevalidata si sa nu recomande unattended move mode. |
|
| 64 | ||
| 65 |
## Recomandari operationale |
|
| 66 | ||
| 67 |
Pentru camere sau destinatii noi, prima rulare trebuie sa fie dry-run: |
|
| 68 | ||
| 69 |
```bash |
|
| 70 |
./media-importer.sh -s "/path/to/camera" -d "/path/to/destination" --dry-run -v |
|
| 71 |
``` |
|
| 72 | ||
| 73 |
Verificati in output ca: |
|
| 74 | ||
| 75 |
- fiecare fisier sursa are o destinatie distincta; |
|
| 76 |
- nu exista mesaje de overwrite; |
|
| 77 |
- conflictele sunt suffixate, sarite explicit sau duc la abort; |
|
| 78 |
- pentru GoPro, sursa datei este cea asteptata, inclusiv sidecar `THM`/`LRV` cand exista. |
|
| 79 | ||
| 80 |
Pentru date cu valoare mare sau cand sursa poate fi pastrata, preferati temporar: |
|
| 81 | ||
| 82 |
```bash |
|
| 83 |
./media-importer.sh -s "/path/to/camera" -d "/path/to/destination" --verify-mode strict --keep-originals -v |
|
| 84 |
``` |
|
| 85 | ||
| 86 |
## Regula de oprire |
|
| 87 | ||
| 88 |
Daca un agent gaseste o copie a scriptului care: |
|
| 89 | ||
| 90 |
- foloseste `mv` direct in move mode; |
|
| 91 |
- permite overwrite; |
|
| 92 |
- sterge sursa fara verificare; |
|
| 93 |
- nu rezerva destinatii planificate; |
|
| 94 |
- sau nu poate demonstra ca trece testul `timestamp-collision`; |
|
| 95 | ||
| 96 |
atunci agentul trebuie sa opreasca integrarea unattended si sa raporteze riscul ca posibil bug de pierdere de date. |