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

```bash
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`)