From 5f55dfe7da2b100c6e16b8f12d35ab3a8b65b45f Mon Sep 17 00:00:00 2001 From: sylvain p Date: Thu, 7 May 2026 12:26:41 +0200 Subject: [PATCH] Rewrite README around install + dev workflow Pivots the README from a feature/spec dump to a getting-started doc: quick Docker bootstrap, local dev steps, repo layout, useful pnpm commands, and an explicit "POC, unfinished" warning at the top with known limitations listed. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 158 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 113 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 7e8e7ac..ced5f30 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,127 @@ -# CRA Manager - Compte Rendu d'Activité +# CRA-Helper -## Overview +> ⚠️ **POC non finalisé.** Cette application est une preuve de concept exploratoire pour la gestion de comptes-rendus d'activité (CRA) de consultants. Le workflow métier est partiel, l'auth est absente, et plusieurs cas d'usage ne sont pas couverts. À utiliser comme base de réflexion ou de fork, pas en production. -A French timesheet management application (CRA - Compte Rendu d'Activité) built as a pnpm workspace monorepo. Consultants use it to track and report hours worked across multiple projects each month. +Application web pour saisir et suivre les heures travaillées par projet, par mois — typiquement pour des prestataires/consultants devant remettre un CRA mensuel. + +## Démarrage rapide (Docker) + +Le moyen le plus simple : tout est containerisé (Postgres + API + front). + +```bash +cp .env.example .env +docker compose up -d +``` + +Ouvrir http://localhost:8080. + +Premier démarrage : un service `migrate` pousse le schéma Drizzle dans Postgres avant que l'API ne démarre. Les comptes/données de seed ne sont pas fournis — tout est vide. + +Pour arrêter : `docker compose down` (les données Postgres sont conservées dans le volume `postgres_data`). `docker compose down -v` pour repartir à zéro. + +## Démarrage en dev local (sans Docker) + +Prérequis : +- Node.js 24 +- pnpm 10 +- Un PostgreSQL accessible + +```bash +pnpm install +export DATABASE_URL=postgres://user:pass@localhost:5432/cra +pnpm --filter @workspace/db run push # pousse le schéma +PORT=3000 pnpm --filter @workspace/api-server run dev +PORT=5173 BASE_PATH=/ pnpm --filter @workspace/cra-app run dev +``` + +API sur `:3000`, front Vite sur `:5173` avec HMR. Le front appelle `/api/...` en relatif — en dev il faut soit servir front+api derrière le même proxy, soit configurer le proxy Vite (non fait pour l'instant). ## Stack -- **Monorepo tool**: pnpm workspaces -- **Node.js version**: 24 -- **Package manager**: pnpm -- **TypeScript version**: 5.9 -- **Frontend**: React + Vite + Tailwind CSS + shadcn/ui -- **API framework**: Express 5 -- **Database**: PostgreSQL + Drizzle ORM -- **Validation**: Zod (`zod/v4`), `drizzle-zod` -- **API codegen**: Orval (from OpenAPI spec) -- **Build**: esbuild (CJS bundle) -- **Charts**: Recharts -- **Routing**: Wouter +| Couche | Techno | +|--------|--------| +| Monorepo | pnpm workspaces | +| Front | React 19, Vite, Tailwind 4, shadcn/ui, Wouter, TanStack Query | +| API | Express 5, Pino | +| DB | PostgreSQL + Drizzle ORM | +| Validation | Zod, drizzle-zod | +| Codegen API | Orval (depuis l'OpenAPI spec) | +| Bundle API | esbuild (single .mjs) | -## Features +## Structure du repo -- **Dashboard**: Overview with monthly hours chart, project breakdown, active project count, timesheet status -- **Timesheet Management**: Create, view, edit monthly timesheets (CRA) -- **CRA Grid**: Interactive calendar grid where rows = projects, columns = days of month. Click cells to open popover with hour options [0, 0.5, 1, 2, 3, 4, 5, 6, 7, 8]. Includes optional description per cell (amber dot indicator). Auto-save with debounce. Weekend distinction, row/column totals -- **Project Management**: CRUD for projects with code, name, client, category -- **Timesheet Workflow**: Draft → Submitted → Validated status flow -- **Inline Administration**: Sidebar Admin dialog to lock/unlock time entry editing and export/import project, CRA, line, and time-entry data as JSON +``` +artifacts/ + api-server/ Express, bundlé en single-file ESM via esbuild + cra-app/ Front React/Vite (le SPA principal) + mockup-sandbox/ Bac à sable de maquettes (non lié au build prod) -## Database Schema +lib/ + db/ Schéma Drizzle + connexion Postgres + api-spec/ OpenAPI source-of-truth + config Orval + api-zod/ Zod schémas générés + api-client-react/ Hooks React Query générés depuis l'OpenAPI -- `projects` — Project definitions (code, name, client, category) -- `timesheets` — Monthly timesheet headers (year, month, status, collaborator) -- `timesheet_lines` — Project assignments within a timesheet -- `time_entries` — Daily hour entries per line (date, hours, description) +scripts/ Scripts ponctuels TS (tsx) +docker/ Dockerfiles api/web + nginx.conf +``` -## Key Commands +## Modèle de données -- `pnpm run typecheck` — full typecheck across all packages -- `pnpm run build` — typecheck + build all packages -- `pnpm --filter @workspace/api-spec run codegen` — regenerate API hooks and Zod schemas from OpenAPI spec -- `pnpm --filter @workspace/db run push` — push DB schema changes (dev only) -- `pnpm --filter @workspace/api-server run dev` — run API server locally +- `projects` — Référentiel des projets (code, nom, client, catégorie). +- `timesheets` — En-tête de CRA mensuel (année, mois, statut, collaborateur). +- `timesheet_lines` — Lignes affectant un projet à un CRA. +- `time_entries` — Saisie journalière (date, heures, description optionnelle). -## API Endpoints +Workflow d'un CRA : `draft` → `submitted` → `validated`. -- `GET/POST /api/projects` — List/create projects -- `GET/PATCH/DELETE /api/projects/:id` — Project CRUD -- `GET/POST /api/timesheets` — List/create timesheets (filter by year/month) -- `GET/PATCH/DELETE /api/timesheets/:id` — Timesheet CRUD (GET returns full detail with lines and entries) -- `GET/POST /api/timesheets/:id/lines` — Timesheet lines -- `DELETE /api/timesheets/:id/lines/:lineId` — Remove a line -- `PUT /api/timesheets/:id/entries` — Batch upsert time entries -- `GET /api/dashboard/summary` — Dashboard stats -- `GET /api/dashboard/monthly-hours` — Monthly hours breakdown -- `GET /api/dashboard/project-hours` — Hours per project +## API -See the `pnpm-workspace` skill for workspace structure, TypeScript setup, and package details. +Toutes les routes sont sous `/api`. + +| Méthode | Route | Rôle | +|---|---|---| +| `GET / POST` | `/api/projects` | Liste / création | +| `GET / PATCH / DELETE` | `/api/projects/:id` | CRUD projet | +| `GET / POST` | `/api/timesheets` | Liste / création (filtrable year/month) | +| `GET / PATCH / DELETE` | `/api/timesheets/:id` | CRUD CRA (GET = détail complet) | +| `GET / POST` | `/api/timesheets/:id/lines` | Lignes d'un CRA | +| `DELETE` | `/api/timesheets/:id/lines/:lineId` | Supprime une ligne | +| `PUT` | `/api/timesheets/:id/entries` | Upsert batch des saisies | +| `GET` | `/api/dashboard/summary` | Stats globales | +| `GET` | `/api/dashboard/monthly-hours` | Heures par mois | +| `GET` | `/api/dashboard/project-hours` | Heures par projet | + +L'OpenAPI spec se trouve dans `lib/api-spec/`. Après modif : + +```bash +pnpm --filter @workspace/api-spec run codegen +``` + +regénère les Zod et hooks React Query. + +## Commandes utiles + +```bash +pnpm run typecheck # tsc strict sur tout le workspace +pnpm run build # typecheck + build de tout +pnpm --filter @workspace/db run push # pousse le schéma Drizzle (dev) +pnpm --filter @workspace/db run push-force # idem, force (data-loss possible) +pnpm --filter @workspace/api-server run dev # API en watch +pnpm --filter @workspace/cra-app run dev # front en watch +docker compose build # rebuild les images +docker compose logs -f api # logs de l'API +``` + +## Limitations connues (POC) + +- Pas d'authentification ni de multi-utilisateur — tout le monde voit tout. +- Pas d'export PDF / Excel d'un CRA validé. +- Pas de tests automatisés. +- Workflow `submitted → validated` purement déclaratif (pas de notification, pas de signature). +- L'admin sidebar permet d'export/import en JSON, sans validation forte côté serveur. +- Le proxy Vite dev pour `/api` n'est pas configuré — utiliser Docker en attendant. + +## Licence + +MIT.