Saltar a contenido

0011. Agenda propia y ejecución de visitas: check-in sólo hasta hoy y ubicación según el tipo de actividad

Estado: Propuesto; parcialmente reemplazado por ADR 0014 Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): modules/visitas/, shared/ubicacion/, shared/catalogos/ Modificado por: ADR 0014 — sólo para la captura GPS de una ruta manual activa durante la jornada autorizada

Contexto

Las visitas se crean, reprograman y cancelan sólo desde la web (ADR 0029 de fuerza de ventas); en el teléfono el promotor las ejecuta. GET /visitas exige un rango de hasta 62 días, sin paginar, y el alcance de un supervisor incluye a sus supervisados (ADR 0048 de fuerza de ventas). El check-in pasa una visita PLANIFICADA a EN_CURSO, rechaza con 409 una adelantada y exige coordenadas si el tipo de actividad requiere geolocalización; el check-out lleva un estado FINALIZADA elegido (ADR 0031 de fuerza de ventas). La respuesta trae distancia_metros_checkin e is_checkin_fuera_rango, y destino con el nombre que tenían el cliente, el local o el prospecto al registrar la visita (ADR 0065 de fuerza de ventas, propuesto): un CHECK de la base exige la parte de cada id que la visita tiene.

Decisión

  • La agenda es la del promotor de la sesión: GET /visitas con promotor_id propio y el rango de la semana visible (día y semana). Sin crear, reprogramar ni cancelar visitas en la app.
  • Cada visita se nombra con su destino, no cruzándola con la cartera: nombre comercial o, sin él, razón social del cliente (o el nombre del prospecto), y el local debajo si la visita lo tiene. local es null sólo cuando la visita no tiene local. Así la agenda y Mi ruta no dependen de crm-svc-clientes y un cliente transferido conserva su nombre. Los requerimientos se nombran por su visita.
  • Check-in sólo en una visita PLANIFICADA de hoy o atrasada: la app no lo ofrece para días futuros, en lugar de esperar el 409.
  • Ubicación: el permiso se pide en el primer check-in, no al abrir la app. Si el tipo de actividad (cat_tipos_actividad) la requiere y no hay permiso o posición en ~10 s, el check-in se bloquea con una explicación; si no la requiere, se envía cuando se obtiene y se sigue sin ella si no. En el check-out se envía si está a mano.
  • Fuera de rango avisa, no bloquea: si la respuesta marca is_checkin_fuera_rango, se muestra la distancia; la regla es del servidor.
  • Check-out: el promotor elige un estado del tipo FINALIZADA del catálogo y puede dejar observaciones.
  • Horas según el ADR 0004: con conexión sólo utc_offset; la hora del dispositivo se reserva para el modo sin conexión.
  • Un 409 recarga la visita y muestra el motivo: la cancelaron o reprogramaron desde la web, y gana el servidor.
  • Los catálogos de tipos de actividad y estados de visita se cargan al entrar y se guardan en shared/catalogos/.

Alternativas descartadas

  • Mostrar también las visitas de los supervisados — mezcla en la agenda del día trabajo que el promotor no hace; se decide aparte para supervisores.
  • Nombrar las visitas con la lista de clientes de la cartera — tras una transferencia mostraría «fuera de tu cartera» y ataría la agenda a otro servicio.
  • Pedir la ubicación al abrir la app — sin contexto el promotor tiende a negarla, y muchas actividades no la necesitan.
  • Bloquear el check-in fuera de rango en la app — duplica una regla del servidor que todavía está pendiente (geocerca, ADR 0031 de fuerza de ventas).

Consecuencias

  • Una visita creada en la web aparece en el teléfono al refrescar la agenda; no hay avisos push.
  • Sin permiso de ubicación, las actividades que la requieren no se pueden ejecutar: la app explica cómo activarlo en ajustes.
  • La ubicación en segundo plano no se usa para la agenda ni para el check-in. La captura GPS de una ruta manual activa se rige por la excepción acotada del ADR 0014: sólo dentro de la jornada autorizada y con los permisos de plataforma correspondientes.
  • Si la razón social cambia en clientes, la visita muestra la de entonces.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.