From f81d11aa27d3f2b0c7b99ba8040ffec22817c095 Mon Sep 17 00:00:00 2001 From: Jacket-69 Date: Tue, 2 Jun 2026 23:20:39 -0400 Subject: [PATCH] =?UTF-8?q?docs(h5):=20addendum=20de=20revisi=C3=B3n=20SRS?= =?UTF-8?q?=20=E2=80=94=20reconciliar=20criterios=20con=20ADRs=20(H-04)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resuelve la decisión H-04 de FTR-03 (revisión del primer entregable): cómo tratar los criterios numéricos del SRS que cambiaron por evidencia. Enfoque elegido: addendum + arreglar espejo (no se reescribe la historia). docs/SRS.md (espejo vivo): - §2.13: CP-12 → ≤2000 ms p95 (ADR-0019); nuevas filas CP-01c' (±30%/≥75, ADR-0021) y CP-01a-95 (IC95 inf 0.860, P=100%, ADR-0016). - §2.7 RN-05, §2.10 Rendimiento, §2.15 ítem 5: performance ≤2000 ms p95. - Nota CP-01 ampliada con CP-01c'/CP-01a-95. - Nuevo §2.17 'Addendum de revisión post-implementación': tabla de reconciliación original→vigente con ADR y causa, anclada en la nota §2.12. El SRS LaTeX del vault (entregable congelado) recibe el mismo §2.17 con los criterios originales intactos en su cuerpo; PDF regenerado, versión previa archivada. Los entregables ya presentados (Segunda Eval) no se editan. --- docs/SRS.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/SRS.md b/docs/SRS.md index 137cdfb..a3d77b5 100644 --- a/docs/SRS.md +++ b/docs/SRS.md @@ -223,7 +223,7 @@ El re-despacho **no es automático**: el sistema presenta la propuesta al operad - **RN-02 — Saturación crítica (Echo/Delta + única unidad Básica):** si la única unidad Disponible es Básica y el incidente es Echo o Delta, el sistema **escala alerta** (despacha igual con flag rojo "Despacho sub-óptimo crítico — unidad inadecuada") en lugar de bloquear el despacho. El operador puede anular. El evento queda registrado con campo especial `despacho_suboptimo: true` en el log. - **RN-03 — Log inmutable:** cada despacho genera un registro JSON inmutable con todos los campos del cálculo. Solo se permite agregar eventos posteriores (cancelación, finalización, re-despacho) como entradas adicionales; nunca editar ni eliminar. - **RN-04 — Taller excluido:** unidades con estado = Taller no participan en el cálculo bajo ninguna circunstancia. -- **RN-05 — Rendimiento:** el cálculo completo (árbol de triaje + A* + selección de unidad) debe completarse en ≤ 1 segundo para flotas de hasta 50 unidades, y en ≤ 300 ms para flotas de hasta 10 unidades. +- **RN-05 — Rendimiento:** el cálculo completo (árbol de triaje + A* + selección de unidad) debe completarse en **≤ 2 000 ms p95 para flotas de hasta 50 unidades** (criterio ajustado por evidencia tras el spike CP-12, [ADR-0019](architecture/decisions/0019-spike-cp12-criterio-ajustado.md); el objetivo original era ≤ 1 segundo — ver §2.17). Para flotas pequeñas (≤ 10 unidades) el cálculo se mantiene holgadamente bajo ese techo. - **RN-06 — Confirmación humana de re-despacho:** el sistema propone el re-despacho pero no lo ejecuta sin confirmación explícita del operador de despacho. - **RN-07 — Append-only de logs:** los logs solo admiten append de nuevos eventos. Cualquier intento de modificar un registro existente debe fallar con error y generar una entrada de alerta en el log de auditoría. - **RN-08 — Saturación de flota:** si no existen unidades en estado Disponible, el sistema reporta el estado de saturación e identifica las unidades EnRuta con menor progreso de trayecto como candidatas a re-dirección, para consideración del operador. @@ -292,8 +292,8 @@ El re-despacho **no es automático**: el sistema presenta la propuesta al operad |---|---| | **Precisión de ruteo** | La distancia de la ruta calculada por A* debe coincidir con la calculada por OSRM (oracle externo sobre el mismo grafo OSM) con `\|Δ_distance\| / d_OSRM ≤ 0.30` en ≥ 75 de 100 pares del fixture committeado (CP-01a). La divergencia en duración se reporta a título observacional (CP-01b). Ver [ADR-0011](architecture/decisions/0011-reformulacion-criterio-it01.md) para la justificación del experimento que reformuló este criterio. | | **Confiabilidad** | El sistema debe estar disponible el 99,9% del tiempo en horario operativo (equivale a ≤ 8,76 horas de downtime anual) | -| **Rendimiento — flota grande** | El cálculo completo (triaje + A* + selección) se completa en ≤ 1 segundo para flotas de hasta 50 unidades simultáneas | -| **Rendimiento — flota pequeña** | El cálculo completo se completa en ≤ 300 ms para flotas de hasta 10 unidades simultáneas | +| **Rendimiento — flota grande** | El cálculo completo (triaje + A* + selección) se completa en ≤ 2 000 ms p95 para flotas de hasta 50 unidades simultáneas (criterio ajustado por [ADR-0019](architecture/decisions/0019-spike-cp12-criterio-ajustado.md); objetivo original ≤ 1 segundo — ver §2.17) | +| **Rendimiento — flota pequeña** | El cálculo completo se completa holgadamente bajo el techo p95 para flotas de hasta 10 unidades simultáneas | | **Trazabilidad** | Cada despacho confirmado persiste su log con todas las variables del cálculo: respuestas de triaje, categoría MPDS, costos por unidad, unidad seleccionada, ETA, ruta y timestamp | | **Tolerancia a errores** | Coordenadas fuera del rango IV Región son rechazadas con mensaje descriptivo antes de ejecutar cualquier cálculo; el sistema nunca entrega resultado sobre entrada inválida | | **Usabilidad** | Un operador entrenado completa el árbol de triaje (ingreso de coordenadas + respuestas) en ≤ 90 segundos bajo condiciones normales de operación | @@ -373,9 +373,11 @@ El dataset cubre las cinco categorías MPDS con distribución orientada a los ca | CP-09 | Validación de coordenadas — fuera de rango | lat = −31.200000, lon = −71.300000 | Rechazo con mensaje "Coordenadas fuera del área de cobertura (IV Región)" | No se ejecuta A* ni cálculo de costo; ningún log de despacho generado | | CP-10 | Saturación de flota | Todas las unidades en estado EnRuta o EnEscena | Sistema reporta saturación; lista candidatas a re-dirección ordenadas por progreso ascendente | Mensaje de saturación visible; no se genera despacho automático | | CP-11 | Empate de costo — desempate lexicográfico | Incidente con U03 y U07 (ambas Avanzada) con T_viaje idéntico calculado | U03 seleccionada | ID seleccionado = "U03" (menor lexicográfico respecto a "U07") | -| CP-12 | Performance — flota de 50 unidades | 50 unidades Disponibles (fixture sintético, generado por bench script fuera del dataset de aceptación); incidente Echo ingresado | Cálculo completo completado | Tiempo total (triaje + A* × 50 + argmin) ≤ 1 000 ms medido en servidor de prueba | +| CP-12 | Performance — flota de 50 unidades | 50 unidades Disponibles (fixture sintético, generado por bench script fuera del dataset de aceptación); incidente Echo ingresado | Cálculo completo completado | Tiempo total (triaje + A* × 50 + argmin) **≤ 2 000 ms p95** (criterio ajustado por evidencia, [ADR-0019](architecture/decisions/0019-spike-cp12-criterio-ajustado.md); medido p95 = 1 941 ms). El SRS original pedía ≤ 1 000 ms (ver §2.17). | +| CP-01c' | Paridad de `duration` post-calibración (snap-to-edge) | Mismos 100 pares; A* calibrado experimental + snap-to-edge a `factor_calibracion = 0.80` | duration de la ruta encontrada | `\|Δ_duration\| / T_OSRM ≤ 0.30` en ≥ 75/100 (medido 78/100). Recalibra el objetivo histórico ±15%/≥85 — ver [ADR-0021](architecture/decisions/0021-cp01c-snap-to-edge-criterio-realista.md) | +| CP-01a-95 | Confianza estadística de CP-01a | Fixture v3 cartesiano N=300 (`tests/fixtures/osrm_oracle_v3.json`); bootstrap B=1000, semilla 2026 | fracción dentro de ±30% y su IC95 | `IC95_inferior(fracción) ≥ 0.75` Y `P(fracción ≥ 0.75) ≥ 0.95` (medido: fracción 0.897, IC95 inf 0.860, P = 100%). Ver [ADR-0016](architecture/decisions/0016-camino-95-cp01a.md) | -¹ **Nota CP-01** — La formulación original del criterio (`|T_A* − T_OSRM| / T_OSRM ≤ 0.05` en ≥ 95/100) se reformuló tras el experimento real ejecutado el 2026-05-18: el A* simple del SRS no modela las penalidades de giro/semáforo ni el speed factor de OSRM, lo que produce divergencias sistemáticas en `duration`. La métrica `distance` es el proxy de paridad de ruta defendible. Ver [ADR-0011](architecture/decisions/0011-reformulacion-criterio-it01.md) con los datos del experimento y la justificación. +¹ **Nota CP-01** — La formulación original del criterio (`|T_A* − T_OSRM| / T_OSRM ≤ 0.05` en ≥ 95/100) se reformuló tras el experimento real ejecutado el 2026-05-18: el A* simple del SRS no modela las penalidades de giro/semáforo ni el speed factor de OSRM, lo que produce divergencias sistemáticas en `duration`. La métrica `distance` es el proxy de paridad de ruta defendible (CP-01a). Posteriormente la paridad de `duration` se cerró con snap-to-edge bajo el criterio recalibrado CP-01c' (±30%/≥75, [ADR-0021](architecture/decisions/0021-cp01c-snap-to-edge-criterio-realista.md)) y la confianza estadística de CP-01a se verificó como CP-01a-95 sobre el fixture v3 ([ADR-0016](architecture/decisions/0016-camino-95-cp01a.md)). Síntesis en §2.17. Ver [ADR-0011](architecture/decisions/0011-reformulacion-criterio-it01.md) con los datos del experimento y la justificación. --- @@ -404,7 +406,7 @@ El dataset cubre las cinco categorías MPDS con distribución orientada a los ca 4. **Re-despacho — comportamiento correcto en frontera:** CL-05 (progreso 60%) no genera propuesta de re-despacho; CL-06 (progreso 40%) sí genera propuesta con espera de confirmación. Ambos comportamientos verificados por CP-06 y CP-07. -5. **Performance:** El cálculo completo se ejecuta en ≤ 1 000 ms para flota de 50 unidades y en ≤ 300 ms para flota de 10 unidades, medidos en el servidor de prueba bajo carga nominal. (Verificado por CP-12.) +5. **Performance:** El cálculo completo se ejecuta en ≤ 2 000 ms p95 para flota de 50 unidades, medido en el servidor de prueba bajo carga nominal (criterio ajustado por evidencia, [ADR-0019](architecture/decisions/0019-spike-cp12-criterio-ajustado.md); el objetivo original ≤ 1 000 ms — ver §2.17). (Verificado por CP-12.) 6. **Trazabilidad completa:** Cada despacho confirmado genera un log JSON con los campos obligatorios: id, timestamp ISO 8601, respuestas de triaje, categoría MPDS, costos desglosados por unidad evaluada, unidad seleccionada, ETA, ruta de nodos, flag de sub-óptimo y operador. (Verificado por CP-06 y CP-08.) @@ -476,3 +478,20 @@ La implementación Java aporta: - **Performance benchmarking** contra JVM caliente (informe final). **Veredicto**: Python como implementación primaria del sistema; Java como validador del núcleo. La partición refleja el ecosistema disponible (Python tiene OSMnx; Java tiene JGraphT) y se documenta en la decisión arquitectónica del proyecto. + +--- + +## 2.17 Addendum de revisión post-implementación + +Esta sección se agrega tras la implementación (hitos H2–H5) y **no invalida** el SRS: documenta los criterios numéricos que se **reformularon o ajustaron por evidencia empírica** al medir el sistema contra un oracle OSRM 5.27 sobre el grafo OSM real de la conurbación La Serena–Coquimbo, con su decisión arquitectónica (ADR) y su causa. Es coherente con la nota **Importante** de la sección 2.12: los ETA son aproximaciones y la validación numérica exacta se difirió a la fase de implementación con datos reales — exactamente lo que ocurrió al medir. La versión LaTeX congelada del SRS conserva los criterios originales en su cuerpo; esta tabla es la reconciliación canónica. + +| Criterio | Original (§2.10 / §2.13) | Vigente (medido) | ADR | Naturaleza del cambio | +|---|---|---|---|---| +| **CP-01** (paridad de ruteo) | `duration`: error relativo ≤ 5% en ≥ 95/100 | Reformulado a ±30% en ≥ 75/100 en dos criterios: **CP-01a** (`distance`, medido 78/100) y **CP-01c'** (`duration` con snap-to-edge, medido 78/100) | 0011, 0013, 0020, 0021 | Reformulación + desviación. El ±5% en `duration` es inalcanzable sin reimplementar el modelo de costo `car.lua` de OSRM (penalización de giros, semáforos, perfil de velocidad por clase de vía). | +| **CP-01a-95** (confianza estadística) | — (criterio nuevo, derivado por bootstrap) | Cumplido sobre el fixture v3 (N=300, rutas inter-comuna): fracción dentro de ±30% = 0.897; IC95 inferior 0.860 ≥ 0.75; P(fracción ≥ 0.75) = 100% | 0016 | Cumplido. El margen estrecho de la muestra v2 (78/100) era sesgo hacia rutas urbanas cortas, no una limitación del A*. | +| **CP-12 / RN-05** (performance) | Tiempo total ≤ 1 000 ms para 50 unidades | ≤ 2 000 ms p95 (medido p95 = 1 941 ms, A* secuencial) | 0019 | Ajuste por evidencia + desviación. La paralelización del A* queda como deuda para v2. | +| **v_max** heurística A* | 140 km/h (38.89 m/s) | 180 km/h (50 m/s) | 0010 | Ajuste técnico necesario: preserva la admisibilidad de la heurística ante motorway (120 km/h) × factor_sirena (1.4) = 168 km/h. | + +**Criterios sin cambio.** El resto del SRS se cumple según lo especificado. En particular **RT-02** (equivalencia entre Python y Java, ±5% en numéricos) se mantiene **intacto** y verificado bit-exacto (12/12 OK en integración continua); RN-09 (umbral de snap de 500 m), la función de costo (α = 1, β = 600 s) y el árbol de triaje (12/12 incidentes del dataset) se cumplen tal como se especificó. + +**Trazabilidad.** El detalle de cada decisión vive en los ADR citados (`docs/architecture/decisions/`) y en la matriz de trazabilidad (`docs/quality/trazabilidad.md`).