# NH TRANS — Site officiel

Site public de NH TRANS, entreprise spécialisée dans la douane, le transit, le transport de marchandises,
l'import-export, la manutention, l'entreposage et l'accompagnement logistique des particuliers et des entreprises,
au Cameroun et à l'international.

Ce dépôt contient l'application Laravel complète : site public, tableau de bord d'administration, base métier,
authentification admin, CRUD, médiathèque, messages, paramètres, utilisateurs, journal d'activité et tests.

## Stack technique

- PHP 8.2
- Laravel 12
- Blade (moteur de templates)
- Vite 7 (deux bundles séparés : site public et tableau de bord)
- Tailwind CSS v4
- JavaScript vanilla (aucune dépendance front-end supplémentaire)
- Base de données de développement : SQLite

## Prérequis

- PHP 8.2 avec Composer
- Node.js 18+ et npm

## Installation locale

```bash
composer install
npm install
cp .env.example .env   # si .env n'existe pas déjà
php artisan key:generate
php artisan migrate
php artisan db:seed --class=InitialSiteContentSeeder --force
```

## Lancement en développement

```bash
php artisan serve
npm.cmd run dev
```

## Compilation des assets (production)

```bash
npm.cmd run build
```

## Routes publiques

| Route         | Nom de route   | Description                                    |
|---------------|----------------|-------------------------------------------------|
| `/`           | `home`         | Accueil                                          |
| `/a-propos`   | `about`        | À propos                                         |
| `/services`   | `services`     | Nos 7 services                                   |
| `/galerie`    | `gallery`      | Réalisations                                     |
| `/contact`    | `contact`      | Contact public avec enregistrement des messages  |
| `/admin/login`| `admin.login`  | Connexion administrateur fonctionnelle           |

Il n'existe volontairement aucune page « Équipe » sur ce site.

## Tableau de bord d'administration

Le tableau de bord `/admin/*` est raccordé au back-end depuis l'intervention CODEX-001 : authentification réelle,
routes protégées, modèles Eloquent, FormRequest, policies, CRUD, médiathèque, messages, paramètres, utilisateurs et
journal d'activité.

### Accès en local

Le dashboard redirige vers [`/admin/login`](http://localhost:8000/admin/login) sans session valide. Créer un compte
admin local avec la commande documentée dans [`docs/admin-operations.md`](docs/admin-operations.md).

### Modules disponibles

| Domaine | Écrans |
|---|---|
| Vue générale | Tableau de bord (`/admin`) |
| Contenus du site | Toutes les pages, Accueil, À propos, Page Services, Page Galerie, Page Contact |
| Collections | Services, Partenaires, Clients, Réalisations / Galerie (+ archives), Médias |
| Communication | Messages reçus (+ détail et réponse par e-mail) |
| Configuration | Navigation, Paramètres généraux, Coordonnées, SEO, E-mail |
| Administration | Utilisateurs, Journal d'activité |

### Ressources dédiées

- Layout : `resources/views/layouts/admin.blade.php`
- Styles : `resources/css/admin.css` (variables de marque reprises de `app.css`, esthétique plus sobre et dense,
  distincte du site public)
- Interactions : `resources/js/admin.js` (sidebar, drawer mobile, onglets, modals, confirmations, toasts, aperçu
  d'image local, répéteurs, éditeur de texte riche minimal — aucune requête réseau)
- Composants réutilisables : `resources/views/components/admin/*`

### Données persistantes

Les anciennes données fictives `config/admin_demo.php` et le contrôleur
`app/Http/Controllers/Admin/AdminPrototypeController.php` ont été retirés du runtime. Les contenus et collections
sont désormais stockés en base et servis par des contrôleurs admin dédiés.

### Conventions de nommage des champs

Les formulaires utilisent des noms de champs structurés pensés pour le back-end, par exemple `hero[title]`,
`services[0][title]`, `partners[0][website_url]`. Le détail complet est documenté dans
[`docs/dashboard-field-map.md`](docs/dashboard-field-map.md).

### Documentation back-end

- [`docs/backend-action-inventory.md`](docs/backend-action-inventory.md) : état final CODEX-001 et preuves de vérification.
- [`docs/backend-architecture.md`](docs/backend-architecture.md) : architecture métier et responsabilités.
- [`docs/admin-operations.md`](docs/admin-operations.md) : exploitation admin locale sans secret durable.
- [`docs/deployment-checklist.md`](docs/deployment-checklist.md) : checklist préproduction/production.
- [`docs/dashboard-field-map.md`](docs/dashboard-field-map.md) et
  [`docs/dashboard-backend-handoff.md`](docs/dashboard-backend-handoff.md) : archives utiles du prototype CLAUDE-003.

### Sécurité

Les routes `/admin/*` sont protégées par session admin, middleware de compte actif et policies. Les secrets SMTP,
mots de passe et clés d'application ne doivent pas être documentés dans les fichiers du dépôt.

## Architecture des vues

```
resources/views/
├── layouts/
│   ├── app.blade.php           Layout public (head, header, footer, @yield('content'))
│   └── admin.blade.php         Layout du tableau de bord (sidebar, topbar, drawer mobile)
├── pages/
│   ├── home.blade.php
│   ├── about.blade.php
│   ├── services.blade.php
│   ├── gallery.blade.php
│   └── contact.blade.php
├── admin/
│   ├── auth/login.blade.php    Page autonome (hors layout public), authentification admin
│   ├── dashboard.blade.php
│   ├── content/                Éditeurs des 5 pages publiques + vue d'ensemble
│   ├── services/, partners/, clients/, gallery/   Modules de collection (index, form, archive)
│   ├── media/index.blade.php
│   ├── messages/                Boîte de réception + détail/réponse
│   ├── navigation/index.blade.php
│   ├── settings/                general, contact, seo, email
│   ├── users/                   index, form
│   └── activity/index.blade.php
└── components/
    ├── site-header.blade.php, site-footer.blade.php
    ├── page-hero.blade.php, section-heading.blade.php, breadcrumb.blade.php
    ├── service-card.blade.php, value-card.blade.php, gallery-card.blade.php
    ├── contact-card.blade.php, logo-cloud.blade.php, logo-cloud-item.blade.php, call-to-action.blade.php
    ├── responsive-image.blade.php, admin-login-card.blade.php
    ├── logo.blade.php          Affiche le logo officiel (ou un texte de secours)
    ├── icon.blade.php          Pictogrammes SVG sobres, sans dépendance externe
    └── admin/                  Composants dédiés au tableau de bord (field, seo-fields, media-picker,
                                 richtext, repeater-item, status-badge, stat-card, list-toolbar, pagination,
                                 empty-state, bulk-actions-bar, action-bar, modal, tabs, collapsible, sidebar, topbar)
```

Les pages utilisent l'héritage classique de Blade (`@extends('layouts.app')` / `@section` / `@yield`), et non les
composants anonymes `<x-layouts.app>`, pour rester cohérent avec la séparation `layouts/` / `pages/` / `components/`.

## Contenus publics

Les contenus publics sont maintenant servis depuis la base via les contenus publies, les collections actives et les
parametres applicatifs. `config/nh_trans.php` reste une source d'amorcage/historique utilisee par le seeder initial,
mais ce n'est plus la source runtime principale du site.

Voir [`docs/backend-architecture.md`](docs/backend-architecture.md) pour l'architecture courante et
[`docs/public-content-map.md`](docs/public-content-map.md) pour la cartographie historique des champs publics.

## Règles de coordination entre agents

Ce projet est développé par deux agents IA en parallèle : Claude (front-end) et Codex (back-end, tableau de bord,
base de données). **Toute intervention doit être précédée de la lecture intégrale de [`coordination.md`](coordination.md)**,
qui contient l'historique chronologique complet des interventions, les décisions techniques et les règles de
collaboration obligatoires. Ne jamais modifier ce fichier rétroactivement : uniquement ajouter de nouvelles entrées.

## Logo et identité visuelle

Le fichier source du logo officiel (`logo NH Trans.jpg`) est conservé intact à la racine du projet. Une copie
strictement identique (checksum SHA-256 vérifié) est utilisée par le site sous
`public/assets/images/branding/logo-nh-trans.jpg`.

**Règles strictes** : le logo ne doit jamais être redessiné, recadré, recoloré, recompressé avec perte de qualité ou
modifié de quelque façon que ce soit. Seul un redimensionnement d'affichage via CSS est autorisé. La palette de
couleurs du site (`resources/css/app.css`, bloc `@theme`) a été extraite par échantillonnage précis des pixels du
logo — voir `coordination.md`, intervention CLAUDE-002, pour le détail de la méthode.

## Structure des médias et de la galerie

```
public/assets/images/
├── branding/   Logo officiel (copie identique)
├── home/       Réservé aux futures photographies de la page Accueil
├── about/      Réservé aux futures photographies de la page À propos
├── services/   Réservé aux futures photographies par service
├── gallery/    Réservé aux futures photographies de réalisations
├── partners/   Réservé aux futurs logos de partenaires
└── clients/    Réservé aux futurs logos de clients
```

Ces dossiers sont actuellement vides (hors branding) : en l'absence de photographies réelles, le site utilise des
compositions SVG/CSS sobres (illustrations maritimes/logistiques abstraites) plutôt que des images génériques,
d'IA ou de banque non vérifiées.

### Procédure d'ajout ou remplacement d'une image

1. Uploader le fichier depuis la médiathèque admin ou le déposer dans le stockage public prévu par l'environnement.
2. Renseigner le média et son texte alternatif depuis l'écran admin concerné.
3. Publier le contenu ou la collection concernée.
4. Ne pas remplacer le logo officiel via un upload courant : il est protégé.

## Formulaire de contact, connexion administrateur et dashboard

Ces interfaces sont fonctionnelles depuis CODEX-001 :

- Le formulaire de contact (`POST /contact`) valide, protege contre le spam simple, enregistre en base et peut notifier
  via le mailer Laravel configure.
- La connexion administrateur (`POST /admin/login`) authentifie les comptes actifs, limite les tentatives et ouvre une
  session admin.
- Le tableau de bord (`/admin/*`) est protege et execute des actions reelles en base.

## État actuel du site

Le site public est visuellement stabilise et alimente par les contenus publies en base. Le tableau de bord
d'administration est raccorde au back-end: contenus, collections, medias, messages, navigation, parametres,
utilisateurs et audit.

## Éléments restant à traiter avant production publique

- Renseigner les coordonnees officielles NH TRANS.
- Ajouter les vrais partenaires, clients, realisations de galerie et photographies.
- Configurer domaine/vhost, HTTPS, base cible, stockage cible, mailer et sauvegardes.
- Faire une recette metier complete avec les contenus et droits definitifs.
- Ajouter une API uniquement si un besoin produit reel est valide.

## Preparation production

Le domaine de production indique dans les documents de deploiement (a titre
d'exemple/placeholder, a confirmer avec NH TRANS) est :

```text
https://estnh-trans.com
```

Fichiers principaux (procedure preparee, pas encore executee) :

- `.env.production.example` : modele partageable sans secret.
- `deployment/README-PRODUCTION.md` : procedure de mise en ligne cPanel/Apache.
- `deployment/database/nh_trans_production.sql` : export MySQL a generer et verifier par reimportation le moment venu (absent a ce jour).
- `deployment/cpanel/document-root-recommended.md` : document root recommande vers `public/`.
- `deployment/scripts/post-deploy.sh` et `deployment/scripts/post-deploy.ps1` : controles post-deploiement.
- `docs/production-environment.md` et `docs/database-export.md` : details techniques.

Le compte administrateur de production devra etre cree avec
`php artisan admin:create`, avec des identifiants propres a NH TRANS jamais
reutilises d'un autre projet. Il devra forcer le changement du mot de passe
temporaire a la premiere connexion. Le mot de passe temporaire ne doit jamais
etre stocke dans les fichiers du depot.
