Comandero (terminal de mano)

El comandero es un M5Stack Cardputer (una calculadora de bolsillo con teclado y pantalla) que vende contra Agapanto sin computador: busca productos con el teclado, elige cliente o mesa y cobra. Guarda el catálogo y los clientes en su tarjeta microSD, así que busca al instante, y si se cae el Wi-Fi sigue vendiendo: las ventas quedan en cola y se envían solas al volver la conexión.

Cada venta se convierte en una factura normal de Agapanto, a nombre del usuario que el comandero tiene asignado.

Qué se necesita

• El módulo Comandero activo en la empresa (flag COMANDERO).
• Para administrarlo: el permiso CONFIG_CREDENCIALES.
• El usuario a cuyo nombre vende el comandero necesita ACCESO_POS y no puede tener ACCESO_SOLO_RED_POS.
• Una tarjeta microSD en FAT32 dentro del Cardputer (las de más de 32 GB suelen venir en exFAT; hay que formatearlas).
• El Cardputer con el firmware del comandero (arranca directo en la app; el Wi-Fi se elige ahí mismo, ver Wi-Fi).

Vincular un comandero

1. En Agapanto: Configuración → Comanderos → Nuevo comandero. Ponle un nombre (p. ej. Caja 1), elige el usuario con el que vende y, si quieres, el documento y la forma de pago por defecto.
2. Aparece un código de 6 dígitos que vale 10 minutos y sirve una sola vez.
3. Enciende el Cardputer. La primera vez pide la red Wi-Fi; luego escribe la dirección del servidor (por defecto https://agapanto.com.co), Enter, escribe el código y Enter.
4. Dice Vinculado como Caja 1 y descarga el catálogo y los clientes. La barra de arriba muestra el avance (cat 3/14, luego cli 1/2).

Desde la misma pestaña puedes generar otro código (para cambiar de equipo o volver a vincular), revocarlo (se desconecta al instante y deja de vender) o eliminarlo. Las facturas que registró se conservan.

La pantalla

La pantalla tiene dos vistas y se alterna entre ellas con Space (cuando no hay nada escrito).

● Caja 1

Mesa: M1

$12.500

3 productos 5 und

+1 Café tinto (2)

> _

● Caja 1$12.500

2 Café tinto$5.000

1 Pan de bono$2.500

2 Jugo natural$5.000

Mesa: M1

> _

Izquierda: vista Total (la de siempre). Derecha: vista Detalle, con la línea seleccionada resaltada.

• Barra superior: el punto indica la conexión (verde en línea, amarillo conectando, rojo sin conexión), el nombre del comandero, ^2 si hay 2 ventas esperando envío y, en la vista detalle, el total.
• Total: cliente o mesa elegidos, el total grande y cuántos productos y unidades lleva.
• Detalle: una línea por producto con su subtotal.
• Línea de aviso: confirma lo que acaba de pasar (+1 Café tinto, Factura #64 $154.502, errores).
• Línea de entrada: lo que escribes. Con fondo azul (cliente>) estás buscando clientes.

El total es una estimación

El comandero suma los precios guardados en la SD. El total oficial lo calcula Agapanto con los impuestos y llega en la confirmación (Factura #64 $154.502).

Teclas del Cardputer que conviene conocer

El teclado es pequeño, así que varias teclas se consiguen con Fn:

Tecla	Cómo se pulsa
Esc	Fn+` (Fn + la tecla de arriba a la izquierda, rotulada esc). En el cobro, el menú y las listas basta esa tecla sola.
Flecha arriba / abajo	Fn+; / Fn+.
Borrar	del
Menú	Opt
Menú (otra forma)	botón G0 (el de arriba, fuera del teclado)

Vender: buscar y agregar productos

Teclas	Acción
escribir	Busca por código o por nombre (sin importar tildes ni mayúsculas). Se pueden escribir varios pedazos separados por espacio, en cualquier orden: cas ind o ind cas encuentran Castaño de Indias. Una sola palabra corta también vale como iniciales: cdi. Los resultados salen ordenados por relevancia: código exacto, comienzo del nombre, palabras completas y en el orden escrito, favoritos y nombres más cortos primero. Bajo la lista se ve el nombre completo del resaltado (útil cuando varios empiezan igual).
Enter	Agrega el producto cuyo código coincide exacto; si no, el resultado resaltado. Luego vuelves a la vista en la que estabas.
número antes del texto	Cantidad: 3cafe (o 3*cafe, o 3 cafe) + Enter agrega 3 unidades. Acepta decimales (0.5queso). Si el texto completo es un código que empieza por números (3M01), se toma como código; y si con la cantidad no hay resultados (7up), se busca el texto completo.
Fn+; / Fn+.	Mover el resaltado en los resultados. Sin texto escrito, cambia la línea seleccionada del carrito.
Fn+` (Esc)	Borra lo escrito. Sin texto: la primera vez avisa, la segunda anula la cuenta (como "cancelar" en el POS).
Space (sin texto)	Alterna Total ↔ Detalle.

Corregir el carrito

Sin nada escrito, estas teclas actúan sobre la línea seleccionada (la última que agregaste, o la que elijas con las flechas):

Teclas	Acción
= o +	Suma 1 unidad.
-	Resta 1 unidad; en 0 quita la línea.
del	Quita la línea.

En la vista Total no ves las líneas, pero la línea de aviso dice qué se cambió (2 Café tinto, Quitado: Pan de bono).

Cuentas abiertas: un pedido por cliente o mesa

Cada cliente o mesa tiene su propia cuenta, y puedes llevar varias a la vez: elegir otro cliente cambia de cuenta (no le pasa los productos). La cuenta es la misma prefactura del POS: si la mesa 3 ya tiene un pedido abierto en una caja, el comandero abre ese mismo pedido, y lo que agregues desde el comandero aparece en el POS al instante (y al revés).

• CLIENTE GENERAL (el cliente por defecto) es una cuenta propia de cada comandero: nunca toma el pedido de un cajero.
• Al cobrar una cuenta, el comandero vuelve a la del cliente por defecto.
• Las cantidades son enteras (como en el POS).
• Si mientras cobras alguien cambió esa cuenta en el POS, el cobro no se hace y avisa La cuenta cambió: revisa y vuelve a cobrar.

Teclas	Acción
`	Cambia la búsqueda entre Productos y Clientes (la entrada se pone azul). Sin escribir nada muestra las cuentas abiertas con su total; la que tienes abierta sale en azul.
Up / Down + Enter (sin texto)	Abre la cuenta resaltada.
escribir + Enter	Busca por nombre o NIT y abre la cuenta de ese cliente.
un número	Si la empresa tiene mesas, abre directamente esa mesa (la mesa M1 o Mesa 1 es la 1).
del (sin texto)	Vuelve a la cuenta del cliente por defecto.
Fn+` (Esc) o `	Regresa a productos sin cambiar nada.

Mesas de dos cifras

Si existen la mesa 1 y la 12, al teclear 1 el comandero espera un instante por si viene otro dígito. Para elegir la 1 sin esperar, pulsa Enter.

Atajos de productos

Teclas	Acción
Alt+A … Alt+Z	Asigna a esa letra el producto resaltado en la búsqueda (o la línea seleccionada del carrito).
Fn+A … Fn+Z	Agrega el producto asignado a esa letra.

Los atajos se guardan en el propio comandero, así que cada equipo tiene los suyos.

Cobrar

Teclas	Acción
Tab o Fn+Enter	Abre el cobro (desde la venta).
Tab / flechas	Cambia la forma de pago. La primera es la predeterminada del comandero.
dígitos	Lo que entregó el cliente; muestra el cambio. Sin dígitos se cobra el valor exacto.
Enter	Registra la venta.
Ctrl+Enter	Registra la venta pagada completa de una vez, sin teclear lo recibido.
` o Fn+` (Esc)	Vuelve a la vista Detalle para agregar o quitar productos.

Al confirmar suena un tono y aparece Factura #N con el total oficial. La cuenta se cierra (en el POS también) y vuelves a la cuenta del cliente por defecto.

Menú (Opt)

Opción	Para qué
1 Recargar catálogo y clientes	Descarga todo de nuevo (normalmente no hace falta: los cambios de productos y precios llegan solos).
2 Reintentar envíos	Fuerza el envío de las ventas en cola.
3 Ventas rechazadas	Lista las ventas que Agapanto no aceptó y el motivo.
4 Servidor / vincular	Cambia la dirección del servidor: Enter la guarda sin volver a vincular; Tab pide un código nuevo.
5 Wi-Fi	Elegir o cambiar la red (ver abajo).
6 Info	Red y señal, IP, servidor, estado, productos y clientes, cola, memoria, batería. Con Up/Down se recorre la lista.

Opt, ` o Fn+` cierra el menú.

Ahorro de batería

Si no se toca ninguna tecla, la pantalla baja el brillo a los 45 segundos y se apaga al minuto. La red sigue conectada: las ventas en cola se envían y el catálogo se actualiza con la pantalla apagada. Cualquier tecla (o el botón G0) la enciende de nuevo; esa primera tecla solo enciende, no escribe ni agrega nada.

Wi-Fi

El comandero recuerda hasta 5 redes y se conecta solo a la más fuerte que tenga a la vista. La pantalla Wi-Fi (menú 5, o sola la primera vez) lista las redes cercanas con su señal y un candado si piden contraseña; las guardadas dicen guardada y la actual conectada.

Tecla	Hace
Up / Down	Elegir red
Enter	Conectar. Si es nueva y tiene candado, pide la contraseña (Tab la muestra u oculta).
r	Buscar redes otra vez
f	Olvidar la red guardada resaltada
h	Red oculta: escribir el nombre (SSID) a mano
Esc	Volver

Si la contraseña está mal lo dice (Contraseña incorrecta) y la red no se guarda; solo se guarda cuando conecta.

Sin conexión

Cada cambio a una cuenta (agregar, quitar, anular, cobrar) se guarda primero en la microSD y después se envía. Si no hay conexión:

• Queda en cola (^3 en la barra = 3 cambios pendientes) y el comandero sigue trabajando con el catálogo y el último estado conocido de cada cuenta.
• Al volver la conexión se envían en orden, uno por uno.
• Si algo se envía dos veces (por ejemplo, se cortó justo antes de la confirmación), Agapanto lo reconoce y no lo aplica dos veces ni crea otra factura.
• Si Agapanto rechaza un cambio (la cuenta ya se cobró o se anuló en el POS, producto borrado…), sale de la cola y queda en Menú → 3 con el motivo; la cuenta se vuelve a cargar tal como está en Agapanto.

Los cambios de productos y precios hechos en Agapanto llegan al comandero en pocos segundos. Los clientes nuevos llegan cuando el comandero se reconecta, o con Menú → 1.

Problemas frecuentes

«Inserta una microSD (FAT32)» con la tarjeta puesta

La tarjeta está en exFAT (típico en las de 64 GB o más). Formatéala en FAT32 desde un computador y vuelve a abrir la app.

«sin_conexion ESP_ERR_HTTP_CONNECT» al vincular

El Cardputer no llega al servidor. Revisa la dirección (los dos puntos : se escriben con Shift+;) y que el Wi-Fi sea el correcto: la IP del Cardputer aparece abajo en la pantalla de vinculación. Algunos routers aíslan los equipos Wi-Fi entre sí; con un servidor en la misma red local, conéctalo por cable o desactiva el aislamiento.

«Código inválido o vencido»

El código dura 10 minutos y sirve una vez. Genera otro en Configuración → Comanderos.

«Comandero revocado en Agapanto»

Alguien lo revocó o se vinculó en otro equipo. Genera un código nuevo y vuelve a vincular desde Menú → 4 → Tab.