Forge-Engine/document_engine/pages/pages.md

document_engine/pages/

CRUD des pages d'un support de formation (_document_pages, voir db/supports/create_support.py) — retour utilisateur du 21/09/2026: "il faut implémenter un système de page". Un support est désormais composé de plusieurs pages, chacune portant son propre flux d'éléments (voir document_engine/elements/, filtré par page_id). Un support a TOUJOURS au moins une page (create_support en crée une par défaut, ensure_document_pages_schema en garantit une pour les supports plus anciens) — la garde "jamais supprimer la dernière page" est un garde-fou métier posé par l'appelant (voir routes/document/document_page_delete.py), pas une contrainte de ce paquet.

add_document_page(slug: str, title: str | None = None) -> int

Ajoute une page en fin de la bande d'onglets. title par défaut : "Page N" (N = position 1-indexée + 1) si non fourni.

• Retour : l'id de la nouvelle page.
• Exceptions : aucune levée explicitement.

list_document_pages(slug: str) -> list[dict[str, Any]]

Toutes les pages du support, triées par order_index.

• Retour : liste de dicts (une ligne de table chacun).
• Exceptions : aucune.

get_document_page(slug: str, page_id: int) -> dict[str, Any] | None

Récupère une seule page par id.

• Retour : le dict de la page, ou None si l'id n'existe pas.
• Exceptions : aucune.

update_document_page(slug: str, page_id: int, title: str) -> None

Renomme une page. Un titre vide (une fois .strip()-é) est silencieusement ignoré — la page garde son titre précédent plutôt que de se retrouver sans nom dans la bande d'onglets.

• Retour : aucun.
• Exceptions : aucune.

move_document_page(slug: str, page_id: int, new_index: int) -> None

Réordonne une page dans la bande d'onglets (glisser-déposer) — renumérote intégralement order_index sur toutes les pages, même principe que document_engine.move_document_element (jamais un décalage un par un).

• Retour : aucun.
• Exceptions : aucune.

replace_document_content(slug: str, seed_pages: list[list[dict[str, Any]]]) -> None

Remplace TOUT le contenu du support par seed_pages — utilisée UNIQUEMENT quand le créateur choisit "utiliser le contenu du modèle" en appliquant un thème (voir routes/document/document_theme_apply.py et document_engine/themes/), jamais appelée sans confirmation explicite côté client (action destructive, irréversible côté serveur). seed_pages est une liste de pages, chaque page une liste de blocs {"kind", "attributes", "children"} (children optionnel, uniquement pour un bloc kind="row" — un seul niveau de profondeur, comme le moteur de rangées lui-même). Les attributs fournis sont fusionnés sur element_default_attributes(kind), jamais un remplacement brut. Les nouvelles pages sont créées AVANT que les anciennes soient supprimées (jamais l'inverse) : passer par zéro page, même brièvement, déclenche le filet de sécurité de ensure_document_pages_schema (un support a toujours au moins une page), qui recréerait une "Page 1" vide parasite.

• Retour : aucun.
• Exceptions : aucune levée explicitement.

delete_document_page(slug: str, page_id: int) -> None

Supprime une page ET ses éléments (DELETE FROM _document_elements WHERE page_id = ? explicite — la contrainte FOREIGN KEY ... ON DELETE CASCADE n'existe que pour les supports créés après l'ajout des pages, voir db/supports/ensure_document_pages_schema.py pour les anciens). Ne refuse JAMAIS de supprimer la dernière page restante — cette règle est posée par l'appelant, pas par cette fonction bas niveau (même découpage que routes/game/screens/screen_delete.py côté jeu, où le garde-fou vit aussi dans la route).

• Retour : aucun.
• Exceptions : aucune.