Convenciones de Código — Finnova

Este documento define las convenciones de código obligatorias para el equipo de Finnova. Aplica tanto al repositorio de backend (Node.js) como al de frontend (React Native). Todos los miembros del equipo deben seguirlas independientemente de su rol principal.

📝 Mensajes de commit

Usamos Conventional Commits como estándar. Cada commit debe seguir este formato:

Formato

<type>: <descripción en imperativo>

Tipos permitidos

Tipo	Cuándo usarlo
`feat`	Nueva funcionalidad
`fix`	Corrección de bug
`hotfix`	Corrección urgente en producción
`docs`	Cambios en documentación
`refactor`	Reorganización de código sin cambio de comportamiento
`test`	Agregar o modificar tests
`chore`	Mantenimiento: dependencias, CI, configuración
`style`	Cambios de formato (Prettier, ESLint sin lógica)
`perf`	Mejoras de rendimiento

Reglas

Máximo 72 caracteres en la primera línea.
Si el cambio necesita explicación, agregar un cuerpo separado por una línea en blanco.

Ejemplos

✅ Correcto

feat: agregar endpoint de JWT
fix: corregir calculo de IVA
chore: actualizar ESLint a v9
docs: agregar diagrama de flujo de autenticación
refactor: separar UserCard a atomo y molecula

❌ Incorrecto

arreglé el login           ← sin tipo
feat: cambios varios       ← descripción no informativa
Fix: Corregir Bug    ← mayúsculas incorrectas

🏷️ Nomenclatura

Archivos y carpetas

camelCase para todos los archivos y carpetas.
Excepción: componentes React Native usan PascalCase.

✅  userService.js        authModule.ts       financeHelper.js
✅  UserCard.tsx          LoginPage.tsx        FinancialSummaryCard.tsx
❌  user_service.js       auth-module.ts       User-Card.tsx

Variables y funciones

Elemento	Convención	Ejemplo
Variables y funciones	camelCase	`getUserBalance`, `isAuthenticated`
Constantes globales	UPPER_SNAKE_CASE	`MAX_RETRY_ATTEMPTS`, `API_BASE_URL`
Clases y tipos	PascalCase	`UserService`, `TransactionEntity`
Interfaces (TS)	PascalCase con prefijo `I`	`IUser`, `ITransaction`
Enums (TS)	PascalCase	`TransactionType`, `UserRole`
Booleanos	Prefijo `is`, `has`, `can`, `should`	`isLoading`, `hasError`, `canRetry`

Idioma

Código (variables, funciones, archivos, tipos): en inglés.
Comentarios explicativos: en español.
Mensajes de commit: en español.
Documentación en la Wiki: en español.

🎨 Estilo de código

El estilo es obligatorio y bloqueante: el CI rechaza PRs que no pasen lint o Prettier.

ESLint

Configuración base: eslint:recommended + reglas del proyecto.
0 errores, 0 warnings para que el CI pase.
No usar // eslint-disable salvo casos excepcionales documentados con un comentario que explique el por qué.

Prettier

Prettier es obligatorio y su configuración es la fuente de verdad del formato.
Nunca formatear manualmente lo que Prettier puede resolver.
Configuración base del proyecto:

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "arrowParens": "avoid"
}

TypeScript

Usar TypeScript en todo el código del proyecto (tanto backend como frontend).
Prohibido usar any salvo en casos excepcionales documentados.
Preferir tipos explícitos sobre inferencia en parámetros de funciones.
Habilitar strict: true en tsconfig.json.

Comentarios

Solo comentar el por qué, nunca el qué (el código bien nombrado ya dice qué hace).
Máximo una línea por comentario. Evitar bloques de comentarios largos.
En español.

// ✅ Comenta el por qué (no obvio)
// El backend de pagos exige que el monto venga en centavos enteros
const amountInCents = Math.round(amount * 100);

// ❌ Comenta lo obvio (innecesario)
// Multiplica el monto por 100
const amountInCents = amount * 100;

🗂️ Estructura de archivos

Backend — módulo por dominio

Cada módulo dentro de src/modules/ sigue esta estructura interna:

modules/<domain>/
  <domain>.controller.ts    # Manejo de requests/responses HTTP
  <domain>.service.ts       # Lógica de negocio
  <domain>.repository.ts    # Acceso a base de datos
  <domain>.routes.ts        # Definición de rutas
  <domain>.dto.ts           # Data Transfer Objects (validación de entrada)
  <domain>.types.ts         # Tipos e interfaces del dominio

Frontend — Feature-Sliced Design

Respetar estrictamente las capas de FSD. Una capa solo puede importar de capas inferiores:

pages → features → shared

pages/ importa de features/ y shared/.
features/ importa de shared/.
shared/ no importa de ninguna otra capa del proyecto.
platform/ es transversal — provee adaptadores de infraestructura (navegación, storage) y puede ser usado por cualquier capa.

Estructura de carpetas del proyecto:

src/
├── shared/              # Código reutilizable sin lógica de negocio
│   ├── ui/              # Componentes genéricos (Atomic Design)
│   ├── lib/             # Utilidades, helpers, hooks genéricos
│   └── api/             # Cliente HTTP base y configuración
│
├── features/            # Módulos por dominio de negocio
│   ├── auth/
│   │   ├── ui/          # Componentes y pantallas del módulo
│   │   ├── model/       # Estado, lógica de negocio, tipos
│   │   └── api/         # Llamadas al backend de este módulo
│   ├── leaderboard/
│   │   ├── ui/
│   │   ├── model/
│   │   └── api/
│   ├── fdc/             # Financial Data Connection
│   │   ├── ui/
│   │   ├── model/
│   │   └── api/
│   ├── investments/
│   │   ├── ui/
│   │   ├── model/
│   │   └── api/
│   ├── accounting/
│   │   ├── ui/
│   │   ├── model/
│   │   └── api/
│   ├── rewards/
│   │   ├── ui/
│   │   ├── model/
│   │   └── api/
│   ├── courses/
│   │   ├── ui/
│   │   ├── model/
│   │   └── api/
│   └── subscription/
│       ├── ui/
│       ├── model/
│       └── api/
│
├── pages/               # Pantallas raíz (entry points de navegación)
│   ├── HomeScreen.tsx
│   └── ...Screen.tsx
│
└── platform/            # Adaptadores de infraestructura nativa
    ├── navigation/      # Configuración de React Navigation
    └── storage/         # Persistencia local (AsyncStorage, etc.)

Componentes dentro de shared/ui/ siguen Atomic Design:

atoms/ — componente mínimo sin lógica de negocio (botón, input, texto).
molecules/ — combinación de atoms con lógica simple.
organisms/ — bloques complejos reutilizables compuestos de molecules/atoms.

🔄 Flujo de Pull Request

Todo cambio va en una rama siguiendo EST01: Estándar de ramas.
Nunca hacer push directo a main o develop.
El PR debe incluir: descripción del cambio, cómo probarlo, y referencia a la tarea (si aplica).
Al menos 1 miembro del equipo debe revisar y aprobar antes de hacer merge.
El CI debe estar en verde (lint + tests + security audit) para poder mergear.

📝 Mensajes de commit​

🏷️ Nomenclatura​

Archivos y carpetas​

Variables y funciones​

Idioma​

🎨 Estilo de código​

ESLint​

Prettier​

TypeScript​

Comentarios​

🗂️ Estructura de archivos​

Backend — módulo por dominio​

Frontend — Feature-Sliced Design​

🔄 Flujo de Pull Request​

📎 Recursos relacionados​