📏 Estándares de Desarrollo

RutaCC - Guía de Estándares y Convenciones
Versión 1.0 | Junio 2026
Proyecto: RutaCC
Tipo: Estándares de Desarrollo
Fecha: 18 de Junio de 2026
Audiencia: Desarrolladores

📑 Índice de Contenidos

  1. Introducción
  2. Estándares PHP
  3. Estándares SQL
  4. Estándares HTML/CSS
  5. Estándares JavaScript
  6. Estándares de Seguridad
  7. Convenciones de Nombres
  8. Estructura de Archivos
  9. Documentación y Comentarios
  10. Control de Versiones (Git)
  11. Estándares de Pruebas

1. Introducción

Este documento establece los estándares de desarrollo que deben seguir todos los desarrolladores del proyecto RutaCC. El cumplimiento de estos estándares garantiza:

2. Estándares PHP

2.1 Estructura de Archivos PHP

Todo archivo PHP debe seguir esta estructura:

<?php
/**
 * Descripción breve del archivo
 * 
 * Descripción detallada si es necesario.
 * 
 * @author Nombre del Desarrollador
 * @version 1.0
 * @since Fecha de creación
 */

// 1. Inclusión de dependencias
require_once __DIR__ . '/security.php';

// 2. Verificación de seguridad
requireAuth();

// 3. Obtención de datos de sesión
$tenant_id = getCurrentTenantId();
$user_id = getCurrentUserId();

// 4. Procesamiento de la petición
try {
    // Lógica del negocio
} catch (Exception $e) {
    secureLog("Error: " . $e->getMessage());
    http_response_code(500);
    echo json_encode(['success' => false, 'message' => 'Error interno']);
    exit;
}
?>

2.2 Uso Obligatorio de Prepared Statements

❌ INCORRECTO - Vulnerable a inyección SQL: 
$sql = "SELECT * FROM vehiculos WHERE id = " . $_GET['id'];
$result = $conn->query($sql);
✅ CORRECTO - Usa prepared statements: 
$sql = "SELECT * FROM vehiculos WHERE id = ? AND tenant_id = ?";
$vehiculo = fetchOne($sql, "ii", [$_GET['id'], $tenant_id]);

2.3 Funciones Helper Obligatorias

Se deben usar las funciones helper centralizadas:

Función Uso Ejemplo
fetchOne() Obtener un registro $user = fetchOne($sql, "i", [$id]);
fetchAll() Obtener múltiples registros $users = fetchAll($sql, "i", [$tenant]);
executePreparedQuery() Ejecutar INSERT/UPDATE/DELETE executePreparedQuery($sql, "s", [$name]);
insertAndReturnId() Insertar y obtener ID $id = insertAndReturnId($sql, "ss", [...]);
sanitizeInput() Sanitizar datos de entrada $name = sanitizeInput($_POST['name']);
secureLog() Registrar eventos secureLog("Usuario login", "INFO");

2.4 Manejo de Errores

✅ Patrón correcto de manejo de errores: 
try {
    $result = executePreparedQuery($sql, "i", [$id]);
    echo json_encode(['success' => true, 'data' => $result]);
} catch (Exception $e) {
    secureLog("Error en operación: " . $e->getMessage(), "ERROR");
    http_response_code(500);
    echo json_encode([
        'success' => false,
        'message' => 'Error al procesar la solicitud'
    ]);
}

2.5 Respuestas JSON Estándar

Todas las APIs deben responder en formato JSON con esta estructura:

// Respuesta exitosa
{
  "success": true,
  "data": { ... },
  "message": "Operación exitosa"
}

// Respuesta de error
{
  "success": false,
  "message": "Descripción del error"
}

3. Estándares SQL

3.1 Convenciones de Nombres

Elemento Convención Ejemplo
Tablas minúsculas, plural vehiculos, despachos
Columnas minúsculas, snake_case tenant_id, fecha_creacion
Primary Keys id id INT AUTO_INCREMENT
Foreign Keys {tabla}_id tenant_id, vehiculo_id
Índices idx_{tabla}_{columna} idx_tenant_estado
Constraints fk_{tabla}_{referencia} fk_vehiculo_tenant

3.2 Todas las Tablas Deben Tener

3.3 Consultas SQL

✅ Consulta bien formada: 
SELECT v.id, v.patente, v.marca, v.modelo, 
       c.nombre AS conductor_nombre
FROM vehiculos v
LEFT JOIN despachos d ON d.vehiculo_id = v.id
LEFT JOIN conductores c ON d.conductor_id = c.id
WHERE v.tenant_id = ? 
  AND v.estado = ?
ORDER BY v.patente ASC;

3.4 Uso de Transacciones

Cuando una operación involucra múltiples tablas, usar transacciones:

$conn->begin_transaction();
try {
    executePreparedQuery($sql1, "i", [$id]);
    executePreparedQuery($sql2, "i", [$id]);
    $conn->commit();
} catch (Exception $e) {
    $conn->rollback();
    secureLog("Transacción fallida: " . $e->getMessage());
    throw $e;
}

4. Estándares HTML/CSS

4.1 Estructura HTML

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Título de la Página - RutaCC</title>
    <link rel="stylesheet" href="css/styles.css">
</head>
<body>
    <!-- Contenido -->
    <script src="js/api.js"></script>
</body>
</html>

4.2 Convenciones CSS

Elemento Convención Ejemplo
Clases kebab-case .card-header, .btn-primary
IDs camelCase #mainContainer
Variables --prefijo-nombre --color-primary

4.3 Accesibilidad

5. Estándares JavaScript

5.1 Convenciones

Elemento Convención Ejemplo
Variables camelCase let usuarioActual;
Constantes UPPER_SNAKE_CASE const MAX_INTENTOS = 3;
Funciones camelCase, verb + sustantivo obtenerUsuarios()
Clases PascalCase class DespachoManager

5.2 Uso de Fetch API

✅ Patrón estándar para llamadas API: 
async function cargarDatos() {
    try {
        const response = await fetch('api/endpoint.php');
        if (!response.ok) throw new Error('Error HTTP');
        const data = await response.json();
        
        if (data.success) {
            procesarDatos(data.data);
        } else {
            mostrarError(data.message);
        }
    } catch (error) {
        console.error('Error:', error);
        mostrarError('Error de conexión');
    }
}

5.3 Módulos JavaScript

Usar el patrón de módulo para organizar el código:

const Vehiculos = {
    listar: async function() {
        return await API.get('vehiculos_list.php');
    },
    
    crear: async function(datos) {
        return await API.post('vehiculos_create.php', datos);
    },
    
    actualizar: async function(datos) {
        return await API.post('vehiculos_update.php', datos);
    }
};

6. Estándares de Seguridad

6.1 Reglas Obligatorias

⚠️ REGLAS DE SEGURIDAD - CUMPLIMIENTO OBLIGATORIO
# Regla Justificación
1 NUNCA concatenar variables en SQL Prevención de inyección SQL (OWASP A03)
2 SIEMPRE validar tenant_id en consultas Aislamiento multi-tenant
3 SIEMPRE incluir security.php Autenticación obligatoria
4 NUNCA mostrar errores detallados al usuario Prevención de fuga de información
5 SIEMPRE sanitizar inputs del usuario Prevención de XSS (OWASP A07)
6 NUNCA guardar contraseñas en texto plano Usar password_hash() con bcrypt
7 NUNCA guardar credenciales en el código Usar config/database.php
8 SIEMPRE usar HTTPS en producción Cifrado de datos en tránsito

6.2 Validación de Datos

✅ Validación completa de datos: 
// Validar tipo
$id = filter_var($data['id'], FILTER_VALIDATE_INT);
if ($id === false) {
    throw new Exception('ID inválido');
}

// Validar rango
if ($id <= 0) {
    throw new Exception('ID debe ser positivo');
}

// Validar email
$email = filter_var($data['email'], FILTER_VALIDATE_EMAIL);
if (!$email) {
    throw new Exception('Email inválido');
}

7. Convenciones de Nombres

7.1 Archivos PHP

Tipo Convención Ejemplo
Listado {modulo}_list.php vehiculos_list.php
Crear {modulo}_create.php pedidos_create.php
Actualizar {modulo}_update.php conductores_update.php
Eliminar/Desactivar {modulo}_disable.php bodegas_disable.php
API/acción específica {modulo}_{accion}.php despachos_iniciar.php

7.2 Archivos HTML

Tipo Convención Ejemplo
Páginas principales {modulo}.html vehiculos.html
Fichas {modulo}_ficha.html despachos_ficha.html
Dashboard dashboard.html dashboard.html

7.3 Variables PHP

Tipo Convención Ejemplo
Variables simples camelCase $tenantId, $vehiculoActual
Variables de BD snake_case $tenant_id, $user_id
Constantes UPPER_SNAKE_CASE DB_HOST, DEBUG_MODE
Arrays plural $vehiculos, $pedidos

8. Estructura de Archivos

8.1 Estructura del Proyecto

public_html/
├── config/
│   └── database.php          # Configuración de BD
├── css/
│   └── styles.css            # Estilos globales
├── js/
│   ├── api.js                # Cliente HTTP
│   ├── auth.js               # Autenticación
│   ├── map.js                # Mapas
│   └── utils.js              # Utilidades
├── components/               # Componentes reutilizables
├── img/                      # Imágenes
├── docs/                     # Documentación
├── logs/                     # Logs (protegido)
├── security.php              # Seguridad central
├── auth_functions.php        # Funciones auth
├── db.php                    # Conexión BD (legacy)
├── *.php                     # APIs
├── *.html                    # Vistas
└── .htaccess                 # Configuración Apache

9. Documentación y Comentarios

9.1 Comentarios en Código

✅ Comentarios útiles: 
/**
 * Calcula la distancia entre dos puntos usando la fórmula de Haversine
 * 
 * @param float $lat1 Latitud del punto 1
 * @param float $lon1 Longitud del punto 1
 * @param float $lat2 Latitud del punto 2
 * @param float $lon2 Longitud del punto 2
 * @return float Distancia en kilómetros
 */
function calcularDistancia($lat1, $lon1, $lat2, $lon2) {
    // Convertir grados a radianes
    // ... código ...
}
❌ Comentarios inútiles: 
// Incrementa i en 1
$i++;

// Retorna el resultado
return $resultado;

9.2 Documentación de APIs

Toda API debe documentar:

10. Control de Versiones (Git)

10.1 Ramas

Rama Propósito
main Código en producción, estable
develop Integración de features
feature/{nombre} Nuevas funcionalidades
bugfix/{nombre} Corrección de errores
hotfix/{nombre} Correcciones urgentes en producción

10.2 Commits

Formato de mensajes de commit:

tipo(scope): descripción breve

[cuerpo opcional con más detalles]

[issue reference opcional]

Tipos:
- feat: Nueva funcionalidad
- fix: Corrección de bug
- docs: Cambios en documentación
- style: Cambios de formato (sin cambio de lógica)
- refactor: Refactorización de código
- test: Agregado o corregido tests
- chore: Tareas de mantenimiento

10.3 Ejemplos de Commits

feat(despachos): agregar cálculo automático de ruta óptima

Se implementó el algoritmo OSRM para calcular la mejor ruta 
de entrega considerando los pedidos asignados al despacho.

Resuelve: #45

fix(vehiculos): corregir validación de patente única por tenant

La validación no consideraba el tenant_id, permitiendo 
patentes duplicadas entre diferentes empresas.

Resuelve: #52

11. Estándares de Pruebas

11.1 Tipos de Pruebas

Tipo Descripción Cobertura Mínima
Pruebas Unitarias Funciones individuales 80% del código crítico
Pruebas de Integración Interacción entre módulos Flujos principales
Pruebas Funcionales Casos de uso completos Todos los casos de uso
Pruebas de Seguridad Vulnerabilidades OWASP Top 10
Pruebas de Rendimiento Carga y estrés 100 usuarios concurrentes

11.2 Checklist Pre-Despliegue

✅ Checklist antes de pasar a producción:
📌 Nota Final:
El cumplimiento de estos estándares es obligatorio para todos los desarrolladores del proyecto. Las violaciones deben ser corregidas antes de hacer merge a las ramas principales. El líder técnico es responsable de verificar el cumplimiento en cada revisión de código.

RutaCC - Estándares de Desarrollo v1.0

Confidencial - Junio 2026