geoproject-app/claude.md

GeoProject - Web-to-Print Interface

Vue d'ensemble

Application web-to-print permettant la mise en page de récits (narratives) imprimables. L'édition de contenu se fait via Kirby CMS (headless), la mise en page est rendue par PagedJS, et l'interface d'édition réactive utilise Vue 3.

Stack technique

• Frontend: Vue 3 (Composition API) + Vite
• Print engine: PagedJS (CSS Paged Media)
• CMS: Kirby 5 (headless, flat-file)
• Backend: PHP 8.1+

Architecture

/src                         # Vue 3 SPA
  ├── main.js               # Bootstrap Vue
  ├── App.vue               # Root + init PagedJS
  ├── style.css             # Styles globaux
  ├── components/
  │   ├── blocks/           # COMPOSANTS DE BLOCS (HeadingBlock, TextBlock, etc.)
  │   │   └── index.js      # Export central des blocs
  │   ├── editor/           # PANNEAUX D'ÉDITION (PageSettings, TextSettings, etc.)
  │   ├── ui/               # COMPOSANTS UI RÉUTILISABLES (InputWithUnit, MarginEditor, etc.)
  │   ├── PagedJsWrapper.vue   # Wrapper principal PagedJS
  │   ├── ElementPopup.vue     # Popup d'édition d'élément
  │   ├── PagePopup.vue        # Popup d'édition de page
  │   ├── SidePanel.vue        # Panneau latéral
  │   ├── PreviewLoader.vue    # Loader de preview
  │   └── StylesheetViewer.vue # Viewer de feuilles de style
  ├── composables/          # COMPOSABLES VUE (useCssSync, useCssUpdater, etc.)
  ├── stores/               # STORES PINIA (narrative.js, stylesheet.js)
  └── utils/                # UTILITAIRES JS (css-parsing.js, etc.)

/api/cache                 # Cache des données API (donorbox_data.json, etc.)

/public                    # Kirby CMS + assets statiques
  ├── index.php           # Entry Kirby
  ├── composer.json       # Dépendances PHP
  ├── assets/
  │   ├── css/            # CSS sources (exclus du déploiement)
  │   ├── fonts/          # Webfonts
  │   └── svg/            # Icônes SVG
  ├── site/
  │   ├── blueprints/     # Schémas de contenu Kirby
  │   ├── templates/      # Templates PHP Kirby
  │   ├── snippets/       # Snippets PHP (header.php injecte Vue)
  │   ├── plugins/        # Plugins Kirby
  │   ├── accounts/       # Comptes utilisateurs (exclu déploiement)
  │   ├── cache/          # Cache Kirby (exclu déploiement)
  │   └── sessions/       # Sessions (exclu déploiement)
  ├── content/            # Contenus markdown Kirby
  └── media/              # Médias uploadés

/.forgejo/workflows        # CI/CD Forgejo
/Dockerfile.ci            # Image Docker pour CI (à copier sur VPS)

Flux de données

1. Kirby → Stocke/gère le contenu (flat-files)
2. Templates PHP → Rendent le wrapper HTML + injectent Vue
3. Vue → Interface réactive pour éditer la mise en page
4. PagedJS → Transforme le contenu en pages imprimables

Points clés

Intégration Vite/Kirby

/public/site/snippets/header.php gère le dev/prod :

• Dev : charge depuis localhost:5173
• Prod : charge depuis /assets/dist/

PagedJS

• CSS @page rules dans les composants Vue
• Initialisé via Previewer dans App.vue
• Preview navigable avec interface de navigation

State Management

• Pinia utilisé pour la gestion d'état
• stores/narrative.js : État du récit/narrative (contenu, navigation)
• stores/stylesheet.js : État des feuilles de style CSS

Conventions de placement (IMPORTANT : respecter cette organisation)

Nouveau composant de bloc (heading, text, image, etc.) → /src/components/blocks/NomBlock.vue + export dans blocks/index.js

Nouveau panneau d'édition/settings → /src/components/editor/NomSettings.vue

Nouveau composant UI réutilisable (input, bouton, etc.) → /src/components/ui/NomComposant.vue

Nouveau composable Vue (logique réutilisable) → /src/composables/useNomComposable.js

Nouveau store Pinia → /src/stores/nom.js

Nouvelle fonction utilitaire → /src/utils/nom-util.js

Cache API externe → /api/cache/nom_data.json

Nouveau template/snippet Kirby → /public/site/templates/ ou /public/site/snippets/

Nouveau blueprint Kirby → /public/site/blueprints/

Commandes

npm run dev      # Vite dev server (5173)
npm run build    # Build prod dans /public/assets/dist/
# Kirby sur serveur PHP séparé

Déploiement

CI/CD Forgejo

• Workflow : .forgejo/workflows/deploy.yml
• Image Docker : forgejo-ci-node:latest (construite depuis Dockerfile.ci)
• Déploiement via FTP avec lftp

Fichiers/dossiers exclus du déploiement FTP

assets/local/          # Assets locaux
assets/css/src/        # Sources SCSS
assets/css/*.css       # CSS compilés localement
assets/css/*.map       # Source maps
assets/css/*.scss      # Sources SCSS
site/accounts/         # Comptes utilisateurs
site/cache/            # Cache Kirby
site/sessions/         # Sessions actives

Build process

1. Clone du repo
2. npm ci : Install des dépendances
3. Copie de /public vers /dist
4. npm run build : Vite build dans /dist/assets/dist/
5. Déploiement FTP de /dist vers production

Conventions

• Composants Vue : PascalCase
• CSS : Variables pour theming, scoped styles
• Print CSS : W3C Paged Media spec
• Stores Pinia : camelCase pour les fichiers, PascalCase pour les noms (ex: useNarrativeStore)
• Composables : Préfixe use (ex: useCssSync)
• Code naming : English preferred (ex: narrative instead of recit)