# Dev Init — Nouveau projet web fullstack ## Règle absolue **NE JAMAIS démarrer ou arrêter le serveur dev.** Le serveur tourne déjà (honcho ou tmux). Tu dois SEULEMENT lire les logs. ## Initialisation du projet ### 1. Structure de base Créer les dossiers `server/` et `frontend/`. Initialiser les `package.json` avec `"type": "module"`. ### 2. Backend (server/) ```bash cd server npm init -y npm install fastify @fastify/cors @fastify/swagger @fastify/swagger-ui @fastify/static @fastify/multipart fastify-type-provider-zod zod jose postgres drizzle-orm dotenv npm install -D @types/node tsx typescript drizzle-kit ``` **index.ts pattern :** ```typescript import Fastify from "fastify"; import { serializerCompiler, validatorCompiler, jsonSchemaTransform } from "fastify-type-provider-zod"; const app = Fastify({ logger: { level: "error" } }); app.setValidatorCompiler(validatorCompiler); app.setSerializerCompiler(serializerCompiler); // Register plugins: cors, multipart, swagger, swagger-ui, static // Register route plugins with prefix // Listen on PORT env var ``` **Auth middleware pattern :** Le middleware tente dans l'ordre : cookie session → JWT Auth0 → API token DB. ```typescript import { createRemoteJWKSet, jwtVerify } from "jose"; const JWKS = createRemoteJWKSet(new URL(`https://${AUTH0_DOMAIN}/.well-known/jwks.json`)); async function authPreHandler(request: FastifyRequest, reply: FastifyReply) { // 1. Cookie session (SSO .tuls.me) const cookie = request.cookies["auth-token"]; if (cookie) { const payload = verifyInternalJwt(cookie); // HS256 via AUTH_SECRET if (payload) { request.user = payload; return; } } // 2. Bearer JWT (Auth0) const auth = request.headers.authorization; if (auth?.startsWith("Bearer ")) { const token = auth.slice(7); try { const { payload } = await jwtVerify(token, JWKS, { audience: AUTH0_AUDIENCE }); request.user = { sub: payload.sub, email: payload.email, roles: payload["https:///roles"] || [] }; return; } catch {} // 3. API token (prefixed, hashed in DB) if (token.startsWith("_")) { const hash = sha256(token); const apiToken = await db.select().from(apiTokens).where(eq(apiTokens.tokenHash, hash)).limit(1); if (apiToken[0]) { request.user = { sub: apiToken[0].userId }; return; } } } reply.code(401).send({ error: "Unauthorized" }); } ``` **API tokens :** - Préfixe projet (`_`) + `crypto.randomUUID()` - Stocké en DB : SHA-256 du token (jamais le token brut) - Endpoints : `POST /api/auth/tokens` (create), `GET /api/auth/tokens` (list), `DELETE /api/auth/tokens/:id` (revoke) **RBAC Auth0 :** - Rôles configurés dans Auth0 Dashboard (ex: `admin`, `member`) - Roles injectés dans le JWT via Auth0 Rule/Action : `https:///roles` - Check côté route : `if (!request.user.roles.includes("admin")) reply.code(403).send(...)` **Route pattern :** ```typescript import type { FastifyPluginAsync } from "fastify"; import type { ZodTypeProvider } from "fastify-type-provider-zod"; const routes: FastifyPluginAsync = async (fastify) => { const app = fastify.withTypeProvider(); app.get("/", { schema: { response: { 200: MyZodSchema } } }, async (request) => { ... }); }; ``` ### 3. Frontend (frontend/) ```bash cd frontend npm create vue@latest . -- --typescript --router --no-pinia --no-vitest --no-e2e --no-eslint --no-prettier npm install @auth0/auth0-spa-js npm install -D tailwindcss @tailwindcss/vite ``` **vite.config.ts** : ajouter `tailwindcss()` plugin + proxy `/api` et `/data` vers le backend. **shadcn-vue :** ```bash npx shadcn-vue@latest init -y -b slate npx shadcn-vue@latest add button card badge dialog input textarea select separator ``` **Thème dark** dans `src/assets/index.css` : CSS variables dans `:root` (pas de light/dark toggle sauf demandé). **Auth0** : composable `useAuth.ts` avec Auth0Client, initAuth(), login(), logout(), getAccessToken(). PKCE flow avec redirect vers `/callback`. ### 4. Procfile + .env **Procfile :** ``` server: cd server && PORT= npx tsx watch src/index.ts frontend: cd frontend && npx vite --host ``` **Convention .env :** - `server/.env` — secrets backend (jamais commité) - `server/.env.example` — template commité (valeurs vides ou fake) - `frontend/.env` — config publique frontend **Variables standard backend :** ```env PORT= DATABASE_URL=postgres://user:pass@localhost:5434/ AUTH0_DOMAIN=otomata.us.auth0.com AUTH0_AUDIENCE=https://api..proj.otomata.tech AUTH_SECRET= # Pour JWT internes / SSO cookie ``` **Variables standard frontend :** ```env VITE_AUTH0_DOMAIN=otomata.us.auth0.com VITE_AUTH0_CLIENT_ID= VITE_AUTH0_AUDIENCE=https://api..proj.otomata.tech ``` ### 5. Auth0 Créer une app SPA dans le tenant `otomata.us.auth0.com` : ```bash auth0 apps create --name "" --type spa --callbacks "https://.dev/callback" --logout-urls "https://.dev" --web-origins "https://.dev" ``` Créer une API si besoin : ```bash auth0 apis create --name " API" --identifier "https://api..proj.otomata.tech" ``` ### 6. Tests ```bash cd server npm install -D vitest ``` **package.json :** ```json { "scripts": { "test": "vitest run", "test:watch": "vitest" } } ``` **Structure :** tests co-localisés dans `server/src/` (ex: `routes/items.test.ts` à côté de `routes/items.ts`). **Pattern test API :** ```typescript import { describe, it, expect } from "vitest"; import { buildApp } from "../index.js"; // Export app factory describe("GET /api/items", () => { it("returns items", async () => { const app = await buildApp(); const res = await app.inject({ method: "GET", url: "/api/items" }); expect(res.statusCode).toBe(200); }); }); ``` Utiliser `app.inject()` de Fastify (pas besoin de supertest). DB de test via `DATABASE_URL` dans `.env.test`. ## API Documentation Swagger UI automatique via les Zod schemas. Rien à maintenir manuellement. ```typescript // Dans index.ts await app.register(swagger, { openapi: { info: { title: " API", version: "1.0.0" } }, transform: jsonSchemaTransform, }); await app.register(swaggerUi, { routePrefix: "/api/docs" }); ``` - **Swagger UI** : `/api/docs` (interactif, testable) - **Spec OpenAPI JSON** : `/api/doc` (pour clients auto-générés) - Chaque route avec `schema: { body, querystring, params, response }` en Zod est auto-documentée ## Gestion de projet Issues GitHub comme backlog. Voir `/projects` pour la gestion cross-repo. ```bash # Créer une issue gh issue create --title "Feature X" --body "Description" --label "enhancement" # Lister les issues gh issue list # Fermer gh issue close 42 ``` Labels standard : `bug`, `enhancement`, `infra`, `design`. ## Conventions - API RESTful sous `/api/*` - OpenAPI auto-générée depuis les Zod schemas - Swagger UI sur `/api/docs` - Routes protégées par `authPreHandler` (Fastify preHandler hook) - Frontend : composants dans `components/`, pages dans `views/` - Fichiers runtime servis par Fastify via @fastify/static sur `/data/*` - DB : PostgreSQL Docker local (port 5434), natif en prod - Pas de fichier > 500 lignes - Pas de code legacy, pas de fallbacks (lever une erreur)

dev-init

Installation

Preview