feat: [TESIS-29] add internal admin panel for API service templates

[TomasMartin2004]

Ticket de Jira

https://proyectofinalfrlp.atlassian.net/browse/TESIS-29

---

Descripción

Backoffice interno en /admin para administrar las plantillas globales de APIs (tabla services) sin tocar SQL a mano, implementado con Avo 4 como panel definitivo del proyecto.

Decisión de librería (evaluadas las 4 alternativas):

• ActiveAdmin 3.5.1 (estable): depende de sassc, gema C sin mantenimiento desde 2020 — riesgo alto de no compilar en Ruby 4.0.2 + Rails 8 API-only. Descartada.
• ActiveAdmin 4: aún beta, agrega build de Tailwind/Node al repo, CI y deploy. Descartada.
• Administrate 1.0: sin soporte JSONB out-of-box (habría que escribir un custom field a mano). Descartada.
• Avo 4.0.11 (elegida): estable, Rails 8 first-class, assets precompilados (cero Node), field code para editar JSON (el "componente visual de editor JSON" que pide la card), desarrollo activo, Community tier gratis cubre todo el alcance. Cada tabla administrable futura = un archivo de resource (~15 líneas) — sin retrabajo.

Implementación:

• Ruta aislada y protegida: Avo montado en /admin con login propio en /admin/sign_in (página HTML con sesión — sin popup de HTTP Basic), respaldado por el nuevo modelo AdminUser (tabla admin_users, scope Devise independiente del JWT de la API, tal como sugiere la card). Los User de las PyMEs no acceden. Logout desde el menú de Avo. Admin inicial por seeds: admin@backoffice.com / admin123.
• Recurso Service: index con columnas clave (id, service_name, type, uri) — los 4 mappers quedan ocultos del listado y se editan en show/forms como campos code (JSON pretty-printed).
• Validación JSON en el modelo Service: los writers de los mappers aceptan String (formulario) además de Hash; JSON inválido o que no sea un objeto ⇒ registro inválido, error visible, no se persiste nada y se conserva el valor anterior. Al vivir en el modelo, la garantía aplica a cualquier vía de escritura futura (no solo al panel).
• Middlewares para el panel en application.rb (Cookies, Session::CookieStore, Flash, MethodOverride). La API JWT sigue stateless (navigational_formats = [:html] solo habilita el redirect al login del scope admin; la API sigue devolviendo 401 JSON).
• Solo se expone services — el resource de User que scaffoldeó el instalador fue eliminado (la card prohíbe exponer datos de clientes).

---

Evidencia visual

---

Cómo probar

1. bundle install && bundle exec rails db:migrate && bundle exec rails db:seed
2. bundle exec rails server y abrir http://localhost:3000/admin → redirige a la página de login /admin/sign_in.
3. Credenciales incorrectas → error visible. Ingresar admin@backoffice.com / admin123 → entra al panel.
4. Menú → Services: listado con id, nombre, tipo y URI (sin mappers).
5. "Create new service" → cargar nombre/tipo/URI/método + un mapper como {"customer_zip_code": "destino.codigoPostal"} → Save → detalle con los JSON persistidos.
6. Editar y poner {esto no es json en un mapper → Save → error "no es un JSON válido", nada se persiste.
7. Logout desde el menú del usuario (arriba a la derecha).
8. bundle exec rspec spec/requests/admin/ spec/models/service_spec.rb spec/models/admin_user_spec.rb — cubre el flujo de login (redirect sin sesión, credenciales inválidas, acceso OK), listado, alta con JSON válido, rechazo de JSON inválido/escalar, edición y la coerción de mappers a nivel modelo.

---

Impacto y consideraciones

¿Introduce breaking changes?
No. La API REST no cambia; los middlewares agregados no afectan requests JWT.

¿Requiere nuevas variables de entorno?
No. Los administradores viven en la tabla admin_users (alta vía seeds o consola).

¿Afecta la arquitectura o genera un nuevo patrón?
Sí — Avo queda como el backoffice definitivo: recursos administrables futuros se agregan creando app/avo/resources/<entidad>.rb + su controller en app/controllers/avo/. Nuevo scope de autenticación admin_user (Devise, sesión) separado del scope user (JWT).

---