LMNP Organizer

Plateforme full-stack de gestion locative et de simulation fiscale pour la Location Meublée Non Professionnelle (LMNP).
Gestion des biens, baux, états des lieux, suivi des amortissements par composants et liasse fiscale au régime réel simplifié.

---

Présentation

La gestion de biens immobiliers meublés en France sous le statut fiscal LMNP (Location Meublée Non Professionnelle) implique des obligations juridiques, administratives et comptables rigoureuses. Les bailleurs doivent gérer des contrats de location conformes, des inventaires obligatoires, des états des lieux d'entrée et de sortie, la révision des loyers, l'amortissement par composants des immobilisations et des déclarations fiscales complexes.

LMNP Organizer est une application web open-source et conteneurisée conçue pour automatiser et simplifier l'ensemble du cycle de vie de la gestion locative meublée pour les propriétaires-bailleurs en gestion directe.

---

Fonctionnalités clés

🏢 Gestion des biens et du patrimoine

• Fiches détaillées des biens : Enregistrement des adresses, identifiants fiscaux, caractéristiques du bâti, diagnostics de performance énergétique (DPE) et équipements.
• Espaces privatifs structurés : Modélisation des pièces principales, pièces de service et annexes avec un ordre de visite persistant pour les états des lieux.
• Diagnostics immobiliers réglementaires : Suivi et archivage des certificats obligatoires avec alertes d'expiration.

👥 Locataires et dossiers de candidature

• Registre des locataires : Suivi des locataires principaux et des colocataires avec coordonnées et dossiers de candidature.
• Garants et Visale : Prise en charge des personnes physiques garantes, des organismes de caution et de la garantie Visale d'Action Logement.
• Protection et purge des candidatures : Chiffrement dans le navigateur des données et justificatifs de candidature, puis suppression 90 jours après leur sélection, leur rejet ou leur retrait, ou dès l'expiration d'un dossier resté 90 jours sans modification ; les pièces d'identité des anciens locataires sont supprimées 3 ans après la fin du bail.

📑 Baux et conformité juridique

• Modèles de contrats : Génération de baux meublés standards d'un an renouvelables et de baux étudiants non renouvelables de 9 mois.
• Actes de cautionnement : Suivi d'intégrité SHA-256 et empreinte déterministe liant directement les actes aux données du contrat.
• Révision des loyers : Calcul automatisé de l'indexation des loyers basé sur l'Indice de Référence des Loyers (IRL) officiel trimestriel de l'INSEE.
• Dépôts de garantie : Validation automatique du plafond légal (maximum 2 mois de loyer hors charges) et suivi de la restitution.

📋 États des lieux et inventaires

• Inspection pas à pas par pièce : Parcours guidé suivant la séquence de visite prédéfinie du logement.
• Inventaire du mobilier : Liste de contrôle des équipements obligatoires en LMNP par pièce.
• Photos de preuve : Prise de photos pour la vue d'ensemble des pièces et les éléments dégradés, compressées au format WebP et hachées côté backend.
• Comparaison entrée / sortie : Rapprochement automatique pour calculer les retenues équitables sur le dépôt de garantie.

💶 Suivi des loyers et facturation

• Appels de loyer automatisés : Génération mensuelle des échéances liées aux baux actifs.
• Moteur d'imputation des règlements : Enregistrement des paiements reçus, gestion des règlements partiels, trop-perçus, annulations et remboursements.
• Quittances de loyer en PDF : Génération et téléchargement de quittances PDF conformes pour les loyers acquittés.

🧾 Dépenses et emprunts

• Classification intelligente des dépenses : Catégorisation automatique en charge déductible ou en immobilisation (actif capitalisé) selon le seuil de 500 € HT et les règles par catégorie.
• Tableaux d'amortissement d'emprunt : Génération des échéanciers de prêt (capital, intérêts, assurance) avec points d'ajustement manuel pour correspondre aux relevés bancaires.

📊 Amortissements par composants

• Décomposition des actifs : Amortissement des biens selon des composants standardisés (Gros œuvre, Toiture, Façade, Agencements, Équipements) avec exclusion obligatoire de la quote-part de terrain.
• Événements de cycle de vie : Gestion des bilans d'ouverture, des mises au rebut, des remplacements et des révisions de composants.

🏛️ Simulation fiscale et exercices fiscaux

• Régime Réel Simplifié LMNP : Simulations préremplies des liasses fiscales françaises (Formulaire 2033 : bilan et compte de résultat, et Formulaire 2042-C-PRO : déclaration de revenus).
• Suivi des reports : Calcul automatisé et suivi illimité dans le temps des reports de déficits fiscaux et des amortissements réputés différés (ARD - Article 39 C du CGI).

---

Architecture et stack technique

flowchart TD
    Client["SPA Angular 22 (Runtime Bun)"]
    Backend["Backend Spring Boot 4 (Java 25)"]
    Mongo[("Replica Set MongoDB 8.0")]
    OIDC["Fournisseur d'identité OIDC (voidAuth / Dex)"]
    Storage["Stockage de fichiers local (Pièces jointes & baux)"]

    Client -->|API REST + Cookie de session| Backend
    Client -->|Flux OAuth2 / OIDC| OIDC
    Backend -->|Validation des jetons| OIDC
    Backend -->|Transactions ACID & Données| Mongo
    Backend -->|Lecture / Écriture / Compression WebP| Storage

Chiffrement des candidatures

Le mécanisme de chiffrement de bout en bout défini par l'ADR-0034 protège les données et justificatifs de candidature avant leur envoi au serveur :

sequenceDiagram
    autonumber
    participant B as Navigateur du bailleur
    participant P as Passkey WebAuthn
    participant S as Serveur LMNP Organizer
    participant C as Navigateur du candidat

    Note over B,S: Activation des candidatures
    B->>P: Enrôle une passkey et demande le résultat PRF
    P-->>B: Secret PRF local
    B->>B: Génère la paire de clés du bailleur
    B->>B: Dérive par HKDF-SHA-256 puis chiffre la clé privée par AES-256-GCM
    B->>S: Envoie la clé publique et l'enveloppe de clé privée chiffrée

    Note over S,C: Création et saisie d'un dossier
    C->>S: Ouvre le lien public du logement par un GET sans effet
    S-->>C: Fournit la notice et la clé publique du bailleur
    C->>C: Génère la capacité et la clé du dossier
    C->>C: Chiffre la clé du dossier par RSA-OAEP 3072 / SHA-256
    C->>S: POST avec la capacité en en-tête et la clé de dossier chiffrée
    S->>S: Ne conserve qu'une empreinte de la capacité
    S-->>C: Fournit l'identifiant du brouillon vide
    C->>C: Remplace l'URL par identifiant + capacité + clé après #

    Note over S,C: Saisie ultérieure du dossier
    C->>C: Chiffre les champs et les PDF/JPEG/PNG par AES-256-GCM
    C->>S: Envoie seulement les chiffrés et utilise la capacité d'accès

    Note over B,S: Lecture d'un dossier soumis
    B->>S: Demande le dossier avec sa session OIDC
    S-->>B: Retourne les chiffrés et les enveloppes de clés
    B->>P: Déverrouille avec la passkey et demande le résultat PRF
    P-->>B: Secret PRF local
    B->>B: Ouvre la clé privée, puis la clé du dossier et son contenu

    Note over B,P: Ajout ultérieur d'une passkey
    B->>P: Enrôle une nouvelle passkey depuis un navigateur déjà déverrouillé
    B->>B: Chiffre la même clé privée dans une nouvelle enveloppe
    B->>S: Ajoute uniquement cette enveloppe chiffrée

• Le navigateur n'envoie pas le fragment # : il transmet seulement la capacité dans l'en-tête d'autorisation, jamais la clé du dossier. Tant qu'ils appartiennent à la candidature, le serveur ne reçoit pas non plus le résultat PRF, la clé privée en clair, les champs personnels ou le contenu des justificatifs.

• OIDC autorise l'accès aux chiffrés mais ne permet pas de les déchiffrer.

• Un déverrouillage partage la clé non exportable en mémoire entre les onglets LMNP du même profil navigateur ; fermer tous les onglets ou redémarrer le navigateur impose une nouvelle passkey.

• Les justificatifs sont limités aux formats PDF, JPEG et PNG, à 25 Mo par fichier et 250 Mo par candidature.

• La perte du lien privé oblige le candidat à recommencer ; la perte de toutes les passkeys rend les dossiers existants irrécupérables.

• Un intrus contrôlant l'hôte ne peut pas ouvrir les contenus déjà stockés, mais peut compromettre le client web servi lors d'une utilisation ultérieure et capturer alors les données déchiffrées.

• La sélection crée seulement la copie minimale prénom, nom et contact dans le modèle Locataire actuel encore en clair ; son chiffrement relève du ticket #146 et aucun justificatif n'est copié automatiquement.

• Backend :

  • Langage : Java 25 (LTS)
  • Framework : Spring Boot 4.0.7 (Spring WebMvc, Spring Data MongoDB, Spring Security OAuth2 Client)
  • Génération de PDF : OpenHTMLtoPDF (PDFBox)
  • Traitement d'images : Intégration CLI ImageMagick pour la conversion et l'optimisation automatique en WebP
  • Tests : JUnit 5, MockMvc, Testcontainers MongoDB, JaCoCo (couverture de code minimale de 80 % requise)

• Frontend :

  • Framework : Angular 22 (Composants standalone, Signals, Formulaires réactifs typés)
  • Styles : Design tokens modernes en Vanilla SCSS (_tokens.scss, _palette.scss) avec composants Angular Material
  • Gestionnaire de paquets et environnement d'exécution : Bun 1.3+
  • Tests : Vitest (tests unitaires) & Playwright (tests E2E sur navigateur)

• Base de données :

  • MongoDB 8.0 configuré en replica set mono-nœud (rs0) pour prendre en charge les transactions ACID multi-documents.

• Authentification :

  • OpenID Connect (OIDC) compatible avec voidAuth, Keycloak, Dex ou tout autre fournisseur d'identité OAuth2.

---

Prérequis

Assurez-vous d'avoir installé les outils suivants sur votre machine :

• Docker & Docker Compose (Docker 26+, Compose v2.20+)
• Kit de développement Java (JDK) 25 (pour le développement backend natif)
• Bun 1.3+ (ou Node.js 22+ pour le développement frontend natif)

---

Prise en main

1. Configurer les variables d'environnement

Créez votre fichier local .env à partir de l'exemple fourni :

cp .env.example .env

Mettez à jour les variables de configuration dans .env :

# Identifiants MongoDB
MONGO_ROOT_USERNAME=lmnp
MONGO_ROOT_PASSWORD=votre-mot-de-passe-securise-url-safe

# Configuration du fournisseur d'identité OIDC
OIDC_ISSUER_URI=http://localhost:8090/realms/voidAuth
OIDC_CLIENT_ID=lmnp-client
OIDC_CLIENT_SECRET=votre-secret-client-oidc
# Autorité OIDC qui accorde la capacité Administrateur
OIDC_ADMIN_ROLE=admin

# Ports de développement (pour compose.dev.yml)
BACKEND_PORT=8080
FRONTEND_PORT=8081

---

2. Option A : Lancement via Docker Compose (Recommandé)

Lancez la stack de développement complète (replica set MongoDB, backend, frontend) avec reconstruction à chaud des conteneurs :

docker compose -f compose.dev.yml up --build

• Application Frontend : http://localhost:8081
• API Backend : http://localhost:8080
• MongoDB : localhost:27017

Pour exécuter le profil de production à la place :

docker compose up --build

---

3. Option B : Développement local natif

Si vous préférez exécuter le backend et le frontend directement sur votre machine hôte pour une itération plus rapide :

Étape 1 : Démarrer MongoDB

Démarrez le conteneur du replica set MongoDB :

docker compose -f compose.dev.yml up -d mongodb

Étape 2 : Démarrer le Backend (Java 25)

Rendez-vous dans le répertoire backend et lancez Spring Boot :

cd backend
./mvnw spring-boot:run

Étape 3 : Démarrer le Frontend (Angular 22)

Dans un autre terminal, installez les dépendances avec Bun et démarrez le serveur de développement Angular :

cd frontend
bun install
bun run start

Le frontend sera accessible sur http://localhost:4200 et relaiera les requêtes API vers http://localhost:8080 via proxy.conf.json.

---

Tests et assurance qualité

Le projet applique une pyramide de tests stricte sur 3 niveaux avec une couverture de code minimale de 80 % requise à la fois sur le frontend et le backend.

1. Niveau de tests Backend

Exécute les tests unitaires et d'intégration avec Spring Boot Test et Testcontainers MongoDB :

cd backend
./mvnw clean test        # Exécuter les tests unitaires
./mvnw clean verify      # Exécuter l'ensemble des tests avec vérification de couverture JaCoCo et linter

2. Niveau de tests Frontend

Exécute les tests unitaires rapides (Vitest), la vérification des types et les tests E2E avec bouchons (mocks) :

cd frontend
bun run test             # Tests unitaires via Vitest
bun run lint             # Vérifications ESLint Angular
bun run typecheck        # Validation TypeScript
bun run e2e              # Tests navigateur Playwright (authentification bouchonnée)
bun run e2e:ui           # Lanceur de tests interactif Playwright UI

3. Niveau E2E Full-Stack en conditions réelles

Exécute les parcours utilisateurs complets de bout en bout dans un environnement entièrement conteneurisé comprenant un Replica Set MongoDB, l'authentification OIDC avec Dex et un service mock de l'IRL de l'INSEE :

./scripts/e2e-real/run.sh

Les artéfacts et les traces d'exécution des tests sont enregistrés dans .e2e-real-artifacts/.

---

Structure du dépôt

lmnp-organizer/
├── backend/                  # Application Java 25 / Spring Boot 4
│   ├── src/main/java/        # Modèles de domaine, services, contrôleurs REST, dépôts
│   ├── src/main/resources/   # Propriétés de l'application, modèles PDF, règles juridiques
│   └── src/test/             # Suite de tests unitaires et d'intégration (Testcontainers)
├── frontend/                 # Application monopage (SPA) Angular 22
│   ├── src/app/              # Composants standalone, services, modèles
│   ├── src/app/components/   # Modules fonctionnels (Appartements, Baux, Fiscalité, etc.)
│   ├── e2e/                  # Tests bout en bout Playwright
│   └── e2e-real/             # Tests Playwright en environnement réel complet
├── compose.yml               # Définition Docker Compose de production
├── compose.dev.yml           # Définition Docker Compose de développement
├── compose.e2e.yml           # Stack Docker Compose pour les tests E2E réels (Dex, Mock INSEE, Mongo)
├── docs/                     # Spécifications du projet, ADR et recherches
│   ├── adr/                  # Décisions d'architecture (Architectural Decision Records)
│   ├── spec/                 # Cahier des charges et spécifications produit (PRD)
│   └── agents/               # Instructions et conventions pour les agents IA
├── scripts/                  # Scripts utilitaires (lanceurs E2E, données d'initialisation)
├── CONTEXT.md                # Glossaire métier unique de référence et règles de gestion légales
└── AGENTS.md                 # Règles d'ingénierie et normes d'architecture

---

Documentation et standards métier

• CONTEXT.md : Référence canonique pour la terminologie LMNP, les invariants légaux et les règles comptables.
• Spécification PRD : Récits utilisateurs fonctionnels (User Stories), choix techniques et périmètre du projet.
• AGENTS.md : Règles de code, standards Angular, bonnes pratiques Spring Boot et workflows Git.
• Registres de décisions d'architecture (docs/adr/) : Historique des décisions d'architecture majeures.

---

Intégration et déploiement continus (CI/CD)

Le pipeline GitLab CI s'exécute à chaque push et sur chaque merge request (.gitlab-ci.yml) :

1. Étape test : Exécution en parallèle de backend-test (mvn clean verify), frontend-test (bun test avec couverture) et frontend-e2e (Playwright).
2. Étape real-backend-e2e : Tests d'intégration full-stack multi-conteneurs (./scripts/e2e-real/run.sh).
3. Étape publish : Construction et publication des images de conteneurs de production vers le registre de conteneurs GitLab via Buildah lors de la création de tags et des fusions sur la branche par défaut.

---

Licence

Ce projet est sous licence GNU Affero General Public License v3.0 (AGPL-3.0). Consultez le fichier LICENSE pour plus de détails.