Organisation des dossiers
Chaque dossier a un rôle précis. Quand tu cherches quelque chose, demande-toi d'abord : est-ce une règle du métier, ou une question d'HTTP ? La réponse te dit dans quelle moitié chercher.
L'arborescence
timemanager-api/
├── config/ la configuration, par environnement
├── lib/
│ ├── timemanager/ LE MÉTIER : les règles, la base de données
│ └── timemanager_web/ LE WEB : HTTP, JSON, sessions, documentation
├── priv/
│ ├── repo/migrations/ la structure des tables, migration par migration
│ ├── repo/seeds.exs le premier General Manager
│ ├── repo/demo_seeds.exs les données de démonstration
│ └── gettext/ les traductions des e-mails et notifications (fr, en)
├── test/ les tests, rangés comme lib/
└── mix.exs le projet : dépendances et alias (mix setup…)lib/timemanager/ : le métier
Un contexte (un fichier à la racine) et, à côté, un dossier du même nom pour ses schémas (les tables) :
| Contexte | Ses schémas | Rôle |
|---|---|---|
accounts.ex | accounts/user.ex, password_token.ex, user_notifier.ex, email_layout.ex | comptes, mots de passe, liens envoyés par e-mail et leur mise en page |
auth/ | sessions.ex, token.ex, refresh_token.ex | les sessions : jeton d'accès (JWT) et jeton de rafraîchissement |
authorization.ex | le seul endroit où les droits sont décidés | |
clocks.ex | clocks/clock.ex | les pointages d'arrivée et de départ |
device_actions.ex | ce qu'un téléphone peut envoyer (action, identifiant, heure) | |
workingtime.ex | workingtime/time_tracking.ex, break.ex, working_time_change.ex | les journées, les pauses, l'historique des modifications |
teams.ex | teams/team.ex, team_member.ex | les équipes et leurs membres |
corrections.ex | corrections/correction_request.ex | les demandes de correction |
absences.ex | absences/absence.ex | les jours d'absence |
week_validations.ex | week_validations/week_validation.ex | les semaines validées par un manager |
notifications.ex | notifications/notification.ex, text.ex | la cloche, et la phrase de chaque notification |
reports.ex | les totaux et les moyennes | |
personal_data.ex | la copie de « Mes données » | |
localized_dates.ex | les dates écrites en français ou en anglais | |
repo.ex, mailer.ex, application.ex, release.ex | la connexion à la base, l'envoi d'e-mails, le démarrage, les migrations en production |
lib/timemanager_web/ : le web
| Fichier ou dossier | Rôle |
|---|---|
endpoint.ex | la porte d'entrée : ce que chaque requête traverse |
router.ex | l'aiguillage : chaque adresse et son contrôleur |
plugs/authenticate.ex | qui appelle ? (cookie + CSRF pour le web, Bearer pour le mobile) |
plugs/cors.ex | quels sites ont le droit d'appeler l'API depuis un navigateur |
session_cookies.ex | pose et efface les cookies de session du web |
params.ex | lit un identifiant venu de l'adresse ("5" → 5) |
controllers/*_controller.ex | un contrôleur par ressource : ClockController, UserController… |
controllers/*_json.ex | la vue JSON de chaque ressource : les champs envoyés, ni plus ni moins |
controllers/fallback_controller.ex | toute erreur devient une réponse JSON avec un code stable |
controllers/changeset_json.ex | la forme des erreurs 422 (errors et details) |
api_docs/ | la description Swagger, à part des contrôleurs : schemas/, paths/, api_spec.ex |
gettext.ex | les traductions |
config/ : la configuration
| Fichier | Quand il est lu |
|---|---|
config.exs | toujours : les réglages communs (fuseau de la mairie, Europe/Paris) |
dev.exs, test.exs, prod.exs | selon l'environnement (MIX_ENV) |
runtime.exs | au démarrage, en production : lit les variables d'environnement (base, secrets, e-mails) |
Pourquoi runtime.exs ?
Les autres fichiers sont lus à la compilation : l'image Docker serait figée avec les valeurs du moment. runtime.exs est lu au démarrage du serveur, ce qui permet de garder les secrets hors de l'image et de les fournir par l'environnement. La liste des variables est dans Docker et images.
test/ : les tests
Les tests suivent la même coupure que lib/ :
| Dossier | Ce qu'on y teste |
|---|---|
test/timemanager/ | le métier, en appelant directement les contextes (clocks_test.exs, week_lock_test.exs…) |
test/timemanager_web/ | les routes, avec de vraies requêtes HTTP (clock_controller_test.exs, api_docs_test.exs…) |
test/support/ | les outils : conn_case.ex (requêtes connectées), data_case.ex (base), fixtures/ (fabriquer un compte, une équipe…) |