Usa el contrato revisado de mutación de pedidos
La mutación de pedidos de Driver es una transición de estado autorizada por el servidor, no una pulsación de botón ni asignación de estado del lado del cliente. Las actualizaciones de uno o varios pedidos, decisiones de asignación, medios, ubicación, motivos, ETA, efectos de cola y acciones posteriores deben permanecer separados.
La navegación, un aviso, un pedido devuelto, una vista previa de imagen, una comprobación de ubicación, un evento socket o un agregado de integrantes no confirman un cambio duradero del pedido.
Disponibilidad
Los controles de mutación dependen condicionalmente del tipo de pedido/solicitud, estado devuelto actual, propiedad de Driver, configuración del proyecto, permisos, conectividad, carga, bloqueos, contexto de asignación y requisitos visibles.
La visibilidad del control es solo un filtro del cliente. El servicio debe autorizar de manera independiente a Driver, relación con pedido/asignación, transición destino, bloqueo, concurrencia, motivo obligatorio, medios y ubicación.
Requisitos previos
- Vincula la identidad del actor a la sesión autenticada.
- Lee la revisión actual del pedido/asignación inmediatamente antes de mutar.
- Usa un comando de transición tipado en lugar de un valor de estado genérico enviado por el cliente.
- Define motivo/comentario obligatorio, ETA, imagen, ubicación y configuración para cada transición.
- Proporciona estrategia de idempotencia/concurrencia y un recibo de resultado observable.
- Para grupos, identifica explícitamente cada integrante y el resultado esperado por integrante.
Límites de responsabilidad
| Responsable | Responsabilidad |
|---|---|
| Interfaz de Driver App | Presentar controles que parecen elegibles, requisitos, carga y errores sin afirmar autoridad |
| Controlador del cliente | Construir una intención tipada, preservar estado incierto y evitar reintentos a ciegas |
| API de pedidos | Autenticar, autorizar propiedad, bloquear, validar transición/entradas y producir recibo durable |
| API de asignación | Controlar las decisiones de aceptar/rechazar una asignación por separado del estado del pedido |
| Servicios de medios/ubicación | Validar/guardar solo tras autorización y limpiar ante fallos |
| Coordinador de grupos | Devolver un resultado por integrante; nunca ocultar resultados parciales |
| Servicios posteriores | Historial, mensajes, informes, cola, logística, sockets, notificaciones, correo, webhooks, trabajos y plugins |
| Despachador/operador | Conciliar resultados inciertos, en conflicto o parciales |
Entradas y resultados
Las entradas de un pedido pueden incluir transición prevista, motivo/comentario, ETA, posición de entrega, ubicación candidata, imagen y revisión del pedido. Los requisitos varían según transición/configuración; el cliente por sí solo no determina un grafo completo de estados anteriores/nuevos.
El contrato de resultado debe distinguir:
- solicitud rechazada antes de cualquier efecto;
- escritura de pedido aceptada;
- escritura de medios/ubicación aceptada o limpiada;
- acciones posteriores completas, parciales o fallidas;
- revisión actual del pedido devuelta; y
- clasificación de reintento seguro/duplicado.
Una mutación agrupada es un conjunto de actualizaciones de integrantes autorizadas independientemente. La agregación actual del cliente puede devolver null para integrantes fallidos y ocultar el éxito parcial. Un contrato seguro devuelve recibos explícitos por integrante y no afirma una reversión atómica.
Seguridad y privacidad
- Autoriza antes de cargar una imagen, escribir ubicación o mutar el pedido.
- Valida en el servidor coordenadas finitas, vigencia, política de simulación, destino, marca temporal y propósito.
- Recorta y valida motivos/comentarios con significado; no aceptes espacios en blanco como prueba de política.
- Mantén los detalles de medios, ubicación, pedido, participantes, token, bloqueo y proveedor fuera de registros/evidencia públicos.
- No trates un PIN del cliente, imagen, control de permisos ni lista local de ubicación como autorización del servidor.
Límites y estados de fallo
| Estado | Interpretación requerida |
|---|---|
| Control visible/habilitado | Solo candidato del cliente |
| Modal de requisitos | Solo comprobación previa local |
| Solicitud cargando | Resultado sin resolver; no reintentar |
| Error devuelto | Puede que medios/ubicación/acciones posteriores anteriores aún requieran limpieza |
| Pedido devuelto | Solo respuesta del pedido, no todas las acciones posteriores |
| Navegación/aviso | Solo presentación del cliente |
| Resultados de grupo mixtos/null | Resultados parciales por integrante |
| Socket/push | Indicación de transporte, no recibo durable |
| Formulario force/recuperación | Rama condicional del cliente, no contrato de servidor garantizado |
El código fuente actual no establece mutaciones exactamente una vez, idempotencia completa, medios/ubicación/pedido/acciones posteriores atómicos, reversión de grupo ni éxito desplegado.
Diagnóstico
El servicio rechaza un control visible
Trata la interfaz y la validación del servidor como aspectos distintos. Actualiza una vez el pedido autorizado y concilia propiedad/bloqueo/configuración; no eludas el control.
Se agota el tiempo de solicitud o cambia la navegación
No repitas. Consulta la revisión actual de pedido/asignación y exige idempotencia/recibo de resultado antes de decidir si el reintento es seguro.
Difiere un integrante del grupo
Registra el resultado de cada integrante y concilia de manera independiente. No informes éxito del grupo a partir de la navegación agregada ni de un subconjunto de tarjetas.
Medios o ubicación tuvieron éxito antes del fallo del pedido
Ejecuta la ruta de limpieza/conciliación aprobada. No supongas reversión; informa por separado las etapas de pedido, medios y ubicación.
Aparece un formulario force
Trátalo como recuperación condicional, no como prueba de que el servidor haya emitido la condición tipada esperada. Exige un contrato de error explícito y revisado.
Guías relacionadas: Usar el contrato de solicitudes logísticas · Usar el contrato de mapas revisado · Aceptar una solicitud de entrega