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) <noreply@anthropic.com>
This commit is contained in:
sylvain p
parent
7fd8598b8c
commit
5f55dfe7da
158
README.md
158
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
|
## Stack
|
||||||
|
|
||||||
- **Monorepo tool**: pnpm workspaces
|
| Couche | Techno |
|
||||||
- **Node.js version**: 24
|
|--------|--------|
|
||||||
- **Package manager**: pnpm
|
| Monorepo | pnpm workspaces |
|
||||||
- **TypeScript version**: 5.9
|
| Front | React 19, Vite, Tailwind 4, shadcn/ui, Wouter, TanStack Query |
|
||||||
- **Frontend**: React + Vite + Tailwind CSS + shadcn/ui
|
| API | Express 5, Pino |
|
||||||
- **API framework**: Express 5
|
| DB | PostgreSQL + Drizzle ORM |
|
||||||
- **Database**: PostgreSQL + Drizzle ORM
|
| Validation | Zod, drizzle-zod |
|
||||||
- **Validation**: Zod (`zod/v4`), `drizzle-zod`
|
| Codegen API | Orval (depuis l'OpenAPI spec) |
|
||||||
- **API codegen**: Orval (from OpenAPI spec)
|
| Bundle API | esbuild (single .mjs) |
|
||||||
- **Build**: esbuild (CJS bundle)
|
|
||||||
- **Charts**: Recharts
|
|
||||||
- **Routing**: Wouter
|
|
||||||
|
|
||||||
## 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)
|
artifacts/
|
||||||
- **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
|
api-server/ Express, bundlé en single-file ESM via esbuild
|
||||||
- **Project Management**: CRUD for projects with code, name, client, category
|
cra-app/ Front React/Vite (le SPA principal)
|
||||||
- **Timesheet Workflow**: Draft → Submitted → Validated status flow
|
mockup-sandbox/ Bac à sable de maquettes (non lié au build prod)
|
||||||
- **Inline Administration**: Sidebar Admin dialog to lock/unlock time entry editing and export/import project, CRA, line, and time-entry data as JSON
|
|
||||||
|
|
||||||
## 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)
|
scripts/ Scripts ponctuels TS (tsx)
|
||||||
- `timesheets` — Monthly timesheet headers (year, month, status, collaborator)
|
docker/ Dockerfiles api/web + nginx.conf
|
||||||
- `timesheet_lines` — Project assignments within a timesheet
|
```
|
||||||
- `time_entries` — Daily hour entries per line (date, hours, description)
|
|
||||||
|
|
||||||
## Key Commands
|
## Modèle de données
|
||||||
|
|
||||||
- `pnpm run typecheck` — full typecheck across all packages
|
- `projects` — Référentiel des projets (code, nom, client, catégorie).
|
||||||
- `pnpm run build` — typecheck + build all packages
|
- `timesheets` — En-tête de CRA mensuel (année, mois, statut, collaborateur).
|
||||||
- `pnpm --filter @workspace/api-spec run codegen` — regenerate API hooks and Zod schemas from OpenAPI spec
|
- `timesheet_lines` — Lignes affectant un projet à un CRA.
|
||||||
- `pnpm --filter @workspace/db run push` — push DB schema changes (dev only)
|
- `time_entries` — Saisie journalière (date, heures, description optionnelle).
|
||||||
- `pnpm --filter @workspace/api-server run dev` — run API server locally
|
|
||||||
|
|
||||||
## API Endpoints
|
Workflow d'un CRA : `draft` → `submitted` → `validated`.
|
||||||
|
|
||||||
- `GET/POST /api/projects` — List/create projects
|
## API
|
||||||
- `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
|
|
||||||
|
|
||||||
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.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user