@saulwade/swl-ses 1.0.0

package/habilidades/rails-experto/recursos/active-record.md

@@ -0,0 +1,260 @@
+# Active Record Avanzado
+
+Referencia de patrones avanzados de Active Record para Rails 7+.
+
+---
+
+## Concerns — comportamiento compartido entre modelos
+
+Los concerns encapsulan lógica reutilizable que múltiples modelos comparten.
+
+```ruby
+# app/models/concerns/trackable.rb
+module Trackable
+  extend ActiveSupport::Concern
+
+  included do
+    belongs_to :created_by_user, class_name: 'User', optional: true
+    belongs_to :updated_by_user, class_name: 'User', optional: true
+
+    before_create { self.created_by_user = Current.user }
+    before_save   { self.updated_by_user = Current.user }
+  end
+end
+
+# app/models/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :buscar, ->(termino) {
+      where("titulo ILIKE :q OR descripcion ILIKE :q", q: "%#{sanitize_sql_like(termino)}%")
+    }
+  end
+end
+
+# Uso en modelo
+class Post < ApplicationRecord
+  include Trackable
+  include Searchable
+end
+```
+
+**Regla**: usar `sanitize_sql_like` siempre que el término de búsqueda viene del usuario.
+
+---
+
+## Counter Cache — contadores automáticos
+
+Evita `SELECT COUNT(*)` repetidos en vistas de listas.
+
+```ruby
+# En la asociación (migration y modelo)
+class Comment < ApplicationRecord
+  belongs_to :post, counter_cache: true
+end
+
+# Migración para agregar la columna
+class AddCommentsCountToPosts < ActiveRecord::Migration[7.1]
+  def change
+    add_column :posts, :comments_count, :integer, default: 0, null: false
+    # Inicializar contadores en datos existentes
+    Post.find_each { |p| Post.reset_counters(p.id, :comments) }
+  end
+end
+
+# Uso — no ejecuta query adicional
+post.comments_count  # lee la columna, no hace COUNT(*)
+```
+
+**Touch**: `belongs_to :post, counter_cache: true, touch: true` actualiza `updated_at` del post al crear/eliminar un comentario — útil para cache HTTP.
+
+---
+
+## Optimistic Locking con lock_version
+
+Previene actualizaciones concurrentes que sobreescriben datos.
+
+```ruby
+# Migración
+add_column :posts, :lock_version, :integer, default: 0
+
+# Rails lo activa automáticamente al existir la columna.
+# Cuando dos usuarios editan el mismo registro:
+post_a = Post.find(1)  # lock_version = 5
+post_b = Post.find(1)  # lock_version = 5
+
+post_a.update!(titulo: "Versión A")  # lock_version → 6, OK
+post_b.update!(titulo: "Versión B")  # lanza ActiveRecord::StaleObjectError
+```
+
+```ruby
+# En el controller, rescatar y reintentar
+def update
+  @post.update!(post_params)
+rescue ActiveRecord::StaleObjectError
+  @post.reload
+  flash.now[:alert] = 'Otro usuario modificó este registro. Revisa los cambios.'
+  render :edit, status: :conflict
+end
+```
+
+---
+
+## Soft Delete con paranoia / discard
+
+Dos opciones idiomáticas:
+
+```ruby
+# Opción A: gem 'discard' (más simple, recomendada para Rails 7+)
+class Post < ApplicationRecord
+  include Discard::Model
+  default_scope -> { kept }
+end
+
+post.discard   # marca deleted_at, no elimina de BD
+post.undiscard # restaura
+
+# Migración necesaria
+add_column :posts, :discarded_at, :datetime
+add_index  :posts, :discarded_at
+
+# Opción B: gem 'paranoia' (más funcionalidad, más magia)
+class Post < ApplicationRecord
+  acts_as_paranoid
+end
+
+post.destroy   # soft delete (sets deleted_at)
+post.really_destroy!  # elimina permanentemente
+Post.with_deleted      # incluye registros eliminados
+```
+
+---
+
+## Single Table Inheritance (STI)
+
+**Cuándo usar STI**: subtipos con comportamiento distinto pero mismos atributos base.
+**Cuándo NO**: subtipos con atributos muy distintos → usar polimorfismo o tablas separadas.
+
+```ruby
+# Una sola tabla "vehicles" con columna "type"
+class Vehicle < ApplicationRecord
+  validates :marca, presence: true
+end
+
+class Car < Vehicle
+  validates :puertas, numericality: { greater_than: 0 }
+end
+
+class Truck < Vehicle
+  validates :capacidad_toneladas, numericality: { greater_than: 0 }
+end
+
+# Rails almacena el nombre de clase en la columna "type"
+Car.create!(marca: "Toyota", puertas: 4)
+Vehicle.all        # devuelve Cars y Trucks
+Car.all            # solo Cars
+```
+
+**Anti-patrón**: columnas `null: true` en exceso por diferencias de atributos → señal de que STI no es la solución correcta.
+
+---
+
+## Bulk Operations (Rails 6+)
+
+Para insertar o actualizar grandes volúmenes sin instanciar modelos.
+
+```ruby
+# insert_all — ignora duplicados por defecto
+Post.insert_all([
+  { titulo: "Post 1", status: "publicado", author_id: 1 },
+  { titulo: "Post 2", status: "borrador",  author_id: 2 }
+])
+
+# upsert_all — actualiza si existe conflicto en la PK
+Post.upsert_all(
+  registros,
+  unique_by: :titulo,
+  update_only: [:status, :updated_at]
+)
+
+# NOTA: insert_all/upsert_all NO ejecutan callbacks ni validaciones.
+# Usar solo para importaciones masivas donde el origen es confiable.
+```
+
+---
+
+## ActiveRecord::Encryption (Rails 7+)
+
+Cifrado transparente de columnas sensibles sin cambios en el código de negocio.
+
+```ruby
+# config/application.rb
+config.active_record.encryption.primary_key        = Rails.application.credentials.ar_encryption[:primary_key]
+config.active_record.encryption.deterministic_key  = Rails.application.credentials.ar_encryption[:deterministic_key]
+config.active_record.encryption.key_derivation_salt = Rails.application.credentials.ar_encryption[:salt]
+
+# Modelo
+class User < ApplicationRecord
+  encrypts :numero_tarjeta
+  encrypts :email, deterministic: true  # permite búsquedas exactas
+end
+
+# Uso — transparente para el código
+user.email           # devuelve valor descifrado
+User.find_by(email: "a@b.com")  # funciona por ser deterministic: true
+```
+
+**Regla**: usar `deterministic: true` solo cuando necesitas buscar por el campo. Sin `deterministic`, el cifrado usa nonce aleatorio (más seguro).
+
+---
+
+## Callbacks — cuándo usar y anti-patrones
+
+**Callbacks válidos:**
+- `before_validation`: normalizar datos (`strip`, `downcase`)
+- `before_save`: derivar valores calculados del mismo modelo
+- `after_initialize`: valores default complejos
+
+**Callbacks a evitar:**
+```ruby
+# MAL — request HTTP en callback (bloquea la transacción DB)
+after_create :notificar_por_email  # si el mailer falla, la TX puede quedar abierta
+
+# BIEN — delegar a un job
+after_create_commit -> { NotificarJob.perform_later(id) }
+
+# MAL — lógica de negocio en callback (difícil de testear y reutilizar)
+before_save :calcular_precio_total_con_impuestos_y_descuentos
+
+# BIEN — service object que llama al modelo con el valor ya calculado
+```
+
+---
+
+## Query cache y EXPLAIN
+
+```ruby
+# Ver el plan de ejecución SQL de una query
+Post.includes(:author).where(status: :publicado).explain
+# Imprime EXPLAIN ANALYZE en PostgreSQL
+
+# Query cache — Rails cachea queries idénticas dentro de la misma request
+# Forzar recarga cuando el cache interfiere en tests:
+ActiveRecord::Base.connection.clear_query_cache
+
+# Índices que casi siempre se necesitan
+add_index :posts, :status
+add_index :posts, [:author_id, :created_at]  # índice compuesto para order frecuente
+add_index :posts, :discarded_at              # si usas soft delete
+```
+
+---
+
+## Referencias externas
+
+- [Active Record Associations — Rails Guides](https://guides.rubyonrails.org/association_basics.html)
+- [Active Record Query Interface](https://guides.rubyonrails.org/active_record_querying.html)
+- [Active Record Encryption](https://guides.rubyonrails.org/active_record_encryption.html)
+- [gem discard](https://github.com/jhawthorn/discard)
+- [gem bullet (detección N+1)](https://github.com/flyerhzm/bullet)

package/habilidades/rails-experto/recursos/hotwire-turbo.md

@@ -0,0 +1,293 @@
+# Hotwire: Turbo y Stimulus
+
+Referencia completa de Hotwire para Rails 7+: Turbo Drive, Turbo Frames,
+Turbo Streams, Stimulus y Action Cable.
+
+---
+
+## Turbo Drive — navegación sin page reload
+
+Turbo Drive intercepta clics en `<a>` y envíos de `<form>` para hacer
+fetch en segundo plano y reemplazar solo `<body>`. Está activo por defecto.
+
+```erb
+<%# Deshabilitar Turbo Drive en un enlace específico %>
+<%= link_to "Descargar PDF", reporte_path, data: { turbo: false } %>
+
+<%# Deshabilitar en un formulario que redirecciona a URL externa %>
+<%= form_with url: pago_externo_path, data: { turbo: false } do |f| %>
+```
+
+**Regla**: no deshabilitar Turbo Drive globalmente. Si hay conflictos, resolver
+usando `data-turbo="false"` selectivamente.
+
+---
+
+## Turbo Frames — actualización parcial de la página
+
+Un Turbo Frame delimita una región de la página. Los enlaces y formularios
+dentro del frame solo actualizan ese frame, no toda la página.
+
+```erb
+<%# app/views/posts/index.html.erb %>
+<%= turbo_frame_tag "lista-posts" do %>
+  <%= render @posts %>
+  <%= link_to "Cargar más", posts_path(page: @proxima_pagina) %>
+<% end %>
+
+<%# El controller debe devolver la misma etiqueta en la respuesta %>
+<%# app/views/posts/index.html.erb (respuesta al frame) %>
+<%= turbo_frame_tag "lista-posts" do %>
+  <%= render @posts %>
+<% end %>
+```
+
+```ruby
+# Edición inline sin modal — el formulario de edición está en su propio frame
+# app/views/posts/_post.html.erb
+<%= turbo_frame_tag dom_id(post) do %>
+  <h2><%= post.titulo %></h2>
+  <%= link_to "Editar", edit_post_path(post) %>
+<% end %>
+
+# app/views/posts/edit.html.erb
+<%= turbo_frame_tag dom_id(@post) do %>
+  <%= render "form", post: @post %>
+<% end %>
+```
+
+**Regla**: el `id` del `turbo_frame_tag` en la respuesta debe coincidir exactamente
+con el del frame que hizo la solicitud. Si no coincide, Turbo lo descarta.
+
+---
+
+## Turbo Streams desde controller
+
+Para actualizar múltiples partes de la página en una sola respuesta.
+
+```ruby
+# app/controllers/posts_controller.rb
+def create
+  @post = Post.new(post_params.merge(author: current_user))
+
+  respond_to do |format|
+    if @post.save
+      format.turbo_stream
+      format.html { redirect_to @post }
+    else
+      format.turbo_stream do
+        render turbo_stream: turbo_stream.replace(
+          "new_post_form",
+          partial: "posts/form",
+          locals: { post: @post }
+        )
+      end
+      format.html { render :new, status: :unprocessable_entity }
+    end
+  end
+end
+```
+
+```erb
+<%# app/views/posts/create.turbo_stream.erb %>
+<%= turbo_stream.prepend "lista-posts", partial: "posts/post", locals: { post: @post } %>
+<%= turbo_stream.update  "new_post_form", partial: "posts/form", locals: { post: Post.new } %>
+<%= turbo_stream.update  "posts-count", @posts_count %>
+```
+
+**Acciones disponibles**: `append`, `prepend`, `replace`, `update`, `remove`,
+`before`, `after`.
+
+---
+
+## Turbo Streams desde jobs con Action Cable (broadcast)
+
+Para actualizar la UI de múltiples usuarios en tiempo real.
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  after_create_commit  -> { broadcast_prepend_to "posts" }
+  after_update_commit  -> { broadcast_replace_to "posts" }
+  after_destroy_commit -> { broadcast_remove_to "posts" }
+
+  # Con partial personalizado
+  after_create_commit -> {
+    broadcast_prepend_to "posts",
+      partial: "posts/post_card",
+      locals: { post: self }
+  }
+end
+```
+
+```erb
+<%# En la vista que recibe los broadcasts %>
+<%= turbo_stream_from "posts" %>
+
+<div id="lista-posts">
+  <%= render @posts %>
+</div>
+```
+
+```ruby
+# Broadcast desde un job (para operaciones async)
+class PublicarPostJob < ApplicationJob
+  def perform(post_id)
+    post = Post.find(post_id)
+    post.update!(status: :publicado)
+    Turbo::StreamsChannel.broadcast_replace_to(
+      "posts",
+      target: dom_id(post),
+      partial: "posts/post",
+      locals: { post: post }
+    )
+  end
+end
+```
+
+---
+
+## Stimulus — controllers de JavaScript
+
+Stimulus conecta comportamiento JS a elementos HTML mediante atributos `data-*`.
+
+```javascript
+// app/javascript/controllers/contador_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["valor"]
+  static values  = { inicio: { type: Number, default: 0 } }
+
+  connect() {
+    this.count = this.inicioValue
+    this.actualizar()
+  }
+
+  incrementar() {
+    this.count++
+    this.actualizar()
+  }
+
+  actualizar() {
+    this.valorTarget.textContent = this.count
+  }
+}
+```
+
+```erb
+<%# En la vista %>
+<div data-controller="contador" data-contador-inicio-value="5">
+  <span data-contador-target="valor"></span>
+  <button data-action="click->contador#incrementar">+1</button>
+</div>
+```
+
+**Reglas de Stimulus:**
+- Un controller por responsabilidad (no acumular lógica no relacionada)
+- `connect()` para setup, `disconnect()` para cleanup (event listeners externos)
+- Usar `values` para pasar datos desde el servidor, no leer del DOM
+- Preferir `targets` sobre `querySelector` para referencias a elementos
+
+---
+
+## Action Cable — canal completo
+
+```ruby
+# app/channels/notificaciones_channel.rb
+class NotificacionesChannel < ApplicationCable::Channel
+  def subscribed
+    stream_for current_user
+  end
+
+  def unsubscribed
+    stop_all_streams
+  end
+end
+
+# app/channels/application_cable/connection.rb
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = find_verified_user
+    end
+
+    private
+
+    def find_verified_user
+      if (verified = User.find_by(id: cookies.encrypted[:user_id]))
+        verified
+      else
+        reject_unauthorized_connection
+      end
+    end
+  end
+end
+
+# Broadcast desde cualquier parte del sistema
+NotificacionesChannel.broadcast_to(
+  usuario,
+  { tipo: "nueva_tarea", mensaje: "Te asignaron una tarea" }
+)
+```
+
+```javascript
+// app/javascript/controllers/notificaciones_controller.js
+import { Controller } from "@hotwired/stimulus"
+import consumer from "channels/consumer"
+
+export default class extends Controller {
+  connect() {
+    this.subscription = consumer.subscriptions.create("NotificacionesChannel", {
+      received: (data) => this.mostrar(data)
+    })
+  }
+
+  disconnect() {
+    this.subscription.unsubscribe()
+  }
+
+  mostrar(data) {
+    // Actualizar UI con la notificación
+    console.info("Notificación:", data.mensaje)
+  }
+}
+```
+
+---
+
+## Morphing con Turbo 8 (Rails 7.1+)
+
+Turbo 8 introduce morphing: en lugar de reemplazar el DOM completo, hace un diff
+inteligente que preserva el estado del cliente (scroll, focus, valores de input).
+
+```ruby
+# app/controllers/posts_controller.rb
+def index
+  @posts = Post.includes(:author).publicados.recientes
+  # Turbo 8 hace morph del <body> en lugar de reemplazarlo completo
+  # No requiere configuración extra si las vistas tienen IDs estables en elementos clave
+end
+```
+
+```erb
+<%# Forzar refresh completo de un frame específico (sin morph) %>
+<%= turbo_frame_tag "estadisticas", refresh: :morph do %>
+  <%= render "estadisticas" %>
+<% end %>
+```
+
+**Regla para morphing**: los elementos clave DEBEN tener `id` estable
+(`dom_id(@post)` o equivalente). Sin `id`, Turbo no puede hacer el diff correctamente
+y puede perder estado o duplicar elementos.
+
+---
+
+## Referencias externas
+
+- [Turbo Handbook](https://turbo.hotwired.dev/handbook/introduction)
+- [Stimulus Handbook](https://stimulus.hotwired.dev/handbook/introduction)
+- [Action Cable — Rails Guides](https://guides.rubyonrails.org/action_cable_overview.html)
+- [Hotwire — repositorio oficial](https://github.com/hotwired/hotwire-rails)