Convenciones de codigo

Reglas y patrones que todo el equipo debe seguir para mantener consistencia en el codebase de Zentto.

TypeScript

• Strict mode habilitado en todos los tsconfig.json
• Prohibido usar any — usar tipos concretos o unknown con validacion
• Preferir interface sobre type para objetos
• Nombrar interfaces con PascalCase sin prefijo I: Product, no IProduct
• Exportar tipos desde archivos dedicados (types.ts) en cada modulo

API (Express + Node.js)

• Cada modulo tiene su propio Router en routes.ts y logica en service.ts
• Siempre usar async/await, nunca callbacks o .then()
• Todas las queries pasan por stored procedures — cero SQL directo en TypeScript
• Usar callSp(), callSpOut(), callSpTx() de db/query.ts
• Parametrizar siempre — nunca concatenar valores en strings SQL
• Respuestas estandar: {"ok": true, "data": [...], "total": n}
• Errores estandar: {"ok": false, "mensaje": "descripcion"}

Frontend (React + Next.js)

• Componentes funcionales con hooks — no class components
• Usar componentes de @zentto/shared-ui para UI consistente
• Hooks de datos de @zentto/shared-api (useApi, useTimezone, etc.)
• Cada pagina en su directorio dentro de src/app/ (App Router de Next.js)
• Estilos con Tailwind CSS — no CSS custom salvo excepciones justificadas
• Estado local con useState/useReducer; estado global solo si es necesario

SQL y Base de datos

• Naming de SPs: usp_[Schema]_[Entity]_[Action]
• Todas las fechas en UTC-0 — usar SYSUTCDATETIME() o NOW() AT TIME ZONE 'UTC'
• Cero GETDATE() o NOW() sin timezone
• Listados devuelven TotalCount para paginacion
• Escrituras devuelven Resultado (ID o -1) y Mensaje
• Parametros JSON para bulk/detail: OPENJSON (SQL Server) / jsonb_array_elements (PG)
• Todo cambio en ambos motores — sin excepciones

Fechas y timezone

Git y control de versiones

• Rama principal: main (deploy automatico a produccion)
• Ramas de feature: feat/nombre-corto
• Ramas de fix: fix/nombre-corto
• Commits en formato: feat(modulo): descripcion, fix(modulo): descripcion
• Nunca hacer git push --force a main
• PRs requieren revision antes de merge

# Ejemplos de mensajes de commit
feat(inventario): agregar endpoint de lotes
fix(pos): corregir calculo de descuento por porcentaje
feat(schema): manufactura y flota — paridad dual-DB
docs: actualizar contrato OpenAPI v1.4

Seguridad

• Nunca versionar secretos o credenciales — usar .env y .gitignore
• Passwords hasheados con bcrypt — verificacion en Node.js, no en SQL
• Autenticacion via JWT — validar en middleware authMiddleware
• CORS manejado en Nginx con flag always
• Variables de entorno sensibles solo en GitHub Secrets o /opt/zentto/.env.*

Nomenclatura del proyecto