williamandClaude Sonnet 5
64ee7292d4
document_engine.md listait encore seulement 3 sous-dossiers alors que pages/ existait déjà avant cette session — corrigé au passage. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# 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.
|