Deploy / Build and Deploy to Production (push) Successful in 15s

Details

docs: update CLAUDE.md with detailed project structure and conventions

- Add comprehensive architecture documentation with all component folders
- Document placement conventions for blocks, editor panels, UI components
- Add CI/CD deployment details and excluded files
- Remove donorbox cache file from repository

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-08 16:22:32 +01:00

5.5 KiB

Raw Blame History

GeoProject - Web-to-Print Interface

Vue d'ensemble

Application web-to-print permettant la mise en page de récits 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 (recit.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

Kirby → Stocke/gère le contenu (flat-files)
Templates PHP → Rendent le wrapper HTML + injectent Vue
Vue → Interface réactive pour éditer la mise en page
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/recit.js : État du récit (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

Clone du repo
npm ci : Install des dépendances
Copie de /public vers /dist
npm run build : Vite build dans /dist/assets/dist/
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: useRecitStore)
Composables : Préfixe use (ex: useCssSync)

5.5 KiB Raw Blame History