<markdown>
# Documentation technique - Projet Immobilier CISN

## 1. Vue d'ensemble du projet

### Objectifs et problématiques adressées
Ce projet WordPress développé par CISN (Compagnie Immobilière du Sud de Nantes) vise à :
- Présenter et gérer un double catalogue de biens immobiliers neufs et anciens
- Intégrer deux flux de données distincts : **Leizee** (biens neufs) et **Hektor/Périclès** (biens anciens)
- Proposer une recherche unifiée sur l'ensemble des biens disponibles
- Fournir des outils de simulation financière (calculateurs)
- Assurer la gestion des agences et références immobilières

### Contexte métier et utilisateurs cibles
- **Utilisateurs finaux** : Particuliers recherchant un logement (neuf/ancien, achat/location)
- **Gestionnaires** : Équipes CISN gérant les contenus et programmes
- **Partenaires** : 
  - **Leizee** : logiciel de gestion immobilière (programmes neufs)
  - **Hektor/Périclès** : logiciel de gestion des annonces traditionnelles

### Historique du projet et évolutions majeures
- Version 2.0 du thème CISN Immobilier
- Intégration du plugin WIA Leizee v2.0 pour la synchronisation Leizee
- Architecture de recherche unifiée combinant deux sources de données
- Système de sécurité CSP (Content Security Policy)

## 2. Architecture technique

### Stack technologique
- **CMS** : WordPress
- **Thème personnalisé** : CISN Immobilier v2.0
- **Plugin principal** : WIA Leizee v2.0 (interface API Leizee)
- **Framework CSS** : Bootstrap 5
- **Bibliothèques JavaScript** :
  - jQuery, Swiper.js, Leaflet.js, noUiSlider, Lity
- **Sources de données** :
  1. **API Leizee** : Programmes immobiliers neufs
  2. **CSV/Fichiers Hektor/Périclès** : Biens anciens (import via `/cisn_pericles`)

### Flux de données dual

#### 1. Flux Leizee (Biens neufs)
- **Source** : API Leizee
- **Plugin** : WIA Leizee v2.0
- **Stockage** : 
  - Custom Posts `programme` 
  - Tables dédiées : `wp_leizee_lot`, `wp_leizee_annexe`
- **Synchronisation** : Automatique via API

#### 2. Flux Hektor/Périclès (Biens anciens)
- **Source** : Fichiers CSV depuis dossier `../cisn_pericles` 
- **Stockage** : Table `wp_pericles_annonce`
- **Synchronisation** : Import batch via endpoint `/api/sync`

### Architecture de recherche unifiée
Le système utilise une **requête UNION** complexe dans `functions-biens.php:searchBiens()` pour interroger simultanément :
- Table Hektor : `pericles_annonce` 
- Table Leizee : `leizee_lot`

Cette architecture permet une recherche transparente sur l'ensemble du catalogue.

## 3. Structure du code

### Organisation des répertoires
```
wp-content/themes/
├── functions-biens.php (★ logique de recherche unifiée)
├── page-recherche.php (interface de recherche)
├── parts/
│   ├── detail-annonce-hektor.php (template biens anciens)
│   ├── detail-annonce-leizee.php (template biens neufs)
│   └── detail-annonce-autre.php (template générique)
└── css/, js/, blocks/

wp-content/plugins/wia-leizee/
├── wia-leizee.php
└── inc/classes/wia_leizee_import-class.php (★ import API Leizee)
```

### Modules principaux

#### 1. Moteur de recherche unifiée (`functions-biens.php`)
- **Fonction centrale** : `searchBiens($r, $save = TRUE)`
- **Responsabilités** :
  - Construction de requêtes SQL parallèles pour Hektor et Leizee
  - Unification des résultats via UNION
  - Gestion des filtres (prix, surface, lieu, type, dispositifs)
  - Mapping des champs entre les deux systèmes

#### 2. Gestion des templates dynamiques
- **Logique** : Détection automatique du type de bien par préfixe ID
  - `P` = Hektor/Périclès → `detail-annonce-hektor.php`
  - `L` = Leizee → `detail-annonce-leizee.php`
- **Implémentation** : Hook `template_include` dans `functions-biens.php:125`

#### 3. Plugin WIA Leizee
- **Import automatique** : Synchronisation API Leizee vers WordPress
- **Tables dédiées** : Création de `leizee_lot` et `leizee_annexe`
- **Actions WordPress** : `astraga_wia_leizee_lot` pour post-traitement

## 4. Fonctionnalités clés

### 4.1 Système de recherche dual
La recherche combine intelligemment deux sources :

```sql
-- Exemple simplifié de la logique UNION
SELECT * FROM pericles_annonce WHERE [filtres Hektor]
UNION 
SELECT * FROM leizee_lot WHERE [filtres Leizee adaptés]
```

**Adaptations par source** :
- **Prix** : `pv` (Hektor) vs `prix_valeur` (Leizee)  
- **Surface** : `surf_hab` vs `surface_totale_number`
- **Ville** : Gestion spéciale Leizee avec `ville_rattachement`

### 4.2 Filtres de recherche avancés
- **Types de biens** : Appartement, Maison, Terrain, etc.
- **Géolocalisation** : Gestion des villes et rattachements
- **Budget** : Prix d'achat ou loyers
- **Caractéristiques** : Surface, nombre de pièces
- **Dispositifs** : BRS, PSLA (codes 21 et 4 dans Leizee)

### 4.3 Gestion géographique complexe
- **Fonction** : `getRealCityNames()` pour normalisation des noms
- **Cas spécial** : "Pornic" vs "Pornichet" 
- **Leizee** : Support `ville_rattachement` + jointures sur CPTs WordPress

## 5. Base de données

### Tables principales

#### Tables Leizee (créées automatiquement)
```sql
wp_leizee_lot (
  idlot, ville_nom, ville_lat, ville_lon, ville_rattachement,
  prix_valeur, surface_totale_number, nb_pieces, dispositif_aide
)

wp_leizee_annexe (
  idlot, idtype, libelle, surface
)
```

#### Table Hektor/Périclès
```sql  
wp_pericles_annonce (
  no_asp, pv, surf_hab, nb_pce, ville, type_bien, transaction
)
```

### Synchronisation des données

#### Processus Leizee
1. **Avant import** : Dépublication programmes (`wia_leizee_import_before`)
2. **Import API** : Création/MAJ Custom Posts + meta fields
3. **Post-traitement** : Insertion dans `leizee_lot` via action `astraga_wia_leizee_lot`
4. **Finalisation** : Republication conditionnelle (`wia_leizee_should_skip`)

#### Processus Hektor
1. **Import CSV** : Lecture fichiers depuis `../cisn_pericles`
2. **Endpoint** : `/api/sync` pour déclenchement manuel
3. **Stockage direct** : Table `pericles_annonce`

## 6. Recherche de biens - Analyse technique

### Architecture de la requête unifiée

La fonction `searchBiens()` constitue le cœur du système. Elle génère une requête complexe combinant deux sources :

```php
function searchBiens($r, $save = TRUE) {
    global $wpdb, $question, $map, $typesBiens;
    
    // 1. Construction des filtres Hektor
    $where = array();
    $where['type'] = 'type_bien IN (...)';
    $where['lieu'] = 'ville = "..."';
    $where['prix'] = 'pv BETWEEN ... AND ...';
    
    // 2. Adaptation pour Leizee  
    $whereLeizee = $where;
    $whereLeizee['prix'] = str_replace('pv ', 'prix_valeur ', $where['prix']);
    $whereLeizee['lieu'] = '(ville_nom IN (...) OR ville_rattachement IN (...))';
    
    // 3. UNION des deux requêtes
    $sql = "SELECT * FROM pericles_annonce WHERE " . implode(' AND ', $where) . "
            UNION
            SELECT * FROM leizee_lot WHERE " . implode(' AND ', $whereLeizee);
}
```

### Gestion des spécificités par source

#### Mapping des champs
```php
$map = array(
    'prix' => 'pv',           // Hektor
    'loyer' => 'loyer_cc',    // Hektor  
    'ville' => 'ville',       // Hektor
);

// Adaptation automatique pour Leizee :
// 'pv' → 'prix_valeur'
// 'surf_hab' → 'surface_totale_number' 
// 'nb_pce' → 'nb_pieces'
```

#### Cas complexes

**Gestion géographique Leizee** :
```php
if (isset($whereLeizee['lieu'])) {
    $whereLeizee['lieu'] = '(
        ville_nom IN (' . $cities . ')
        OR ville_rattachement IN (' . $cities . ')  
        OR idlot IN (
            -- Jointure complexe avec les CPT WordPress ville
            select w.meta_value from wp_postmeta w 
            where w.meta_key="wia_leizee_lot_idlot" 
            and w.post_id in (...)
        )
    )';
}
```

**Dispositifs d'aide** :
```php
if ($dispositif === 1) {      // BRS
    $where['dispositif'] = 'dispositif_aide = 21';
} elseif ($dispositif === 2) { // PSLA  
    $where['dispositif'] = 'dispositif_aide = 4';
}
```

## 7. API et interfaces

### Endpoints REST
- `/api/search` : Recherche unifiée de biens
- `/api/sync` : Import données Hektor/Périclès
- `/api/rappeler` : Demande de rappel
- `/api/contacter` : Contact agence
- `/api/envoi-fiche` : Envoi fiche bien

### API Leizee
- **Authentification** : Configurée dans plugin WIA Leizee
- **Synchronisation** : Import programmes + lots automatique
- **Webhook** : Actions WordPress pour post-traitement

### Shortcodes disponibles
- `[programmes]` : Liste programmes Leizee avec pagination
- `[calculateur_mensualites]` : Simulateur mensualités
- `[calculateur_emprunt]` : Simulateur capacité emprunt

## 8. Sécurité et performance

### Content Security Policy
```php
$cspWhitelist = [
    'cisn.immo', 'leizee.com', 'google.com', 
    'openstreetmap.org', 'estimator.cityscan.fr'
];
```

### Optimisations requêtes
- **Index BDD** : Sur `idlot`, `ville_nom`, `prix_valeur` (Leizee)
- **Pagination** : Native WordPress pour programmes
- **Cache** : Sessions PHP pour dernière recherche utilisateur

## 9. Maintenance et évolution

### Points d'attention
1. **Synchronisation** : Surveillance des imports Leizee et Hektor
2. **Mapping champs** : Évolutions des APIs externes
3. **Performance** : Optimisation requêtes UNION
4. **Géolocalisation** : Maintenance table correspondances villes

### Logs et monitoring
- Import Leizee : Actions WordPress `wia_leizee_*`
- Erreurs SQL : Logs WordPress standards
- API Hektor : Endpoint `/api/sync` avec retours JSON

## 10. Glossaire technique

- **UNION SQL** : Combinaison des résultats de deux tables distinctes
- **Leizee** : Logiciel immobilier neuf avec API REST
- **Hektor/Périclès** : Logiciel traditionnel avec export CSV
- **WIA** : Web Images Associées (développeur plugin)
- **CPT** : Custom Post Types WordPress
- **ACF** : Advanced Custom Fields
- **CSP** : Content Security Policy
</markdown>