notazof/yavsc
1
0
Fork 0
Code Issues Pull requests Projects 1 Releases 3 Packages Wiki Activity Actions

doc cleanup

Browse source
This commit is contained in:
Paul Schneider 2026-06-20 19:00:10 +01:00
commit 4192c7cbf9
3 changed files with 0 additions and 427 deletions
Download patch file Download diff file Expand all files Collapse all files

3
doc/Dictionnaire.md
View file

@ -9,12 +9,9 @@ c'est un instantané, pas une référence vivante.
## Règle de résolution ## Règle de résolution
Un projet hérite des dictionnaires de son activité et de tous Un projet hérite des dictionnaires de son activité et de tous
ses ancêtres jusqu'à la racine. ses ancêtres jusqu'à la racine.
Ainsi, les termes juridiques sont toujours disponibles, quel que Ainsi, les termes juridiques sont toujours disponibles, quel que
soit le domaine du projet. soit le domaine du projet.

424
doc/challenges/2026-06-14-trunk-cleanup.md
View file

@ -1,424 +0,0 @@
# Défi : aligner `main` sur l'intention trunk + nettoyage CSS/JS
> Énoncé : 2026-06-14, par Paul Schneider.
> Statut : **ouvert**.
## Énoncé
Atteindre, sur la branche `main` et en mode trunk, l'état
intentionnel qui a déjà opéré sur la branche `themeok` (la
référence). Concrètement :
1. **Libérer le dépôt de son code inutile** : retirer les assets
vendor non utilisés (Quill, dropzone.min.css, jquery-ui si plus
personne ne s'en sert, etc.) et tout ce qui n'est référencé
nulle part dans le code applicatif.
2. **Bien nettoyer le CSS et le JS** : déplacer les vendor libs
sous un régime cohérent (npm + esbuild), arrêter le
double-tracking (fichiers versionnés + bundles esbuild), poser
des conventions claires.
3. **À minima, ne pas casser** le JS et le CSS de
`_Layout.cshtml`. C'est l'invariant non-négociable.
4. **Introduire immédiatement** des tests d'UI automatisés pour
servir de garde-fou contre la régression, à chaque commit.
## Pourquoi maintenant
`themeok` est devenu, dans la pratique, la branche de référence
pour le look et le comportement front. `main` n'a pas reçu les
commits correctifs de `themeok`, et son état est plus dégradé
(caches navigateur, état runtime, scripts inline qui plantent sur
du contenu vide).
Tant que la divergence existe, on risque de :
- cherry-picker à la main en ratant un commit,
- ne pas voir une régression front parce qu'on ne teste pas en
navigateur,
- accumuler de la dette visuelle sur `main` jusqu'à un point de
non-retour.
## État actuel
### `themeok` (référence, à 4 commits devant `main`)
```
ec8fd4b6 fix(cookies): set Identity cookies to SameSite=Lax in dev
76fef567 chore: remove Quill
379413f3 chore: snapshot of themeok branch as visual reference
d71490f5 chore: stop tracking vendor lib files
31906a78 WIP : Js and css cleanup ← point de départ du WIP
30587248 ← ancêtre commun avec main
```
État du working tree : propre. `dotnet test` : 11/11 verts.
Serveur dev local démarre sans warning (à part le certificat
HTTPS de dev non trusted, sans gravité).
### `main` (à remettre au niveau)
```
2a9760ca docs: roadmap à jour, archive TODO.fr
8f768240 WIP: refactoring pour déploiement
30587248 ← même ancêtre commun
```
État runtime connu : **look catastrophique** sur
`http://localhost:5000`. Diagnostic (cf.
[§ Résultats du diagnostic](#résultats-du-diagnostic)) :
- Le HTML est rendu correctement, toutes les CSS et JS sont
servies en HTTP 200.
- Le "look catastrophique" vient du **contenu vide** (Home/Index
n'a aucune section) et d'une **erreur JS** dans un script
inline qui plante quand le carousel est vide.
### `refac/js-bundle` (suspendue)
```
fad7fc8d refac: remove jQuery + jQuery UI imports from datetime
79658c84 refac: remove vendor imports from chat entry
6455178b refac: load jQuery + Bootstrap as global scripts in _Layout
ed7522c5 fix: drop nuget bootstrap and popper.js, npm bundles
196f4b0b chore: gitignore node_modules, build/, wwwroot/lib
```
Trois commits de migration jQuery-en-script-global. **Pas encore
fusionnés dans `themeok` ni dans `main`**. À intégrer dans le
plan, mais pas en première priorité.
## Résultats du diagnostic
Reproduit en worktree `~/Workspace/yavsc-main/` sur branche
`diag/main` (basée sur `main@2a9760ca`).
### Procédure
```bash
git worktree add -b diag/main ../yavsc-main main
cp ~/Workspace/yavsc/.env ~/Workspace/yavsc-main/.env
# Forcer le port : appsettings de main contient
# "Kestrel.Endpoints.Http.Url": "http://localhost:3002" qui entre
# en conflit avec le port 5000 du dev settings. Override par env :
cd ~/Workspace/yavsc-main/src/Yavsc.Org
Kestrel__Endpoints__Http__Url=http://localhost:5060 \
Kestrel__Endpoints__Https__Url=https://localhost:5061 \
ConnectionStrings__YavscConnection="Server=localhost;Port=5432;Database=yavscdev;Username=yavscdev;Password=***" \
ASPNETCORE_ENVIRONMENT=Development \
dotnet bin/Debug/net10.0/Yavsc.Org.dll
```
> **Note de Paul** : la procédure d'install / dev principale
> est en fait `cd contrib; make reinstall` (qui build en
> Release, copie vers `/srv/www/yavsc/`, et gere le service
> systemd `yavscOrg` sur port 3002). Le `dotnet run` direct
> n'est qu'un raccourci de debug. Le diagnostic ci-dessus a
> été fait en `dotnet run` sur un port libre (5060) parce que
> le port 3002 etait deja occupe par le service systemd
> existant.
### Fichiers servis (HTTP 200, taille correcte)
| URL | Code | Taille |
|--------------------------------------------------|------|---------|
| `/lib/jquery-ui/jquery-ui.min.css` | 200 | 30770 |
| `/lib/bootstrap.quartz.min.css` | 200 | 244113 |
| `/css/site.css` | 200 | 3009 |
| `/lib/jquery-ui/external/jquery/jquery.js` | 200 | 285314 |
| `/lib/jquery-ui/jquery-ui.js` | 200 | 521054 |
| `/lib/bootstrap/dist/js/bootstrap.bundle.min.js` | 200 | 80721 |
| `/js/site.js` | 200 | 364 |
| `/lib/bootstrap/js/carousel.js` | 200 | 7141 |
### HTML rendu (extrait du `<body>`)
```html
<nav class="navbar navbar-expand-sm navbar-dark bg-dark">...</nav>
<div id="myCarousel" class="carousel slide" data-ride="carousel" data-interval="6000">
<div class="carousel-inner" role="listbox">
</div> <!-- VIDE -->
</div>
<div class="container py-4">
<!-- VIDE -->
</div>
<footer class="border-top footer text-muted">
<div class="container">&copy; WTFPL 2025 ...</div>
</footer>
<script>
$(document).ready(function(){
var car = $('.carousel').first();
var fi = car.children('.carousel-inner').first()
.children('.item').first(); <!-- null : plante -->
var capt = fi.children('.carousel-caption-s');
fi.addClass('active');
car.animate({...});
})
</script>
```
### Cause racine
1. Le HTML est structurellement correct : navbar Bootstrap 5
`bg-dark`, carousel Bootstrap 4 (`data-ride`), container
Bootstrap. Toutes les CSS et JS sont chargées.
2. Le **carousel est vide** (`<div class="carousel-inner">` sans
enfant `.item`). Le script inline
`car.children('.carousel-inner').first().children('.item').first()`
retourne `null` → `fi.children(...)` lève
`TypeError: Cannot read properties of null` → erreur console
qui stoppe la chaîne d'initialisation.
3. Le **container principal est vide** : aucune section de
contenu → page visuellement blanche malgré le BG art.
### Diff `main` vs `themeok` (fichiers versionnés)
| Fichier | Diff |
|------------------------------------------------|-------------|
| `_Layout.cshtml` | identique |
| `_Nav.cshtml` | identique |
| `site.css` | identique |
| `_Layout.cshtml.css` (Razor scoped) | identique |
| `appsettings-org.Development.json` | identique |
| `appsettings-org.json` (production) | `Kestrel.Endpoints.Http.Url` = `3002` sur main, absent sur themeok |
Donc **structurellement, `main` et `themeok` servent le même
HTML** quand on les lance en dev. La différence visible est due
au contenu des vues, pas aux fichiers de structure.
## Critères d'acceptation
Le défi est résolu quand :
- [ ] **CA1** : `main` contient les 4 commits de `themeok`
(`d71490f5`, `379413f3`, `76fef567`, `ec8fd4b6`) — par merge ou
cherry-pick.
- [ ] **CA2** : la branche `refac/js-bundle` est mergée (ou
re-intégrée) sur `main`, via un commit explicite (pas un
merge fast-forward silencieux).
- [ ] **CA3** : un test d'UI automatisé (Selenium Driver) existe et
passe sur `main` ET sur `themeok`. Le test vérifie au minimum :
- la page d'accueil répond 200,
- le HTML contient la navbar Bootstrap,
- la CSS `bootstrap.quartz.min.css` est chargée sans erreur,
- aucun script `<script src>` ne retourne 404.
- [ ] **CA4** : la liste des vendor libs effectivement utilisées
par le code applicatif est documentée (un fichier
`doc/vendor-libs.md` ou équivalent). Tout fichier dans
`wwwroot/lib/` non listé est candidat à la suppression.
- [ ] **CA5** : aucun script inline ne plante au chargement
d'une page. Vérifié par le test d'UI (CA3) qui collecte les
erreurs console.
- [ ] **CA6** : `Home/Index.cshtml` contient au moins une
section visible (hero ou équivalent) — sinon le "look
catastrophique" persiste même avec tout le reste correct.
## Stratégie de tests d'UI automatisés
Outil proposé : **Playwright** (C# / .NET, pour rester dans la
stack actuelle). À introduire en premier, **avant** les autres
commits, pour servir de filet de sécurité dès le début.
### Phase A — Bootstrap des tests UI
1. Créer un projet de test UI séparé :
`test/yavsc.UiTests/yavsc.UiTests.csproj`
2. Dépendance : `Microsoft.Playwright` (NuGet).
3. Une classe `BaseUiTest` qui :
- démarre le serveur sur un port dédié (5050 par convention),
- configure Kestrel via `WebApplicationFactory<Program>`,
- lance Playwright en mode headless.
4. Un premier test `HomePage_ShouldRender` qui vérifie CA3.
### Phase B — Extension de la couverture
Tests à ajouter au fil de l'eau, un par commit :
- `HomePage_Navbar_IsBootstrapDark`
- `HomePage_NoConsoleErrors`
- `AccountPage_Login_AndLogout` (quand pertinent)
- `BlogListPage_Renders`
### Garde-fou
À chaque commit qui touche `Views/`, `wwwroot/`, ou
`HostingExtensions.cs`, **les tests UI doivent passer**. C'est
la règle. Si on n'a pas le temps de migrer toute la suite de
tests, on ajoute au moins un test qui couvre le changement.
## Plan d'attaque
### Étape 0 — Tests UI (garde-fou immédiat)
Avant tout cherry-pick, mettre en place le projet de tests UI et
le premier test CA3. C'est le filet.
### Étape 1 — Cherry-pick des commits `themeok` sur `main`
Dans l'ordre chronologique, en testant à chaque commit :
- `d71490f5` (gitignore)
- `379413f3` (snapshot, vide)
- `76fef567` (Quill)
- `ec8fd4b6` (cookies)
OU un merge `themeok → main` (plus risqué si `main` a divergé
entre temps, mais ici c'est le bon choix car les 4 commits sont
consécutifs et bien isolés).
### Étape 2 — Nettoyage de fond
- Lister les vendor libs (`wwwroot/lib/`) réellement utilisées
par le code (grep `src/Yavsc.Org/`).
- Documenter dans `doc/vendor-libs.md`.
- Pour les libs inutilisées : `git rm` (trackées) ou
documentation (non trackées sur `themeok`).
- Pour les libs utilisées : confirmer qu'elles sont dans
`package.json` ou statiquement référencées par un bundle
esbuild.
### Étape 3 — Fusion `refac/js-bundle` → `main`
Cherry-pick des 3 commits, ou merge de la branche. Vérifier que
`core.bundle.min.js` (et les autres bundles) se génèrent
correctement via `npm run build:js` après le merge.
### Étape 4 — Test runtime manuel
- Démarrer le serveur dev.
- Naviguer sur Home, About, Contact, Blogspot, Account/Login.
- Vérifier visuellement l'absence d'erreur console.
- Comparer avec l'état de référence sur `themeok`.
### Étape 5 — Remplir `Home/Index.cshtml` (optionnel)
Si on a le temps et le contenu, ajouter une section hero et une
section services, pour que la page d'accueil ne soit plus vide.
## Risques identifiés
### R1 — Cache navigateur trompeur
Après un `git checkout` rapide, le navigateur peut servir une
version cachée du bundle avec un hash obsolète. Toujours faire
`Ctrl+Shift+R` ou vider le cache avant de juger un look.
Mitigation : le test UI (CA3) charge en Playwright, qui ne cache
pas. Donc on a un verdict objectif.
### R2 — Double binding Kestrel : `main` veut 3002, dev settings forcent 5000
`appsettings-org.json` sur `main` contient
`"Kestrel": { "Endpoints": { "Http": { "Url": "http://localhost:3002" } } }`.
Le dev settings le merge avec 5000/5001, mais en prod-like (via
`make reinstall` + systemd), c'est 3002.
**Ce qu'on a en local** :
- **Service systemd `yavscOrg`** (user `yavsc`,
`ExecStart=/srv/www/yavsc/Yavsc.Org`) : tourne sur **port
3002**, sert le build Release publié. C'est ce que Paul
utilise pour le dev runtime "proche prod".
- **`dotnet run` depuis VSCode** (ou worktree) :
`ASPNETCORE_ENVIRONMENT=Development` → port **5000/5001** via
`appsettings-org.Development.json`.
Les deux setups sont légitimes et cohabitent. Le test d'UI
automatique doit pouvoir tourner contre les deux.
**Décision à prendre** : doit-on garder cette divergence
main/themeok ou aligner ? Mon avis : aligner sur 5000/5001 partout
en dev, et garder 3002 pour la prod (ce qui est déjà le cas
implicitement).
### R3 — `.env` non versionné
Le `.env` contient des secrets SMTP/ANTHROPIC et n'est pas dans
git. Le copier manuellement sur un worktree est une opération
manuelle qu'on peut oublier.
Mitigation : `doc/install.md` doit documenter cette étape. À
réviser.
### R4 — Ports utilisés
`5000/5001` : dev Yavsc
`3001/3002` : autre service `yavsc` user (prod-like) sur la machine
`5050/5051`, `5060/5061` : ports libres utilisés pour diag/tests
À documenter pour ne pas se marcher dessus.
### R5 — Quiproquos de branches
On a déjà perdu du temps dans cette session à ne pas savoir
quelle branche était active. Règle : **toujours** vérifier
`git branch -a` et `git status` au début d'une session, et
l'écrire en mémo.
## Ce qui est déjà fait (récap session 2026-06-14)
- 4 commits sur `themeok` (cf. log ci-dessus)
- Worktree `~/Workspace/yavsc-main/` sur `diag/main` créé
- Diagnostic de `main` effectué, cause racine identifiée
- 11/11 tests `dotnet test` verts
- `dotnet build` 0 erreur
## À faire
### Court terme (prochaine session)
- [ ] **Phase 0a** : documenter `cd contrib; make reinstall` dans
`doc/install.md` (s'il existe, à créer sinon) — c'est la
procédure officielle de Paul, elle doit être la référence
- [ ] Phase 0b : bootstrap tests UI Playwright
- [ ] Phase 1 : cherry-pick ou merge des 4 commits sur `main`
- [ ] Phase 2 : `doc/vendor-libs.md`
### Moyen terme
- [ ] Phase 3 : fusion `refac/js-bundle`
- [ ] Phase 4 : test runtime manuel
- [ ] Phase 5 : remplir `Home/Index.cshtml` (si scope confirmé)
### Long terme (backlog)
- [ ] Auditer les autres vues internes pour migration Bootstrap 5
- [ ] Documenter la procédure d'install (incluant la copie
manuelle du `.env`)
- [ ] Réviser `doc/install.md` si existant
- [ ] CI : intégrer les tests UI Playwright dans le pipeline
## Annexes
### Liens utiles
- `doc/Architecture.md` : architecture générale de Yavsc
- `ROADMAP.md` : roadmap produit
- `git log themeok` : historique de la branche de référence
- `git log refac/js-bundle` : branche de migration jQuery
### Historique de cette session
Voir `memory/2026-06-14.md` (mémo interne OpenClaw) pour le récit
détaillé, quiproquos compris. Ce document-ci est l'**énoncé
exécutif** ; le mémo est l'**historique de travail**.
### Environnement d'exécution (état au 2026-06-14)
Sur la machine de dev, **deux process Yavsc** peuvent tourner en
parallèle :
| Process | Port | User | Lance par | Build |
|----------------------------------|-------|---------|----------------------------|--------------|
| Service systemd `yavscOrg` | 3002 | `yavsc` | `cd contrib; make reinstall` | Release |
| `dotnet run` / VSCode | 5000 | `paul` | VSCode ou CLI | Debug |
**Avant de lancer un nouveau `dotnet run`** :
1. `ss -ltn | grep -E ':5000|:5001|:3002|:3001'` : voir qui écoute
2. `ps -ef | grep Yavsc.Org` : voir les process
3. Si 5000 occupé par `paul` : OK, c'est ton dev
4. Si 5000 occupé par autre : **ne pas lancer**, choisir un
autre port (5060+) ET modifier `appsettings-org.Development.json`
du worktree pour pointer dessus (les vars d'env
`Kestrel__Endpoints__*__Url` peuvent forcer le port)
5. **Ne jamais toucher au service systemd** sauf demande explicite
de Paul

0
doc/doct/ùd
View file