RF-008 — Administración de listas de precios y resolución de precio por región¶


Estado	En producción (`main`, `staging`)
Tipo	Widget de admin + rutas API propias
Ubicación	`src/admin/widgets/price-list-variant.tsx` · `src/api/admin/custom/price-lists/current/` · `src/api/store/custom/products/[id]/`
Depende de	Módulo Pricing — RF-000

Requisito¶

Administrar las variantes incluidas en una lista de precios desde su propia página de detalle, con búsqueda sobre el catálogo, visibilidad del precio de lista, del precio especial y del stock, y alta o baja masiva de variantes. Consultar las listas de precios vigentes en el día según la zona horaria de la operación. Exponer al storefront el producto con su precio ya calculado por región.

Solución adoptada¶

Extender el detalle de la lista de precios (price_list.details.after) con un widget que opera sobre el Admin SDK, y agregar dos rutas propias para las consultas que la API nativa no resuelve en un solo llamado.

flowchart LR
    subgraph ADM[Dashboard]
        W[Widget de variantes<br/>price_list.details]
        R1["/admin/custom/price-lists/current"]
    end
    subgraph SF[Storefront]
        R2["/store/custom/products/:id"]
    end
    W -->|priceList.prices · productVariant.list| PL[(Price List)]
    W -->|batchPrices: alta y baja| PL
    R1 -->|listPriceLists · vigencia del día| PL
    R2 -->|price_set + contexto de región| PR[(Pricing)]
    PR --> V[Variantes con calculated_price]

Funciones¶

Función	Superficie	Detalle
Listado de variantes de la lista	Widget	Producto, variante, SKU, opciones, precio especial, precio original y stock disponible
Búsqueda e incorporación	Widget	Búsqueda sobre el catálogo, selección múltiple con precio por variante y alta por lote
Edición y baja	Widget	Modificación del precio especial y remoción de variantes por lote
Listas vigentes hoy	`GET /admin/custom/price-lists/current`	Listas activas que inician o finalizan en el día, con paginación y orden por fecha
Producto con precio calculado	`GET /store/custom/products/:id`	Producto y variantes con `calculated_price` resuelto para la región indicada

Reglas de negocio¶

Calcular la vigencia del día en la zona horaria de la operación —America/Asuncion por defecto, parametrizable por consulta— y no en UTC.
Considerar vigente la lista activa cuyo inicio o fin cae dentro del día evaluado.
Operar altas y bajas de precios por lote sobre la lista, en una sola llamada por operación.
Resolver el precio del storefront con el contexto de región, devolviendo el producto completo aunque no existan conjuntos de precio asociados.

Ajustes de presentación¶

Dos widgets de inyección de CSS complementan las pantallas nativas, sin lógica asociada:

Widget	Zona	Efecto
`price-list-widen-title-col`	`price_list.details.after`	Ensanchar la columna de título para admitir nombres largos de producto
`product-desc-shortener`	`product.details.after`	Limitar la descripción del producto a tres líneas

Criterios de aceptación¶

#	Criterio
1	Buscar una variante por título o SKU y agregarla a la lista con su precio especial
2	Visualizar precio original, precio especial y stock de cada variante incluida
3	Quitar varias variantes de la lista en una sola operación
4	Obtener las listas vigentes del día con el corte horario de Asunción
5	Devolver al storefront el producto con `calculated_price` por región

Limitaciones conocidas¶

Depender de la estructura de respuesta del módulo Pricing según versión: la ruta de listas vigentes contempla varias formas de retorno para tolerar el cambio.
Mantener las rutas de scaffold /store/custom y /admin/custom sin uso funcional.