feat: [TESIS-102] add product category and the primary warehouse to the list

[TomasMartin2004]

🔗 Ticket de Jira

TESIS-102 — bloquea a TESIS-62

---

📝 Descripción

Cierra los dos agujeros de datos que hoy impiden implementar la tabla del Master Catalog (TESIS-62), y que además alcanzan a TESIS-63, donde el Select de categoría se pinta deshabilitado porque no hay nada detrás.

Salió de auditar TESIS-62: de sus 8 columnas, Category no tenía columna en products, y Location Node no tenía forma de resolverse porque ProductListSerializer no expone ninguna referencia a depósitos.

Categoría

products.category, string nullable, con vocabulario en Product::CATEGORIES — Electronics, Machinery, Cabling, Power, los valores que muestran los diseños — validado por inclusión con allow_nil, porque los productos que ya existen no tienen categoría y no hay con qué inferirla.

Deliberadamente sin CHECK constraint, y vale explicarlo porque se aparta de lo que hace el resto del esquema. Todas las columnas que hoy tienen uno (orders.status, services.type, failed_events.status, shipments.status) llevan un vocabulario de sistema: máquinas de estado que la aplicación transiciona, donde el motor tiene que ser la última garantía porque las escrituras por lote saltean el modelo. Una categoría de producto es taxonomía de negocio: la elige el usuario y la lista va a crecer. Un CHECK ahí obligaría a una migración por cada categoría nueva, y no compra nada que el validador de modelo no dé ya.

Nodo principal en el listado

El listado suma primary_warehouse y warehouse_count, no el desglose completo. La columna Location Node muestra un nodo, y GET /products/:id ya devuelve todos los depósitos: mantener el serializer de listado más liviano que el de detalle es la razón de que existan los dos.

Primario es el depósito con más unidades, desempatando por el warehouse_id más bajo. Sin ese desempate, dos depósitos con la misma cantidad devolverían el que a Postgres le convenga y la columna cambiaría entre dos refrescos sin que haya pasado nada — hay un spec dedicado a eso. Las filas en 0 se saltean, así que warehouse_count es coherente con primary_warehouse: cuando el conteo es 0 el nodo es null, que no es lo mismo que tener 0 unidades en un depósito conocido.

preload y no includes

El index precarga, y la elección es load-bearing. includes deja que Rails elija entre precargar y hacer JOIN; acá el JOIN rompe: with_total_stock ya agrupa por products.id con su propio SELECT, así que resolver la asociación como eager_load sumaría las columnas de stocks y warehouses a ese SELECT y Postgres rechazaría la consulta por columnas fuera del GROUP BY. preload garantiza las consultas separadas.

Vocabulario para el Select

GET /api/v1/products/categories expone Product::CATEGORIES para que el modal de alta y el filtro del listado no repitan la lista en el frontend.

---

🛠️ Cambios realizados

• Migración add_category_to_products: columna category e índice (company_id, category) — compuesto y no sobre category sola, porque el default_scope de CompanyScoped ya pone company_id en el WHERE de toda consulta del listado
• Product: constante CATEGORIES, validación de inclusión con allow_nil, y #primary_stock — que ordena en Ruby a propósito, porque quien llama ya precargó stocks: :warehouse y un order ahí dispararía una query por fila
• ProductSerializer y ProductListSerializer: category
• ProductListSerializer: primary_warehouse ({ id, name, quantity } o null) y warehouse_count
• ProductsController: preload(stocks: :warehouse) en index, category en product_params, y la acción categories
• config/routes.rb: get :categories, on: :collection dentro de products
• Seeds: categorías asignadas fuera del bloque de find_or_create_by! —que sólo corre al crear— para que las bases ya sembradas antes de que existiera la columna también las reciban, con un if que mantiene la idempotencia
• Specs: 5 de modelo para primary_stock (sin stock, más unidades, desempate, filas en 0, todas en 0), 3 de categoría, y en request el nodo principal, el conteo, el desempate, los ceros, el nodo nulo, el N+1 de warehouses y el endpoint de categorías

---

🧪 Cómo probar

1. bin/rails db:migrate → agrega la columna y el índice
2. bin/rails db:seed dos veces → idempotente; los productos de Norte quedan en Electronics y los de Sur en Machinery
3. GET /api/v1/products → cada fila trae category, primary_warehouse y warehouse_count
4. GET /api/v1/products/categories → { "data": ["Electronics", "Machinery", "Cabling", "Power"] }
5. POST /api/v1/products con category: "Groceries" → 422; con category: "Electronics" → 201
6. Asignar el mismo producto a dos depósitos con cantidades distintas y pedir el listado dos veces → primary_warehouse es siempre el mismo

---

📸 Evidencia visual

N/A (backend).

Validación reproducida local:

• bundle exec rspec → 471 examples, 0 failures
• bundle exec rubocop --force-exclusion → 122 archivos, sin ofensas
• bin/brakeman -q → No warnings found
• La migración corrida contra la base real regenera un db/schema.rb idéntico al del commit

---

⚠️ Impacto y consideraciones

• Breaking changes: no. La columna es nullable y los dos campos nuevos del listado se suman; ningún consumidor actual se rompe.
• Payload del listado: crece en dos campos por fila. primary_warehouse es un objeto de tres claves, no el array de depósitos: la diferencia con ProductSerializer se mantiene a propósito.
• Queries: el index pasa de 2 a 4 consultas por página (productos + total + stocks + warehouses), constantes, no por fila. Hay un spec que lo fija.
• Fuera de alcance, y nombrado en vez de omitido: el tab "In Transit" y el "+500 Incoming" que pide TESIS-62 no son un campo que falte sino un dominio que no existe — no hay modelo de transferencias entre nodos, ni de órdenes de compra o recepciones. Quedan documentados como recorte en el PR de TESIS-62.
• Sin cambios de entorno: no requiere variables nuevas ni servicios externos.