Auditoria de docs

Esta pagina registra el estado actual del sitio de documentacion: que se verifico, que sigue sin confirmarse, riesgos conocidos y decisiones de arquitectura para futuros mantenedores.

Estado de cobertura por locale

La navegacion de la documentacion esta traducida en todos los locales soportados, pero la profundidad del contenido todavia no esta sincronizada. Ingles es la fuente de verdad para el conjunto de paginas mas profundo.

Locale	Cobertura actual	Siguiente accion recomendada
EN	Cobertura completa/mas profunda: 31 paginas MDX, incluyendo paginas hijas detalladas para API, backend, frontend y arquitectura	Mantener EN como fuente verificada mientras avanza el trabajo de paridad
ES	Cobertura parcial/top-level: 17 paginas MDX, principalmente paginas landing de seccion	Traducir o resumir las paginas hijas faltantes de EN, o marcar cada traduccion pendiente explicitamente
EUS	Cobertura parcial/top-level: 17 paginas MDX, principalmente paginas landing de seccion	Traducir o resumir las paginas hijas faltantes de EN, o marcar cada traduccion pendiente explicitamente

Checklist de paridad de locales

Al anadir una pagina de docs, crear o actualizar el contenido correspondiente en en, es y eus dentro del mismo cambio.
Si la traduccion completa no esta lista, anadir la pagina del locale con un heading traducido y una nota explicita Translation pending / Traduccion pendiente / Itzulpena pendiente.
Mantener alineados la navegacion, las entradas _meta.ts y los links de pagina en los tres locales.

Que se verifico

Las siguientes afirmaciones se cruzaron contra el codigo real bajo backend-js/, frontend-app/ y docs/:

Estructura monorepo: tres paquetes (backend-js, frontend-app, docs) bajo pnpm workspaces. Verificado desde pnpm-workspace.yaml.
Inventario de endpoints backend: todos los endpoints de la referencia API se verificaron contra archivos backend-js/src/app/api/*/route.ts.
Flujos de auth: access token (Bearer JWT, 15 min) + refresh token (cookie HTTP-only, 7 dias) confirmados desde backend-js/src/app/lib/jwt.ts y backend-js/src/app/config/envConfig.ts.
Maquina de estados de paquetes: pending -> assigned -> in_transit -> delivered | undelivered | failed confirmada desde backend-js/src/app/types/index.ts.
Efectos secundarios de email al cambiar estado: confirmados desde backend-js/src/app/lib/packageStatus/packageStatusSideEffects.service.ts.
Tipos de token: refresh_token, tracking_token, reset_pwd_token, activate_account_token confirmados desde backend-js/src/app/types/index.ts.
Inconsistencia del nombre de BD: schema.sql crea la base como erronka; backend-js/.env.example la documenta como pakag. Marcado como Needs verification en docs de environment.
Origen de Google Directions: coordenadas hardcodeadas en backend-js/src/app/api/routes/create/service/create.service.ts; riesgo confirmado y documentado en security y environment.
Rutas de archivos del cliente API frontend: todas las rutas app/lib/api/* se referencian como estan documentadas; las ubicaciones exactas de tipos TypeScript se verificaron desde app/utils/types/api/.

Que sigue sin verificar (Needs verification)

Los siguientes items no pudieron confirmarse sin acceso a un entorno en ejecucion o test de integracion completo:

Schemas exactos de request/response para endpoints solo-admin que el frontend actual no llama (/api/packages/create, /api/packages/update, /api/routes/create, etc.).
Defaults de paginacion para endpoints de listado (/api/packages/list, /api/users/list, /api/logs/listAll).
Variantes de respuesta de error mas alla de { error: string }: forma completa de error por status code.
Dominio de produccion y configuracion CORS (documentado como riesgo, no confirmado).
URL de activacion: las docs indican que reutiliza RESET_BASE_URL; el comportamiento exacto en un entorno vivo no esta verificado.
Pantallas UI de admin en frontend: algunas ubicaciones de pantallas mencionadas en domain/frontend no pudieron fijarse a paths concretos.

Riesgos conocidos

Severidad	Riesgo	Referencia
High	`JWT_SECRET` tiene un fallback hardcodeado en `envConfig.ts`; si no se define en produccion, el fallback es visible publicamente en el repo	Security page, CLAUDE.md §4.2
High	`DEFAULT_USER_PASSWORD` tiene el mismo problema de fallback hardcodeado	Security page, CLAUDE.md §4.3
Medium	`handleError` reenvia mensajes internos de error en respuestas HTTP 500	CLAUDE.md §4.5
Medium	Paquetes de rate limiting instalados (`@upstash/ratelimit`) pero no implementados	CLAUDE.md §7.2
Low	Las variables env de MySQL no se validan al arrancar; posibles fallos silenciosos	CLAUDE.md §4.4
Low	`GOOGLE_DIRECTIONS_API_KEY` usa asercion TypeScript `!` sin guard al arrancar	CLAUDE.md §4.10

Decisiones de arquitectura del sitio de docs

Layout custom: las docs no usan el layout de nextra-theme-docs. En su lugar, docs/app/[lang]/layout.tsx implementa sidebar, header y layout de contenido totalmente custom para permitir control total de diseno.
Rutas por locale: el locale es el primer segmento de URL (/en/, /es/, /eus/). El middleware en docs/middleware.ts redirige paths sin locale a /en/.
Busqueda: implementada como busqueda estatica client-side por titulo de pagina mediante DocsSearch.tsx. No hay indice full-text. Ctrl+K / Cmd+K abre el modal.
Tabla de contenidos: PageToc.tsx lee headings del DOM tras mount (limitado a .docs-content). Los headings reciben IDs estables mediante slugify en mdx-components.tsx.
TOC movil: MobilePageTools.tsx renderiza un boton bajo el header que abre un drawer inferior con el TOC y un acceso a busqueda.
i18n: los diccionarios viven en docs/app/i18n/. Anadir un item de nav requiere actualizar la interfaz DocsDictionary y los tres archivos de locale.
IDs de headings MDX: los componentes MDX h2, h3, h4 se sobrescriben en docs/mdx-components.tsx para autogenerar atributos id mediante slugify.

Estado de build y busqueda

Feature	Estado
Redirect raiz `/` a `/en`	Funciona via `docs/app/page.tsx` + middleware
Rutas con prefijo locale	Funcionan: `/en/`, `/es/`, `/eus/`
Fallback de locale (p. ej. `/backend` -> `/en/backend`)	Funciona via `docs/middleware.ts`
TOC por pagina (desktop)	Funciona: sticky lateral derecho via `PageToc.tsx`
TOC por pagina (movil)	Funciona: drawer inferior via `MobilePageTools.tsx`
Busqueda Ctrl+K	Funciona: busqueda estatica de titulos via `DocsSearch.tsx`
Anchor links de headings	Funcionan: IDs generados via `slugify` en `mdx-components.tsx`
Boton copiar en bloques de codigo	Funciona via `CodeBlock.tsx`
Sidebar movil	Funciona via `MobileMenu.tsx`
View transitions	Funcionan: CSS view transitions en navegacion

Como deben actualizar docs futuros agentes

Anadir un endpoint backend: actualizar docs/content/en/api/index.mdx. Anadir ejemplos request/response. Verificar desde los route.ts y dtos/ reales. Marcar lo no verificado con > [!NOTE] Needs verification.
Anadir una pagina o hook frontend: actualizar docs/content/en/frontend/index.mdx.
Anadir una seccion o pagina de docs: crear/actualizar el contenido en los tres arboles de locale (docs/content/en/, docs/content/es/ y docs/content/eus/) en el mismo cambio. Si la traduccion completa no esta terminada, anadir heading traducido y marcar la pagina como Traduccion pendiente.
Mantener alineada la profundidad por locale: cuando EN reciba una pagina hija mas profunda, anadir placeholders o traducciones equivalentes en ES/EUS para que el conteo de paginas y la estructura de nav no diverjan silenciosamente.
Arreglar un link roto: todos los links internos deben llevar prefijo de locale (por ejemplo /es/setup). Los links sin locale tambien funcionan via redirect de middleware, pero se prefieren links con locale explicito.
Mantener docs veraces: no documentar comportamiento que no pueda verificarse desde el codigo. Usar callouts > [!NOTE] con “Needs verification” para cualquier cosa incierta.