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

![Tableau de bord CRA Manager](docs/dashboard.png)

## 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

| 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 :

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