# 🛠️ GUIDE DE DÉVELOPPEMENT - BTPXPRESS FRONTEND

## 📋 Table des matières

- [Prérequis](#prérequis)
- [Installation](#installation)
- [Configuration](#configuration)
- [Structure du projet](#structure-du-projet)
- [Conventions de code](#conventions-de-code)
- [Workflow de développement](#workflow-de-développement)
- [Composants](#composants)
- [Services API](#services-api)
- [Gestion de l'état](#gestion-de-létat)
- [Routing](#routing)
- [Styling](#styling)
- [Debugging](#debugging)
- [Bonnes pratiques](#bonnes-pratiques)

---

## 🔧 Prérequis

### **Logiciels requis**

| Logiciel | Version | Vérification |
|----------|---------|--------------|
| **Node.js** | 20.x LTS | `node --version` |
| **npm** | 10.x | `npm --version` |
| **VS Code** | Latest | Recommandé |

### **Extensions VS Code recommandées**

- **ES7+ React/Redux/React-Native snippets**
- **Prettier - Code formatter**
- **ESLint**
- **TypeScript Vue Plugin (Volar)**
- **Tailwind CSS IntelliSense**
- **Auto Rename Tag**
- **Path Intellisense**

---

## 📦 Installation

### **1. Cloner et installer**

```bash
cd btpxpress/btpxpress-client
npm install
```

### **2. Configurer les variables d'environnement**

Créer `.env.local` :

```bash
NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1
NEXT_PUBLIC_KEYCLOAK_URL=http://localhost:8180
NEXT_PUBLIC_KEYCLOAK_REALM=btpxpress
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=btpxpress-frontend
```

### **3. Lancer le serveur de développement**

```bash
npm run dev
```

Ouvrir http://localhost:3000

---

## ⚙️ Configuration

### **next.config.js**

```javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
  images: {
    domains: ['localhost'],
  },
  env: {
    API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
}

module.exports = nextConfig
```

### **tsconfig.json**

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "paths": {
      "@/*": ["./*"],
      "@/components/*": ["./components/*"],
      "@/services/*": ["./services/*"],
      "@/types/*": ["./types/*"],
      "@/hooks/*": ["./hooks/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}
```

---

## 📁 Structure du projet

```
btpxpress-client/
├── app/                          # App Router (Next.js 15)
│   ├── (auth)/                   # Groupe de routes authentifiées
│   │   ├── layout.tsx            # Layout avec sidebar
│   │   ├── dashboard/
│   │   │   └── page.tsx          # /dashboard
│   │   ├── chantiers/
│   │   │   ├── page.tsx          # /chantiers (liste)
│   │   │   ├── [id]/
│   │   │   │   └── page.tsx      # /chantiers/[id] (détails)
│   │   │   └── nouveau/
│   │   │       └── page.tsx      # /chantiers/nouveau
│   │   └── ...
│   ├── login/
│   │   └── page.tsx              # /login
│   ├── layout.tsx                # Layout racine
│   ├── page.tsx                  # / (accueil)
│   └── globals.css               # Styles globaux
├── components/
│   ├── layout/
│   │   ├── Header.tsx
│   │   ├── Sidebar.tsx
│   │   └── Footer.tsx
│   ├── forms/
│   │   ├── ChantierForm.tsx
│   │   └── ClientForm.tsx
│   ├── tables/
│   │   └── DataTableWrapper.tsx
│   └── common/
│       ├── LoadingSpinner.tsx
│       └── ErrorMessage.tsx
├── services/
│   ├── api/
│   │   ├── chantierService.ts
│   │   ├── clientService.ts
│   │   └── apiClient.ts
│   ├── auth/
│   │   └── keycloakService.ts
│   └── utils/
│       └── formatters.ts
├── types/
│   ├── models/
│   │   ├── Chantier.ts
│   │   └── Client.ts
│   └── api/
│       └── responses.ts
├── hooks/
│   ├── useAuth.ts
│   ├── useChantiers.ts
│   └── useToast.ts
├── contexts/
│   ├── AuthContext.tsx
│   └── ThemeContext.tsx
└── public/
    ├── images/
    └── icons/
```

---

## 📝 Conventions de code

### **Nommage**

| Élément | Convention | Exemple |
|---------|------------|---------|
| **Composants** | PascalCase | `ChantierForm.tsx` |
| **Fichiers** | PascalCase (composants), camelCase (autres) | `Header.tsx`, `apiClient.ts` |
| **Variables** | camelCase | `const userName = ...` |
| **Constantes** | UPPER_SNAKE_CASE | `const API_URL = ...` |
| **Types/Interfaces** | PascalCase | `interface ChantierDTO` |
| **Hooks** | camelCase avec `use` | `useAuth()` |

### **Structure d'un composant**

```typescript
'use client'; // Si nécessaire (composant client)

import React from 'react';
import { Button } from 'primereact/button';
import type { ChantierDTO } from '@/types/models/Chantier';

interface ChantierFormProps {
  chantier?: ChantierDTO;
  onSubmit: (data: ChantierDTO) => void;
  onCancel: () => void;
}

export const ChantierForm: React.FC<ChantierFormProps> = ({
  chantier,
  onSubmit,
  onCancel,
}) => {
  // Hooks
  const [loading, setLoading] = React.useState(false);

  // Handlers
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    // ...
  };

  // Render
  return (
    <form onSubmit={handleSubmit}>
      {/* JSX */}
    </form>
  );
};
```

---

## 🔄 Workflow de développement

### **1. Créer une branche**

```bash
git checkout -b feature/nom-de-la-fonctionnalite
```

### **2. Développer**

1. Créer le type TypeScript (`types/models/`)
2. Créer le service API (`services/api/`)
3. Créer le composant (`components/`)
4. Créer la page (`app/`)
5. Tester

### **3. Tester localement**

```bash
npm run dev
npm run lint
npm test
```

### **4. Commit et Push**

```bash
git add .
git commit -m "feat: ajout de la fonctionnalité X"
git push origin feature/nom-de-la-fonctionnalite
```

---

## 🧩 Composants

### **Composant fonctionnel avec TypeScript**

```typescript
import React from 'react';

interface Props {
  title: string;
  count: number;
  onIncrement: () => void;
}

export const Counter: React.FC<Props> = ({ title, count, onIncrement }) => {
  return (
    <div>
      <h2>{title}</h2>
      <p>Count: {count}</p>
      <button onClick={onIncrement}>Increment</button>
    </div>
  );
};
```

### **Composant avec PrimeReact**

```typescript
'use client';

import { DataTable } from 'primereact/datatable';
import { Column } from 'primereact/column';
import { Button } from 'primereact/button';

export const ChantierTable = ({ chantiers }) => {
  const actionBodyTemplate = (rowData) => {
    return (
      <Button
        icon="pi pi-pencil"
        className="p-button-rounded p-button-text"
        onClick={() => handleEdit(rowData)}
      />
    );
  };

  return (
    <DataTable value={chantiers} paginator rows={10}>
      <Column field="nom" header="Nom" sortable />
      <Column field="code" header="Code" sortable />
      <Column field="statut" header="Statut" />
      <Column body={actionBodyTemplate} header="Actions" />
    </DataTable>
  );
};
```

---

## 🔌 Services API

### **Client API de base**

```typescript
// services/api/apiClient.ts
import axios from 'axios';

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Intercepteur pour ajouter le token
apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

export default apiClient;
```

### **Service spécifique**

```typescript
// services/api/chantierService.ts
import apiClient from './apiClient';
import type { ChantierDTO } from '@/types/models/Chantier';

export const chantierService = {
  getAll: async (): Promise<ChantierDTO[]> => {
    const response = await apiClient.get('/chantiers');
    return response.data;
  },

  getById: async (id: string): Promise<ChantierDTO> => {
    const response = await apiClient.get(`/chantiers/${id}`);
    return response.data;
  },

  create: async (data: ChantierDTO): Promise<ChantierDTO> => {
    const response = await apiClient.post('/chantiers', data);
    return response.data;
  },

  update: async (id: string, data: ChantierDTO): Promise<ChantierDTO> => {
    const response = await apiClient.put(`/chantiers/${id}`, data);
    return response.data;
  },

  delete: async (id: string): Promise<void> => {
    await apiClient.delete(`/chantiers/${id}`);
  },
};
```

---

## 🎨 Styling

### **PrimeReact Theme**

```typescript
// app/layout.tsx
import 'primereact/resources/themes/lara-light-blue/theme.css';
import 'primereact/resources/primereact.min.css';
import 'primeicons/primeicons.css';
```

### **CSS Modules**

```typescript
// components/Header.module.css
.header {
  background-color: #fff;
  padding: 1rem;
}

// components/Header.tsx
import styles from './Header.module.css';

export const Header = () => {
  return <header className={styles.header}>...</header>;
};
```

---

## 🐛 Debugging

### **React DevTools**

Installer l'extension Chrome/Firefox : React Developer Tools

### **Console logs**

```typescript
console.log('Debug:', data);
console.error('Error:', error);
console.table(array);
```

### **Debugger**

```typescript
const handleClick = () => {
  debugger; // Point d'arrêt
  // ...
};
```

---

## ✅ Bonnes pratiques

### **1. Typage strict**

```typescript
// ❌ Mauvais
const data: any = ...

// ✅ Bon
const data: ChantierDTO = ...
```

### **2. Gestion des erreurs**

```typescript
try {
  const data = await chantierService.getAll();
  setChantiers(data);
} catch (error) {
  console.error('Erreur:', error);
  toast.current?.show({
    severity: 'error',
    summary: 'Erreur',
    detail: 'Impossible de charger les chantiers',
  });
}
```

### **3. Loading states**

```typescript
const [loading, setLoading] = useState(false);

const loadData = async () => {
  setLoading(true);
  try {
    const data = await service.getData();
    setData(data);
  } finally {
    setLoading(false);
  }
};
```

---

**Dernière mise à jour** : 2025-09-30  
**Version** : 1.0  
**Auteur** : Équipe BTPXpress