Saltar al contenido principal

POS — la ficha del cliente se autocompleta con el documento

En POS › Caja, los datos del cliente se escribían a mano en cada venta. Ahora, al teclear el documento, el POS busca al cliente en sus ventas anteriores y autocompleta nombre, teléfono y correo. Si el documento es nuevo, no bloquea nada: se continúa con los datos que se tengan.

Qué cambió​

  • Búsqueda por documento. A partir de 5 caracteres (con 450 ms de espera) se consulta GET /api/pos/clientes/:documento. La fuente única de clientes es la tabla usuarios (REQ-DAT-02: los clientes de la clínica son filas con rol Cliente veterinaria y comparten tabla con el personal y los clientes del almacén). El documento está cifrado con índice ciego, así que se busca por su huella.
  • La primera compra registra al cliente. Si el documento no existe en usuarios, el cobro lo crea con rol Cliente veterinaria (nombre, teléfono y correo del formulario; si no hay correo se genera uno interno cli-…@sin-correo.local y una contraseña aleatoria, para que la fila cumpla las restricciones sin permitir inicio de sesión). En la segunda compra el POS ya lo encuentra y autocompleta. La venta guarda pos_ventas.id_cliente (FK usuarios, ON DELETE SET NULL) además del snapshot de nombre/teléfono/correo, que no cambia aunque después se edite el cliente (migración 1792730422557).
  • El formulario manda para la factura. El autocompletado solo rellena campos vacíos, así que lo que el cajero escribe se conserva; el correo de la factura es el del formulario (enviarFactura usa dto.correo). El alta del cliente se resuelve antes de la transacción de la venta: si falla, la venta se registra sin enlace y la omisión se audita (POS_CLIENTE_NO_REGISTRADO).
  • Autocompletado sin sorpresas. Solo rellena los campos que faltan; mientras busca muestra «Buscando cliente por documento…», si lo encuentra «Cliente encontrado: …» y si no, «Documento nuevo: complete los datos que tenga».
  • Máscara de teléfono. El campo muestra (300)-123-4567 mientras se escribe y guarda solo los dígitos (10 máximo), reutilizando utils/telefono.ts.
  • Correo válido para enviar la factura. La casilla «Enviar factura por correo» queda deshabilitada hasta que el correo tenga un formato válido; si se invalida, se desmarca sola. El cobro también lo exige y el API valida el formato con @IsEmail.

Archivos clave​

  • ccf-almacen-api/src/domains/pos/pos.service.ts — obtenerClientePorDocumento() (mezcla de los últimos 20 registros de ese documento).
  • ccf-almacen-api/src/domains/pos/pos.controller.ts — GET /api/pos/clientes/:documento.
  • ccf-almacen-web/src/pages/pos.tsx — búsqueda con espera, autocompletado, máscara de teléfono y validación del correo.
  • ccf-almacen-web/src/api/pos.ts — getClientePos().

Cómo verificarlo​

  1. Escribe un documento que ya haya comprado: nombre, teléfono y correo se rellenan.
  2. Escribe un documento nuevo: aparece «Documento nuevo» y puedes continuar.
  3. Con un correo inválido, la casilla de enviar factura no se puede marcar; al corregirlo se habilita.
  4. El teléfono se pinta con la máscara y en la base/venta quedan solo los dígitos.

Actualización 2026-11-11: el formato del correo ya no se valida en el DTO que viaja con la venta en curso (provocaba el aviso «cliente.correo must be an email» mientras se escribía). La comprobación ocurre al cobrar, y solo con dos efectos: enviar la factura y guardar el correo en la ficha del cliente. Ver POS — el cliente se registra al cobrar.