Vai al contenuto principale

docDevs.page.eyebrow

logo du site

docDevs.page.subtitle

docDevs.page.metaHighlight

Objectif et contexte du projet

Lexikongo è un'applicazione Nuxt (SSR) progettata per promuovere e preservare la lingua kikongo, con funzionalità collaborative che permettono agli utenti di inviare, validare e consultare parole e verbi in kikongo, con traduzioni in francese e inglese.

L application est construite pour etre evolutive : ajout de nouvelles langues, gestione 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 account (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.

Parole e verbi validati

  • 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.

Invii in attesa

  • pending_words_submissions / pending_verbs_submissions : donnees envoyees par les contributores avant validation (statut, phonetique, classe, radical, suffixe...).
  • pending_words_translations / pending_verbs_translations : traductions liees aux invios 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 invios (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).

Gestione dei ruoli e dei permessi

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

  • Utente (user): accesso in sola lettura al dizionario pubblico (parole e verbi approvati). Può gestire il proprio profilo.
  • Contributeur (contributor) : peut soumettre delle mots et dei 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 invios, archivage, corrections directes dans les tables principales, parfois gestione 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.

Invio

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

Moderation

  • POST /api/admin/manage-submissions: endpoint centrale per approvare, rifiutare o eliminare un invio. Attiva:
    • creation du parola / verbo 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 parola/verbo valide (surface, traductions, phonetique...).
  • GET /api/words, GET /api/verbs : ricerca 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 verbo

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.