ObsiViewer/docs/URL_STATE/URL_STATE_QUICK_START.md

# UrlStateService - Quick Start Guide

## 🚀 Démarrage en 5 minutes

### Étape 1: Lancer le backend (Terminal 1)
```bash
cd c:\dev\git\web\ObsiViewer
node server/index.mjs
```

**Attendu**: Logs du serveur, port 4000 actif
```
[Config] { MEILI_HOST: 'http://127.0.0.1:7700', ... }
[Server] Listening on port 4000
```

### Étape 2: Lancer le frontend (Terminal 2)
```bash
cd c:\dev\git\web\ObsiViewer
npm run dev
```

**Attendu**: Angular dev server, port 3000 actif
```
✔ Compiled successfully.
✔ Application bundle generation complete.
➜  Local:   http://localhost:3000/
```

### Étape 3: Ouvrir le navigateur (Terminal 3)
```bash
# Ouvrir une URL avec paramètres
http://localhost:3000/?note=Allo-3/test-new-file.md
```

**Attendu**: Note s'ouvre directement

---

## 📋 Tests Rapides (5 minutes)

### Test 1: Deep-link note
```
URL: http://localhost:3000/?note=Allo-3/test-new-file.md
Résultat: Note ouverte ✅
```

### Test 2: Filtre dossier
```
URL: http://localhost:3000/?folder=Allo-3
Résultat: Liste filtrée par dossier ✅
```

### Test 3: Filtre tag
```
URL: http://localhost:3000/?tag=home
Résultat: Vue recherche, filtre par tag ✅
```

### Test 4: Recherche
```
URL: http://localhost:3000/?search=test
Résultat: Barre de recherche remplie ✅
```

### Test 5: Interaction → URL
```
Étapes:
1. Cliquer un dossier dans la sidebar
2. Observer l'URL
Résultat: URL change vers ?folder=... ✅
```

---

## 🎯 URLs Prêtes à Tester

Copier/coller dans le navigateur:

```
# Ouvrir une note
http://localhost:3000/?note=Allo-3/test-new-file.md

# Filtrer par dossier
http://localhost:3000/?folder=Allo-3

# Filtrer par tag
http://localhost:3000/?tag=home

# Rechercher
http://localhost:3000/?search=home

# Combinaison: dossier + note
http://localhost:3000/?folder=Allo-3&note=Allo-3/test-new-file.md

# Combinaison: tag + recherche
http://localhost:3000/?tag=home&search=test
```

---

## ⚠️ Troubleshooting

### Problème: Écran bleu/vide
**Solution**: 
1. Vérifier que le backend tourne: `curl http://localhost:4000/api/vault/metadata`
2. Hard reload: `Ctrl+F5`
3. Vérifier la console: `F12 → Console`

### Problème: URL ne change pas après interaction
**Solution**:
1. Vérifier que vous êtes en mode Nimbus (bouton "✨ Nimbus" en haut)
2. Vérifier que le backend répond
3. Vérifier la console pour les erreurs

### Problème: Note ne s'ouvre pas
**Solution**:
1. Vérifier que le chemin de la note existe
2. Vérifier la casse (sensible à la casse)
3. Vérifier que le dossier "Allo-3" existe

### Problème: Erreur dans la console
**Solution**:
1. Copier l'erreur complète
2. Vérifier les logs du serveur
3. Consulter `URL_STATE_INTEGRATION_TEST.md` pour les cas connus

---

## 📊 Vérification Rapide

### Backend OK?
```bash
curl http://localhost:4000/api/vault/metadata
```
**Attendu**: JSON avec liste des notes

### Frontend OK?
```bash
curl http://localhost:3000
```
**Attendu**: HTML de l'application

### Proxy OK?
```bash
# Dans le navigateur, ouvrir:
http://localhost:3000/?folder=Allo-3
# Vérifier que la liste se filtre
```

---

## 🎓 Concepts Clés

### URL Parameters
- `?note=...` → Ouvre une note
- `?folder=...` → Filtre par dossier
- `?tag=...` → Filtre par tag
- `?quick=...` → Filtre par quick link
- `?search=...` → Applique la recherche

### Priorité
- Si `note` est présent → ouvre la note
- Sinon si `tag` est présent → filtre par tag
- Sinon si `folder` est présent → filtre par dossier
- Sinon si `quick` est présent → filtre par quick link
- Sinon → affiche toutes les notes

### Synchronisation
- URL change → AppComponent reçoit l'update → UI se met à jour
- Utilisateur clique → AppComponent appelle urlState → URL change

---

## 📝 Prochaines Étapes

1. **Tester les 5 tests rapides** (5 min)
2. **Exécuter le guide complet** (`URL_STATE_INTEGRATION_TEST.md`) (30 min)
3. **Documenter les résultats**
4. **Corriger les bugs éventuels**
5. **Déployer en production**

---

## 📞 Aide Rapide

| Question | Réponse |
|----------|---------|
| Où est le guide de test? | `URL_STATE_INTEGRATION_TEST.md` |
| Où est la documentation complète? | `URL_STATE_INTEGRATION_SUMMARY.md` |
| Comment lancer le backend? | `node server/index.mjs` |
| Comment lancer le frontend? | `npm run dev` |
| Quel port pour le backend? | 4000 |
| Quel port pour le frontend? | 3000 |
| Mode Nimbus activé? | Bouton "✨ Nimbus" en haut à droite |
| Erreur NG0201? | Vérifier que UrlStateService est injecté |
| URL ne change pas? | Vérifier que vous êtes en mode Nimbus |

---

**Bon test! 🚀**