Guide Développeur : Architecture Multi-Docker

L'écosystème Next.js / MongoDB isole chaque site client dans un conteneur Docker. Le Portail centralisé communique avec les conteneurs clients via une base de données partagée et un protocole SSO.

Déclaration d'un nouveau site client

Pour intégrer un nouveau site dans l'écosystème, ajoutez-le dans le tableau AVAILABLE_SITES du fichier T:\Kodeix\Portail Kodeix\lib\sites.ts :

export interface SiteConfig {
  id: string;          // Identifiant unique
  name: string;        // Nom
  description: string; // Description
  url: string;         // URL en production
  localUrl: string;    // URL locale de dev (ex: http://localhost:3003)
}

export const AVAILABLE_SITES: SiteConfig[] = [
  {
    id: "nouveau-site",
    name: "Nouveau Site Client",
    description: "Site vitrine",
    url: "https://nouveau-site.fr",
    localUrl: "http://localhost:3003"
  }
];

Attribution de droits

Pour qu'un utilisateur du Portail puisse administrer ce site, ajoutez l'ID du site (ex: "nouveau-site") dans le tableau sites de son document MongoDB dans la collection user.

Guide Développeur : Authentification SSO (JWT)

Le Portail génère un token JWT signé avec une clé partagée ADMIN_SECRET_KEY. Ce token est envoyé au conteneur client pour créer une session d'administration locale sécurisée.

Route d'auto-login client

Le site client doit implémenter une API de connexion SSO dans app/api/auth/sso/route.ts :

import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

function verifyJwt(token: string, secret: string): any {
  try {
    const [headerB64, payloadB64, signatureB64] = token.split('.');
    const expectedSig = crypto
      .createHmac('sha256', secret)
      .update(`${headerB64}.${payloadB64}`)
      .digest('base64url');
    if (expectedSig !== signatureB64) return null;
    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
    if (payload.exp && Date.now() / 1000 > payload.exp) return null;
    return payload;
  } catch {
    return null;
  }
}

export async function GET(req: NextRequest) {
  const { searchParams } = new URL(req.url);
  const token = searchParams.get('token');
  if (!token) return new NextResponse('Token manquant', { status: 400 });

  const secretKey = process.env.ADMIN_SECRET_KEY || 'default-secret-key';
  const decoded = verifyJwt(token, secretKey);
  if (!decoded || !decoded.authenticated) {
    return new NextResponse('Non autorisé', { status: 403 });
  }

  const response = NextResponse.redirect(new URL('/?editMode=true', req.url));
  response.cookies.set('admin_session', 'true', {
    httpOnly: true,
    secure: true,
    sameSite: 'none', // Nécessaire car le site est embarqué dans l'iframe du Portail
    maxAge: 60 * 60 * 2, // 2 heures
    path: '/',
  });
  return response;
}

Guide Développeur : Les composants du CMS

Le système d'édition repose sur le composant parent SettingsProvider et les composants d'édition visuels associés.

Configuration de l'API de sauvegarde groupée

Pour minimiser les appels réseaux et optimiser les performances, l'API côté client doit accepter les mises à jour groupées (Bulk Write) sur le modèle de configuration MongoDB :

import { NextRequest, NextResponse } from 'next/server';
import connectDB from '@/lib/mongodb';
import Setting from '@/models/Setting';

export async function PUT(req: NextRequest) {
  try {
    await connectDB();
    if (req.cookies.get('admin_session')?.value !== 'true') {
      return new NextResponse('Non autorisé', { status: 401 });
    }
    const { changes } = await req.json(); // format: { [key]: value }
    if (!changes) return new NextResponse('Données manquantes', { status: 400 });

    const bulkOps = Object.entries(changes).map(([key, value]) => ({
      updateOne: {
        filter: { key },
        update: { $set: { value } },
        upsert: true
      }
    }));
    await Setting.bulkWrite(bulkOps);
    return NextResponse.json({ success: true });
  } catch (error: any) {
    return new NextResponse(error.message, { status: 500 });
  }
}

Utilisation des composants CMS dans vos pages

<EditableText id="hero.desc" defaultValue="Texte" as="p" />

<EditableImage id="hero.img" defaultSrc="/img.jpg" alt="A" />

<EditableButton id="hero.btn" defaultText="Lien" defaultUrl="/" />

Guide Développeur : Déploiement Docker & Proxy

Chaque conteneur Next.js doit être compilé avec le mode de sortie standalone pour minimiser l'usage mémoire.

1. Dockerfile Standardisé

FROM node:18-alpine AS base
FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
ENV PORT 3000
ENV HOSTNAME "0.0.0.0"
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

2. Configuration Reverse Proxy (Nginx)

Le reverse proxy assure l'acheminement des sous-domaines vers les conteneurs Docker appropriés :

server {
    listen 80;
    server_name lamijardinier.fr;

    location / {
        proxy_pass http://127.0.0.1:3001; # Port exposé du conteneur client
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

AI System Directives: Core Principles

This section serves as a direct instruction set for AI coding assistants modifying or expanding client sites within the Kodeix CMS eco-system.

Rule 1: Maintain Codebase Cleanliness

• No Emojis in Code files: You are strictly forbidden from placing emoji characters inside HTML tags, text nodes, page layouts, or source code. Always use modern, responsive SVG vector graphics or React-icons.
• Preserve Unrelated Comments: Do not remove existing JSDoc documentation, code comments, or configuration files unless requested.
• Local Scratch Storage: Store temporary test scripts or database seeders only inside the designated /scratch directory under the conversation identifier. Do not pollute the main repository.

AI System Directives: Aesthetics & Design System

Every interface must feel premium, fluid, and visually harmonious. Follow these styling restrictions when generating components or adjusting Tailwind CSS grids:

Color Harmonies & Theme Best Practices

• Custom HSL Colors: Do not utilize default saturated raw colors (e.g. standard Tailwind `bg-red-500` or raw hex `#ff0000`). Prefer HSL variables synced with the active theme context.
• Dark Mode Consistency: Maintain light/dark theme variables using the [data-theme="dark"] attribute or system preferences. Ensure text maintains high contrast ratios in both modes.
• Glassmorphism: Use backdrop-filter: blur(12px) alongside transparent white/black borders to construct premium modern headers and floating bars.

AI System Directives: CMS & Hydration Standards

Inline visual CMS editing requires a decoupled data-binding architecture. Ensure your changes do not conflict with React's reconciliation steps.

Preventing Hydration Warnings

1. Dynamic Element Selection in EditableText: Use a dynamic React wrapper tag based on the target element. E.g., if rendering an as="span", ensure the outer element is typed as a span so that HTML nesting remains semantic and valid.
2. Server-Side Pre-Rendering (SSR): To eliminate text flickering during load (layout shift), ensure that layout.tsx fetches settings directly from the MongoDB database at build/request time and initializes the `SettingsProvider` context via initialSettings.
3. Whitespace Control: Long text fields (e.g. Terms of Service, Legal Articles) must respect line breaks. Always apply the CSS style white-space: pre-line or Tailwind's whitespace-pre-line on editable text containers.

Interactive Code Reference (CMS Component Structure)

Ensure new inputs bind directly to context hooks:

import { useSettings } from '@/components/SettingsContext';

export default function HeroSection() {
  const { t, editMode } = useSettings();
  
  return (
    <section>
      <EditableText 
        id="hero.title" 
        defaultValue="L'ami Jardinier" 
        as="h1" 
      />
      <EditableText 
        id="hero.subtitle" 
        defaultValue="Des services d'excellence pour vos espaces verts" 
        as="p" 
      />
    </section>
  );
}

AI System Directives: QA, Testing & SEO Targets

All updates must pass build integration tests and remain fully optimized for SEO crawler indexing.

1. End-to-End Testing (Selectors)

To enable Playwright and Cypress test suites to easily interact with dynamic fields:

• Every editable element must contain a unique, static id attribute.
• Buttons, text inputs, and link wrappers should include a data attribute (e.g. data-testid="cms-save-btn") for easy selection.

2. SEO Best Practices

• Heading Hierarchy: Ensure there is only one <h1> element per page.
• Meta Tag Definition: Always append proper metadata descriptions and localized SEO fields to the Next.js page files.
• Alt Text Accessibility: Always supply descriptive alt texts dynamically to <img> tags. For EditableImage, save the alt text dynamically alongside its URL if possible.