# Manuel d'installation et de déploiement

## Table des matières

1. [Prérequis](#1-prérequis)
2. [Structure des répertoires](#2-structure-des-répertoires)
3. [Installation d'Apache 2.4](#3-installation-dapache-24)
4. [Installation de PHP 8.2](#4-installation-de-php-82)
5. [Configuration d'Apache](#5-configuration-dapache)
6. [Oracle Instant Client](#6-oracle-instant-client)
7. [Déploiement de l'application](#7-déploiement-de-lapplication)
8. [Initialisation de la base SQLite](#8-initialisation-de-la-base-sqlite)
9. [Démarrage et vérification](#9-démarrage-et-vérification)
10. [Modèle deux instances (dev / prod)](#10-modèle-deux-instances-dev--prod)
11. [Gestion du dépôt Git](#11-gestion-du-dépôt-git)
12. [Paramètres applicatifs](#12-paramètres-applicatifs)
13. [Journaux et débogage](#13-journaux-et-débogage)

---

## 1. Prérequis

| Composant | Version minimale | Notes |
|---|---|---|
| Windows | 10 / 11 | Testé sur Windows 11 Home |
| Apache HTTPD | 2.4.x | Binaires VS17 x64 |
| PHP | 8.2.x | Thread-safe (TS) pour mod_php |
| Oracle Instant Client | 19c | Requis pour le module Oracle |
| Git | 2.x | Gestion du code source |

> **PHP doit être la version Thread-Safe (TS)** car il est chargé comme module Apache (`php8apache2_4.dll`).

---

## 2. Structure des répertoires

```
C:\Users\jolyo\ppowa-64S\          ← racine de l'instance (exemple prod)
├── httpd-2.4\                     ← serveur Apache
│   ├── conf\httpd.conf
│   └── logs\
├── php-8.2.17\                    ← interpréteur PHP
│   ├── php.ini
│   ├── php8apache2_4.dll
│   └── ext\
└── my-app\                        ← code source de l'application
    ├── mon-appli\                 ← racine web (DocumentRoot)
    │   ├── index.php
    │   ├── bootstrap.php
    │   ├── login.php
    │   ├── includes\
    │   ├── modules\
    │   ├── admin\
    │   ├── assets\
    │   └── i18n\
    ├── lib\                       ← bibliothèques PHP (non web)
    │   ├── Config.php
    │   ├── Database.php
    │   ├── Auth.php
    │   └── ...
    ├── securite\                  ← données sensibles (non web)
    │   └── database.sqlite        ← base SQLite (créée automatiquement)
    └── log\                       ← journaux applicatifs (créés automatiquement)
        ├── app.log
        ├── debug.log
        └── trace.log
```

> Les répertoires `securite/` et `log/` sont **hors du DocumentRoot** et ne sont pas accessibles via HTTP.

---

## 3. Installation d'Apache 2.4

1. Télécharger les binaires Apache 2.4 pour Windows (VS17 x64) depuis [apachelounge.com](https://www.apachelounge.com/).
2. Extraire dans `C:\Users\jolyo\ppowa-64S\httpd-2.4\`.
3. Vérifier que le Visual C++ Redistributable correspondant est installé.

---

## 4. Installation de PHP 8.2

1. Télécharger PHP 8.2.x **Thread Safe (TS) x64** depuis [windows.php.net](https://windows.php.net/download/).
2. Extraire dans `C:\Users\jolyo\ppowa-64S\php-8.2.17\`.
3. Copier `php.ini-production` vers `php.ini` et ajuster :

```ini
; Répertoire des extensions
extension_dir = "C:/Users/jolyo/ppowa-64S/php-8.2.17/ext"

; Extensions requises
extension=bz2
extension=curl
extension=fileinfo
extension=gd
extension=gettext
extension=gmp
extension=intl
extension=imap
extension=ldap
extension=mbstring
extension=exif          ; doit être après mbstring
extension=openssl
extension=sockets
extension=sqlite3
extension=zip

; Oracle (choisir selon la version d'Instant Client installée)
extension=oci8_19       ; pour Oracle Instant Client 19c

; Encodage par défaut
default_charset = "UTF-8"
```

> **Ne pas activer `pdo_sqlite`** : l'application utilise la classe native `SQLite3` (extension `sqlite3`).

---

## 5. Configuration d'Apache

Éditer `C:\Users\jolyo\ppowa-64S\httpd-2.4\conf\httpd.conf` :

```apache
; Chemins
define PHPINSTALLDIR "C:/Users/jolyo/ppowa-64S/php-8.2.17"
PHPIniDir "${PHPINSTALLDIR}"
Define SRVROOT "C:/Users/jolyo/ppowa-64S/httpd-2.4"
ServerRoot "${SRVROOT}"

; Ports d'écoute
Listen 8081     ; production
Listen 8180     ; développement

; Chargement du module PHP
AddHandler application/x-httpd-php .php
AddType application/x-httpd-php .php .phtml
LoadModule php_module "C:/Users/jolyo/ppowa-64S/php-8.2.17/php8apache2_4.dll"

; Racine web (production)
DocumentRoot "C:/Users/jolyo/ppowa-64S/my-app/mon-appli"
<Directory "C:/Users/jolyo/ppowa-64S/my-app/mon-appli">
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

; Page d'accueil par défaut
<IfModule dir_module>
    DirectoryIndex index.php index.html
</IfModule>

; Journaux
ErrorLog  "logs/error.log"
LogLevel  warn
CustomLog "logs/access.log" common
```

### VirtualHost développement (port 8180)

Ajouter à la fin de `httpd.conf` (ou dans un fichier inclus) :

```apache
<VirtualHost *:8180>
    DocumentRoot "C:/Users/jolyo/sw/sw/mon-appli"
    <Directory "C:/Users/jolyo/sw/sw/mon-appli">
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog  "logs/dev-error.log"
    CustomLog "logs/dev-access.log" common
</VirtualHost>
```

---

## 6. Oracle Instant Client

Le module Oracle nécessite Oracle Instant Client 19c pour l'extension OCI8.

1. Télécharger **Instant Client Basic 19.x** (64-bit) depuis [oracle.com](https://www.oracle.com/database/technologies/instant-client.html).
2. Extraire dans un répertoire, par exemple `C:\oracle\instantclient_19_25\`.
3. Ajouter ce répertoire au `PATH` système Windows.
4. Redémarrer Apache pour que le `PATH` soit pris en compte.

### Connexion standard (host:port/service)

Les bases sont enregistrées dans l'interface d'administration avec :
- **Hôte** (`host`)
- **Port** (défaut : 1521)
- **Nom de service** (`service_name`)
- **Utilisateur** / **Mot de passe**
- **SYSDBA** : cocher si connexion AS SYSDBA

La chaîne de connexion OCI8 construite est `host:port/service_name`.

### Connexion cloud (wallet)

Pour Oracle Autonomous Database ou connexion via wallet :
1. Télécharger le wallet depuis Oracle Cloud Console.
2. Extraire le wallet dans un répertoire accessible par Apache.
3. Dans l'interface d'administration, saisir le chemin du wallet et l'alias TNS.

Le module positionne automatiquement la variable `TNS_ADMIN` pointant vers le répertoire du wallet.

### Initialisation de session OCI8

À chaque connexion, le module exécute automatiquement :

```sql
ALTER SESSION SET nls_sort            = BINARY
ALTER SESSION SET nls_date_format     = 'YYYY-MM-DD"T"HH24:MI:SS'
ALTER SESSION SET nls_timestamp_format = 'YYYY-MM-DD"T"HH24:MI:SS'
BEGIN dbms_session.set_identifier(client_id => '<app_title>'); END;
BEGIN dbms_application_info.set_module(module_name => ..., action_name => ...); END;
```

---

## 7. Déploiement de l'application

### Cloner le dépôt

```bash
cd C:\Users\jolyo\ppowa-64S\my-app
git clone https://git.yaodb-blog.fr/ojo/sw.git .
# ou pour l'instance de développement :
cd C:\Users\jolyo\sw
git clone https://git.yaodb-blog.fr/ojo/sw.git sw
```

### Structure après clonage

```
my-app\
├── mon-appli\   ← racine web
├── lib\         ← bibliothèques
├── docs\        ← documentation
└── (securite\ et log\ créés automatiquement au premier démarrage)
```

### Droits d'accès

Le processus Apache (qui tourne sous le compte Windows de l'utilisateur courant sur cet environnement) doit avoir accès en lecture/écriture à :
- `securite\` — pour la base SQLite
- `log\` — pour les journaux

Ces répertoires sont créés automatiquement par `bootstrap.php` si nécessaires.

---

## 8. Initialisation de la base SQLite

La base SQLite est **auto-initialisée** au premier accès à l'application. La classe `Database` crée le schéma complet si le fichier n'existe pas.

**Fichier** : `securite/database.sqlite`

**Schéma créé automatiquement** :

| Table | Description |
|---|---|
| `profiles` | Profils utilisateurs (admin, developer, oracle_admin, user, visitor) |
| `users` | Comptes utilisateurs |
| `settings` | Paramètres applicatifs (clé/valeur) |
| `auth_config` | Configuration des méthodes d'authentification |
| `modules` | Catalogue des modules activés |
| `oracle_groups` | Groupes de bases Oracle |
| `oracle_databases` | Bases Oracle enregistrées |
| `oracle_access` | Droits d'accès par utilisateur ou groupe AD |
| `oracle_roles` | Rôles Oracle applicatifs |
| `oracle_role_perms` | Permissions associées aux rôles |
| `oracle_role_grants` | Attribution de rôles aux utilisateurs |
| `oracle_role_includes` | Hiérarchie de rôles |

**Compte administrateur par défaut** : créé automatiquement lors du premier démarrage (voir `seedInitialData()` dans `lib/Database.php`).

**Migrations** : les colonnes ajoutées après la version initiale (ex. colonne `sysdba` sur `oracle_databases`) sont appliquées automatiquement via `migrate()` à chaque démarrage.

---

## 9. Démarrage et vérification

### Démarrer Apache

```bat
C:\Users\jolyo\ppowa-64S\httpd-2.4\bin\httpd.exe
```

Pour l'exécuter en service Windows :

```bat
httpd.exe -k install -n "Apache24"
net start Apache24
```

### Vérifier PHP et OCI8

```bat
C:\Users\jolyo\ppowa-64S\php-8.2.17\php.exe -m
```

La sortie doit inclure `oci8` et `sqlite3`.

### Accéder à l'application

| Instance | URL |
|---|---|
| Production | http://localhost:8081/ |
| Développement | http://localhost:8180/ |

### Séquence de démarrage (bootstrap)

À chaque requête, `mon-appli/bootstrap.php` exécute dans l'ordre :

1. Configuration PHP (log des erreurs, pas d'affichage)
2. Définition de `ROOT_PATH`
3. Chargement de `lib/Config.php` (constantes globales)
4. Création du répertoire `log/` si nécessaire
5. Enregistrement de l'autoloader PSR-0 sur `lib/`
6. Démarrage de la session (`Session::start()`)
7. Initialisation de la base SQLite (`Database::getInstance()`)
8. Chargement des paramètres applicatifs (`Settings::getInstance()`)
9. Configuration du logger (modes debug/trace depuis la base)
10. Authentification de l'utilisateur courant (`Auth::getCurrentUser()`)
11. Découverte et enregistrement des modules (`modules/*/module.php`)
12. Initialisation de l'internationalisation (`I18n::init()`)
13. Détermination du thème actif

---

## 10. Modèle deux instances (dev / prod)

L'environnement utilise deux instances Apache sur le même poste :

| | Développement | Production |
|---|---|---|
| Port | 8180 | 8081 |
| Code source | `C:\Users\jolyo\sw\sw\mon-appli` | `C:\Users\jolyo\ppowa-64S\my-app\mon-appli` |
| Base SQLite | `sw\sw\securite\database.sqlite` | `ppowa-64S\my-app\securite\database.sqlite` |

### Synchronisation dev → prod

Les modifications sont développées et testées dans `sw\sw`, puis synchronisées manuellement vers `ppowa-64S\my-app` avant commit :

```bat
robocopy C:\Users\jolyo\sw\sw\mon-appli ^
         C:\Users\jolyo\ppowa-64S\my-app\mon-appli ^
         /MIR /XD .git /XF *.log
```

Ou par copies ciblées pour un fichier spécifique :

```bat
copy "C:\Users\jolyo\sw\sw\mon-appli\modules\oracle\_report_tablespaces.php" ^
     "C:\Users\jolyo\ppowa-64S\my-app\mon-appli\modules\oracle\"
```

> La base SQLite et les journaux **ne sont pas synchronisés** : chaque instance maintient sa propre base de données (utilisateurs, paramètres, bases Oracle enregistrées).

---

## 11. Gestion du dépôt Git

**Dépôt** : `https://git.yaodb-blog.fr/ojo/sw.git`  
**Branche principale** : `main`

### Fichier `.gitignore` recommandé

```
securite/
log/
*.log
```

### Workflow typique

```bash
# Développement et test dans sw/sw
# ...

# Synchronisation vers ppowa-64S (test prod)
copy ...

# Commit et push
git add -p
git commit -m "Description des modifications"
git push origin main
```

---

## 12. Paramètres applicatifs

Les paramètres sont stockés dans la table `settings` de la base SQLite et administrables via l'interface (`/admin/settings.php`).

### Constantes fixes (`lib/Config.php`)

| Constante | Valeur par défaut | Description |
|---|---|---|
| `SESSION_NAME` | `mon_appli_sess` | Nom du cookie de session |
| `SESSION_LIFETIME` | `3600` | Durée de session en secondes |
| `DEFAULT_LANGUAGE` | `en` | Langue par défaut |
| `DEFAULT_THEME` | `light` | Thème par défaut |
| `DEBUG_MODE` | `false` | Mode debug (surchargeable en base) |
| `TRACE_MODE` | `false` | Mode trace (surchargeable en base) |
| `DB_PATH` | `securite/database.sqlite` | Chemin de la base SQLite |

### Langues supportées

`fr`, `en`, `de`, `es`, `it`, `pl`, `ro`

### Thèmes disponibles

| Identifiant | Description |
|---|---|
| `os` | Suit le thème du système d'exploitation |
| `light` | Thème clair (défaut) |
| `dark` | Thème sombre |
| `colorblind` | Thème adapté aux daltoniens |

### Rôles applicatifs

Système multi-rôles (table `roles` × jointure `user_roles`). Les rôles
sont déclarés par chaque module dans son descripteur (`<module>_admin`
+ `<module>_user`) et synchronisés automatiquement au bootstrap.

| Rôle | Constante | Description |
|---|---|---|
| `app_admin` | `ROLE_APP_ADMIN` | **Super-rôle implicite** — accès à tout |
| `oracle_admin` | — (chaîne) | Configuration Oracle + droits transverses |
| `oracle_user` | — | Consultation Oracle (selon `oracle_access` / `oracle_role_perms`) |
| `cmdb_admin` | — | Configuration de la connexion CMDB |
| `cmdb_user` | — | Consommation de la CMDB |
| `cnp_admin` / `cnp_user` | — | Module CNP (submodule) |

> Un utilisateur peut cumuler 0..N rôles. `app_admin` court-circuite
> tous les checks (`Auth::hasRole`, `Auth::requireRole`,
> `Module::canAccess`).

### Méthodes d'authentification

| Méthode | Constante | Notes |
|---|---|---|
| `local` | `AUTH_LOCAL` | Comptes locaux en base SQLite |
| `ldap` | `AUTH_LDAP` | Authentification LDAP/Active Directory |
| `oauth` | `AUTH_OAUTH` | OAuth2 (configurable) |

---

## 13. Journaux et débogage

### Journaux Apache

```
C:\Users\jolyo\ppowa-64S\httpd-2.4\logs\error.log
C:\Users\jolyo\ppowa-64S\httpd-2.4\logs\access.log
```

### Journaux applicatifs

```
my-app\log\app.log     ← messages applicatifs (warnings, erreurs)
my-app\log\debug.log   ← messages de debug (si debug_mode activé)
my-app\log\trace.log   ← trace des requêtes HTTP (si trace_mode activé)
```

### Activer le mode debug

Dans l'interface d'administration (`/admin/settings.php`), activer `debug_mode` et/ou `trace_mode`.  
Ces paramètres surchargent les constantes `DEBUG_MODE` et `TRACE_MODE` de `Config.php`.

### Diagnostics OCI8

Pour vérifier la connectivité Oracle depuis la ligne de commande :

```bat
C:\Users\jolyo\ppowa-64S\php-8.2.17\php.exe -r "echo phpversion(); phpinfo(INFO_MODULES);" | findstr -i oci
```

L'interface Oracle dispose d'une page de test de connexion (`/modules/oracle/test_connection.php`) accessible depuis l'administration des bases.
