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

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

# Frontend
npm install
npm run dev
```

## Build

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