CRA-Helper/README.md

CRA-Helper

⚠️ 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.

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).

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

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

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)

Structure du repo

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)

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

scripts/            Scripts ponctuels TS (tsx)
docker/             Dockerfiles api/web + nginx.conf

Modèle de données

• 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).

Workflow d'un CRA : draft → submitted → validated.

API

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 :

pnpm --filter @workspace/api-spec run codegen

regénère les Zod et hooks React Query.

Commandes utiles

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.