157 lines
5.9 KiB
Markdown
157 lines
5.9 KiB
Markdown
# Ben-to
|
||
|
||
Constructeur de bento pixel-art, multi-plateforme (web + Android + iOS).
|
||
|
||
## Stack
|
||
|
||
- Web: SolidJS (Vite)
|
||
- Mobile: Capacitor
|
||
- Données: catalogue embarqué, progression locale (offline, sans compte cloud en V1)
|
||
- Qualité: Vitest + Playwright + Axe + Lighthouse
|
||
|
||
Partage des URLs recette (`/r/…`) et métadonnées Open Graph : voir [docs/seo-recipe-sharing.md](docs/seo-recipe-sharing.md).
|
||
|
||
Matomo (analytics + bandeau cookies) : voir [docs/matomo-analytics.md](docs/matomo-analytics.md) et `apps/web/.env.example`.
|
||
|
||
## Démarrage
|
||
|
||
```bash
|
||
npm install
|
||
npm run pipeline:recipes
|
||
npm run dev:web
|
||
```
|
||
|
||
Les **recettes** (fichiers `*.lang.bentext`), les **couvertures** (`ressources/public/`, placeholders dans `ressources/recipe-placeholder-covers/`), les **sprites ingrédients** (`ressources/public/ingredients.png`, `ingredient-sprites.bentext`, source Aseprite sous `ressources/source/`) sont **versionnés dans ce dépôt** — pas de synchronisation avec un serveur de contenus externe.
|
||
|
||
Après modification des sources, régénérer le catalogue :
|
||
|
||
```bash
|
||
npm run pipeline:recipes
|
||
```
|
||
|
||
Règles d’édition des fichiers bentext : `.cursor/rules/recipes-bentext.mdc`.
|
||
|
||
## Tester l'app web
|
||
|
||
À exécuter depuis la **racine** du dépôt.
|
||
|
||
**Même chaîne que la CI** (ESLint + TypeScript, Vitest avec **couverture** sur les packages métier, Playwright + Axe, pas de duplication unit/int séparée dans ce script) :
|
||
|
||
```bash
|
||
npm run pipeline:recipes # régénère le catalogue si besoin (dev / e2e)
|
||
npm run test:ci
|
||
```
|
||
|
||
Voir [CONTRIBUTING.md](CONTRIBUTING.md) (hook pre-commit, tickets, Gherkin `@int-*`).
|
||
|
||
Les **e2e** (`npm run test:e2e` ou via `test:ci`) s’appuient sur `playwright.config.ts` : le serveur Vite est démarré avec `npm run dev:web` si aucun n’écoute déjà sur le port (voir `reuseExistingServer`).
|
||
|
||
Pour **régénérer les GIF** du tour d’accueil (fichiers dans `apps/web/public/tour/`, hors `test:ci`) : `npm run tour:capture` — nécessite `ffmpeg` sur la machine (`playwright.tour-capture.config.ts`).
|
||
|
||
**Contrôles ciblés sur le paquet `apps/web`** (lint + types du front uniquement) :
|
||
|
||
```bash
|
||
npm run lint -w apps/web
|
||
npm run typecheck -w apps/web
|
||
```
|
||
|
||
**Build de production** du front :
|
||
|
||
```bash
|
||
npm run pipeline:recipes
|
||
npm run build:web
|
||
```
|
||
|
||
## Tester sur un téléphone Android (Capacitor)
|
||
|
||
Le shell natif est dans `**apps/mobile**` et embarque le build statique `**apps/web/dist**` (voir `apps/mobile/capacitor.config.ts`).
|
||
|
||
Un correctif **patch-package** (`patches/@capacitor-community+sqlite+8.1.0.patch`) remplace `proguard-android.txt` par `proguard-android-optimize.txt` dans le plugin SQLite (exigence R8 / AGP récents). Il est réappliqué à chaque `**npm install`** via le script `**postinstall`**.
|
||
|
||
**Important — répertoire courant** : `pipeline:recipes`, `build:web` et les scripts `mobile:`* sont définis dans le `**package.json` à la racine** du dépôt (`ben-to/`, là où se trouve ce README). Si vous lancez `npm run …` depuis `**apps/mobile`**, npm cherche ces scripts dans le workspace mobile et échoue (`Missing script`). Vérifiez avec `ls package.json` : vous devez voir le manifest racine, pas celui du sous-dossier.
|
||
|
||
### Prérequis
|
||
|
||
- [Android Studio](https://developer.android.com/studio) (SDK + outils plate-forme).
|
||
- Sur le téléphone : **Options pour les développeurs** activées, puis **Débogage USB** (câble USB) ou **Débogage sans fil** (Wi‑Fi) selon votre appareil.
|
||
|
||
### Première fois : ajouter la plateforme Android
|
||
|
||
Si le dossier `**apps/mobile/android/`** n’existe pas encore dans votre clone :
|
||
|
||
```bash
|
||
cd apps/mobile
|
||
npx cap add android
|
||
cd ../..
|
||
```
|
||
|
||
### Build du web, sync Capacitor, lancer sur l’appareil
|
||
|
||
**Toujours depuis la racine du dépôt** (puis Android Studio s’ouvre sur `apps/mobile/android`) :
|
||
|
||
```bash
|
||
npm install
|
||
npm run pipeline:recipes
|
||
npm run build:web
|
||
npm run mobile:sync
|
||
npm run mobile:open:android
|
||
```
|
||
|
||
(`mobile:sync` / `mobile:open:android` appellent le workspace `**@ben-to/mobile**` ; évite les erreurs du type `No workspaces found` si le flag `-w` ne cible pas le bon nom.)
|
||
|
||
Dans Android Studio : choisir votre téléphone comme cible, puis **Run** (▶).
|
||
|
||
En ligne de commande (appareil déjà autorisé / `adb devices` OK), **toujours depuis la racine** :
|
||
|
||
```bash
|
||
npm run mobile:run:android
|
||
```
|
||
|
||
### Modifier le front sans tout régénérer (optionnel)
|
||
|
||
Pour charger l’UI depuis votre PC sur le réseau local (évite un `build:web` à chaque changement), vous pouvez temporairement renseigner dans `apps/mobile/capacitor.config.ts` un bloc `server: { url: "http://VOTRE_IP_LAN:3000", cleartext: true }` (à retirer avant release), puis lancer le front avec l’écoute réseau :
|
||
|
||
```bash
|
||
npm run dev:web -- --host 0.0.0.0
|
||
```
|
||
|
||
Adaptez le pare-feu / le même Wi‑Fi entre le PC et le téléphone.
|
||
|
||
## Qualité obligatoire
|
||
|
||
```bash
|
||
npm run check:quality
|
||
npm run test:unit
|
||
npm run test:integration
|
||
npm run test:e2e
|
||
```
|
||
|
||
## CI / Sécurité
|
||
|
||
- `.github/workflows/ci.yml` — qualité, couverture, e2e + artefacts qualité, Lighthouse, **assembleDebug Android**, rapport PR
|
||
- `.github/workflows/security.yml` — CodeQL, `npm audit`, Gitleaks ([activation upload SARIF](docs/CODE_SCANNING.md))
|
||
- `.github/workflows/dependency-review.yml` — revue des dépendances sur les PR (selon options du dépôt)
|
||
- `.github/workflows/mobile-release.yml`
|
||
|
||
## Publication V1 (web + Android)
|
||
|
||
Checklist gel release : [docs/V1_LAUNCH_CHECKLIST.md](docs/V1_LAUNCH_CHECKLIST.md).
|
||
|
||
## Déploiement CapRover
|
||
|
||
- Le dépôt contient `Dockerfile` et `captain-definition` pour un déploiement via CapRover (hors GitHub Actions).
|
||
|
||
## Ticketing GitHub
|
||
|
||
Création rapide des issues MVP :
|
||
|
||
```bash
|
||
./scripts/github/create-issues.sh kazerlelutin/ben-to
|
||
```
|
||
|
||
Tickets post-MVP (builder SOLID, suppression des barrels `index`, SEO OG recettes) : gabarits sous [.github/ISSUE_TEMPLATE/](.github/ISSUE_TEMPLATE/) (`04`–`06`), corps dans [docs/tickets/](docs/tickets/), création en masse après `gh auth login` :
|
||
|
||
```bash
|
||
./scripts/github/create-post-mvp-issues.sh
|
||
```
|