Qaudit — Sistema Web de Gestión de Auditorías de Inventario¶

Requisitos para reemplazar el flujo manual de auditoría de inventario en tienda de Zavidoro Corporation, con integración REST al sistema legado QUICK POS. Contexto académico: tesis de Licenciatura en Informática (UAA). Cliente real: Zavidoro Corporation (retail Nike/Sol, Paraguay).

Problema¶

El equipo de auditoría de inventario de Zavidoro ejecuta un proceso 100% manual y en papel: tras la lectura RFID (provista por un proveedor externo que genera un Excel comparativo de diferencias contra QUICK POS), imprimen el reporte, lo dividen físicamente entre auditores, buscan los faltantes/sobrantes en sala y depósito anotando a mano, consolidan en un único documento, cargan los ajustes uno por uno en QUICK POS, imprimen el cierre y lo firman. El costo de dejarlo sin resolver: para tiendas medianas/grandes el proceso se extiende hasta tres días hábiles, sin trazabilidad digital de quién halló qué, con errores de transcripción y consolidación, y con riesgo de carga manual ítem por ítem en el sistema comercial.

Evidence¶

Proceso documentado por relevamiento directo con una persona que vive el proceso (jefa de implementaciones y soporte de Zavidoro). El flujo de inicio a fin, la dinámica de división por hojas, el caso "mal entallado" como egreso de concepto distinto, y el cierre con firma del encargado están relevados y quedaron documentados en el anteproyecto (ver docs/anteproyecto/05_Qaudit_Anteproyecto_v6.md).
Frecuencia y duración: hasta 4 inventarios/año por tienda; tiendas grandes (Nike/Sol) tardan ~3 días, en buena parte por el tiempo de búsqueda física más la consolidación y carga manual.
Viabilidad técnica confirmada: QUICK POS expone API REST documentada (Swagger revisado); servidores de tienda conectados al central por VPN corporativa; identidades corporativas Microsoft (@zavidoro.com.py) disponibles.
⚠️ Assumption — las métricas de línea base son estimaciones, no medidas. La tabla de §8 del anteproyecto está marcada "estimado" y la satisfacción del equipo está "por medir". La línea base cuantitativa (tiempos, errores, recursos) debe validarse vía el objetivo específico 1 antes de afirmar la mejora.

Users¶

Primario — Auditor de inventario (@zavidoro.com.py): se desplaza a la tienda, se conecta a la red de la tienda, crea o se une a la sesión de auditoría de esa tienda, carga el Excel, participa de la distribución y búsqueda física, registra hallazgos, concilia y dispara los ajustes. Cualquier auditor de la sesión puede ejecutar cualquier paso (sin jerarquía interna).
Secundario — Administrador (Diana, jefa de implementaciones y soporte): no es usuaria operativa. Solo gestiona el alta/baja de tiendas (hostname, puerto, código de sucursal) y el whitelisting de usuarios habilitados desde un panel admin.
Participante no-usuario — Encargado de tienda y presentes: firman el documento de cierre desde el dispositivo del auditor; no tiene cuenta en el sistema.
No es para: usuarios fuera del dominio @zavidoro.com.py; el proceso de lectura RFID (sigue siendo del proveedor externo); ninguna otra operación de QUICK POS distinta a egresos/ingresos de ajuste.

Hypothesis¶

Creemos que digitalizar el flujo completo de auditoría —carga del Excel RFID, distribución digital de la búsqueda, conciliación automática y generación de remitos en QUICK POS vía API— reducirá el tiempo de ejecución, eliminará los errores de consolidación manual y producirá evidencia documental formal para el equipo de auditoría de Zavidoro. Sabremos que acertamos cuando, en al menos dos sesiones de auditoría reales, el tiempo total se reduzca ≥50% respecto a la línea base, los errores de consolidación lleguen a cero, y la carga de ajustes en QUICK POS baje de 30–60 min manuales a menos de 2 minutos vía API.

Success Metrics¶

Métrica	Línea base (a validar en OE1)	Meta con Qaudit	Cómo se mide
Tiempo total de ejecución del inventario	3–5 h (estimado)	Reducción ≥ 50%	Cronometraje en prueba piloto, ≥2 sesiones reales
Errores de consolidación	5–15 por sesión (estimado)	Cero (proceso automático)	Conteo de discrepancias en la consolidación piloto vs. método manual
Tiempo de carga de ajustes en QUICK POS	30–60 min manual (estimado)	< 2 min (vía API)	Medición del lapso emisión de remitos en piloto
Trazabilidad del proceso	Ninguna	Registro completo por auditor, ítem y sesión	Verificación de existencia de registro digital por hallazgo
Satisfacción del equipo auditor	Por medir (encuesta previa)	Mejora significativa	Encuesta pre/post piloto

Scope¶

MVP — lo mínimo para probar la hipótesis en una sesión de auditoría real, de punta a punta:

Autenticación SSO corporativa restringida a @zavidoro.com.py, con whitelisting de usuarios habilitados.
Panel de administración: gestión de tiendas (incluye datos de conexión por tienda) y de usuarios habilitados.
Selección de tienda y creación/incorporación a una sesión de auditoría (una sola sesión activa por tienda; múltiples auditores por sesión).
Carga y procesamiento del Excel comparativo generado por el RFID, con cálculo de diferencias y agrupación por división de producto.
Distribución digital de ítems a buscar entre los auditores de la sesión.
Vista de búsqueda física por auditor: registro de hallazgos, cantidad encontrada y observación por ítem.
Conciliación: cálculo de la diferencia final por ítem y agrupación por tipo de ajuste.
Integración con QUICK POS: generación automatizada de RemitoEgreso y RemitoIngreso vía API, una llamada por tipo de ajuste.
Firma digital del encargado de tienda y presentes (canvas), vinculada a la sesión.
Reporte de cierre en PDF con detalle de ajustes y comprobantes, enviado por correo a TODOS los firmantes.
Dashboard gerencial de métricas por tienda y sesión.

Out of scope (explícitamente no se construye, aunque se pida):

Reemplazo o modificación del proceso de lectura RFID — sigue siendo del proveedor externo; Qaudit consume su Excel.
Consulta de stock en tiempo real contra QUICK POS (ConsultaGral) — el stock de BAS llega en el Excel; no se reconsulta.
Cualquier operación de QUICK POS fuera de egresos/ingresos de ajuste — fuera de alcance por límite del proyecto.
Integración con sistemas de terceros distintos a QUICK POS — fuera de alcance.
Firma electrónica avanzada/cualificada con valor jurídico ante terceros — la firma canvas es evidencia de conformidad interna (firma electrónica simple, Ley N° 6822/2021).
Automatización de la lógica de "despacho" por temporada — se difiere; valor por defecto FAL26 hasta que negocio defina la regla (no bloqueante).

Delivery Milestones¶

#	Milestone	Outcome (cambio visible para el usuario)	Status	Plan
1	Acceso y administración	Un auditor inicia sesión con su cuenta corporativa y solo entra si está habilitado; el admin gestiona tiendas y usuarios	in-progress	docs/plans/qaudit.plan.md
2	Sesión y carga del Excel	Un auditor selecciona tienda, abre/se une a la sesión y carga el Excel RFID viendo las diferencias ≠ 0 por división	pending	—
3	Distribución y búsqueda física	Los auditores reciben ítems asignados y registran hallazgos, cantidades y observaciones desde su dispositivo en tienda	pending	—
4	Conciliación e integración QUICK POS	El sistema calcula los ajustes finales y emite los remitos de egreso/ingreso en QUICK POS automáticamente	pending	—
5	Firma y reporte de cierre	El encargado firma en pantalla y el reporte PDF de cierre se genera y envía por correo	pending	—
6	Dashboard gerencial	Visualización de métricas de auditoría por tienda y sesión	pending	—
7	Prueba piloto comparativa	Validación en ≥2 sesiones reales contra la línea base (OE1) con las métricas de §Success Metrics	pending	—

Open Questions¶

[ ] Schema real del Excel RFID: definir las columnas exactas del archivo crudo (no el modificado por el equipo), incluyendo cómo viene codificada la división (apparel / equipment / footwear). Marcado como bloqueante en el relevamiento; "en camino" al cierre del chat. Confirmar antes de construir el parser (Milestone 2).
[ ] Catálogo de conceptos en QUICK POS: confirmado AJU como concepto de ajuste y que "mal entallado" va en el mismo remito que los faltantes (con observación por ítem). Validar que no requiera un concepto distinto en algún caso.
[ ] RemitoIngreso — origen: se usará S (sin origen) provisionalmente; pendiente confirmación de quien configura el QUICK POS de la tienda.
[ ] Lógica de despacho por temporada: por defecto FAL26; negocio debe definir la regla de agrupación por temporada+año (y el manejo de >3 años) para una mejora posterior.
[ ] Criterio de distribución de ítems: la segmentación principal es por división (un auditor por rubro). Falta definir si el reparto dentro de una división es automático (equitativo) o manual.
[ ] Formato/plantilla del reporte de cierre: confirmar si existe una plantilla preexistente que Nike espere respetar.
[ ] Detección de conectividad a la red de tienda: el SSID no es accesible desde el navegador; se usará un probe HTTP al QUICK POS de la tienda con mensaje no categórico ("podría ser la red"). Confirmar endpoint de health.

Risks¶

Riesgo	Probabilidad	Impacto	Mitigación
Sin Excel crudo, el parser se construye sobre supuestos y hay que rehacer la capa de procesamiento	Media	Alto	Conseguir el archivo real antes del Milestone 2; bloquear esa milestone hasta tenerlo
Línea base son estimaciones, no medidas → la mejora no es demostrable cuantitativamente	Media	Alto	Ejecutar OE1 (medición de línea base) y encuesta previa antes del piloto
Acceso al entorno on-premise de QUICK POS de la tienda piloto no está bajo control del proyecto	Media	Alto	Coordinar disponibilidad temprano; tener una tienda alternativa; validar conectividad VPN antes del piloto
Comportamiento real de la API (autogeneración de `Numero`, `origen`, sincronía) difiere del Swagger	Baja	Medio	Probar contra un QUICK POS real con cuenta de servicio antes de la integración final (Milestone 4)
Conceptos/`despacho` mal mapeados generan remitos incorrectos en producción	Baja	Alto	Validar con quien opera QUICK POS; revisar lista de ajustes antes de aplicar; trazabilidad ítem→remito
Relevamiento fragmentado (info revelada en capas) deja requisitos ocultos	Media	Medio	Sesión de relevamiento estructurada con cuestionario antes de cerrar cada milestone dependiente del negocio

Status: DRAFT — solo requisitos. Planificación de implementación pendiente vía /plan. Decisiones técnicas ya acordadas (stack, modelo de datos, mecánica de integración) están registradas en el RFC (docs/rfcs/RFC-0001-qaudit-arquitectura.md) y los planes, no en este PRD.