# Catálogo precargado de abarrotes

## Paso a paso

Así se usa el catálogo. El detalle está en las secciones numeradas.

### Importar productos del catálogo

1. En el menú lateral abre **📦 Productos → Inventario**.
2. Pulsa **📦 Importar del Catálogo**.
3. Busca por nombre o filtra por categoría y haz clic en cada producto que quieras (queda marcado con ✅).
4. Pulsa **Importar seleccionados**.
5. Los productos se crean con existencia en 0. Registra la mercancía real con [Compras](./compras.md) o **📥 Agregar Nuevo Inventario**, y ajusta el precio si en tu tienda es distinto.

Ver secciones 3 a 5.

## 1. ¿Qué es el Catálogo Precargado?

Es una lista de referencia de **cerca de 900 productos frecuentes de abarrotes en México** (refrescos, cerveza, lácteos, pan, botanas, dulces, granos, enlatados, condimentos, aceites, cuidado personal, limpieza, cigarros, desechables y congelados), con nombre, categoría, proveedor sugerido y precio/costo de referencia ya capturados. Sirve para **poblar rápido el inventario de una tienda nueva** (o agregar líneas completas de producto a una ya existente) sin tener que dar de alta cada artículo a mano desde **➕ Nuevo Producto**.

Los productos del catálogo son **plantillas**, no inventario real: al importarlos se crean en tu base con **existencia en 0**. La idea es que después recibas/cuentes la mercancía real y la registres con **📥 Agregar Nuevo Inventario** (ver el [manual de Inventario](./inventario.md#7-agregar-nuevo-inventario-entrada-de-mercancía)), y ajustes el precio o costo si en tu tienda son distintos a los de referencia.

**Quién puede usarlo:** Catálogo Precargado es de **administrador únicamente** — tanto ver el catálogo como importar productos requieren permisos de admin (`requireAdmin`). Un cajero no ve el botón ni puede llamar a estas rutas.

## 2. Llegar al módulo

Desde **Inventario**, clic en **📦 Importar del Catálogo** (junto a "Agregar Nuevo Inventario" y "Nuevo Producto"). Se abre el modal "Importar del Catálogo Precargado".

La primera vez que se abre en la sesión, el catálogo completo se descarga una sola vez y queda en memoria; abrirlo de nuevo no vuelve a pedirlo al servidor.

## 3. Buscar y filtrar

- **Buscador**: por nombre, descripción o categoría (por ejemplo, escribir "coca" muestra todas las presentaciones de Coca-Cola; escribir "limpieza" muestra toda esa categoría aunque no aparezca en el nombre).
- **Filtro de categoría**: limita la vista a una sola categoría (Bebidas, Lácteos, Limpieza del Hogar, etc.).
- Ambos filtros se pueden combinar y se aplican sobre el catálogo ya cargado, sin recargar la página.

## 4. Seleccionar productos

Cada producto se muestra como una tarjeta con nombre, categoría, precio de referencia y proveedor sugerido — el mismo estilo de tarjeta que el catálogo del Punto de Venta. Clic en una tarjeta la marca (✅ y borde resaltado); clic de nuevo la desmarca.

El contador **"N seleccionados"**, junto al filtro de categoría, se actualiza en vivo con cuántos productos llevas marcados. La selección se mantiene aunque cambies el texto de búsqueda o el filtro de categoría — puedes buscar "refrescos", marcar varios, luego buscar "limpieza" y seguir marcando sin perder lo ya elegido.

## 5. Importar al inventario

1. Con al menos un producto seleccionado, clic en **Importar seleccionados**.
2. El sistema crea un producto por cada clave seleccionada, con:
   - **Cantidad inicial: 0** (no se asume que ya tienes esa mercancía físicamente).
   - **Categoría** igual a la del catálogo (queda disponible como filtro y columna en la tabla de Inventario).
   - **Costo y precio** iguales a los de referencia del catálogo (ajustables después desde Inventario, igual que cualquier otro producto).
   - Un lote inicial de cantidad 0, para que el producto ya tenga estructura de lotes lista para recibir mercancía.
3. Al terminar, el modal se cierra, la selección se limpia y la tabla de Inventario se refresca mostrando los productos recién importados.

**Si alguna clave seleccionada ya no existe en el catálogo** (por ejemplo, si el catálogo se actualizó entre que se cargó y se importó), el sistema la omite silenciosamente en el conteo de "importados" y avisa con un mensaje aparte cuántas se omitieron — no es un error que detenga el resto de la importación.

> **Código de barras:** los productos del catálogo que ya traen su código lo conservan al importarse (aparece junto a la categoría y se puede buscar por él), de modo que el lector USB los reconoce desde el primer día. Al iniciar el sistema, los productos ya importados que no tengan código reciben el del catálogo (si coincide el nombre). Si el código ya lo usa otro producto, se importa sin código.

## 6. Qué pasa si importo el mismo producto dos veces

El sistema **sí evita crear el mismo producto dos veces**: como los productos no guardan la "clave" del catálogo, la detección se hace por **nombre** — antes de crear cada producto, `bulkImportFromCatalogo` revisa si ya existe en Inventario un producto cuyo nombre (sin importar mayúsculas/espacios) coincida con el del item del catálogo. Si ya existe, la clave se agrega a `duplicados` y **no se crea** un producto nuevo; el modal muestra un aviso aparte con cuántos productos ya existían y no se volvieron a importar, igual que hace con las claves no encontradas.

Esto significa que si vuelves a seleccionar e importar la misma clave en otra sesión, no se duplica el producto en Inventario. La detección es por nombre exacto, así que **sí** se puede dar de alta un producto "parecido" con un nombre ligeramente distinto (por ejemplo, si lo renombraste manualmente desde Inventario antes de reimportar el original) — la validación no reconoce esos dos nombres como el mismo producto.

## 7. Preguntas frecuentes

**¿Por qué los productos importados aparecen con 0 de existencia si el catálogo trae cantidades?**
El catálogo no trae cantidades — es una lista de referencia de qué productos existen y a qué precio se venden típicamente, no de cuánta mercancía tienes tú. Después de importar, registra la mercancía real con **📥 Agregar Nuevo Inventario**.

**¿Puedo editar el precio o costo antes de importar?**
No desde este modal — se importan con los valores de referencia del catálogo. Ajústalos después desde Inventario (✏️ Editar), igual que cualquier producto dado de alta manualmente.

**¿Los productos del catálogo tienen proveedor asignado automáticamente?**
No. El catálogo trae un "proveedor sugerido" solo como referencia visual en la tarjeta, pero el producto se importa **sin proveedor asignado** en Inventario — tienes que asignarlo tú manualmente si lo quieres relacionar con uno de tus [proveedores](./proveedores.md) reales.

**¿Puedo importar productos de categorías distintas al mismo tiempo?**
Sí. El filtro de categoría solo afecta qué se ve en la tarjeta mientras buscas; la selección puede combinar productos de cualquier categoría y se importan todos juntos con un solo clic en "Importar seleccionados".