# Matriz de decision para stock operativo, ventas, reportes y realtime

## Objetivo

Definir una ruta de modernizacion que permita:

- mantener una sola fuente de verdad para el stock operativo;
- no romper ventas, reportes ni tablero;
- conservar el codigo legacy para auditoria, comparacion y rollback controlado;
- soportar correctamente productos con receta, sin receta, transformados y no transformados;
- soportar cancelacion por item, cancelacion total de pedido, anulacion de venta y reposicion de stock.

## Principio rector

No se deben eliminar todas las vistas.

La regla correcta es:

- las vistas pueden seguir existiendo para catalogo, joins comodos, cocina y reportes;
- las vistas legacy no deben seguir participando en decisiones de stock operativo o validacion realtime;
- el stock operativo debe salir de tablas reales y de un proveedor moderno unico.

## Fuente de verdad propuesta

### Stock operativo unico

La fuente de verdad para stock operativo debe salir de:

- `tm_producto_pres`
- `tm_producto_ingr`
- `tm_insumo`
- `tm_detalle_pedido`
- `tm_pedido`
- `tm_detalle_venta`
- `tm_venta`
- `kardex`

### Reglas base

1. Si `crt_stock = 0`
   - no se valida ni descuenta stock;
   - el producto puede venderse sin control de inventario.

2. Si `crt_stock = 1` y `receta = 0`
   - el stock sale de `tm_producto_pres.stock`;
   - el descuento y reposicion afectan a la presentacion final.

3. Si `crt_stock = 1` y `receta = 1`
   - el stock sale de `tm_insumo.stock` segun `tm_producto_ingr`;
   - varias presentaciones pueden compartir el mismo insumo;
   - el stock visible debe calcularse por la restriccion real del insumo compartido.

## Estado actual detectado

### Camino moderno ya existente

Hay piezas modernas ya montadas:

- `models/venta_model.php`
  - `obtenerStockProducto($idPres)`
  - `listarProductos()` ya arma stock segun receta/insumos
  - `restablecerInventario()` repone segun receta o producto final
- `views/venta/js/venta_index.js`
  - `tieneStockDisponible()`
  - `actualizarStockVisual()`
  - `reponerStockVisual()`
- `views/venta_rapida/js/venta_rapida.js`
  - mismas funciones equivalentes para validacion y repaint visual

### Camino legacy aun activo

Todavia hay dependencias directas de `v_stock_pedido` en puntos sensibles:

- favoritos (`listarProdsMasVend()`)
- busqueda (`buscar_producto()`)
- endpoint `control_stock_pedido()`
- flujos viejos desde `venta_orden.js`

Esto significa que hoy conviven dos motores de stock:

- motor moderno por receta / insumo real
- motor legacy por vista resumida

Ese doble camino es el principal riesgo actual.

## Decision arquitectonica

### Se queda

Estas piezas pueden seguir existiendo y usandose:

| Componente | Decision | Motivo |
| --- | --- | --- |
| `v_productos` | Se queda | Sirve para catalogo y joins de presentacion |
| `v_prod_favorito` | Se queda | Sirve para lista de favoritos |
| `v_mesas` | Se queda | Sirve para visualizacion de mesas |
| `v_cocina_me` | Se queda | Sirve para cocina y estados operativos |
| `v_ventas_con` | Se queda | Sirve para reportes y consolidado historico |
| vistas de inventario/resumen | Se quedan | Son utiles para reporting y auditoria |

### Se aisla

| Componente | Decision | Motivo |
| --- | --- | --- |
| `v_stock_pedido` | Se aisla | No debe seguir decidiendo stock operativo |
| `control_stock_pedido()` | Se aisla | Queda solo para compatibilidad o comparacion |
| lecturas legacy desde favoritos/busqueda | Se migran | Deben leer el mismo proveedor moderno |

### Se convierte en oficial

| Componente | Decision | Motivo |
| --- | --- | --- |
| `obtenerStockProducto()` o un proveedor equivalente central | Oficial | Debe ser la fuente unica de stock calculado |
| `tm_producto_pres.stock` | Oficial para `receta = 0` | Control de stock por presentacion |
| `tm_insumo.stock` | Oficial para `receta = 1` | Control de stock por receta compartida |
| `kardex` | Oficial para auditoria | Debe reflejar cada entrada/salida/reposicion |

## Matriz por funcionalidad

### 1. Mostrar stock en la carta

**Debe usar:** proveedor moderno unico.

**No debe usar:** `v_stock_pedido`.

**Alcance:**

- venta en mesas
- para llevar
- delivery
- venta rapida
- favoritos
- busqueda

**Riesgo actual:**

- categoria normal ya esta mas cerca del camino moderno;
- favoritos y busqueda aun pueden mostrar un stock distinto al real.

### 2. Validar stock al agregar producto

**Debe usar:** la misma fuente moderna del stock visible.

**No debe usar:** vistas legacy ni calculos duplicados por pantalla.

**Condicion obligatoria:**

- la validacion de disponibilidad y el badge visual deben salir del mismo objeto de stock.

### 3. Descontar stock al tomar pedido

**Debe usar:** tablas reales + kardex.

**Regla:**

- si el pedido se registra, el descuento debe quedar persistido;
- si falla el registro, no debe descontar stock.

**Alcance:**

- mesas
- para llevar
- delivery
- venta rapida

### 4. Reponer stock al cancelar un item

**Debe usar:** reposicion sobre tablas reales.

**Regla:**

- si el item controlaba stock, se repone;
- si no controlaba stock, no se toca inventario;
- debe registrar kardex de ingreso/reposicion.

### 5. Cancelar todo el pedido / toda la mesa

**Debe usar:** reposicion total + cierre consistente del pedido.

**Regla funcional:**

- todos los items activos deben pasar a estado cancelado;
- la mesa debe liberarse;
- el stock debe volver;
- la interfaz debe dejar de mostrar el pedido.

**Observacion importante:**

Hoy el flujo funcional existe, pero backend aun no es totalmente atomico porque la reposicion y el cierre no viven en una sola unidad transaccional de punta a punta.

### 6. Anular venta emitida

**Debe usar:** `tm_venta`, `tm_detalle_venta`, `tm_pedido`, reposicion de stock y kardex.

**Regla:**

- si una venta se anula correctamente, se debe reponer inventario segun el tipo de producto;
- el comprobante debe quedar en estado correcto para reportes y envio SUNAT/PSE.

### 7. Agregar stock / ingresos manuales

**Debe usar:** tablas reales + kardex.

**Regla:**

- los ingresos no deben depender de vistas resumidas;
- cualquier recalculo visual debe leer el stock real ya persistido.

### 8. Reportes

**Debe usar:**

- `tm_venta`
- `tm_detalle_venta`
- `tm_pedido`
- `tm_pedido_mesa`
- `tm_tipo_pago`
- `kardex`
- vistas consolidadas como `v_ventas_con` si ayudan a simplificar lectura

**No necesitan:** usar `v_stock_pedido` para nada.

### 9. Mozo

**Debe seguir saliendo de:**

- `tm_pedido_mesa.id_mozo`

**Impacto de la modernizacion de stock:**

- bajo impacto directo;
- mejora indirecta porque reduce pedidos colgados o inconsistentes que luego ensucian el reporte por mozo.

### 10. Pagos, descuentos y comisiones

**Debe seguir saliendo de:**

- `tm_venta`

Campos relevantes:

- `id_tipo_pago`
- `pago_efe`
- `pago_tar`
- `pago_yape`
- `pago_plin`
- `pago_tran`
- `descuento_tipo`
- `descuento_personal`
- `descuento_monto`
- `comision_tarjeta`
- `comision_delivery`

**Impacto de la modernizacion de stock:**

- no debe alterar la logica contable o de arqueo;
- solo debe asegurar que la transaccion de venta no quede a medio camino.

## Productos con y sin insumos

### Producto sin receta

Ejemplo:

- gaseosa individual
- postre unitario
- bebida cerrada

Regla:

- stock propio en `tm_producto_pres.stock`;
- venta descuenta presentacion final;
- cancelacion repone la misma presentacion.

### Producto con receta y stock compartido

Ejemplo:

- 1/8 pollo a la brasa
- 1/8 pollo con chaufa
- 1/8 pollo con ensalada
- 1/4 pollo mixto
- 1 pollo entero con papa

Regla:

- todos consumen el mismo insumo base `POLLO STOCK`;
- el nombre comercial del plato no cambia la logica de stock;
- la disponibilidad real sale de la receta configurada por presentacion.

## Realtime

## Objetivo

Que todos los canales vean el mismo stock con la menor latencia posible.

### Canales que deben compartir motor

- mesas
- para llevar
- delivery
- venta rapida

### Recomendacion

1. Un solo proveedor moderno genera el stock payload.
2. El front actualiza visualmente sobre ese payload.
3. El backend persiste descuento/reposicion sobre tablas reales.
4. El legacy queda solo para comparacion interna, no para responder al usuario final.

## Impacto esperado si se aplica esta estrategia

### Impacto positivo

- menos desalineacion de stock entre pantallas;
- menos riesgo de negativos visuales falsos;
- mejor soporte para insumos compartidos;
- misma logica para todos los canales;
- reportes mas consistentes porque la operacion deja menos estados anormales.

### Impacto controlado

- no obliga a rehacer tablero ni reportes;
- no obliga a eliminar vistas utiles;
- no rompe mozos, pagos ni descuentos si se limita el cambio al motor de stock operativo.

### Riesgo principal a vigilar

- que algun modulo siga leyendo `v_stock_pedido` sin que lo notemos;
- que la cancelacion total siga sin atomicidad completa;
- que algun repaint visual no se refresque despues de cancelacion o anulacion.

## Orden recomendado de implementacion

### Fase 1. Aislar legacy

- dejar `v_stock_pedido` fuera del camino principal;
- marcar `control_stock_pedido()` como compatibilidad;
- identificar todo modulo que siga leyendolo.

### Fase 2. Unificar lectura de stock

Migrar a proveedor moderno unico en:

- `listarProductos()`
- `listarProdsMasVend()`
- `buscar_producto()`
- cualquier endpoint de validacion de stock
- cualquier badge o contador visual de stock

### Fase 3. Unificar repaint frontend

Asegurar que todos los frontends usen la misma estructura de stock para:

- agregar item
- cancelar item
- cancelar pedido completo
- limpiar interfaz
- recalcular disponibilidad al vuelo

### Fase 4. Blindar cancelaciones y anulaciones

Objetivo:

- una sola operacion logica para cerrar pedido, reponer stock, registrar kardex y liberar mesa.

### Fase 5. Shadow compare temporal

Mantener el legacy vivo solo para comparacion interna:

- moderno responde al usuario;
- legacy se usa para auditar diferencias;
- si hay divergencia, se loguea.

## Decision final recomendada

### Lo que SI debemos hacer

- mantener vistas utiles para lectura y reporte;
- sacar `v_stock_pedido` del flujo operativo;
- consolidar una sola fuente moderna para stock;
- dejar el legacy como referencia y auditoria.

### Lo que NO debemos hacer

- no eliminar todas las vistas;
- no mezclar dos motores activos de stock en produccion;
- no dejar favoritos, busqueda o venta rapida leyendo stock por un camino distinto al de mesas.

## Resumen ejecutivo

La modernizacion no debe apuntar a "dejar de usar vistas".
Debe apuntar a "dejar de usar vistas legacy para decisiones de stock en tiempo real".

Con esa separacion:

- stock operativo queda unificado y mas seguro;
- ventas, mozo, pagos y reportes no se rompen;
- realtime mejora;
- el sistema conserva trazabilidad y capacidad de comparacion con el legado.
