• RETRASOS LOTT: El contador de 2h en muelle es automático. Las alarmas de parálisis manual/automática van directo a Tráfico (Transflota), NUNCA al cliente final sin revisión.
• RADAR HOS (Reg. CE 561/2006): El servidor audita en bloque asíncrono cada 60 segundos la telemetría de toda la flota. Si un chófer excede las 04:00h de conducción continua, la Control Tower recibe una alarma sonora/visual inyectada vía SignalR para proceder al desvío seguro (parada 45m). Prohibido contactar por móvil durante el parpadeo rojo por distracción grave.
• BÓVEDA IA PLANA: Queda prohibida la arquitectura de carpetas tradicionales. Documentos se listan en un DataGrid masivo filtrable; la IA extrae la metainformación en background.
• CONTROL TOWER: Reutilización obligatoria de Trips.razor. Se conectará vía SignalR a la app móvil para absorber los eventos SOS y Retrasos de los conductores en vivo.

Deploy API (.NET)

cd c:\App\DevuOS\apps\Transflota
python fix_server.py

Deploy Landing Page (Roadmap Cosmos + guía)

cd c:\App\DevuOS\apps\Transflota
python deploy_web.py

Tras editar cosmos_roadmap.js: bump ?v= en el <script> de esta página y fila en web/COSMOS_WEB_CHANGELOG.md. Widget Cosmos: localStorage ci_roadmap_v26 (si el % no cuadra con la web, recarga dura o borra esa clave en DevTools → Application).

Deploy eCMR (Python)

cd c:\App\DevuOS\apps\Transflota
python deploy_ecmr.py

Config Nginx

python fix_nginx.py

Comandos del Servidor

# Logs
journalctl -u transflota-api.service -n 50 --no-pager

# Estado
systemctl status transflota-api.service

# Reiniciar
systemctl restart transflota-api.service

# eCMR logs
journalctl -u ecmr-api.service -n 50 --no-pager

• NUNCA usar --self-contained false para deploy
• SIEMPRE borrar obj/ y bin/ ante cambios de nombre
• SIEMPRE fijar permisos: chown transflota.com_admin:psaserv
• SIEMPRE incluir ConnectionStrings en appsettings del servidor
• NUNCA comandos SSH largos desde el IDE — usar scripts Python
• NUNCA usar [FromForm] con IFormFile (rompe Swagger)
• NGINX editar siempre en /var/www/vhosts/system/transflota.com/conf/
• TERMINAL si se cuelga: ejecutar desde CMD/PowerShell nativo fuera del IDE
• NUNCA ejecutar dotnet build/run/ef desde la terminal de Antigravity — usar PowerShell externo
• SIEMPRE usar CREATE TABLE/INDEX IF NOT EXISTS en migraciones EF que coexisten con raw SQL de arranque
• SIEMPRE mantener la separación de 3 servicios (API / ECMR / WEB) en .antigravity_state.json — nunca mezclar URLs ni configs entre ellos
• NORMA SUPREMA DE ANTIMATERIA: TODO cambio en `js` o `css` EXIGE añadir un cache-buster manual (ej: ``) en el HTML para evitar renders zombies, y DESPLEGAR por fondo. JAMÁS ASUMIR que modificar el archivo local actualiza la web del usuario.

• PAdES-B-LTA: NUNCA pegar imágenes simples. El microservicio Python `ecmr-service` inyecta firmas biométricas con Timestamp Autorizado y bloqueo de modificaciones.
• MERCANCÍA V2 (ADR & TEMP): El backend Pydantic y el cliente C# (MAUI) soportan campos avanzados IRU (Clase ADR, Temperatura, Despacho Aduanas) visibles en Web y App mediante la auditoría in-memory del PDF.
• PLANTILLA 24 CASILLAS: La Guardia Civil Europea solo reconoce el formato estándar IRU. El layout del PDF dibuja estrictamente las posiciones geométricas del documento CMR físico avalado por Cetm/IRU.
• METADATOS DE FIRMA: Las firmas requieren 2 líneas inferiores (Nombre/DNI + GPS/Fecha). El lienzo central de la firma se escalará dinámicamente preservando el `aspect ratio` (24mm de alto) sin deformarse.
• ANEXO SUCESIVO (TRAMOS): Si un viaje sufre un "Cambio de Cabeza", el sistema genera automáticamente un Anexo (Casilla 4b) antes del bloque de firmas. Cuidado con el `footer` dinámico: usar `self.check_page_break()`.

1. Systemd ejecutaba DeltaPlanner.Api viejo

El service apuntaba al DLL viejo. Fix: fix_server.py reescribe el service file siempre.

2. PostgreSQL auth failed

appsettings.json sin ConnectionStrings. Fix: fix_server.py incluye appsettings correcto.

3. Microsoft.OpenApi.dll no cargaba

Publish sin self-contained. Fix: SIEMPRE --self-contained true.

4. Permisos incorrectos en servidor

SFTP sube como root, service corre como transflota.com_admin. Fix: chown automático.

5. DeltaPlanner/WeatherForecast fantasma

Proceso zombie + service viejo + cache obj/. Fix: kill proceso + borrar obj/ + limpiar service.

6. Landing page — botón sin respuesta

hero::before (fondo animado 200%x200%) capturaba clics. Fix: pointer-events:none.

8. Cambios en index.html / JS no se reflejan (terminal o caché)

Los scripts IA pueden bloquearse con SSH desde el IDE. Fix: cmd.exe /c python deploy_web.py > log.txt 2>&1. Los navegadores cachean JS/CSS: tras editar cualquier .js del dashboard, mutar el ?v= en la etiqueta <script src="…"> correspondiente en index.html y desplegar. Los datos de roadmaps viven en las vistas Roadmap Transflota y Roadmap Cosmos, no en esta guía.

9. Alertas Web-To-MAUI destruidas en Silencio (Route ID Mismatch)

Al programar el Simulador HTML, los botones de SOS enviaban su payload JSON al Viaje ID 1480. Al llegar a la API ASP.NET Core y buscar en la Base de Datos Postgres, el motor descubría que el Viaje 1480 no existe (la semilla solo crea el 1 y el 2). Por tanto, la API abortaba el procesamiento silenciosamente antes siquiera de disparar el Broadcast SignalR, desconectando virtualmente al Simulador de la cabina de control MAUI. Fix: Hardcodear el Vehículo 1 durante demos o hacer el Data-Binding dinámico.

10. EF Migrations: relation already exists

Tablas creadas por raw SQL en Program.cs no registradas en __EFMigrationsHistory. La migración EF usaba CreateTable() sin idempotencia → crash al aplicar. Fix: Reemplazar por migrationBuilder.Sql("CREATE TABLE IF NOT EXISTS ..."). Suprimir PendingModelChangesWarning con ConfigureWarnings ante mismatch ProductVersion 9.0→10.0.

11. Arquitectura mezclada: API / eCMR / Web sin separación

El estado global (.antigravity_state.json) mezclaba los 3 servicios en un solo bloque TRANSFLOTA_SERVER. La config de producción appsettings.Production.json no tenía Ecmr:BaseUrl explícito. Los agentes IA no encontraban ecmr.transflota.com y confundían servicios repetidamente. Fix: Reorganizar el estado global en bloques SERVER / API / ECMR / WEB. Añadir Ecmr:BaseUrl en appsettings.Production.json. Prevención: Cada servicio nuevo debe tener su propio bloque con URLs local/prod/pública.

12. Error 203/EXEC en Kestrel, 502 Nginx y PDFs Huérfanos (Visor Gris)

Si la API responde 502 Bad Gateway y journalctl devuelve status=203/EXEC, es síntoma crítico de falta de binario Transflota.Api. Originado al lanzar scripts híbridos de deploy con comandos input("Enter") para control de errores, que en ejecuciones headless o background agents crashean silenciamente: el script interrumpía el servidor de IPs viejo pero jamás terminaba de subir la compilación nueva, dejando el servidor vacío. Resolución: Despliegues puramente asíncronos sin prompts. Adicionalmente, este parón originaba un 502 al visor Google Docs Viewer, ocasionando su icónica "Caja Gris de Fallo". Prevención del Visor: Los PDFs ahora los renderiza el sistema Edge Nativamente (`iframe` estricto de Chromium), mitigando la dependencia de EEUU, incluso ante archivos huérfanos sin extensión subidos corruptamente el día 1, que NGINX malinterpretaba como octet-stream. Scripts Python DDL forzaron el resellado a `.pdf` vía SSH.

13. Semáforos de Tráfico en Rojo Permanente (DGT/SCT/PV)

Los 3 semáforos aparecían en 🔴 al entrar. Causa: trafico_service.py inicializa status como "error"; timeouts de SCT (5s) insuficientes para Gencat; WAF bloquea requests directos. Fix: 1) Cache TTL 60s. 2) SCT timeout 5s→20s. 3) CRON cache: */5 * * * * curl → /tmp/sct_cache.xml. 4) Semáforo 3 estados: ok (🟢 fijo), fallback (🟢 parpadeante), error (🔴 parpadeante). Prevención: Verificar cron con crontab -l | grep sct_cache.

Problema Raíz (Marzo 2026)

El portal SCT (Transit) de Cataluña impone un duro Rate-Limit por IP y timeouts. Las peticiones directas desde el servidor fallaban, dejando los semáforos en 🔴 permanente.

Solución Actual: CRON + Cache en Disco

• CRON cada 5 min: curl descarga el XML de Gencat → /tmp/sct_cache.xml (200KB datos reales).
• 3-Tier fetch_sct(): 1) Lee cache local si <10 min → 2) URL directa si cache falta → 3) Mock data (fallback).
• Semáforo 3 estados: 🟢 fijo = datos reales · 🟢 parpadeante = datos de respaldo · 🔴 parpadeante = sin conexión.
• Tooltip en hover muestra "Datos de respaldo — fuente sin conexión".

Verificar cron:

crontab -l | grep sct_cache
# Si no está → python fix_sct_cron.py

Escalado futuro (si hiciera falta)

Si Gencat bloquea curl desde el servidor: valorar ScraperAPI (~$5/mes) con IPs residenciales para mayor disponibilidad.

H0: Infraestructura (Parser, Lexer, AST) — 2w | H1: Sandbox Básico — 3w | H2: Confidence Scoring — 4w | H3: Lanes A/B — 3w | H4: UI + Dashboard — 3w | H5: Production Ready — 4w

Total: 22 semanas

Validators: V1–V11 (Type checking, Lifetime, Memory, Side effects, Domain checks)

Lanes: A (<500ms) | B (<15s) | C (2–5m) | D (Uncapped)

Confidence: 🟢 GREEN (0.95+) | 🟡 YELLOW (0.70–0.94) | 🔴 RED (<0.70)