# flujo-de-trabajo.md — Starter Kit RKM v6

## Primera instalación (local)

1. Crear la BD vacía en MySQL (el nombre que quieras — el instalador adapta el schema).
2. Apuntar DocumentRoot de MAMP a `/public` (o crear un VirtualHost).
3. Abrir `http://localhost/` → redirige a `install.php` automáticamente.
4. Paso 1: verificar requisitos (PHP 7.4+, mysqli, escritura en `config/` y `logs/`).
5. Paso 2: introducir credenciales de BD → prueba la conexión.
6. Paso 3: crear cuenta administrador → instala schema + seed + migraciones.
7. Resultado: se crea `config/config.local.php` y `config/installed.lock`.

**Credenciales demo** (si se importó seed.sql directamente): `admin@rkm.local` / `admin123`.

---

## Hacer un cambio en el backend

1. Identificar la capa correcta:
   - Lógica de negocio → `app/services/`
   - Acceso a datos → `app/models/`
   - HTTP / presentación → `app/controllers/`
2. Si la ruta no existe, agregar en `Router::$routes[]` o seguir la convención `nombre-controlador/método`.
3. Si el método requiere autenticación, llamar `AuthMiddleware::check()` al inicio.
4. Si requiere permiso, llamar `PermissionMiddleware::check('nombre_permiso')`.
5. Ejecutar la lógica y renderizar con `$this->view()`, `$this->json()` o `$this->redirect()`.

---

## Hacer un cambio en frontend (vista)

1. Editar el PHP de la vista en `app/views/módulo/nombre.php`.
2. CSS → `app/views/recursos/módulo/nombre/nombre.css` (y espejo en `public/assets/css/...`).
3. JS → `app/views/recursos/módulo/nombre/nombre.js` (y espejo en `public/assets/js/...`).
4. Usar `filemtime()` en los tags `<link>` y `<script>` para cache busting.
5. Incluir `breadcrumb([...])` en toda vista.
6. No dejar `<style>` ni `<script>` inline de 5+ líneas en vistas PHP.

---

## Agregar un nuevo módulo

1. Crear `app/controllers/NuevoController.php` extendiendo `Controller`.
2. Crear `app/models/NuevoModel.php` extendiendo `Model` (si necesita BD).
3. Crear `app/views/nuevo/index.php` + recursos CSS/JS en `recursos/nuevo/`.
4. Si la URL no sigue la convención automática, agregar la ruta en `Router::$routes[]`.
5. Registrar el permiso en BD (`INSERT INTO permissions`) y asignarlo al rol correcto.
6. Agregar enlace en el layout/menú.

---

## Agregar una migración

1. Crear `sql/NNN_nombre.sql` (orden alfanumérico — el servicio los ejecuta en ese orden).
2. Acceder a `/migrations` como admin para ver pendientes.
3. Ejecutar vía el botón en `/migrations` (POST interno).
4. Verificar en la tabla `migrations` que quedó registrada.

---

## Deploy a producción (cPanel + FTP)

1. Subir archivos modificados vía FTP (excluir `/cache/`, `/logs/`, `config/config.local.php`).
2. Verificar que `config/installed.lock` existe en producción (si no, el sistema redirige al instalador).
3. Si hay migraciones pendientes, ejecutar desde el panel `/migrations` en producción.
4. Si hay cambios de assets, los archivos subidos actualizan `filemtime()` automáticamente.
5. Limpiar caché si corresponde: borrar `/cache/*.cache` por FTP o llamar `(new CacheService())->flush()`.
6. Si se cambiaron assets cacheados por el SW, incrementar `CACHE_NAME` en `service-worker.js`.

---

## Checklist de "terminado"

- [ ] Sin `var_dump()`, `die()` de debug ni comentarios `TODO` activos.
- [ ] Toda ruta nueva con middleware apropiado (`AuthMiddleware` / `PermissionMiddleware`).
- [ ] Inputs de usuario validados y sanitizados antes de usar en SQL o HTML.
- [ ] Prepared statements en cualquier query con parámetros variables.
- [ ] POST protegido con `csrf_verify()`.
- [ ] Assets nuevos con `filemtime()` en el tag.
- [ ] Sin `<style>` / `<script>` inline de 5+ líneas en vistas PHP.
- [ ] Breadcrumb incluido en la vista.
- [ ] Probado en MAMP local.
- [ ] Si hay tabla nueva → migración SQL en `/sql/`.
- [ ] Si hay permiso nuevo → registrado en BD y asignado al rol correcto.