339 lines
8.2 KiB
Markdown
339 lines
8.2 KiB
Markdown
# PolyMPR - Claude Code Context
|
||
|
||
## 📋 Project Overview
|
||
|
||
**PolyMPR** (Poly Management Platform for Resources) is a modular HR management
|
||
system built with **Deno + Fresh** framework. It's designed to help
|
||
organizations manage HR, student records, notes, mobility programs, and
|
||
role-based administration.
|
||
|
||
### Stack
|
||
|
||
- **Runtime**: Deno
|
||
- **Framework**: Fresh (edge-ready web framework)
|
||
- **Database**: PostgreSQL with Drizzle ORM
|
||
- **Frontend**: Preact with signals
|
||
- **Authentication**: JWT-based via cookies
|
||
- **Testing**: Deno test framework with HappyDOM for DOM testing
|
||
|
||
### Current Status
|
||
|
||
🚧 **In Progress** - Application is far from complete. The schema below is the
|
||
**final/definitive schema** that should guide all development.
|
||
|
||
---
|
||
|
||
## 🏗️ Architecture
|
||
|
||
### Module Structure
|
||
|
||
The application uses a **modulith architecture** with the following modules:
|
||
|
||
```
|
||
routes/(apps)/
|
||
├── students/ - Student management & promotions
|
||
├── notes/ - Grade management & academic records
|
||
├── mobility/ - Mobility programs & exchanges
|
||
└── admin/ - Role & permission management
|
||
```
|
||
|
||
### Key Directories
|
||
|
||
- `/routes` - Fresh routes and components
|
||
- `/databases` - Database connection, schema, and migrations
|
||
- `/defaults` - Interfaces and shared types
|
||
- `/tests` - Unit, integration, and E2E tests
|
||
- `/static` - Public assets
|
||
|
||
### Authentication Flow
|
||
|
||
1. User authenticates via CAS (Polytech)
|
||
2. JWT token stored in `sessionToken` cookie
|
||
3. Middleware validates token on each request
|
||
4. Public routes: `/`, `/login`, `/logout`, `/about`, `/contact`
|
||
5. All other routes require authentication
|
||
|
||
---
|
||
|
||
## 📊 Database Schema (Final/Definitive)
|
||
|
||
```mermaid
|
||
erDiagram
|
||
USER {
|
||
string id PK
|
||
string nom
|
||
string prenom
|
||
int idRole FK
|
||
}
|
||
ROLE {
|
||
int id PK
|
||
string nom
|
||
}
|
||
PERMISSION {
|
||
int id PK
|
||
string nom
|
||
}
|
||
ROLE_PERMISSION {
|
||
int idRole PK,FK
|
||
int idPermission PK,FK
|
||
}
|
||
STUDENT {
|
||
int numEtud PK
|
||
string nom
|
||
string prenom
|
||
string idPromo FK
|
||
}
|
||
PROMOTION {
|
||
string idPromo PK
|
||
string annee
|
||
}
|
||
MODULE {
|
||
string id PK
|
||
string nom
|
||
}
|
||
ENSEIGNEMENT {
|
||
string idProf PK,FK
|
||
string idModule PK,FK
|
||
string idPromo PK,FK
|
||
}
|
||
UE {
|
||
int id PK
|
||
string nom
|
||
}
|
||
UE_MODULE {
|
||
string idModule PK,FK
|
||
int idUE PK,FK
|
||
string idPromo PK,FK
|
||
float coeff
|
||
}
|
||
NOTE {
|
||
int numEtud PK,FK
|
||
string idModule PK,FK
|
||
float note
|
||
}
|
||
AJUSTEMENT {
|
||
int numEtud PK,FK
|
||
int idUE PK,FK
|
||
float valeur
|
||
}
|
||
|
||
USER }o--|| ROLE : "a"
|
||
ROLE_PERMISSION }o--|| ROLE : "accorde"
|
||
ROLE_PERMISSION }o--|| PERMISSION : "inclut"
|
||
ENSEIGNEMENT }o--|| USER : "réalisé par"
|
||
ENSEIGNEMENT }o--|| MODULE : "porte sur"
|
||
ENSEIGNEMENT }o--|| PROMOTION : "concerne"
|
||
STUDENT }o--|| PROMOTION : "appartient à"
|
||
UE_MODULE }o--|| MODULE : "associe"
|
||
UE_MODULE }o--|| UE : "appartient à"
|
||
UE_MODULE }o--|| PROMOTION : "pour"
|
||
NOTE }o--|| STUDENT : "reçoit"
|
||
NOTE }o--|| MODULE : "dans"
|
||
AJUSTEMENT }o--|| STUDENT : "concerne"
|
||
AJUSTEMENT }o--|| UE : "dans"
|
||
```
|
||
|
||
### Current Schema (Incomplete)
|
||
|
||
The current Drizzle ORM schema in `/databases/schema.ts` only implements:
|
||
|
||
- `promotions`
|
||
- `students`
|
||
- `mobility`
|
||
|
||
**Migration needed**: Update schema to match the final ER diagram above.
|
||
|
||
---
|
||
|
||
## 🎯 Open Issues (69 total)
|
||
|
||
### UI Pages
|
||
|
||
**Catalog**
|
||
|
||
- 📋 UI - Page Catalogue d'applications (#71)
|
||
|
||
**Components**
|
||
|
||
- 🎨 UI (composant) - Popup Résultats d'import (#75)
|
||
|
||
**Students**
|
||
|
||
- 📋 UI - Admin – Liste des élèves (#79)
|
||
- 📋 UI - Admin – Gestion des promotions (#80)
|
||
- 📋 UI - Admin – Import xlsx élèves (#81)
|
||
- 📋 UI - Admin – Édition d'un élève (#82)
|
||
|
||
**Notes**
|
||
|
||
- 📋 UI - Page Élève – Mes Notes (#72)
|
||
- 📋 UI - Admin – Consulter les notes (#73)
|
||
- 📋 UI - Admin – Importer des notes (.xlsx) (#74)
|
||
- 📋 UI - Admin – Édition notes d'un élève (#76)
|
||
- 📋 UI - Admin – Récap notes élève / semestre (#77)
|
||
- 📋 UI - Admin – Gestion des UEs (#78)
|
||
|
||
**Administration**
|
||
|
||
- 📋 UI - Gestion des utilisateurs (#83)
|
||
- 📋 UI - Gestion des rôles (#84)
|
||
- 📋 UI - Permissions d'un rôle (#85)
|
||
- 📋 UI - Vue des permissions (#86)
|
||
- 📋 UI - Gestion des modules (#87)
|
||
- 📋 UI - Enseignements (Assignations) (#88)
|
||
|
||
---
|
||
|
||
### API Endpoints
|
||
|
||
**Students API**
|
||
|
||
- 📋 GET `/students` (#7)
|
||
- 📋 POST `/students` (#8)
|
||
- 📋 POST `/students/import-csv` (#9)
|
||
- 📋 GET `/students/{numEtud}` (#10)
|
||
- 📋 PUT `/students/{numEtud}` (#11)
|
||
- 📋 DELETE `/students/{numEtud}` (#12)
|
||
- 📋 GET `/promotions` (#13)
|
||
- 📋 POST `/promotions` (#14)
|
||
- 📋 GET `/promotions/{idPromo}` (#15)
|
||
- 📋 PUT `/promotions/{idPromo}` (#16)
|
||
- 📋 DELETE `/promotions/{idPromo}` (#17)
|
||
|
||
**Administration API - Modules & Enseignements**
|
||
|
||
- 📋 GET `/modules` (#23)
|
||
- 📋 POST `/modules` (#24)
|
||
- 📋 GET `/modules/{idModule}` (#25)
|
||
- 📋 PUT `/modules/{idModule}` (#26)
|
||
- 📋 DELETE `/modules/{idModule}` (#27)
|
||
- 📋 POST `/enseignements` (#29)
|
||
- 📋 GET `/enseignements/{idProf}/{idModule}/{idPromo}` (#30)
|
||
- 📋 DELETE `/enseignements/{idProf}/{idModule}/{idPromo}` (#31)
|
||
|
||
**Notes API - UEs & UE-Modules**
|
||
|
||
- 📋 GET `/ues` (#32)
|
||
- 📋 POST `/ues` (#33)
|
||
- 📋 GET `/ues/{idUE}` (#34)
|
||
- 📋 PUT `/ues/{idUE}` (#35)
|
||
- 📋 DELETE `/ues/{idUE}` (#36)
|
||
- 📋 GET `/ue-modules` (#37)
|
||
- 📋 POST `/ue-modules` (#38)
|
||
- 📋 GET `/ue-modules/{idModule}/{idUE}/{idPromo}` (#39)
|
||
- 📋 PUT `/ue-modules/{idModule}/{idUE}/{idPromo}` (#40)
|
||
- 📋 DELETE `/ue-modules/{idModule}/{idUE}/{idPromo}` (#41)
|
||
|
||
**Notes API - Notes & Ajustements**
|
||
|
||
- 📋 GET `/notes` (#42)
|
||
- 📋 POST `/notes` (#43)
|
||
- 📋 POST `/notes/import-xlsx` (#44)
|
||
- 📋 GET `/notes/{numEtud}/{idModule}` (#45)
|
||
- 📋 PUT `/notes/{numEtud}/{idModule}` (#46)
|
||
- 📋 DELETE `/notes/{numEtud}/{idModule}` (#47)
|
||
- 📋 GET `/ajustements` (#48)
|
||
- 📋 POST `/ajustements` (#49)
|
||
- 📋 GET `/ajustements/{numEtud}/{idUE}` (#50)
|
||
- 📋 PUT `/ajustements/{numEtud}/{idUE}` (#51)
|
||
- 📋 DELETE `/ajustements/{numEtud}/{idUE}` (#52)
|
||
|
||
**Administration API - Users, Roles & Permissions**
|
||
|
||
- 📋 GET `/users` (#60)
|
||
- 📋 POST `/users` (#61)
|
||
- 📋 GET `/users/{id}` (#62)
|
||
- 📋 PUT `/users/{id}` (#63)
|
||
- 📋 DELETE `/users/{id}` (#64)
|
||
- 📋 GET `/roles` (#65)
|
||
- 📋 POST `/roles` (#66)
|
||
- 📋 GET `/roles/{idRole}` (#67)
|
||
- 📋 PUT `/roles/{idRole}` (#68)
|
||
- 📋 DELETE `/roles/{idRole}` (#69)
|
||
- 📋 GET `/permissions` (#70)
|
||
|
||
---
|
||
|
||
## 🎨 Design Reference
|
||
|
||
**Figma Prototype**:
|
||
https://www.figma.com/design/La79bsUsWnJCtMsrrt2zGd/Prototype?node-id=0-1
|
||
|
||
This is the **final design specification** for the UI. All UI implementations
|
||
should follow this design.
|
||
|
||
---
|
||
|
||
## 🚀 Development Guidelines
|
||
|
||
### Getting Started
|
||
|
||
```bash
|
||
# Run tests
|
||
deno task test
|
||
|
||
# Start development server
|
||
deno task start
|
||
|
||
# Build for production
|
||
deno task build
|
||
|
||
# Format & lint
|
||
deno task check
|
||
```
|
||
|
||
### Git Workflow
|
||
|
||
1. Create branch: `git checkout -b PMPR-{ISSUE_ID}`
|
||
2. Implement changes
|
||
3. Run tests and linting
|
||
4. Submit PR
|
||
|
||
### Code Style
|
||
|
||
- Format: Follow Deno defaults (enforced via `deno fmt`)
|
||
- Linting: Fresh recommended rules
|
||
- TypeScript strict mode enabled
|
||
- Use Drizzle ORM for database operations
|
||
|
||
### Testing
|
||
|
||
- Write unit tests for business logic
|
||
- Integration tests for API endpoints
|
||
- E2E tests with HappyDOM for UI interactions
|
||
- Mock database with provided helpers
|
||
|
||
---
|
||
|
||
## 📦 Key Dependencies
|
||
|
||
- **fresh@1.7.3** - Web framework
|
||
- **drizzle-orm@0.45.2** - ORM
|
||
- **pg@8.20.0** - PostgreSQL driver
|
||
- **@popov/jwt@1.0.1** - JWT utilities
|
||
- **preact@10.22.0** - UI library
|
||
- **happy-dom@16.0.0** - DOM testing
|
||
|
||
---
|
||
|
||
## 🔗 Related Resources
|
||
|
||
- **Repository**: https://git.polytech.djalim.fr/djalim/PolyMPR
|
||
- **Issue Tracker**: Gitea (via `tea` CLI)
|
||
- **Wiki**: Check CONTRIBUTING.md for dev setup
|
||
- **Database**: PostgreSQL (configured in `.env`)
|
||
|
||
---
|
||
|
||
## 💡 Important Notes
|
||
|
||
1. **Current Limitation**: The database schema in `/databases/schema.ts` does
|
||
NOT match the final ER diagram. This is a priority migration task.
|
||
2. **Design System**: Follow the Figma prototype for all UI work.
|
||
3. **Module Pattern**: Each module should follow the same pattern: routes, API
|
||
endpoints, components, and tests.
|
||
4. **Permissions**: All admin operations should respect the ROLE_PERMISSION
|
||
system.
|
||
5. **Fresh Conventions**: Routes use Fresh's file-based routing convention
|
||
(e.g., `routes/path/index.tsx`).
|