5f55dfe7da
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) <noreply@anthropic.com>
128 lines
4.8 KiB
Markdown
128 lines
4.8 KiB
Markdown
# 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).
|
|
|
|
```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.
|