# 06 - Estándares y Compatibilidad

## Estándar de código

### Naming

| Elemento | Convención | Ejemplo |
|---|---|---|
| Controlador | `PascalCase` + sufijo `Controller` | `ProductoController` |
| Modelo | `PascalCase` + sufijo `Model` | `ProductoModel` |
| Carpeta de vistas | `minúsculas` (nombre del módulo) | `app/views/producto/` |
| Tabla de BD | `minúsculas`, plural | `productos` |
| Columnas de BD | `PascalCase` | `NombreCompleto`, `FechaRegistro` |
| Atributos del modelo | `PascalCase` (coincide con columna BD) | `Nombre`, `Email` |
| Acciones del controlador | `camelCase` + sufijo `Action` | `createAction()`, `dataListAjaxAction()` |
| Archivos de vista | `minúsculas`, `_` para parciales | `list.php`, `_form.php` |
| Migraciones | `{timestamp}_descripcion.php` | `2026_03_02_create_productos_table.php` |
| Seeders | `PascalCase` + sufijo `Seeder` | `ProductoPermissionsSeeder` |
| Módulo en `MODULE_NAME` | `minúsculas` | `'producto'` |
| AccessControl keys | `camelCase` | `'dataListAjax'`, `'editPass'` |

### Formato

- Mantener el estilo existente del repositorio (no reformatear masivamente).
- Clases sin namespace (autoload por classmap y path).
- Arrays con sintaxis `array()` (no `[]`) en código del core y modelos.
- Comillas simples para strings sin interpolación.
- Indentación: 4 espacios (o tab según el archivo existente).

### PHP

- PHP 8.x compatible. Evitar features que rompan en 8.0.
- Siempre `<?php` completo (nunca `<?`).
- Sin `?>` al final de archivos PHP puros.
- `error_log()` para debugging temporal. Remover antes de commit.

## Compatibilidad del framework

### Reglas inquebrantables

1. **No romper el contrato de rutas legacy** `?c=controller&a=action`.
2. **No renombrar controladores/modelos existentes** sin migración planificada.
3. **Mantener semántica de:**
   - `Router::create_action_url($controller, $action, $params)`
   - `Router::redirect_to_action($controller, $action, $params)`
4. **No cambiar la estructura del POST**: `NombreModelo[NombreAtributo]`.
5. **No modificar el pipeline de middleware** sin aprobación del equipo.

### Cambio seguro vs. cambio riesgoso

Un cambio es **seguro** cuando:

| Criterio | |
|---|---|
| No rompe navegación existente | ✓ |
| No rompe login/permisos | ✓ |
| No introduce errores de sintaxis | ✓ |
| Mantiene compatibilidad de configuración | ✓ |
| Es local al módulo afectado | ✓ |

Un cambio es **riesgoso** cuando:

| Criterio | |
|---|---|
| Modifica `core/` | ⚠ |
| Cambia nombres de controladores/acciones | ⚠ |
| Altera la sesión o autenticación | ⚠ |
| Cambia la estructura de `Modules.php` | ⚠ |
| Afecta múltiples módulos | ⚠ |

## UI / Frontend

- Framework CSS: **Metronic 8** (`public/metronic_html_v8.0.23_demo1/`).
- Clases de componentes: `card`, `form-control-solid`, `btn-primary`, `form-select-solid`.
- Select2: `data-control="select2"` en selects.
- DataTables: renderizados por `Lista`/`ListaAjax` desde PHP.
- Iconos: Bootstrap Icons (`bi bi-*`).

## Versionado

- Política: **SemVer** para cambios del core.
  - MAJOR: cambios que rompen compatibilidad.
  - MINOR: funcionalidad nueva compatible.
  - PATCH: correcciones de bugs.
- Registrar cambios relevantes en `CHANGELOG.md`.

## Validación antes de cerrar cambios

```bash
# 1. Lint de archivos modificados
php -l app/controllers/MiController.php
php -l app/models/MiModel.php

# 2. Diagnóstico
php bin/doctor

# 3. (Si aplica) Migraciones y seeders
php bin/migrate up
php bin/seed MiPermissionsSeeder

# 4. (Si aplica) Smoke test
php bin/smoke
```