FleteChat v1.0 — Requerimientos No Funcionales¶

Este documento consolida los requerimientos no funcionales (NFRs) que complementan a las historias de usuario. Están organizados por categoría. Cada NFR tiene un identificador único NFR-NNN, un enunciado observable y, cuando aplica, un objetivo cuantificable.

Muchos de estos NFRs se derivaron de la revisión exhaustiva de las historias (hallazgos del Bloque B — review-v1.0/changelog.md) y de las obligaciones legales de la Ley 81 de Panamá.

Estado¶

Código	Estado
🟡	Propuesto por Kaeus
🟢	Confirmado con el cliente
🔴	En discusión

Performance y latencia¶

ID	Enunciado	Objetivo	Estado
NFR-001	El agente conversacional responde al cliente dentro de una ventana razonable.	p95 ≤ 5 s (incluye tool call al cotizador y a otras fuentes).	🟡
NFR-002	El cotizador (HT-10) devuelve una cotización válida dentro de un tiempo operativo.	p95 ≤ 1.5 s para combinaciones soportadas; timeout máximo del agente al cotizador: 5 s.	🟡
NFR-003	La generación de cada PDF de instructivo (HT-06) se completa dentro del plazo configurado antes de la distribución.	p95 ≤ 5 s por PDF individual.	🟡
NFR-004	El import de listas de precios desde Excel maneja archivos realistas sin bloquear el backoffice.	Archivos con hasta 10 000 filas parseados en ≤ 60 s.	🟡
NFR-005	La consulta del audit log con filtros combinados responde rápidamente incluso con carga histórica.	p95 ≤ 2 s para búsquedas con un rango de fechas ≤ 30 días.	🟡
NFR-006	El chat en tiempo real de handoff (US-035) propaga mensajes con latencia baja.	p95 ≤ 1 s entre envío y visualización en el otro extremo.	🟡

Disponibilidad y continuidad¶

ID	Enunciado	Objetivo	Estado
NFR-007	El sistema mantiene disponibilidad operativa durante horario hábil.	SLA objetivo: 99,5 % en horario hábil (lun–vie 7:00–20:00 America/Panama) una vez estable.	🟡
NFR-008	Ventana de mantenimiento planificada fuera de horario crítico.	Mantenimiento en ventana nocturna o fines de semana, avisada con al menos 48 h de antelación al admin.	🟡
NFR-009	Ante caída de WhatsApp API, el sistema notifica al admin y ejecuta el plan de continuidad documentado.	Detección automática en ≤ 5 minutos; plan de continuidad documentado como NFR operativo (ver P4-01 en `v1.0-fase2-pendientes.md`).	🟡
NFR-010	Ante caída del proveedor LLM (Anthropic), el sistema degrada a handoff manual o mensajería de estado sin perder conversaciones activas.	Detección y degradación en ≤ 2 minutos; conversaciones activas no se pierden.	🟡
NFR-011	Ante caída del generador de PDF o del Blob storage, los embarques afectados pasan a estado `distribución incompleta` y escalan a operador tras N minutos de reintentos fallidos.	N = 15 minutos (configurable); escalación automática.	🟡

Seguridad¶

ID	Enunciado	Objetivo	Estado
NFR-012	Todas las contraseñas se almacenan con hashing resistente a ataques modernos.	Argon2 con parámetros conformes a OWASP ASVS 4.0.	🟡
NFR-013	La comunicación entre cliente, backoffice y servidores es cifrada end-to-end en tránsito.	TLS 1.2+ obligatorio; HSTS habilitado.	🟡
NFR-014	Los datos personales almacenados en base de datos y en almacenamiento de archivos están cifrados en reposo.	Cifrado AES-256 o superior a nivel de disco o de base de datos.	🟡
NFR-015	Los tokens firmados (JWT de backoffice, JWT de formularios públicos, magic links) usan secretos distintos y se rotan periódicamente.	Secretos distintos por propósito; rotación JWT cada 90 días con key versioning; rotación de magic link secret cada 90 días.	🟡
NFR-016	Las API sensibles tienen rate limiting por IP y por cuenta.	Login ≤ 5 intentos/15 min por email; reset password ≤ 5/h por email; consultas de estatus ≤ 10/min por número.	🟡
NFR-017	Los administradores del backoffice usan MFA (multi-factor authentication).	TOTP obligatorio para rol admin desde go-live o v1.1, con justificación documentada si se difiere.	🔴
NFR-018	El acceso de los tres roles del backoffice respeta el principio de mínimo privilegio declarado en US-047.	Matriz de permisos centralizada; ninguna acción disponible fuera de su rol.	🟡
NFR-019	Las credenciales de proveedores externos (Meta, Anthropic, Azure, correo) se gestionan fuera del código y con rotación documentada.	Secrets store gestionado; rotación Meta según política Meta; rotación Azure y correo cada 90 días.	🟡
NFR-020	Los ambientes de desarrollo, staging y producción están aislados y no comparten datos personales reales.	Datos personales reales solo en producción; staging usa datos sintéticos o anonimizados.	🟡
NFR-021	El sistema sanitiza entradas susceptibles de inyección.	Sanitización anti-CSV-injection en imports Excel (PR-227); system prompts hardcoded no sobrescribibles por el cliente (PR-229).	🟡

Retención de datos¶

ID	Enunciado	Objetivo	Estado
NFR-022	La transcripción conversacional se conserva por un horizonte limitado y se condensa después a resumen persistente.	6 meses de transcripción completa, luego resumen breve + atributos persistentes (US-054 PR-008).	🟡
NFR-023	El audit log operativo se retiene por el plazo mínimo necesario para investigaciones.	24 meses mínimo (US-050 PR-192); eventos >12m se archivan a tier frío con índices apropiados.	🟡
NFR-024	Los registros con impacto fiscal o contable (facturación, documentación aduanera, embarques cerrados) se retienen por el plazo normativo panameño.	5 años mínimo; distinguir en la implementación de los 24 meses del audit log operativo.	🟡
NFR-025	Los datos personales que ya cumplieron plazo legal se purgan automáticamente mediante job programado.	Job diario o semanal; cada purga queda registrada en audit log con resumen sin PII.	🟡
NFR-026	El catálogo de plazos de retención por categoría de dato está documentado y es auditable.	Tabla por categoría (facturas, embarques cerrados, PII de contacto, historial conversacional) con plazo mínimo, máximo, base legal.	🔴

Privacidad y Ley 81 (Panamá)¶

ID	Enunciado	Objetivo	Estado
NFR-027	FleteChat responde a solicitudes de ejercicio de derechos Ley 81 dentro del plazo legal.	15 días hábiles desde recepción (US-061 PR-202, configurable por jurisdicción).	🟡
NFR-028	FleteChat mantiene una política de privacidad publicada y versionada en URL oficial.	Documento redactado, publicado y accesible desde el primer contacto del cliente (US-062 PR-206).	🔴
NFR-029	FleteChat designa formalmente un Responsable de Protección de Datos (DPD/DPO) con datos de contacto publicables.	Nombre y canal de contacto en la política de privacidad desde go-live.	🔴
NFR-030	FleteChat registra sus bases de datos personales ante ANTAI si la legislación lo requiere por tipo y volumen de tratamiento.	Trámite completado antes del go-live.	🔴
NFR-031	Las transferencias internacionales de datos (Meta, Anthropic, Azure, correo) están documentadas con su base legal y garantías de protección equivalente.	Cláusulas contractuales tipo o certificaciones reconocidas; enumeradas en la política de privacidad.	🔴
NFR-032	El proveedor LLM no usa los datos de clientes de FleteChat para entrenamiento.	Configuración de telemetría off y opt-out de entrenamiento; paso de referencias por ID en lugar de PII cuando sea posible.	🟡
NFR-033	La eliminación de datos personales del cliente dispara la anonimización de su PII en entradas históricas del audit log.	Reescritura controlada con marcador `[anonimizado]` (US-050 PR-215); la anonimización queda a su vez auditada.	🟡

Idiomas e internacionalización¶

ID	Enunciado	Objetivo	Estado
NFR-034	El agente conversacional atiende al cliente final en español e inglés.	Detección automática por idioma del mensaje; español por defecto (US-053 PR-006).	🟡
NFR-035	El backoffice soporta español e inglés en toda su superficie.	Cada texto de UI cuenta con traducción en ambos idiomas; selector de idioma por usuario.	🟡
NFR-036	Los mensajes proactivos respetan una ventana horaria razonable en zona horaria declarada.	Default 08:00–22:00 `America/Panama` (US-057 PR-197), configurable. Mensajes críticos exentos.	🟡

Capacidad y escala¶

ID	Enunciado	Objetivo	Estado
NFR-037	El sistema soporta un volumen razonable de conversaciones simultáneas.	Capacidad inicial: ≥ 200 conversaciones activas simultáneas (ajustable con carga real).	🟡
NFR-038	El backoffice soporta múltiples operadores en handoff simultáneo sin degradación.	≥ 20 WebSockets abiertos concurrentes con latencia NFR-006 preservada.	🟡
NFR-039	El catálogo admite crecimiento sin degradar performance de cotización.	Hasta 100 000 filas en lista de precios sin afectar NFR-002.	🟡

Observabilidad¶

ID	Enunciado	Objetivo	Estado
NFR-040	El sistema emite logs estructurados con `correlation_id` que cruza todos los componentes de una misma operación.	Cada request, cada tool call del agente, cada envío a WhatsApp / correo / PDF arrastran el mismo `correlation_id`.	🟡
NFR-041	El sistema emite alertas al admin ante errores críticos, tasas de fallo anómalas y eventos de seguridad.	Canal de alerta definido (correo, webhook u otro); umbrales documentados.	🟡
NFR-042	El quality rating de la cuenta Meta Business se monitorea continuamente.	Alerta automática si el rating baja a "Medium" o inferior.	🟡

Accesibilidad del backoffice¶

ID	Enunciado	Objetivo	Estado
NFR-043	El backoffice es utilizable en navegadores modernos estándar.	Soporte a versiones recientes de Chrome, Firefox, Safari, Edge (últimos 2 años).	🟡
NFR-044	El backoffice es utilizable desde móvil para tareas operativas frecuentes.	Responsive mínimo para atención de handoff, consulta de audit log y búsqueda de cotizaciones.	🟡

Gaps abiertos¶

Los NFRs marcados como 🔴 requieren decisión del cliente antes del go-live. Están consolidados en el documento de preguntas pendientes al cliente (v1.0-preguntas-pendientes-cliente.md) y en el Excel de seguimiento.

Resumen de pendientes: - NFR-017 (MFA admin): pasar a historia de v1.1 o mantener en v1.0 con justificación. - NFR-026 (catálogo de retención): redactar con asesor legal panameño antes de go-live. - NFR-028 (política de privacidad publicada), NFR-029 (DPD/DPO), NFR-030 (registro ANTAI), NFR-031 (transferencias internacionales): bloqueantes pre-go-live listados en el Excel de pendientes del cliente.

Convenciones¶

Cada NFR es verificable por el cliente o un auditor externo.
Los objetivos cuantificables son iniciales y ajustables con datos reales de carga; se calibran en los primeros meses post-go-live.
Los NFRs no describen diseño ni implementación; sólo el comportamiento observable del sistema.

Control de versiones¶

Versión	Fecha	Cambios
1.0	2026-04-20	Versión inicial.