roxane/PROJECT_STRUCTURE.md

Roxane - Structure du projet

Roxane est une application de gestion d'adhésions pour Le Retzien Libre, une association libre/open source. Elle gère les membres, les cotisations, et s'intègre avec des services tiers (Dolibarr, ISPConfig, Nextcloud).

Stack technique

Couche	Technologies
Backend	Laravel 12, PHP 8.4, MySQL
Admin	Filament v4, Livewire 3
Frontend	React 19, Inertia v2, Tailwind CSS v4
Auth	Laravel Fortify, 2FA, Spatie Permissions + Shield
Tests	PHPUnit 11
DevTools	Pint, ESLint, Prettier, Sail, Wayfinder

---

Modeles Eloquent

User

• Traits : HasRoles, TwoFactorAuthenticatable
• Relations : members() hasMany(Member)
• Role : Implemente FilamentUser pour l'acces admin.

Member

• Table : members (soft deletes)
• Statuts : draft, valid, pending, cancelled, excluded
• Natures : physical, legal
• Relations :
  • user() belongsTo(User)
  • group() belongsTo(MemberGroup)
  • memberships() hasMany(Membership)
  • ispconfigs() hasMany(IspconfigMember)
  • nextcloudAccounts() hasMany(NextCloudMember)
• Accessors : full_name, retzien_email
• Methodes : lastMembership(), hasService(), isExpired()

Membership

• Table : memberships (soft deletes)
• Statuts : active, expired, pending
• Statuts paiement : paid, unpaid, partial
• Relations :
  • member() belongsTo(Member)
  • author() belongsTo(User, 'admin_id')
  • package() belongsTo(Package)
  • services() belongsToMany(Service) via services_memberships

Package

• Table : packages
• Donnees : custom (1EUR), one-year (12EUR), two-years (24EUR)

Service

• Table : services
• Relations : memberships() belongsToMany(Membership)
• Donnees : mail (RoundCube), file2link, nextcloud, sympa, webhosting

MemberGroup

• Table : member_groups
• Relations : members() hasMany(Member)
• Donnees : admin-interface, website

Contact

• Table : contacts

IspconfigMember

• Table : ispconfigs_members
• Cast : type vers IspconfigType enum, data vers array

NextCloudMember

• Table : nextclouds_members

---

Enums

Enum	Valeurs
IspconfigType	MAIL ("Email"), WEB ("Hebergement"), OTHER ("Autre")

---

Services (couche metier)

Service	Responsabilite
ContactService	Creation de demandes de contact
MemberService	Inscription et desactivation de membres
DolibarrService	Integration ERP via API REST
ISPConfigMailService	Gestion comptes mail via SOAP
ISPConfigWebService	Gestion hebergement web via SOAP (avec cache)
NextcloudService	Gestion comptes Nextcloud via OCS (avec cache 7 jours)

---

Commandes Artisan (synchronisation)

Commande	Description
sync:dolibarr-members	Importe les membres et cotisations depuis Dolibarr
members:cleanup-expired	Desactive les membres expires (Dolibarr + ISPConfig + Nextcloud). --dry-run
sync:ispconfig-mail-members	Lie les membres a leurs comptes mail ISPConfig (@retzien.fr)
sync:ispconfig-web-members	Lie les membres a leurs comptes d'hebergement web
nextcloud:sync-members	Lie les membres a leurs comptes Nextcloud
memberships:sync-services	Synchronise les services associes aux membres

---

Panel Admin (Filament v4)

Structure des ressources

app/Filament/Resources/<Nom>/
  ├── <Nom>Resource.php
  ├── Schemas/<Nom>Form.php
  ├── Tables/<Nom>sTable.php
  ├── Pages/ (List, Create, Edit)
  ├── Widgets/          (optionnel)
  └── RelationManagers/ (optionnel)

Ressources : MemberResource, MembershipResource, PackageResource, ServiceResource, MemberGroupResource, UserResource

Pages custom : Synchronisations (groupe "Paramètres" — lancement manuel des commandes Artisan)

Widgets : MemberCount, MembershipsChart

Actions custom : ServiceToggleAction

Permissions (Spatie + Shield)

Format : Action:Modele en PascalCase (ex: ViewAny:Member, Create:Membership)

Roles :

• super_admin : acces complet
• panel_user : acces au panel avec permissions specifiques

---

Frontend (React + Inertia v2)

Pages

resources/js/pages/
  ├── welcome.tsx / maintenance.tsx / dashboard.tsx
  ├── auth/     (login, register, forgot-password, reset-password, verify-email, two-factor-challenge)
  ├── forms/    (contact.tsx, membership.tsx)
  └── settings/ (profile, password, two-factor, appearance)

Composants principaux

resources/js/components/
  ├── app-shell.tsx / app-header.tsx / app-sidebar.tsx
  ├── nav-main.tsx / nav-user.tsx / nav-footer.tsx
  ├── breadcrumbs.tsx / flash-message.tsx
  ├── two-factor-setup-modal.tsx / appearance-tabs.tsx
  └── ui/ (Shadcn/ui)

---

Notifications

Toutes les notifications sont queueable (ShouldQueue). Le template Blade notifications/mail-template.blade.php est partagé et accepte une variable $appName pour différencier les emails membres des emails admin.

Classe	Canal	Destinataire	Déclencheur
ContactNewRequestNotification	Email	Admin	Soumission formulaire de contact
MemberNewRequestAdminNotification	Email	Admin	Soumission formulaire d'adhésion
MemberNewRequestMemberNotification	Email	Membre	Soumission formulaire d'adhésion (confirmation)
MembershipValidatedNotification	Email	Membre	Validation admin d'une adhésion (action Filament)
MemberDeactivatedMemberNotification	Email	Membre	Désactivation d'un membre
MemberDeactivatedAdminNotification	Email	Admin	Désactivation d'un membre
AdminInvitationNotification	Email	Admin	Création d'un compte administrateur
AdminPasswordResetNotification	Email	Admin	Réinitialisation de mot de passe admin
ServiceActivationRequestNotification	Email	Admin	Demande d'activation de service (dashboard)
SubscriptionExpiredPhase1	Email	Membre	Job planifié d'expiration d'adhésion

Config app_name dans les emails

• Emails membres : config('app.front_name') (variable FRONT_NAME dans .env)
• Emails admin : config('app.name') (variable APP_NAME dans .env)

---

Localisation

Langues : fr, en — fichiers dans lang/{locale}/ : contacts, members, memberships, packages, services, users, member_groups, synchronisations.

---

TODOs identifies dans le code

Fichier	TODO
Notifications (x9)	Propager appName dans ->view() pour toutes les notifications restantes
SubscriptionExpiredPhase1	UI backend pour éditer le contenu du template de notification
User.php	Restreindre l'acces admin en prod aux emails @retzien.fr
SyncDolibarrMembers	Exporter la methode toDate() dans un service/helper
SyncISPConfigMailMembers	Gerer plusieurs emails par membre
SyncISPConfigMailMembers	Ajouter le suivi ispconfig_client_id
MembershipValidatedNotification	Ajouter lien HelloAsso vers le paiement quand disponible
Global	Refactoriser pour rendre générique le projet Roxane (ERP pour association)
Traduction	Crawler le projet pour retrouver toutes les clés manquantes
Global	PHPstan niveau 8
dev-routes.php	Supprimer la route de test mail (/test/mail) avant mise en production