24 de abril de 2026

Manual guiado de Ballista

Estructura de aprendizaje para usar Ballista de principio a fin: orientación, datos base, pedidos, tareas, inventario, facturación, reportes, usuarios y soporte.

Este manual organiza la wiki como un recorrido de uso de Ballista. La idea no es leer pantallas sueltas, sino aprender la app como la usaría un negocio real: primero entender el mapa, después preparar datos base, luego operar pedidos, coordinar tareas, controlar inventario, facturar, revisar indicadores y administrar usuarios y configuración.

La app tiene muchas pantallas, pero el hilo conductor es simple:

El negocio configura datos base.
Ventas crea una orden.
La orden consume o reserva inventario.
El equipo coordina tareas.
Facturación emite documentos electrónicos.
Reportes convierten lo ocurrido en decisiones.
Usuarios, permisos y configuración mantienen el sistema seguro.

Cómo usar este manual

Si eres...	Empieza por	Objetivo
Persona nueva en Ballista	`Ruta 0: orientación`	Entender navegación, Inicio, permisos y vocabulario.
Ventas u operaciones	`Ruta 2: pedidos y seguimiento`	Crear pedidos, revisar detalle y coordinar tareas.
Inventario/producción	`Ruta 3: inventario y productos`	Entender materias primas, lotes, productos compuestos y consumo.
Administración/facturación	`Ruta 4: facturación electrónica`	Configurar FE, emitir, revisar historial y corregir errores.
Gerencia	`Ruta 5: indicadores y decisiones`	Leer ingresos, margen, clientes, conversión, caja y riesgo.
Administración del sistema	`Ruta 6: usuarios, roles y configuración`	Controlar acceso, perfiles, configuración y soporte.

No hace falta leer todo en una sola sesión. El manual está pensado como capacitación progresiva y como referencia cuando alguien se bloquea.

Mapa de la app

Área	Rutas principales	Qué se aprende
Inicio	`/`, `/dashboard`, `/home`	Leer alertas, accesos, pendientes, tareas, pedidos y actividad.
Operación comercial	`/orders`, `/orders/{id}`, `/order-detail`	Crear, buscar, editar, revisar y cerrar pedidos.
Seguimiento	`/tasks`, `/tasks/{id}`	Convertir pendientes en tareas asignadas, notas, calendario y notificaciones.
Inventario	`/materia_prima`, `/lote_producto`, `/producto_compuesto`, `/producto_compuesto_variacion`	Materias primas, lotes, inventario disponible, fórmulas y variantes vendibles.
Cotización	`/cotizador`	Probar productos/lotes antes de comprometer una venta.
Clientes y terceros	`/clientes`, `/clientes_secundarios`, `/mascotas`, `/suppliers`, `/supplier-contacts`	Mantener datos de clientes, dependientes, mascotas, proveedores y contactos.
Catálogos	`/impuestos`, `/unidades`, `/tipos`, `/lineas_producto`	Definir impuestos, unidades, tipos y líneas usadas por pedidos, inventario y reportes.
Facturación	`/billing`, `/billing/historial`, `/billing/configuracion`	Emitir factura electrónica, revisar historial y configurar Hacienda/certificado.
Reportes	`/reports`	Leer indicadores, ventas, costos, clientes, materiales, productos y descargas.
Cuenta y seguridad	`/profile`, `/users`, `/roles`, `/settings`, `/cambiar_contrasena`	Perfil, usuarios, roles, permisos, preferencias y configuración general.
Superadministración	`/admin/tenants`	Administrar organizaciones cuando aplica.

Ruta 0: orientación inicial

Objetivo: que la persona entienda dónde está y que puede hacer antes de tocar datos.

Leccion	Pantalla	Qué debe aprender
0.1 Entrar al sistema	`/login`	Usuario, contraseña, recuperación y sesión.
0.2 Leer Inicio	`/` o `/dashboard`	Inicio no es donde se hace todo; es donde se decide qué módulo necesita atención.
0.3 Entender navegación	Menú lateral/superior	Diferencia entre Operación, Catálogos, Facturación, Reportes y Administración.
0.4 Reconocer permisos	Cualquier módulo	Si un botón no aparece o está deshabilitado, puede faltar permiso.
0.5 Usar ayuda contextual	`Ayuda de este flujo`	Abrir ayuda de la pantalla antes de reportar un problema.

Al cerrar esta ruta, la persona debería poder ubicar el módulo correcto: pedidos para vender, configuración de facturación para datos fiscales o permisos cuando una acción no aparece.

Ruta 1: datos base antes de operar

Objetivo: preparar los datos que hacen posible vender, producir y facturar sin improvisar.

Orden recomendado	Pantalla	Por qué va antes
1	`/impuestos`	Los impuestos afectan líneas de pedido, materias primas y facturación.
2	`/unidades`	Las unidades afectan inventario, fórmulas y conversiones.
3	`/tipos`	Los tipos clasifican pedidos, tareas o registros según configuración.
4	`/lineas_producto`	Las líneas permiten filtrar pedidos, productos y reportes.
5	`/clientes`	Una orden necesita cliente; una factura necesita receptor correcto.
6	`/clientes_secundarios` o `/mascotas`	Dependientes o mascotas si el negocio los usa.
7	`/suppliers` y `/supplier-contacts`	Proveedores y contactos para compras, referencias o trazabilidad.

Antes de crear pedidos conviene revisar los datos base. Un pedido necesita clientes, impuestos, productos, inventario y catálogos para avanzar sin correcciones innecesarias.

Ruta 2: pedidos y seguimiento

Objetivo: recorrer el flujo comercial completo: solicitud del cliente, pedido, detalle, tarea y estado.

Paso	Pantalla	Guía profunda
2.1 Buscar pedidos	`/orders`	Pedidos y ventas
2.2 Crear orden	`Crear pedido` en `/orders`	Pedidos y ventas
2.3 Revisar detalle	`/orders/{id}`	Pedidos y ventas
2.4 Crear seguimiento	`Incluir tarea` o `Nueva tarea`	Tareas
2.5 Dar seguimiento	`/tasks`	Tareas
2.6 Volver al pedido	`Abrir pedido` desde tarea	Tareas

Lo que la persona debe dominar

Tema	Debe poder explicar
Requisitos de una orden	Cliente, fecha prometida, líneas, lote/producto compuesto, impuesto y inventario disponible.
Estados	Pendiente, en proceso, pagado, cancelado, completado/entregado según módulo.
Inventario	Una orden completa puede reservar/rebajar lotes.
Tareas	Una orden puede crear tareas para que el trabajo no quede en memoria.
Facturación	Una orden lista puede pasar a `Facturar este pedido`.

Ruta 3: inventario y productos

Objetivo: entender de dónde sale lo que se vende.

Paso	Pantalla	Qué aprender
3.1 Materias primas	`/materia_prima`	Qué existe como insumo base, impuesto, costo y unidad.
3.2 Lotes	`/lote_producto`	Cantidad disponible, vencimiento, inventario disponible y trazabilidad.
3.3 Productos compuestos	`/producto_compuesto`	Fórmula/receta que consume materias primas.
3.4 Variantes	`/producto_compuesto_variacion`	Presentaciones vendibles con precio y datos comerciales.
3.5 Cotizador	`/cotizador`	Simular una venta antes de crear pedido formal.
3.6 Reportes de inventario	`/reports`	materiales principales, conflictos, inventario en CSV y costos.

Lo que debe quedar claro

Concepto	Explicación simple
Materia prima	Lo que el negocio compra o mantiene como insumo.
Lote	Existencia concreta con cantidad disponible y trazabilidad.
Producto compuesto	Producto preparado desde una fórmula.
Variante	Presentación vendible del producto compuesto.
Reserva/rebaja	Cuando una orden consume inventario disponible, el lote baja disponibilidad.
Conflicto	El sistema no puede cumplir cantidad porque inventario disponible o fórmula no alcanza.

Guía profunda: Inventario y producción.

Ruta 4: facturación electrónica

Objetivo: entender qué significa emitir documentos electrónicos y qué se debe configurar antes.

Paso	Pantalla	Qué aprender
4.1 Configurar emisor	`/billing/configuracion`	Datos fiscales del negocio, ambiente y perfil.
4.2 Cargar certificado	`/billing/configuracion`	Certificado `.p12` y PIN donde corresponda.
4.3 Revisar receptor	`/clientes` y Facturación	Datos fiscales del cliente.
4.4 Emitir	`/billing`	Crear, simular o enviar documento electrónico.
4.5 Venir desde pedido	`/orders/{id}` -> `Facturar este pedido`	Usar líneas reales del pedido.
4.6 Auditar	`/billing/historial`	Ver XML/PDF, estado, errores y evidencia.

Lo que debe quedar claro

Concepto	Explicación
Factura electrónica	Documento fiscal digital que debe cumplir estructura, firma y validación.
Certificado `.p12`	Archivo usado para firmar/autenticar según configuración fiscal.
PIN	Clave del certificado. Debe configurarse con cuidado.
Ambiente	Pruebas o producción real.
Emisor	El negocio que factura.
Receptor	Cliente que recibe el comprobante.
Historial	Lugar para auditar documentos ya emitidos o fallidos.

Guía profunda: Facturación y control.

Ruta 5: indicadores y decisiones

Objetivo: aprender a leer el negocio, no solo ver números.

Paso	Pantalla	Guía profunda
5.1 Resumen operativo	`/reports`, pestaña de resumen operativo	Reportes e indicadores
5.2 Indicadores de clientes	`/reports`, pestaña de crecimiento de clientes	Reportes e indicadores
5.3 Exportar evidencia	`Descargas de Excel`	Reportes e indicadores
5.4 Convertir hallazgos en tareas	`/tasks`	Tareas

Lectura recomendada

Si ves...	Pregunta	Acción
Ingresos sube	¿Se cobró y dejó margen?	Revisar flujo de caja, cuentas por cobrar y margen.
Conflictos de inventario suben	¿Ventas está prometiendo más de lo que inventario soporta?	Revisar lotes, materiales principales y fórmulas.
Recompra baja	¿Los clientes no están regresando?	Crear seguimiento comercial.
Cuentas por cobrar suben	¿Hay ventas sin cobro?	Revisar clientes y antigüedad de cobro.
Concentración de clientes sube	¿Dependemos de pocos clientes?	Diversificar o cuidar cuentas clave.

Ruta 6: usuarios, roles, perfil y configuración

Objetivo: operar con seguridad y soporte.

Pantalla	Qué enseñar
`/profile`	Datos del usuario, acceso rápido a configuración y cuenta.
`/cambiar_contrasena`	Cambio seguro de contraseña.
`/users`	Crear/editar usuarios, revisar estado y acceso.
`/roles`	Definir permisos por rol.
`/settings`	Preferencias generales y accesos a configuración importante.
`/admin/tenants`	Administración multi-organización para superadministración.

Principio de seguridad

Un usuario no debe tener más permisos de los necesarios. Si alguien solo revisa tareas, no debería poder emitir facturas. Si alguien solo factura, no necesariamente debe editar inventario. Los permisos ayudan a que los errores sean menos probables y más fáciles de auditar.

Manual por flujo completo

Flujo A: venta normal con inventario y factura

Crear cliente en /clientes.
Verificar impuestos/unidades/catálogos.
Revisar inventario en /materia_prima y /lote_producto.
Crear pedido en /orders.
Agregar líneas desde lote o producto compuesto.
Confirmar que no haya conflicto de inventario.
Crear tarea de preparación si aplica.
Abrir /orders/{id}.
Revisar líneas, lotes, totales y estado.
Usar Facturar este pedido.
Emitir desde /billing.
Revisar /billing/historial.
Leer impacto en /reports.

Flujo B: pedido con seguimiento interno

Crear pedido.
Activar Incluir tarea en el asistente o crear Nueva tarea desde detalle.
Ir a /tasks.
Cambiar responsable o asignados.
Agregar nota con decisión o bloqueo.
Cambiar estado a in_progress.
Resolver el trabajo.
Marcar done.
Volver al pedido si necesita facturación o cierre.

Flujo C: problema de inventario

Detectar conflicto en pedido o reportes.
Revisar lote en /lote_producto.
Revisar materia prima en /materia_prima.
Si es producto compuesto, revisar fórmula en /producto_compuesto.
Revisar variantes en /producto_compuesto_variacion.
Crear tarea para compras/producción si hay faltante.
Ajustar promesa de entrega en pedido.
Revisar indicador Conflictos de inventario en /reports.

Flujo D: cierre semanal de gerencia

Entrar a /reports.
Elegir rango semanal.
Revisar ingresos, costs, margen/profit, pedidos pagados.
Revisar flujo de caja y cuentas por cobrar.
Revisar repeat rate, active customers y new vs lost.
Revisar conversión y frecuencia de compra.
Revisar productos principales, materiales principales e conflictos de inventario.
Revisar e-invoice operations y historial de facturación.
Convertir hallazgos en tareas.

Estructura recomendada para completar la wiki

Las páginas profundas disponibles:

Estado	Página	Cobertura
Completa	Pedidos y ventas	Pedidos, creación, detalle, inventario, tareas y factura.
Completa	Tareas	Centro, Tablero, Calendario, detalle, notas y notificaciones.
Completa	Inventario y producción	Materias primas, lotes, productos compuestos, variantes, costos, conflictos y trazabilidad.
Completa	Facturación y control	Configuración FE, emisor, receptor, ambiente, emisión, errores e historial.
Completa	Reportes e indicadores	indicadores, fórmulas, lectura, riesgos y acciones.

Páginas que conviene ampliar después:

Prioridad	Página	Qué falta
Media	Datos base y catálogos	Clientes, dependientes, proveedores, impuestos, unidades, tipos y líneas de producto.
Media	Usuarios y permisos	Usuarios, roles, profile, configuración y organización admin.
Media	Inicio/panel principal	Alertas, desglose, menú principal, calendario y actividad global.
Media	Arquitectura de contenido	Criterios editoriales, enlaces internos, estructura y bitácora de mantenimiento.
Baja	Cambios seguros/adopción	Mantener ejemplos vivos de soporte, experiencia de usuario y lanzamiento.

Plantilla para cada página del manual

Cada página educativa debería tener esta estructura:

Sección	Contenido
Objetivo	Qué problema de negocio resuelve la pantalla.
Ruta	URL exacta y variantes.
Antes de usar	Datos previos necesarios.
Estructura visual	Qué se ve en cada bloque.
Botones	Qué hace cada acción real.
Flujo principal	Pasos de principio a fin.
Validaciones	Qué errores bloquean el flujo.
Datos guardados	Qué tablas/áreas cambia.
Relación con otros módulos	Qué depende de qué.
Notificaciones	Qué alertas se crean y dónde aparecen.
Problemas comunes	Causas y dónde revisar.
Para soporte	Qué información incluir al reportar.
Calidad editorial	Título, excerpt, intención clara, enlaces internos y ejemplos naturales.

Esta plantilla evita que la wiki vuelva a ser una lista de pantallas. Cada página debe enseñar una habilidad operativa.

Glosario mínimo

Término	Significado
Organización	Empresa/entorno de datos dentro de Ballista.
Pedido	Registro comercial-operativo que indica cliente, líneas, cantidades, estado y fechas.
Línea	Item dentro de un pedido. Puede venir de lote o producto compuesto.
Lote	Existencia concreta de materia prima/producto con cantidad disponible.
Producto compuesto	Producto construido desde componentes/fórmula.
Variante	Presentación vendible de un producto compuesto.
Task	Pendiente asignado con responsable, estado, prioridad, fecha y notas.
Owner	Responsable principal de una tarea.
Assignee	Usuario colaborador asignado a una tarea.
Factura electrónica	Documento fiscal digital emitido desde Facturación.
indicador	Indicador clave conectado a objetivo de negocio.
Diagnóstico	Métrica que ayuda a investigar, aunque no siempre sea indicador principal.

Resumen

Si la wiki va a funcionar como manual de usuario, debe enseñar la app por recorridos, no por pantallas aisladas. La estructura recomendada es: orientación, datos base, pedidos, tareas, inventario, facturación, reportes y administración. Cada página profunda debe explicar objetivo, prerrequisitos, botones, flujo, validaciones, datos guardados, conexiones, notificaciones y soporte.