Fix passenger startup and clean tracked generated files

2026-03-31 15:14:12 +02:00
parent c1b9fe666b
commit 5385841a62
5908 changed files with 15305 additions and 872091 deletions
@@ -0,0 +1,119 @@
+# Guia de integracion app: API de estado automatico
+
+## Objetivo
+Este endpoint registra actualizaciones automaticas de estado sin tocar el flujo manual existente.
+
+- Endpoint: `POST /api/trips/:id/auto-status`
+- Auth: `Authorization: Bearer <JWT>`
+- Uso: registrar eventos automaticos en backend y auditoria en BBDD.
+
+## Cuando usar esta API en la app
+Usar esta API cuando el estado se genera automaticamente (por ejemplo, logica de geolocalizacion, reglas de negocio automatas, deteccion de llegada/salida, etc.).
+
+No usar esta API para cambios manuales del conductor desde UI normal de estados; para eso se mantiene `POST /api/trips/:id/status`.
+
+## Reglas funcionales clave
+1. Siempre inserta en `c_cambios_estado` con `actualizado_automaticamente = 1`.
+2. Si se envia `id_punto`:
+   - `id_estado` solo puede ser `3`, `4` o `5`.
+   - ademas actualiza `c_viajes_puntos` con `actualizado_automaticamente = 1` y `borrado_en_app = 0`.
+   - el trigger `trg_c_viajes_puntos_tracking_au` genera auditoria en `c_viajes_puntos_tracking`.
+3. Si NO se envia `id_punto`:
+   - `id_estado` puede ser cualquier estado valido de `t_viaje_estados`.
+   - no toca `c_viajes_puntos`.
+4. No actualiza `c_viajes.id_estado`.
+5. No admite fotos en este endpoint (`fotos_concat`, `foto`, multipart).
+
+## Contrato request
+Ruta:
+`POST /api/trips/:id/auto-status`
+
+Body JSON:
+
+```json
+{
+  "id_estado": 5,
+  "id_punto": 8123,
+  "observaciones": "Cambio automatico por regla GPS",
+  "ind_fallido": 0,
+  "latitud": "40.416775",
+  "longitud": "-3.703790",
+  "fecha_y_hora": "2026-02-17 12:34:56"
+}
+```
+
+Campos:
+- `id_estado` (obligatorio, entero > 0).
+- `id_punto` (opcional, entero > 0).
+- `observaciones` (opcional, string).
+- `ind_fallido` (opcional, default `0`; acepta `0/1`, `false/true`).
+- `latitud` y `longitud` (opcionales; se normalizan y pueden quedar `null`).
+- `fecha_y_hora` (opcional, formato `YYYY-MM-DD HH:mm:ss`; si no es valida se usa hora servidor).
+
+## Respuestas esperadas
+- `200 OK`
+
+```json
+{
+  "success": true,
+  "trip_id": 248230,
+  "id_estado": 5,
+  "id_punto": 8123,
+  "actualizado_automaticamente": 1,
+  "updated_at": "2026-02-18T09:30:00.000Z"
+}
+```
+
+- `400` payload invalido.
+- `401` token ausente/invalido.
+- `403` usuario sin permisos sobre el viaje.
+- `404` viaje no existe o punto no existe.
+- `422` si se envia `id_punto` con `id_estado` fuera de `3/4/5`.
+- `500` error interno.
+
+## Ejemplo rapido de consumo (JavaScript/TypeScript)
+```ts
+async function sendAutoStatus({
+  baseUrl,
+  token,
+  tripId,
+  payload
+}: {
+  baseUrl: string;
+  token: string;
+  tripId: number;
+  payload: {
+    id_estado: number;
+    id_punto?: number;
+    observaciones?: string;
+    ind_fallido?: 0 | 1;
+    latitud?: string;
+    longitud?: string;
+    fecha_y_hora?: string;
+  };
+}) {
+  const response = await fetch(`${baseUrl}/api/trips/${tripId}/auto-status`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify(payload)
+  });
+
+  const body = await response.json().catch(() => ({}));
+
+  if (!response.ok) {
+    throw new Error(`auto-status failed: ${response.status} ${JSON.stringify(body)}`);
+  }
+
+  return body;
+}
+```
+
+## Checklist de integracion en app
+1. Enrutar eventos automaticos a `POST /api/trips/:id/auto-status`.
+2. Si el evento es de punto, enviar siempre `id_punto` y `id_estado` en `3/4/5`.
+3. No enviar fotos en este endpoint.
+4. Tratar `422` como error funcional (payload correcto de forma tecnica, pero regla de negocio invalida).
+5. Mantener endpoint manual actual para interaccion humana.