backend/app/refs.py

"""Numéros de référence d'événements — lisibles et recherchables côté admin.

Format : `PREFIX-NNNNNN` (id zéro-paddé sur 6). Déterministe : un événement a
toujours la même référence ; aucune colonne ajoutée en base, l'id (clé primaire)
suffit. Les références ne sont PAS des secrets — le `claim_token` reste le seul
accès privé du propriétaire. Elles servent au support : si un usager écrit en
citant « VU-000019 », on retrouve l'événement instantanément (cf. /admin).

Types :
- cat      → SUIV : déclaration d'un chat perdu (ce que le propriétaire « suit »)
- poster   → AFFI : affiche partagée par un passant
- sighting → VU   : chat repéré / signalé par un trouveur
- lead     → SIGN : signalement transmis au propriétaire (« c'est lui »)
"""
from __future__ import annotations

PREFIXES: dict[str, str] = {
    "cat": "SUIV",
    "poster": "AFFI",
    "sighting": "VU",
    "lead": "SIGN",
}
_BY_PREFIX: dict[str, str] = {v: k for k, v in PREFIXES.items()}


def make_ref(kind: str, id: int) -> str:
    """(kind, id) → « VU-000019 ». kind ∈ PREFIXES."""
    return f"{PREFIXES[kind]}-{id:06d}"


def parse_ref(ref: str) -> tuple[str, int] | None:
    """« vu-19 » / « VU-000019 » → (\"sighting\", 19). None si invalide."""
    ref = (ref or "").strip().upper()
    prefix, _, num = ref.partition("-")
    kind = _BY_PREFIX.get(prefix)
    if not kind or not num.isdigit():
        return None
    return kind, int(num)