Ir al contenido principal

docDevs.page.eyebrow

logo du site

docDevs.page.subtitle

docDevs.page.metaHighlight

Objetivo y contexto del proyecto

Lexikongo es una aplicacion Nuxt (SSR) para preservar y difundir el kikongo, con funciones colaborativas para proponer, validar y consultar palabras y verbos.

La app esta pensada para escalar: nuetus idiomas, gestión de roles, historial de contribuciones e integraciones externas.

Arquitectura de base de datos (MySQL)

Resumen de las tablas principales usadas por Lexikongo.

Usuarios y roles

  • users: informacion de cuenta (user_id, username, email, password hash, fechas, verificacion email).
  • roles y posible tabla de union para asociar roles (user, contributor, admin).

Contenido validado

  • words: palabras validadas con datos linguisticos y autor.
  • verbs: verbos validados con infinitivo, raiz, sufijo y metadatos.
  • word_meanings / verb_meanings: traducciones por idioma.

Propuestas pendientes

  • pending_*_submissions: datos enviados por colaboradores antes de validacion.
  • pending_*_translations: traducciones ligadas a cada propuesta.
  • pending_*_slugs: slugs temporales previos al paso a tablas finales.

Slugs y archivado

  • slugs: tabla unificada de slugs publicos y content_type.
  • archived_submitted_*: historial de propuestas aprobadas/rechazadas.
  • languages: idiomas de traduccion.
  • nominal_classes y derived_verb_types: metadatos linguisticos.

gestión de roles y permisos

Lexikongo usa roles explicitos para controlar acceso a funciones criticas.

  • Usuario (user): lectura publica y gestión de perfil.
  • Colaborador (contributor): envia propuestas que pasan por moderacion.
  • Administrador (admin): modera, valida/rechaza, archiva y gestióna contenido.

Las rutas Nitro validan el rol a partir del JWT en cookie HttpOnly.

API y endpoints (Nitro)

API organizada por recursos en server/api con control de acceso por JWT.

Envio

  • POST /api/contributor/submit-word: envia palabra y crea registros pending.
  • POST /api/contributor/submit-verb: envia verbo (name, root, suffix, phonetic, traducciones).

Moderacion

  • POST /api/admin/manage-submissions: endpoint central para aprobar/rechazar/eliminar.
    • crear registro final de palabra/verbo;
    • transferir traducciones;
    • crear slug definitivo;
    • archivar propuesta procesada;
    • limpiar tablas pending.

Traducciones y slugs

  • PUT /api/admin/word/[slug], PUT /api/admin/verb/[slug]: actualizacion de contenido validado.
  • GET /api/words, GET /api/verbs: listado y busqueda publica con filtros y paginacion.
  • Generacion unificada de slugs con verificacion de unicidad.

Autenticacion y sesion

  • POST /api/auth/login: autentica y genera JWT en cookie segura.
  • GET /api/auth/me: devuelve perfil y roles de la sesion actual.

Ejemplo de flujo: validacion de un verbo

Resumen del flujo aplicado en admin durante una aprobacion.

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);
}

El mismo principio se aplica a palabras con archivado correspondiente.

Herramientas de desarrollo y despliegue

Lexikongo usa la toolchain estandar de Nuxt (Vite).

  • npm install: instalar dependencias.
  • npm run dev: servidor local de desarrollo.
  • npm run build: build de produccion (SSR).
  • npm run preview: previsualizacion local del build.

El despliegue apunta a un entorno compatible Nuxt SSR; las migraciones MySQL deben versionarse y controlarse.

Flujo Git y actualizaciones

Se recomienda un flujo Git clasico para colaborar en Lexikongo:

  • ramas por funcionalidad (feature/*),
  • pull requests con revision de codigo,
  • pruebas manuales/automatizadas antes de merge,
  • registro de cambios en CHANGELOG o equivalente.

Cambios sensibles (auth, roles, migraciones) deben validarse en preproduccion.