designtopack/CLAUDE.md

Design to Pack - Vue d'ensemble du projet

Plateforme de gestion de projets de création de flacons de parfum pour Pochet du Courval.

Stack technique

Couche	Technologies
Backend	Kirby CMS 4 (PHP), flat-file database
Frontend	Vue 3 + Vite 7, Pinia, Vue Router 4, PrimeVue 4.0
PDF	@vue-pdf-viewer 2.5
3D	Three.js (vue interactive 360)
Déploiement	GitLab CI/CD, rsync vers serveur

---

Structure du projet

design-to-pack/
├── src/                          # App Vue.js
│   ├── assets/css/               # Styles globaux
│   ├── components/               # Composants réutilisables
│   │   ├── comments/             # Système de commentaires
│   │   ├── design-to-light/      # Feature DTL
│   │   ├── inspirations/         # Galerie inspirations
│   │   ├── notifications/        # Notifications
│   │   └── project/              # Composants projet
│   │       ├── cards/            # Cartes par type d'étape
│   │       ├── brief/            # Brief client (moodboard)
│   │       └── virtual-sample/   # Échantillon virtuel 3D
│   ├── router/                   # Vue Router
│   ├── stores/                   # Pinia stores
│   ├── utils/                    # Utilitaires
│   ├── views/                    # Pages principales
│   ├── main.js                   # Point d'entrée
│   └── App.vue                   # Composant racine
│
├── public/                       # Kirby CMS
│   ├── content/                  # Données (flat-file)
│   │   ├── projects/             # Pages projets
│   │   ├── clients/              # Pages clients
│   │   ├── design-to-light/      # Page DTL
│   │   └── inspirations/         # Galerie inspirations
│   ├── site/
│   │   ├── blueprints/           # Schémas de données
│   │   │   ├── pages/            # Blueprints des pages
│   │   │   ├── users/            # Blueprints utilisateurs
│   │   │   └── files/            # Blueprints fichiers
│   │   ├── templates/            # Templates PHP + JSON
│   │   ├── controllers/          # Contrôleurs
│   │   ├── models/               # Modèles PHP (Project, Client)
│   │   ├── plugins/              # Plugins custom
│   │   ├── snippets/             # Fragments réutilisables
│   │   └── config/               # Configuration + routes
│   └── media/                    # Fichiers uploadés
│
├── package.json
├── vite.config.js
└── .gitlab-ci.yml

---

Plugins Kirby custom

1. classes/ - Classes partagées

Classes de données utilisées par comments et notifications.

Classe	Rôle
Author	Auteur (name, email, uuid, role)
Position	Position x/y + pageIndex (marqueurs sur PDF)
Location	Localisation (page, file, parent)
PageDetails	Détails de page
FileDetails	Détails de fichier
ProjectDetails	Détails de projet

2. comments/ - Système de commentaires

Plugin adrienpayet/kirby4-comments

Classes:

• BaseComment - Classe de base
• Comment - Commentaire avec replies
• Reply - Réponse à un commentaire

Routes:

Route	Fichier	Description
POST /create-comment.json	routes/create.php	Créer un commentaire
POST /update-comment.json	routes/update.php	Modifier un commentaire
POST /delete-comment.json	routes/delete.php	Supprimer un commentaire
POST /reply-comment.json	routes/reply.php	Répondre à un commentaire

Stockage: Les commentaires sont stockés en YAML dans les métadonnées des fichiers.

3. notifications/ - Système de notifications

Plugin adrienpayet/pdc-notifications

Classes:

• Notification - Notification (type, location, text, author, date, readby[])
• NotificationsPage - Base pour pages avec notifications (extends Page)

Méthodes NotificationsPage:

• createNotification($data) - Créer une notification
• deleteNotification($id) - Supprimer une notification
• readNotification($id) - Marquer comme lue (ajoute userUuid à readby)
• readAllNotifications() - Tout marquer comme lu

Routes:

Route	Description
POST /read-notification.json	Marquer une notification comme lue
POST /read-all-notifications.json	Tout marquer comme lu

4. user-projects/ - Projets autorisés par utilisateur

Plugin adrienpayet/pdc-authorized-projects

User methods:

• currentProjects() - Projets actifs (listed) accessibles à l'utilisateur
• archivedProjects() - Projets archivés (unlisted) accessibles

Logique: Admin = tous les projets, autres = seulement projets assignés.

5. helpers/ - Fonctions utilitaires

Fonction	Description
getFileData($file, $preserveQuality)	Normalise les données fichier (thumb webp, cover, comments)
getGlobalEvaluation($numberedGrade)	Convertit note numérique en lettre A-E avec mention
processDTLProposals($page)	Traite les propositions Design to Light
refreshProjectStepsCache($project, $steps)	Rafraîchit le cache des étapes

6. icons/ - Icônes custom panel

Plugin adrienpayet/pochet-icons - Icônes personnalisées pour le panel Kirby.

7. kql/ - Kirby Query Language

Plugin externe pour requêtes type GraphQL.

8. refresh-cache-button/ - Bouton refresh cache

Plugin externe ajoutant un bouton de rafraîchissement du cache dans le panel.

---

Modèles de données

Utilisateurs (3 rôles)

Rôle	Accès
admin	Tous les projets, panel complet
pochet	Projets assignés uniquement, panel limité
client	Ses projets uniquement, pas de panel

Projet (ProjectPage)

Hérite de NotificationsPage.

Champs principaux:

• title, status (draft/listed/unlisted)
• client - Lien vers ClientPage
• currentStep - Étape courante
• isDTLEnabled - Design to Light activé

Étapes (children):

1. client-brief - Brief client (PDF + moodboard)
2. proposal - Proposition commerciale (PDFs)
3. extended-brief - Brief étendu
4. industrial-ideation - Idéation industrielle (optionnel)
5. virtual-sample - Échantillon virtuel (pistes dynamiques + statiques)
6. physical-sample - Échantillon physique (médias)

Client (ClientPage)

• logo, title
• projects() - Tous les projets
• projectsListed() / projectsUnlisted() - Filtres par statut

---

Stores Pinia

Store	Fichier	Rôle
api	stores/api.js	Communication API (fetch, post, comments, notifications)
user	stores/user.js	Utilisateur courant, permissions
page	stores/page.js	Données de la page courante
projects	stores/projects.js	Liste des projets
dialog	stores/dialog.js	État des modales (contenu, fichier, commentaires)
brief	stores/brief.js	Gestion du brief client
designToLight	stores/designToLight.js	Feature DTL
notifications	stores/notifications.js	Notifications non lues
virtualSample	stores/virtualSample.js	État échantillon virtuel
addImagesModal	stores/addImagesModal.js	Modal ajout images
project	stores/project.js	Utilitaires projet

---

Routes Vue

Path	Vue	Description
/	Home.vue	Liste des projets
/login	Login.vue	Authentification
/account	Account.vue	Compte utilisateur
/notifications	Notifications.vue	Centre de notifications
/inspirations	Inspirations.vue	Galerie d'inspirations
/design-to-light	DesignToLight.vue	Feature DTL
/projects/:id	Kanban.vue	Détail projet (kanban)
/projects/:id/client-brief	Brief.vue	Brief client
/projects/:id/extended-brief	Brief.vue	Brief étendu

---

API Endpoints

Authentification

• POST /login.json - Connexion (email, password)
• GET /logout - Déconnexion

Pages (JSON)

• GET /{uri}.json - Données page + user

Commentaires

• POST /create-comment.json
• POST /update-comment.json
• POST /delete-comment.json
• POST /reply-comment.json

Notifications

• POST /read-notification.json
• POST /read-all-notifications.json

Fichiers

• POST /upload-pdf.json
• POST /upload-images.json
• POST /remove-file.json

Actions

• POST /save-page.json
• POST /save-file.json
• POST /validate-brief.json
• POST /toggle-favorite.json
• POST /request-project-creation.json
• POST /request-optimization-appointment.json

---

Design to Light (DTL)

Système d'évaluation avancée des designs de flacons.

Notation:

• Note globale : A (8-10), B (6-8), C (4-6), D (2-4), E (0-2)
• Indicateurs : Design global, Bague, Épaule, Colonnes & Arêtes, Pied, Fond de Verre
• Position : Complexité, Poids

Propositions DTL liées à:

• Proposition commerciale (PDF)
• Idéation industrielle (PDF)
• Échantillon virtuel - piste dynamique
• Échantillon virtuel - piste statique

---

Fichiers clés à connaître

Frontend

• src/main.js - Init app
• src/router/router.js - Guard + setup
• src/router/routes.js - Définition routes
• src/stores/api.js - Toute la comm API
• src/components/Menu.vue - Navigation latérale
• src/components/project/DialogWrapper.vue - Wrapper modales

Backend

• public/site/config/config.php - Routes, hooks, config
• public/site/controllers/site.php - Contrôleur principal
• public/site/models/project.php - Logique projet
• public/site/plugins/helpers/index.php - Fonctions utilitaires
• public/site/blueprints/pages/project.yml - Structure projet

---

Développement local

# Backend
cd public
composer install
php -S localhost:8888 kirby/router.php

# Frontend
npm install
npm run dev

Build

npm run build          # Production
npm run build:preprod  # Staging (avec sourcemaps)

---

Notes importantes

1. Cache: Les étapes projet sont cachées. Invalidation automatique via hooks Kirby.
2. Permissions: Filtrées côté serveur selon le rôle utilisateur.
3. Commentaires: Positionnés en % (x, y) + pageIndex pour les PDFs multi-pages.
4. Notifications: Stockées par projet, trackées par user UUID dans readby[].
5. Virtual Sample: Pistes dynamiques = pages enfants, pistes statiques = fichiers.

---

Préférences de code et standards

Principes généraux

Clarté avant tout

• Privilégier des noms de variables et fonctions explicites
• Éviter les commentaires sauf en cas de nécessité absolue
• Le code doit être auto-documenté par des noms clairs

Organisation du code

• Factoriser le code en petites fonctions bien nommées
• Éviter les blocs de code longs et complexes dans les hooks de lifecycle
• Une fonction = une responsabilité claire

Ce qui est considéré comme "bricolage" (à éviter)

• Paramètres d'URL pour gérer des états applicatifs
• Commentaires qui expliquent ce que fait le code au lieu de nommer correctement
• Abstractions prématurées ou sur-ingénierie

Style de communication

Feedback direct

• Pas de politesses inutiles
• Dire immédiatement si quelque chose ne va pas
• Tester tout de suite et signaler les problèmes

Qualité attendue

• Standards élevés sur la qualité du code
• Pas de code médiocre accepté
• Exigence de clarté et d'explicité constante