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                              |
| `sync:nextcloud-members`        | Lie les membres a leurs comptes Nextcloud                                      |
| `sync:services-members`         | 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

| Classe                    | Canal | Description                                   |
| ------------------------- | ----- | --------------------------------------------- |
| SubscriptionExpiredPhase1 | Email | Notification d'expiration d'adhesion (queued) |

---

## Localisation

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

---

## TODOs identifies dans le code

| Fichier                   | TODO                                                                       |
|---------------------------|----------------------------------------------------------------------------|
| ContactService            | Envoyer un email a l'administrateur                                        |
| MemberService             | Envoyer des emails au membre + admin a la desactivation                    |
| SubscriptionExpiredPhase1 | Creer un template generique + UI backend pour le contenu                   |
| 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                                       |
| Global                    | Refactoriser pour rendre générique le projet Roxane (ERP pour association) |
| Traduction                | Crawler le prrojet pour retrouver toutes les clés manquantes               |
| Global                    | PHPstan niveau 8                                                           |