Aller au contenu principal

docDevs.page.eyebrow

logo du site

docDevs.page.subtitle

docDevs.page.metaHighlight

Objectif et contexte du projet

Lexikongo est une application Nuxt (SSR) concue pour promouvoir et preserver la langue Kikongo, avec des fonctionnalites collaboratives permettant aux utilisateurs de soumettre, valider et consulter des mots et verbes en Kikongo, avec des traductions en francais et anglais.

L application est construite pour etre evolutive : ajout de nouvelles langues, gestion fine des roles utilisateurs, historisation des contributions et integration potentielle avec des systemes externes (auth centralisee, paiements de soutien, etc.). Le schema de base de donnees existant est conserve et enrichi pour eviter toute regression.

Architecture de la base de donnees (MySQL)

Vue d ensemble des principales tables utilisees par Lexikongo.

Utilisateurs et roles

  • users : informations compte (user_id, username, email, password hashe, dates, verification e-mail...).
  • roles + eventuelle table de jointure (selon version) pour associer les roles (user, contributor, admin) a chaque utilisateur.

Mots et verbes valides

  • words : mots valides (word_id, singular, plural, class_id, phonetic, derived_word, liens vers mots/verbes derivants, is_approved, user_id auteur, etc.).
  • verbs : verbes valides (verb_id, name (infinitif), root, suffix, phonetic, active_verb, derived_verb, derived_from, derived_verb_type_id, is_approved, user_id...).
  • word_meanings / verb_meanings : traductions associees via word_id ou verb_id avec language_code (fr, en, ...) et meaning.

Soumissions en attente

  • pending_words_submissions / pending_verbs_submissions : donnees envoyees par les contributeurs avant validation (statut, phonetique, classe, radical, suffixe...).
  • pending_words_translations / pending_verbs_translations : traductions liees aux soumissions via submission_id.
  • pending_words_slugs / pending_verbs_slugs : slugs temporaires generes cote pending avant bascule dans les tables finales.

Slugs et archivage

  • slugs : table unifiee pour les slugs publics avec slug_id, slug (unique), word_id ou verb_id et content_type (word ou verb).
  • archived_submitted_words / archived_submitted_verbs : archivage des soumissions (statut approved/rejected, admin, raison, lien vers l ID final quand approuve). Utilise pour garder un historique sur une duree limitee.
  • languages : langues de traduction (language_id, language_code, language_name).
  • nominal_classes et derived_verb_types : metadonnees linguistiques (classes nominales, types de verbes).

Gestion des roles et permissions

Lexikongo s appuie sur des roles explicites pour controler l acces aux fonctionnalites critiques (moderation, admin, etc.) :

  • Utilisateur (user) : acces en lecture seule au dictionnaire public (mots et verbes approuves). Peut gerer son profil.
  • Contributeur (contributor) : peut soumettre des mots et des verbes. Les donnees vont dans les tables pending_*_submissions et sont visibles cote admin pour validation.
  • Administrateur (admin) : acces a l espace admin, validation/rejet des soumissions, archivage, corrections directes dans les tables principales, parfois gestion des utilisateurs.

Cote code, les routes Nitro (server/api/*) verifient le role en se basant sur le JWT decode (stocke dans un cookie HttpOnly) et appliquent les gardes necessaires (par ex. autoriser seulement admin sur les endpoints de moderation).

API et endpoints (Nitro)

L API est organisee par ressource dans server/api/... avec controle d acces via JWT.

Soumission

  • POST /api/contributor/submit-word (exemple) : soumettre un mot puis insertion dans pending_words_submissions + pending_words_translations + pending_words_slugs.
  • POST /api/contributor/submit-verb : soumettre un verbe avec name, root, suffix, phonetic, traductions, etc.

Moderation

  • POST /api/admin/manage-submissions : endpoint central pour approuver / rejeter / supprimer une soumission. Declenche :
    • creation du mot / verbe final ;
    • transfert des traductions ;
    • creation du slug dans slugs ;
    • archivage dans archived_submitted_* ;
    • suppression des tables pending.

Traductions et slugs

  • PUT /api/admin/word/[slug], PUT /api/admin/verb/[slug] : mise a jour d un mot/verbe valide (surface, traductions, phonetique...).
  • GET /api/words, GET /api/verbs : recherche et listing cote public avec pagination, filtres, etc.
  • Generation de slug unifie : utilitaires internes pour s assurer de l unicite dans slugs en fonction de content_type.

Auth et session

  • POST /api/auth/login : authentification, generation de JWT et placement en cookie HttpOnly/SameSite.
  • GET /api/auth/me : renvoie le profil courant + roles a partir du JWT.

Exemple de flux : validation d un verbe

Simplification du flux applique dans l endpoint d admin lors d un approve.

async function approvePendingVerb(connection, submission_id, admin_id) {
  // 1. Charger la soumission et ses traductions
  const submission = await fetchPendingVerbWithTranslations(connection, submission_id);

  // 2. Créer le verbe officiel
  const [resVerb] = await connection.execute(`
    INSERT INTO verbs (name, root, suffix, phonetic, active_verb,
                       derived_verb, derived_from, is_approved, user_id,
                       derived_verb_type_id)
    VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
  `, [
    submission.name,
    submission.root,
    submission.suffix ?? null,
    submission.phonetic ?? null,
    submission.active_verb ?? 1,
    submission.derived_verb ?? 0,
    submission.derived_from ?? null,
    submission.user_id ?? null,
    submission.derived_verb_type_id ?? null,
  ]);

  const newVerbId = resVerb.insertId;

  // 3. Transférer les traductions vers verb_meanings
  for (const tr of submission.translations) {
    if (!tr.language_code || !tr.meaning) continue;
    await connection.execute(
      'INSERT INTO verb_meanings (verb_id, language_code, meaning) VALUES (?, ?, ?)',
      [newVerbId, tr.language_code, tr.meaning.trim()]
    );
  }

  // 4. Créer le slug définitif dans la table unifiée "slugs"
  const slug = await ensureUniqueSlugForVerb(connection, submission.slug, newVerbId);

  // 5. Archiver la soumission puis nettoyer les tables pending
  await archiveVerb(connection, submission, 'approved', admin_id, newVerbId, null);
  await deletePendingVerb(connection, submission_id);
}

Le principe est identique pour les mots (words / word_meanings) avec l ecriture dans archived_submitted_words.

Outils de developpement et deploiement

Lexikongo utilise la toolchain standard Nuxt (Vite). Quelques commandes utiles :

  • npm install : installation des dependances.
  • npm run dev : serveur de developpement local.
  • npm run build : build de production (SSR).
  • npm run preview (selon config) : previsualisation locale du build.

Le deploiement actuel cible un environnement compatible Nuxt SSR (par exemple Vercel, avec adaptation du fichier de config). Les scripts de migration et d evolution de schema MySQL doivent etre versionnes et appliques de maniere maitrisee.

Workflow Git et mises a jour

Pour collaborer proprement sur Lexikongo, un workflow Git classique est recommande :

  • creation de branches de fonctionnalites (feature/*),
  • pull requests avec revue de code,
  • tests manuels (et automatises quand disponibles) avant merge,
  • journalisation des changements dans un fichier CHANGELOG ou equivalent.

Les modifications sensibles (auth, roles, migrations DB) doivent etre testees sur un environnement de pre-production avant la mise en ligne.