# Variables d'Environnement - lecoffre-front

## Vue d'ensemble

Ce document détaille toutes les variables d'environnement utilisées dans l'application lecoffre-front, leur utilisation et leur configuration.

## Variables d'environnement supportées

### 1. Configuration API Backend

#### `NEXT_PUBLIC_BACK_API_PROTOCOL`
- **Description**: Protocole utilisé pour communiquer avec l'API backend
- **Valeurs possibles**: `https://`, `http://`
- **Exemple**: `https://`
- **Utilisation**: Construction des URLs d'API

#### `NEXT_PUBLIC_BACK_API_HOST`
- **Description**: Nom d'hôte de l'API backend
- **Exemple**: `api.lecoffre.com`, `dev4.4nkweb.com`
- **Utilisation**: Construction des URLs d'API

#### `NEXT_PUBLIC_BACK_API_PORT`
- **Description**: Port de l'API backend
- **Exemple**: `443`, `8080`, `3001`
- **Utilisation**: Construction des URLs d'API
- **Note**: Peut être vide pour les ports par défaut (80/443)

#### `NEXT_PUBLIC_BACK_API_ROOT_URL`
- **Description**: Chemin racine de l'API
- **Exemple**: `/api`, `/`
- **Utilisation**: Construction des URLs d'API

#### `NEXT_PUBLIC_BACK_API_VERSION`
- **Description**: Version de l'API
- **Exemple**: `v1`, `v2`
- **Utilisation**: Construction des URLs d'API

### 2. Configuration Frontend

#### `NEXT_PUBLIC_FRONT_APP_HOST`
- **Description**: URL de base de l'application frontend
- **Exemple**: `https://app.lecoffre.com`
- **Utilisation**: Redirections et liens internes

#### `NEXT_PUBLIC_FRONT_APP_PORT`
- **Description**: Port de l'application frontend
- **Exemple**: `443`, `3000`
- **Utilisation**: Construction des URLs frontend

### 3. Intégration IDNot (Authentification)

#### `NEXT_PUBLIC_IDNOT_AUTHORIZE_ENDPOINT`
- **Description**: Point d'entrée pour l'autorisation OAuth
- **Exemple**: `/oauth/authorize`
- **Utilisation**: Flux d'authentification

#### `NEXT_PUBLIC_IDNOT_CLIENT_ID`
- **Description**: Identifiant client OAuth
- **Exemple**: `lecoffre-client-id`
- **Utilisation**: Authentification OAuth

#### `NEXT_PUBLIC_IDNOT_BASE_URL`
- **Description**: URL de base du service IDNot
- **Exemple**: `https://idnot.lecoffre.com`
- **Utilisation**: Authentification OAuth

#### `NEXT_PUBLIC_IDNOT_REDIRECT_URI`
- **Description**: URI de redirection après authentification
- **Exemple**: `https://app.lecoffre.com/callback`
- **Utilisation**: Flux d'authentification

### 4. Intégration Docaposte

#### `NEXT_PUBLIC_DOCAPOSTE_API_URL`
- **Description**: URL de l'API Docaposte
- **Exemple**: `https://api.docaposte.com`
- **Utilisation**: Services postaux

### 5. Intégration 4NK (Blockchain)

#### `NEXT_PUBLIC_4NK_URL`
- **Description**: URL de base des services 4NK
- **Exemple**: `https://dev4.4nkweb.com`
- **Utilisation**: Services blockchain et signature

#### `NEXT_PUBLIC_4NK_IFRAME_URL`
- **Description**: URL spécifique pour l'iframe 4NK
- **Exemple**: `https://dev4.4nkweb.com`
- **Utilisation**: Communication iframe
- **Note**: Peut être différente de `NEXT_PUBLIC_4NK_URL`

### 6. Analytics et Monitoring

#### `NEXT_PUBLIC_HOTJAR_SITE_ID`
- **Description**: Identifiant du site Hotjar
- **Exemple**: `123456`
- **Utilisation**: Analytics et heatmaps

#### `NEXT_PUBLIC_HOTJAR_VERSION`
- **Description**: Version de Hotjar
- **Exemple**: `6`
- **Utilisation**: Analytics et heatmaps

### 7. Configuration système

#### `NEXT_PUBLIC_API_URL`
- **Description**: URL générique de l'API
- **Exemple**: `https://api.lecoffre.com`
- **Utilisation**: Appels API génériques

#### `NEXT_PUBLIC_DEFAULT_VALIDATOR_ID`
- **Description**: Identifiant du validateur par défaut
- **Exemple**: `862406317a35064537ac959cb5d8bbdf4f849283b63db3ffa9904de2b3427c43:0`
- **Utilisation**: Validation des entités système
- **Valeur par défaut**: Définie dans `AppConstants.ts`

#### `NEXT_PUBLIC_DEFAULT_STORAGE_URLS`
- **Description**: URLs de stockage par défaut (séparées par des virgules)
- **Exemple**: `https://dev3.4nkweb.com/storage,https://backup.4nkweb.com/storage`
- **Utilisation**: Stockage des données
- **Valeur par défaut**: `https://dev3.4nkweb.com/storage`

### 8. Variables d'environnement système

#### `NEXTJS_APP_ENV_NAME`
- **Description**: Nom de l'environnement
- **Valeurs possibles**: `development`, `staging`, `preprod`, `production`
- **Utilisation**: Sélection de la configuration par environnement
- **Valeur par défaut**: `development`

#### `NODE_ENV`
- **Description**: Environnement Node.js
- **Valeurs possibles**: `development`, `production`
- **Utilisation**: Configuration Next.js

## Configuration par environnement

### Développement
```bash
NEXTJS_APP_ENV_NAME=development
NODE_ENV=development
NEXT_PUBLIC_BACK_API_PROTOCOL=http://
NEXT_PUBLIC_BACK_API_HOST=localhost
NEXT_PUBLIC_BACK_API_PORT=3001
NEXT_PUBLIC_4NK_URL=https://dev4.4nkweb.com
```

### Staging
```bash
NEXTJS_APP_ENV_NAME=staging
NODE_ENV=production
NEXT_PUBLIC_BACK_API_PROTOCOL=https://
NEXT_PUBLIC_BACK_API_HOST=stg-api.lecoffre.com
NEXT_PUBLIC_BACK_API_PORT=443
NEXT_PUBLIC_4NK_URL=https://dev4.4nkweb.com
```

### Production
```bash
NEXTJS_APP_ENV_NAME=production
NODE_ENV=production
NEXT_PUBLIC_BACK_API_PROTOCOL=https://
NEXT_PUBLIC_BACK_API_HOST=api.lecoffre.com
NEXT_PUBLIC_BACK_API_PORT=443
NEXT_PUBLIC_4NK_URL=https://4nk.lecoffre.com
```

## Utilisation dans le code

### Configuration Next.js

Les variables sont configurées dans `next.config.js`:

```javascript
const nextConfig = {
  publicRuntimeConfig: {
    NEXT_PUBLIC_BACK_API_PROTOCOL: process.env.NEXT_PUBLIC_BACK_API_PROTOCOL,
    // ... autres variables
  },
  serverRuntimeConfig: {
    // Même configuration pour le serveur
  },
  env: {
    // Configuration pour le build
  }
};
```

### Initialisation dans l'application

Les variables sont initialisées dans `_app.tsx`:

```typescript
const { publicRuntimeConfig } = getConfig();

MyApp.getInitialProps = async () => {
  return {
    backApiProtocol: publicRuntimeConfig.NEXT_PUBLIC_BACK_API_PROTOCOL,
    // ... autres variables
  };
};
```

### Utilisation dans les services

```typescript
// DatabaseService.ts
private static buildBaseUrl(): string {
  return `${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_PROTOCOL}${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_HOST}:${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_PORT}${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_ROOT_URL}${publicRuntimeConfig.NEXT_PUBLIC_BACK_API_VERSION}`;
}
```

## Déploiement Docker

### Variables de build

```dockerfile
ARG NEXT_PUBLIC_BACK_API_PROTOCOL
ARG NEXT_PUBLIC_BACK_API_HOST
# ... autres variables
```

### Variables d'environnement runtime

```dockerfile
ENV NEXT_PUBLIC_BACK_API_PROTOCOL=${NEXT_PUBLIC_BACK_API_PROTOCOL} \
    NEXT_PUBLIC_BACK_API_HOST=${NEXT_PUBLIC_BACK_API_HOST} \
    # ... autres variables
```

### Exécution

```bash
docker run -e NEXT_PUBLIC_BACK_API_PROTOCOL=https:// \
           -e NEXT_PUBLIC_BACK_API_HOST=api.example.com \
           lecoffre/front:latest
```

## Déploiement Kubernetes

### Via Vault (recommandé)

```yaml
annotations:
  vault.hashicorp.com/agent-inject: "true"
  vault.hashicorp.com/agent-inject-secret-envs: secret/data/lecoffre-front-stg/config/envs
  vault.hashicorp.com/agent-inject-template-envs: |
    {{ with secret "secret/data/lecoffre-front-stg/config/envs" }}
      {{ range $k, $v := .Data.data }}
          export {{ $k }}="{{ $v }}"
      {{ end }}
    {{ end }}
```

### Via ConfigMap

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: lecoffre-front-config
data:
  NEXT_PUBLIC_BACK_API_PROTOCOL: "https://"
  NEXT_PUBLIC_BACK_API_HOST: "api.example.com"
  # ... autres variables
```

## Validation et tests

### Vérification des variables requises

```typescript
const requiredVars = [
  'NEXT_PUBLIC_BACK_API_PROTOCOL',
  'NEXT_PUBLIC_BACK_API_HOST',
  'NEXT_PUBLIC_BACK_API_PORT',
  'NEXT_PUBLIC_BACK_API_ROOT_URL',
  'NEXT_PUBLIC_BACK_API_VERSION'
];

for (const varName of requiredVars) {
  if (!publicRuntimeConfig[varName]) {
    throw new Error(`${varName} is not defined in environment variables`);
  }
}
```

### Tests d'environnement

```bash
# Vérifier les variables définies
env | grep NEXT_PUBLIC_

# Tester la construction d'URL
curl -I $(echo $NEXT_PUBLIC_BACK_API_PROTOCOL$NEXT_PUBLIC_BACK_API_HOST:$NEXT_PUBLIC_BACK_API_PORT$NEXT_PUBLIC_BACK_API_ROOT_URL$NEXT_PUBLIC_BACK_API_VERSION/health)
```

## Bonnes pratiques

1. **Sécurité**: Ne jamais exposer de secrets dans les variables `NEXT_PUBLIC_*`
2. **Validation**: Toujours valider la présence des variables requises
3. **Documentation**: Maintenir la documentation des variables
4. **Tests**: Tester avec différentes configurations d'environnement
5. **Fallbacks**: Prévoir des valeurs par défaut quand possible

## Dépannage

### Variables non définies

```bash
# Vérifier les variables d'environnement
docker exec -it <container> env | grep NEXT_PUBLIC_

# Vérifier la configuration Vault
vault kv get secret/data/lecoffre-front-stg/config/envs
```

### URLs malformées

```bash
# Tester la construction d'URL
node -e "
const config = {
  protocol: process.env.NEXT_PUBLIC_BACK_API_PROTOCOL,
  host: process.env.NEXT_PUBLIC_BACK_API_HOST,
  port: process.env.NEXT_PUBLIC_BACK_API_PORT,
  root: process.env.NEXT_PUBLIC_BACK_API_ROOT_URL,
  version: process.env.NEXT_PUBLIC_BACK_API_VERSION
};
console.log(\`\${config.protocol}\${config.host}:\${config.port}\${config.root}\${config.version}\`);
"
```

---

*Documentation mise à jour le $(date) - Variables d'environnement lecoffre-front*