Plik mapy kodów DurableQR, format w wersji 1

Plik mapy kodów to kompletny spis kodów jednego konta DurableQR: dla każdego kodu określa, dokąd prowadzi skan. Powstał po to, aby wydrukowane kody mogły działać bez DurableQR. Resolver, czyli program, który odczytuje ten plik i odpowiada na skany według reguł z sekcji „Jak obsłużyć skan”, zwraca ten sam status, cel, obsługę ścieżki i nagłówki prywatności co DurableQR, z jednym opisanym wyjątkiem.

Format jest otwarty. Ten dokument, program sprawdzający poprawność pliku (walidator) i pliki przykładowe stanowią całą specyfikację. Decyzje projektowe opisuje ADR-0006 (docs/adr/0006-map-file-v1.md, po polsku).

Pliki

Plik mapy kodów występuje w jednym z dwóch zapisów (kodowań) o identycznej treści:

Każdy plik mapy kodów jest publikowany razem z <nazwa pliku>.sha256 (zob. „Suma kontrolna”).

Reguły bajtów (oba kodowania)

Plik bez rekordów jest poprawny: zawiera tylko wiersz formatu (oraz, dla CSV, nagłówek kolumn).

Kolumny

Każdy rekord ma dokładnie siedem pól w tej kolejności:

KolumnaTypZnaczenie
stable_id10 znaków z 0-9 A-Z, bez I L O UIdentyfikator kodu, segment ścieżki wydrukowany w kodzie QR.
current_urlURL albo brakDokąd kod kieruje skan teraz. Brak wyłącznie wtedy, gdy state to deleted.
fallback_urlURL albo brakAwaryjny adres właściciela. Brak, gdy właściciel go nie ustawił; zawsze brak dla deleted.
updated_atznacznik czasuKiedy utworzono wersję version, czyli kiedy kod ostatnio się zmienił.
actormałe litery, identyfikator szesnastkowy 8-4-4-4-12Identyfikator użytkownika nadany przez usługę logowania; wskazuje osobę z konta, która utworzyła tę wersję. To nie jest e-mail.
versionliczba całkowita od 1 do 9007199254740991Numer wersji kodu, zwiększany przy każdej zmianie.
stateactive, grace, frozen, paused, blocked albo deletedStan cyklu życia kodu. Zob. „Jak obsłużyć skan”.

URL. Zaczyna się od http:// albo https:// (wielkość liter schematu jest dowolna), ma co najmniej jeden znak po //, a jego długość wynosi najwyżej 2048 bajtów UTF-8. Niedozwolone są określone znaki sterujące, odwrotne ukośniki i znaki białe zgodnie z pełną regułą formatu. URL jest przechowywany bajt w bajt tak, jak podał go właściciel: bez normalizacji i bez dodawania ukośnika.

Znacznik czasu. UTC, dokładnie YYYY-MM-DDTHH:MM:SS.mmmZ, z trzema cyframi milisekund i literalnym Z, na przykład 2026-09-01T08:15:02.041Z. Musi oznaczać rzeczywisty moment.

Historia. Plik mapy kodów w wersji 1 zawiera tylko bieżący stan każdego kodu, bez wcześniejszych miejsc docelowych. Historia zmian nie jest częścią tego formatu; historię każdego kodu odczytasz przez API i panel.

Kodowanie CSV

# durableqr-map-file format_version=1
stable_id,current_url,fallback_url,updated_at,actor,version,state
3KQ7M2XWZP,https://example.com/menu,,2026-09-01T08:15:02.041Z,0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40,1,active

Kodowanie JSONL

{"format":"durableqr-map-file","format_version":1}
{"stable_id":"3KQ7M2XWZP","current_url":"https://example.com/menu","fallback_url":null,"updated_at":"2026-09-01T08:15:02.041Z","actor":"0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40","version":1,"state":"active"}

Wersja formatu

Resolver musi sprawdzić format_version w pierwszym wierszu, zanim odczyta resztę, i odrzucić nieznaną wersję. Ten dokument definiuje wyłącznie wersję 1.

Suma kontrolna

Suma to SHA-256 dokładnych bajtów pliku mapy kodów, razem z wierszem formatu. Jest publikowana obok pliku jako <nazwa pliku>.sha256 w formacie sha256sum: 64 małe cyfry szesnastkowe, dwie spacje, sama nazwa pliku i LF.

56434275ccc78eac27629649b77f0ee4c4ea193dc95d5c27cb2c89a4d007a5fe  example.csv

Sprawdź ją bez narzędzia DurableQR: sha256sum -c example.csv.sha256, a na macOS shasum -a 256 -c example.csv.sha256.

Jak obsłużyć skan

Resolver odpowiada na skan https://<host>/<stable_id>. Identyfikator jest pierwszym segmentem ścieżki: początkowe i końcowe / są ignorowane, wszystko po następnym / jest pomijane, a parametry zapytania (query string) nie należą do ścieżki. Dopasowanie uwzględnia wielkość liter.

Dla pustego identyfikatora albo identyfikatora bez rekordu odpowiedź to 404. Dla rekordu odpowiedź zależy od state i obecności fallback_url:

statefallback_urlOdpowiedź
active, grace, frozendowolne302 do current_url
pausedobecne302 do fallback_url
pausedbrak200, neutralna informacja o pauzie, bez reklam
blockeddowolne200, informacja o nadużyciu z procedurą odwołania
deletedzawsze brak404, identyczne jak dla nieistniejącego rekordu

Każda odpowiedź resolvera ma nagłówki Cache-Control: no-store, Referrer-Policy: no-referrer oraz Content-Type: text/html; charset=utf-8, z wyjątkami infrastrukturalnymi opisanymi w źródłowej wersji angielskiej. Odpowiedź 302 ma Location ustawione bajt w bajt na URL i pustą treść odpowiedzi. Brak URL wybranej odpowiedzi oznacza 404, nigdy przekierowanie z pustym Location.

Stany grace i frozen nie zmieniają celu skanu. blocked ma pierwszeństwo przed adresem awaryjnym. Po usuniętym kodzie zostaje znacznik usunięcia (tombstone), żeby jego identyfikatora nie przydzielić ponownie.

Walidator i przykłady

Referencyjny walidator to webapp/scripts/check-map-file.mjs (Node.js 22, bez zależności poza biblioteką standardową):

cd webapp
npm run check:map-file -- path/to/map.csv path/to/map.jsonl

Sprawdza każdą regułę tego dokumentu i plik .sha256 obok każdego pliku mapy kodów; przy każdym problemie podaje numer wiersza. Kończy się kodem 0, gdy wszystkie pliki są poprawne.

Pliki przykładowe znajdują się w webapp/scripts/__fixtures__/map-file-v1/ (example.csv, example.jsonl i ich pliki .sha256). Programy eksportujące i resolvery mogą na nich sprawdzać zgodność z formatem. Cztery pliki pozostają współdzielone przez wersję angielską i polską.

Plik historii celów v1