# Gestion de copropriété — v0.3.1 (28 juin 2026)

Application web interne pour gérer une ou plusieurs copropriétés : personnes, lots, tantièmes, compteurs/relevés et utilisateurs.

**Contexte agent / reprise de session :** voir [`docs/suivi-projet.md`](docs/suivi-projet.md) et [`AGENTS.md`](AGENTS.md).

**Stack :** Python 3 · Flask · SQLite · Gunicorn · Apache (reverse proxy)

**URL de production (actuelle) :** `https://www.stessy.org/papa/`  
Le chemin public est défini **uniquement dans Apache** (`X-Forwarded-Prefix`), pas dans le code Python.

---

## Objectif

Centraliser les données d'une copropriété (ou plusieurs) dans un outil simple :

- fiches **personnes** (contacts, rôles sur les lots) ;
- fiches **lots** (identification, surface, tantièmes, occupants/propriétaires) ;
- **relevés** de compteurs (eau, chauffage, etc.) ;
- **paramètres** par copropriété (types de tantièmes, types de relevés) ;
- **administration** des comptes utilisateurs.

Chaque utilisateur accède aux copropriétés qui lui sont assignées. Une copropriété « active » est sélectionnée en session.

---

## Fonctionnalités v0.2

| Module | Description |
|--------|-------------|
| Authentification | Connexion / déconnexion, protection CSRF, identifiants publics UUID dans les URLs |
| Copropriétés | Sélection, création, édition |
| Personnes | CRUD, contacts multiples, filtres par rôle, suppression logique, rôles dédupliqués au listing |
| Lots | CRUD enrichi (désignation, étage, porte, type paramétrable, n° fiscal), recherche et filtres, infobulles contacts au survol |
| Rôles lot↔personne | Affectation avec date facultative, autocomplétion à l'ajout |
| Relevés | Compteurs par lot, saisie d'index, historique |
| Paramètres | Types de tantièmes, types de relevés et **types de lots** par copropriété |
| Admin | Gestion des utilisateurs et de leurs accès |
| Mon compte | Préférence d'affichage des téléphones (national / international) |
| Navigation | Barre principale (4 entrées) + menu **Plus** pour les liens secondaires |

**Hors périmètre v0.2 :** facturation, AG, documents PDF, envoi d'e-mails, API REST.

---

## Fonctionnalités v0.3

| Module | Description |
|--------|-------------|
| Import Excel | CLI modulaire (`import_excel.py`) : copropriété, personnes, lots, rôles, contacts, surfaces, tantièmes, compteurs |
| Base import test | Écriture dans `data/import-test.db` par défaut ; `--prod` avec sauvegarde automatique |
| Sélecteur BDD | Choix **Production** / **Import (test)** à la connexion ; badge en en-tête si base import active |
| Comptes par défaut | `init_db.py` crée 3 utilisateurs (admin + 2 comptes famille) |
| SQLite | Timeout connexion 30 s, Gunicorn 1 worker, gestion erreurs écriture en admin |

**Hors périmètre v0.3 :** facturation, AG, documents PDF, envoi d'e-mails, API REST.

### v0.3.1

- Document de suivi multi-poste : `docs/suivi-projet.md`, `AGENTS.md`

**Hors périmètre v0.3.1 :** idem v0.3.

---

## Structure du projet

```
copro_gestion/
├── app/
│   ├── routes/          # Blueprints Flask (auth, personnes, lots…)
│   ├── templates/       # Pages HTML (Jinja2)
│   ├── static/          # CSS, JS (infobulles, combobox)
│   ├── templates/macros/ # Macros Jinja réutilisables
│   ├── models.py        # Modèles SQLAlchemy (14 tables)
│   ├── excel_import/    # Logique d'import Excel par contextes
│   ├── database_profiles.py  # Routage prod / import-test
│   └── phone.py         # Normalisation / affichage des téléphones
├── data/                # Bases SQLite (prod, import-test, rapports)
├── docs/                # Questionnaire import Excel
├── import_excel.py      # CLI import Excel
├── tools/               # Scripts utilitaires (questionnaire…)
├── deploy/
│   ├── copro_gestion.service   # Unit systemd
│   ├── install-service.sh      # Installation / réparation du service
│   └── env.example
├── config.py
├── wsgi.py              # Point d'entrée Gunicorn
├── init_db.py           # Création tables + migrations légères
├── create_user.py       # Création d'un utilisateur en CLI
├── run.py               # Serveur de développement local
└── requirements.txt
```

---

## Installation locale (développement)

```bash
cd copro_gestion
python3 -m venv venv
source venv/bin/activate          # Windows : venv\Scripts\activate
pip install -r requirements.txt

python init_db.py                 # Crée data/copropriete.db + compte admin par défaut
python run.py                     # http://127.0.0.1:5000
```

### Créer un utilisateur

```bash
python create_user.py mon_identifiant --admin
python create_user.py --list-coproprietes    # Lister les copropriétés (IDs)
python create_user.py user1 -c 1 -c 2        # Associer aux copropriétés 1 et 2
```

Le script `init_db.py` crée aussi les comptes par défaut si absents (variables `ADMIN_USERNAME` / `ADMIN_PASSWORD` optionnelles pour l'admin).

---

## Déploiement sur le VPS (production)

### Prérequis

- Python 3.10+
- Apache configuré en reverse proxy vers Gunicorn (port **8001**)
- Utilisateur système `www-data`

### 1. Installer l'application

```bash
cd /var/www/stessy.org/copro_gestion
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
./venv/bin/python init_db.py
```

### 2. Variables d'environnement

Copier `deploy/env.example` vers `.env` à la racine du projet :

```bash
cp deploy/env.example .env
# Éditer SECRET_KEY (chaîne aléatoire longue)
```

| Variable | Description | Défaut |
|----------|-------------|--------|
| `SECRET_KEY` | Clé de session Flask | *(à changer en prod)* |
| `DATABASE_URL` | URI SQLAlchemy | `sqlite:///…/data/copropriete.db` |
| `ADMIN_USERNAME` | Login admin créé par `init_db.py` | `stessy.cauet` |
| `ADMIN_PASSWORD` | Mot de passe admin initial | *(voir init_db.py)* |

### 3. Service systemd

```bash
sudo bash deploy/install-service.sh
```

Ce script :

- installe `copro_gestion.service` ;
- recrée le `venv` si invalide (ex. après renommage du dossier) ;
- démarre Gunicorn sur `127.0.0.1:8001`.

Commandes utiles :

```bash
sudo systemctl restart copro_gestion
sudo systemctl status copro_gestion
sudo journalctl -u copro_gestion -f
```

### 4. Apache

Voir `deploy-apache.example.conf`. Exemple minimal :

```apache
RequestHeader set X-Forwarded-Prefix "/papa"
<Location /papa>
    ProxyPass http://127.0.0.1:8001/
    ProxyPassReverse http://127.0.0.1:8001/
</Location>
```

Pour changer l'URL publique, modifier **seulement Apache** (préfixe + `X-Forwarded-Prefix`). Gunicorn et le code restent inchangés.

---

## Base de données

- **Moteur :** SQLite, fichier `data/copropriete.db`
- **Schéma :** créé par `db.create_all()` dans `init_db.py`
- **Évolutions :** migrations ad hoc dans `init_db.py` (pas d'Alembic)

Après chaque mise à jour du code qui modifie le schéma :

```bash
./venv/bin/python init_db.py
sudo systemctl restart copro_gestion
```

Les numéros de téléphone sont stockés au format international (`+33…`). L'affichage national (`06…`) est une préférence par utilisateur (page **Mon compte**).

---

## Exploitation courante

| Action | Commande |
|--------|----------|
| Mettre à jour le code | Synchronisation du partage réseau (`Y:\` ↔ VPS), puis `systemctl restart` |
| Mettre à jour les dépendances | `./venv/bin/pip install -r requirements.txt` |
| Mettre à jour la base | `./venv/bin/python init_db.py` |
| Ajouter un utilisateur | `./venv/bin/python create_user.py …` |
| Logs applicatifs | `journalctl -u copro_gestion -f` |

### Renommer ou déplacer le dossier

Le `venv` contient des chemins absolus. Après un déplacement :

```bash
sudo bash deploy/install-service.sh   # Recrée le venv si nécessaire + réinstalle le service
```

Ou manuellement : supprimer `venv`, recréer, `pip install -r requirements.txt`, adapter les chemins dans `/etc/systemd/system/copro_gestion.service` si besoin.

---

## Sécurité (production)

- Définir une `SECRET_KEY` forte dans `.env`
- Ne pas exposer Gunicorn directement sur Internet (écoute `127.0.0.1` uniquement)
- Changer le mot de passe administrateur initial après la première connexion
- Sauvegarder régulièrement `data/copropriete.db`

---

## Import Excel (CLI)

```bash
pip install openpyxl
python import_excel.py --dry-run --all          # simulation
python import_excel.py --all                    # écrit dans data/import-test.db
python import_excel.py --only personnes
python import_excel.py --only lots --no-reset   # enchaîner sans reset
python import_excel.py --all --prod             # sauvegarde + copropriete.db
```

Rapports dans `data/import-reports/`. Config questionnaire : `data/import-config.json`.

**Comparer prod / import :** choix du fichier SQLite **à la connexion** uniquement. Pour changer de base : déconnexion puis nouvelle connexion.

## Évolutions prévues (hors v0.3.1)

- Migration vers MariaDB (même schéma, `DATABASE_URL`)
- Migration progressive vers PHP (même base, double authentification au login)
- Éventuel passage en Docker pour simplifier le déploiement

---

*Documentation v0.3.1 — 28 juin 2026*