Documento histórico

Este documento se conserva solo para trazabilidad. Consulte el índice maestro para la fuente vigente.

Documento histórico — no usar como fuente de decisiones actuales

Reemplazado por la versión canónica del 2026-07-11. Conservar solo como trazabilidad histórica.

Especificación de Requisitos de Software (SRS)¶

Documento formal que consolida todos los requisitos del sistema IslaBox. Es la referencia contractual entre el equipo de producto, el equipo técnico y los stakeholders para el alcance del MVP.

Estándar seguido: IEEE 830 / IEEE 29148.

1. Introducción¶

1.1 Propósito¶

Este documento especifica los requisitos del sistema IslaBox, una plataforma de gestión de casillero y envíos de paquetes desde Estados Unidos hacia Cuba. Está dirigido a:

Equipo de desarrollo (producto, diseño, backend, mobile)
Stakeholders de negocio
QA y equipo de pruebas
Futuros mantenedores

1.2 Alcance¶

IslaBox cubre el ciclo completo: registro del usuario en EE.UU. → identificación con casillero en Miami → reporte de compras → recepción de paquetes en almacén → conciliación → consolidación → cotización → pago → despacho hacia Cuba → entrega al destinatario → seguimiento post-entrega.

El MVP cubre los procesos operativos (no incluye la automatización de integraciones como tracking API, OCR o integración completa con Stripe como pasarela de pago, que se difieren a Fase 2-3).

1.3 Definiciones, acrónimos y abreviaturas¶

Ver ../01-inicio/glosario.md.

1.4 Referencias¶

Documento	Ubicación
Visión del producto	../../../vision/objetivo.md
Perfiles de usuario	../../../vision/perfiles.md
Modelo de datos	../../../datos/modelo-datos.md
Estados oficiales	../../../datos/estados.md
Reglas de negocio	../../../datos/reglas-negocio.md
Identificador	../../../datos/identificador.md
Categorías y aduana	../../../datos/aduana.md
Normativa cubana	../../../datos/aduana-normativa-cuba.md
KYC	../../../datos/kyc.md
Stack técnico	../../../stack/tecnologias.md
Arquitectura	../../../stack/arquitectura-backend.md
Módulos	../../../modulos/modulos.md
Catálogo de casos de uso	casos-de-uso/catalogo.md
Plan de pruebas	plan-pruebas.md

1.5 Visión general del documento¶

Sección 2: Descripción general del producto
Sección 3: Requisitos funcionales (RF)
Sección 4: Requisitos no funcionales (RNF)
Sección 5: Restricciones
Sección 6: Apéndices

2. Descripción general del producto¶

2.1 Perspectiva del producto¶

IslaBox es un sistema nuevo, no un reemplazo de un sistema anterior. Se compone de:

App móvil (Android en MVP, iOS en Fase 2) para el usuario registrado
API pública (FastAPI) consumida por las apps
Backend de servicios (Django) con ORM, migraciones y lógica de negocio
Backoffice (Django Admin) para operadores y administradores
Almacenamiento de objetos (MinIO) para archivos privados
Cache y locks (Redis) para procesos críticos
Base de datos relacional (PostgreSQL)

2.2 Funciones del producto¶

#	Función	Prioridad
F1	Gestión de usuarios (registro, login, perfil)	Alta
F2	Identificador único de casillero con dígito verificador	Alta
F3	Dashboard con dirección del casillero copiable	Alta
F4	Reporte de compras (prealerta)	Alta
F5	Recepción de paquetes (backoffice)	Alta
F6	Conciliación de paquetes	Alta
F7	Estados de paquete visibles con timeline	Alta
F8	Almacenaje con días gratis y cargos	Alta
F9	Consolidación de paquetes	Alta
F10	Cotización	Alta
F11	Pago o registro de pago	Alta
F12	KYC obligatorio para despachar	Alta
F13	Notificaciones push	Alta
F14	Módulo informativo de aduana	Alta
F15	Tarifario visible	Alta
F16	Backoffice con colas operativas	Alta
F17	Tutoriales por tienda	Alta
F18	Gestión de destinatarios y remitentes	Alta
F19	Servicios adicionales (inspección, prueba, reempaque, devolución)	Alta
F20	Programa de referidos (Fase 2)	Media
F21	Crédito y tarjetas (Fase 2)	Media
F22	Niveles 1/2/3 dinámicos (Fase 2)	Media
F23	API de tracking de transportistas (Fase 2)	Baja
F24	OCR de etiquetas (Fase 2)	Baja
F25	WhatsApp API (Fase 3)	Baja
F26	Integración con Stripe (pasarela de pago online, Fase 2)	Baja
F27	App iOS nativa (Fase 2)	Baja

2.3 Características de los usuarios¶

Tipo de usuario	Características técnicas
Usuario final	Uso móvil intensivo, sin conocimientos técnicos, requiere flujos guiados
Operador	Uso mixto (móvil + desktop), necesita colas y vistas administrativas
Administrador	Uso desktop, requiere control de configuración global

2.4 Restricciones¶

Restricción	Detalle
Stack	Definido en stack/tecnologias.md; no se permite introducir nuevas tecnologías sin aprobación
Idioma de la app	Español (Cuba) en MVP; sin multilenguaje en MVP
País del usuario registrado	Solo EE.UU. (teléfono +1)
Moneda	USD como base
Disponibilidad objetivo	99% en horario operativo (8am-8pm EST)
Cumplimiento de privacidad	Cifrado, URLs firmadas, separación de buckets para KYC

2.5 Supuestos y dependencias¶

Supuesto	Base
Casillero físico en Miami accesible	A acordar antes de lanzamiento
Agencia aliada operativa	A acordar antes de lanzamiento
Res. 175/2022 vigente	Verificable; módulo actualizable
Usuarios aceptan app móvil y KYC	Validar con beta

3. Requisitos funcionales (RF)¶

Cada requisito tiene: identificador, descripción, actor(es), prioridad, criterios de aceptación y trazabilidad a casos de uso.

3.1 Gestión de usuarios¶

RF-001: Registro de usuario¶

Campo	Valor
Descripción	El usuario puede crear una cuenta con nombre, correo, teléfono +1, contraseña y país (fijo en US)
Actor	Usuario final
Prioridad	Alta
Precondición	Ninguna
Postcondición	Usuario creado; recibe identificador; recibe código OTP para verificar teléfono
Criterios de aceptación	- Validación de email formato válido - Teléfono debe ser +1 y 10 dígitos - Contraseña mínimo 8 caracteres, una mayúscula, un número - Verificación por OTP antes de activar la cuenta
Trazabilidad	CU-001

RF-002: Verificación de teléfono por OTP¶

Campo	Valor
Descripción	Tras el registro, el usuario recibe un código OTP de 6 dígitos por SMS al +1
Actor	Usuario final
Prioridad	Alta
Precondición	Usuario registrado pero no verificado
Postcondición	Teléfono marcado como verificado; usuario puede operar
Criterios de aceptación	- Código expira en 5 minutos - Máximo 3 intentos por código - Reenvío disponible tras 60 segundos
Trazabilidad	CU-001

RF-003: Verificación de correo por enlace¶

Campo	Valor
Descripción	El usuario recibe un enlace de verificación al correo registrado
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Enlace expira en 24 horas - Al hacer click, el correo se marca como verificado
Trazabilidad	CU-001

Campo	Valor
Descripción	El usuario accede con email + contraseña
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Rate limit: 5 intentos/min por IP - Mensaje genérico en credenciales inválidas - Sesión persiste 30 días con refresh
Trazabilidad	CU-002

RF-005: Recuperación de contraseña¶

Campo	Valor
Descripción	El usuario puede solicitar un código OTP para resetear contraseña
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- OTP por SMS al teléfono registrado - Nueva contraseña con requisitos mínimos
Trazabilidad	CU-002

RF-006: Edición de perfil¶

Campo	Valor
Descripción	El usuario puede editar nombre, correo (re-verificación), teléfono (re-verificación) y contraseña
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-003

RF-007: Asignación de identificador único¶

Campo	Valor
Descripción	Al crear el usuario, se le asigna un identificador `CP-NNNNNN-D` con dígito verificador Mod-10
Actor	Sistema
Prioridad	Alta
Criterios de aceptación	- Prefijo configurable (default `CP`) - Secuencial único de 6 dígitos - Dígito verificador calculado con algoritmo Mod-10 - Lock distribuido en Redis al generar para evitar duplicados
Trazabilidad	Modelo: datos/identificador.md

3.2 Dashboard y casillero¶

RF-008: Visualización del identificador¶

Campo	Valor
Descripción	El dashboard muestra el identificador del usuario con badge de "Activo"
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-004

RF-009: Copia de dirección del casillero¶

Campo	Valor
Descripción	El usuario puede copiar la dirección completa o por campos individuales (línea 1, línea 2, ciudad, estado, ZIP, teléfono)
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Un toque copia al portapapeles - Selector de plataforma (Amazon, SHEIN, Temu) que muestra el campo Address Line 2 con el identificador
Trazabilidad	CU-004

RF-010: Resumen de paquetes¶

Campo	Valor
Descripción	El dashboard muestra 4 contadores: en camino al almacén, en almacén, en tránsito a Cuba, entregados
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-004

RF-011: Sección "Requiere tu atención"¶

Campo	Valor
Descripción	El dashboard muestra alertas cuando hay KYC rechazado, paquete sin prealerta, almacenaje por vencer, pago pendiente, aduana con info requerida, servicio completado, o producto posiblemente restringido
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-004

RF-012: Tutoriales por tienda¶

Campo	Valor
Descripción	La app muestra tutoriales paso a paso para Amazon, SHEIN y Temu, explicando dónde poner el identificador y la dirección
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Contenido administrable desde Django Admin - Imágenes ilustrativas - Fecha de última actualización visible
Trazabilidad	CU-004

3.3 Prealerta (reporte de compra)¶

RF-013: Crear prealerta¶

Campo	Valor
Descripción	El usuario reporta una compra con tienda, número de orden, fecha, tracking (opcional), categoría, descripción, cantidad, valor, enlace, instrucciones especiales, preferencias de consolidación, servicios adicionales, foto (opcional), remitente y destinatario
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Categoría requerida, una de las 15 operativas - Valor > 0 - Foto opcional pero recomendada - Destinatario requerido (puede ser de su lista o nuevo)
Trazabilidad	CU-005

RF-014: Editar prealerta¶

Campo	Valor
Descripción	El usuario puede editar una prealerta mientras esté en estado `borrador` o `requiere_correccion`
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-005

RF-015: Listar prealertas¶

Campo	Valor
Descripción	El usuario ve sus prealertas con estado, tienda, número de orden, tracking, fecha de compra
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-005

RF-016: Ver detalle de prealerta¶

Campo	Valor
Descripción	El usuario ve el detalle completo de una prealerta con timeline de estados
Actor	Usuario final
Prioridad	Alta
Trazabilidad	CU-005

RF-017: Actualizar tracking¶

Campo	Valor
Descripción	El usuario puede agregar o actualizar el número de tracking de una prealerta existente
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Validación de formato (alfanumérico, 5+ caracteres)
Trazabilidad	CU-005

3.4 Recepción y conciliación (backoffice)¶

RF-018: Registrar paquete recibido¶

Campo	Valor
Descripción	El operador registra un paquete físico: identificador, tracking, tienda, fotos, peso, dimensiones, estado del embalaje, ubicación
Actor	Operador
Prioridad	Alta
Criterios de aceptación	- Foto obligatoria - Identificador validado con Mod-10 antes de asociar - Si no hay identificador, va a cola de conciliación
Trazabilidad	CU-009

RF-019: Conciliar paquete¶

Campo	Valor
Descripción	El operador busca por tracking, nombre, identificador parcial y asocia el paquete a un usuario o lo marca como no identificado
Actor	Operador
Prioridad	Alta
Trazabilidad	CU-009

RF-020: Cambiar estado logístico¶

Campo	Valor
Descripción	El operador puede cambiar el estado de un paquete siguiendo las transiciones válidas del modelo de estados
Actor	Operador
Prioridad	Alta
Criterios de aceptación	- Cada cambio genera un `package_event` con timestamp y operador - Estados inválidos generan error
Trazabilidad	diagramas-uml/estados/estado-paquete.md

3.5 Almacenaje¶

RF-021: Calcular días en almacén¶

Campo	Valor
Descripción	El sistema calcula automáticamente los días desde la fecha de recepción
Actor	Sistema
Prioridad	Alta
Trazabilidad	CU-006

RF-022: Alertar antes del vencimiento¶

Campo	Valor
Descripción	El sistema envía push cuando faltan 5, 3 y 1 día para vencer el período gratuito de 15 días (valor resuelto en preguntas.md)
Actor	Sistema
Prioridad	Alta
Criterios de aceptación	- Job diario ejecuta a las 9am EST - Push no se duplica si ya se envió hoy - El período gratuito es configurable desde Django Admin pero el valor por defecto es 15
Trazabilidad	operaciones/riesgos.md

RF-023: Aplicar cargos por almacenaje¶

Campo	Valor
Descripción	El sistema crea un cargo automático de $0.50 USD por día extra (valor resuelto en preguntas.md) por cada día después del día 15
Actor	Sistema
Prioridad	Alta
Criterios de aceptación	- Cargo visible en el detalle del paquete - Notificación al usuario al aplicar - El costo por día es configurable desde Django Admin pero el valor por defecto es $0.50 - Los cargos se generan como un `Charge` con `category = 'storage'`
Trazabilidad	CU-006

3.6 Consolidación y cotización¶

RF-024: Crear consolidación¶

Campo	Valor
Descripción	El usuario selecciona 2+ paquetes en estado `en_almacen` o `listo_para_consolidar` y los agrupa en una consolidación
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Mismo usuario - KYC aprobado requerido - Mismo destinatario final - Estado inicial `borrador`
Trazabilidad	CU-007

RF-025: Cotizar consolidación¶

Campo	Valor
Descripción	El sistema calcula el costo: peso total × tarifa/lb (barco o avión) + cargos adicionales
Actor	Sistema
Prioridad	Alta
Criterios de aceptación	- Cotización con vigencia de 7 días - Si cambia el peso real o se agregan servicios, se invalida y recalcula
Trazabilidad	CU-007

RF-026: Pagar consolidación¶

Campo	Valor
Descripción	El usuario paga o registra el pago de una cotización vigente
Actor	Usuario final / Operador
Prioridad	Alta
Criterios de aceptación	- KYC aprobado - Cotización vigente - Transición de estado: `pendiente_pago` → `pagada`
Trazabilidad	CU-008

3.7 Envío y entrega¶

RF-027: Despachar envío¶

Campo	Valor
Descripción	El operador marca una consolidación pagada como `despachada` con número de guía maestra y transportista
Actor	Operador
Prioridad	Alta
Trazabilidad	CU-008

RF-028: Tracking del envío¶

Campo	Valor
Descripción	El sistema muestra el estado del envío en una línea de tiempo visual
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Estados: borrador, pendiente_kyc, pendiente_destinatario, pendiente_cotizacion, cotizado, pendiente_pago, pagado, en_preparacion, despachado_desde_almacen, en_transito_a_cuba, en_aduana, liberado_de_aduana, en_reparto, entregado, incidencia, cancelado
Trazabilidad	diagramas-uml/estados/estado-envio.md

RF-029: Notificar entrega¶

Campo	Valor
Descripción	Cuando el envío llega a estado `entregado`, el sistema notifica al usuario por push
Actor	Sistema
Prioridad	Alta
Trazabilidad	CU-008

3.8 KYC¶

RF-030: Iniciar KYC¶

Campo	Valor
Descripción	El usuario puede iniciar el proceso KYC desde el perfil o al intentar despachar por primera vez
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Bloqueo suave: el usuario puede seguir navegando y reportando - Bloqueo duro: no puede despachar, consolidar para envío ni pagar
Trazabilidad	CU-010

RF-031: Cargar documentos KYC¶

Campo	Valor
Descripción	El usuario selecciona tipo de documento, sube foto del frente, reverso (si aplica), selfie con documento, dirección de residencia en EE.UU.
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Formatos: JPG, PNG, PDF - Tamaño máx: 10 MB por archivo - Almacenamiento en bucket privado con URLs firmadas
Trazabilidad	CU-010

RF-032: Revisar KYC¶

Campo	Valor
Descripción	El operador revisa el KYC en el backoffice y lo aprueba, rechaza (con motivo) o requiere más información
Actor	Operador
Prioridad	Alta
Criterios de aceptación	- Aprobado → vigencia 10 años - Rechazado → usuario puede corregir y reenviar
Trazabilidad	datos/kyc.md

3.9 Servicios adicionales¶

RF-033: Solicitar servicio adicional¶

Campo	Valor
Descripción	El usuario puede solicitar inspección visual, prueba funcional, reempaque o devolución a un paquete específico
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Cada servicio tiene su propio ciclo de estados (ver estados.md)
Trazabilidad	modulos/servicios-cargos.md

RF-034: Cargar evidencia de servicio¶

Campo	Valor
Descripción	El operador sube fotos/videos como evidencia del servicio realizado
Actor	Operador
Prioridad	Alta
Criterios de aceptación	- Bucket privado con URLs firmadas - Log de acceso obligatorio
Trazabilidad	stack/almacenamiento-archivos.md

3.10 Notificaciones¶

RF-035: Notificaciones push¶

Campo	Valor
Descripción	El sistema envía push al usuario en eventos clave: compra reportada, paquete recibido, identificado, almacenado, próximo a vencer, consolidación creada, envío despachado, aduana, listo para entrega, devolución, incidencia, referido, crédito, nivel, tarjeta
Actor	Sistema
Prioridad	Alta
Criterios de aceptación	- Se ejecutan vía jobs en background - No bloquean requests
Trazabilidad	operaciones/riesgos.md

RF-036: Historial de notificaciones¶

Campo	Valor
Descripción	El usuario puede ver el historial completo de notificaciones con indicador de no leídas
Actor	Usuario final
Prioridad	Alta
Trazabilidad	flujos/pantallas-mvp.md

3.11 Módulo informativo de aduana¶

RF-037: Ver información de aduana¶

Campo	Valor
Descripción	La app muestra una sección educativa con: qué es un envío no comercial, límites y exenciones, calculadora rápida, artículos restringidos, cambios 2026
Actor	Usuario final
Prioridad	Alta
Criterios de aceptación	- Contenido administrable desde Django Admin - Fecha de última actualización visible - Fuente normativa visible (Res. 175/2022)
Trazabilidad	datos/aduana.md

3.12 Backoffice¶

RF-038: Colas operativas¶

Campo	Valor
Descripción	El backoffice muestra colas de: recepción, conciliación, KYC pendiente, servicios adicionales, consolidaciones por preparar, pagos pendientes, paquetes por vencer, devoluciones activas, incidencias
Actor	Operador
Prioridad	Alta
Trazabilidad	operaciones/backoffice.md

RF-039: Configuración del sistema¶

Campo	Valor
Descripción	El administrador puede editar tarifas, tutoriales, reglas de aduana, categorías, estados, requisitos de niveles, pool promocional, vencimiento de crédito, días gratis de almacenaje
Actor	Administrador
Prioridad	Alta
Trazabilidad	operaciones/backoffice.md

RF-040: Reportes y exportación¶

Campo	Valor
Descripción	El backoffice permite exportar reportes operativos a CSV/Excel y ver auditoría de cambios
Actor	Administrador
Prioridad	Media
Trazabilidad	operaciones/backoffice.md

3.13 Programa de referidos (Fase 2)¶

Los siguientes requisitos están definidos pero su implementación se difiere a Fase 2. La base de datos los contempla desde el día 1.

RF-041: Código de referido¶

Campo	Valor
Descripción	Cada usuario tiene un código único que puede compartir para invitar a otros
Prioridad	Media
Trazabilidad	crecimiento/modelo-crecimiento.md

RF-042: Red de referidos¶

Campo	Valor
Descripción	El usuario puede ver su red de referidos con ventanas individuales de 180 días
Prioridad	Media
Trazabilidad	crecimiento/modelo-crecimiento.md

RF-043: Niveles 1/2/3 dinámicos¶

Campo	Valor
Descripción	El sistema evalúa continuamente el nivel del usuario y puede subirlo o bajarlo
Prioridad	Media
Criterios de aceptación	- Job cada hora recalcula niveles
Trazabilidad	crecimiento/modelo-crecimiento.md

RF-044: Crédito y vencimiento¶

Campo	Valor
Descripción	El sistema acredita crédito por actividad de la red y lo vence según las reglas
Prioridad	Media
Criterios de aceptación	- Crédito no retirable, no transferible, no genera más crédito - Vencimiento configurable
Trazabilidad	crecimiento/modelo-crecimiento.md

RF-045: Tarjetas promocionales¶

Campo	Valor
Descripción	El usuario puede convertir crédito en tarjetas promocionales con vigencia trasladada
Prioridad	Media
Trazabilidad	crecimiento/modelo-crecimiento.md

3.14 Integraciones (Fase 2+)¶

ID	Requisito	Fase
RF-046	OCR de capturas de órdenes	2
RF-047	WhatsApp API para notificaciones	3
RF-048	Sistema de la agencia aliada (webhook/consulta)	2
RF-049	Integración con Stripe (Stripe Checkout + Webhooks) como pasarela de pago online	2
RF-050	Lectura de códigos de barras/QR en almacén (operador)	2
RF-051	Tracking de transportistas (UPS, USPS, FedEx)	2

Renumeración 2026-06-08

La numeración de esta sección se renumeró para eliminar duplicados con la matriz de trazabilidad. Anteriormente existían RF-046 a RF-051 pero algunos chocaban con IDs usados en otros módulos. La nueva numeración es la oficial.

Detalle de RF-049 — Integración con Stripe¶

Proveedor seleccionado: Stripe. Se elige Stripe Checkout por:

Cumplimiento PCI DSS out-of-the-box (no se manejan tarjetas directamente)
Soporte nativo de Webhooks firmados (Stripe-Signature)
SDK oficial en Python (stripe-python) y en Kotlin/Android
Cobertura de métodos de pago comunes en EE.UU. (tarjeta, Apple Pay, Google Pay)
Dashboard operativo y reporting incluidos

Flujo de la integración:

Backend crea una Stripe Checkout Session con amount, currency='usd', metadata={shipment_id, user_id, quote_id} y success_url + cancel_url de la app.
Backend persiste el checkout_session_id en payments.provider_reference con status='pendiente'.
App recibe el url de la Checkout Session y abre el WebView/Chrome Custom Tab.
Usuario completa el pago en la UI de Stripe.
Stripe envía webhook a /api/v1/webhooks/stripe/ con eventos checkout.session.completed o payment_intent.succeeded.
Backend verifica la firma con STRIPE_WEBHOOK_SECRET antes de procesar.
Backend actualiza Payment.status='completado', provider_reference con el payment_intent_id, y transiciona Shipment.status='pagado'.

Requisitos no funcionales derivados:

RNF-049: La verificación de firma del webhook es obligatoria; rechazar cualquier evento sin firma válida.
RNF-050: Las claves STRIPE_SECRET_KEY y STRIPE_WEBHOOK_SECRET se almacenan en variables de entorno, nunca en código.
RNF-051: Idempotencia: el handler de webhook debe ser idempotente (un mismo event.id no se procesa dos veces).
RNF-052: Modo test durante MVP-beta; switch a live solo en lanzamiento a producción.
RNF-053: Reintentos de webhook: Stripe reintenta hasta 3 días; el handler debe responder 2xx rápido (< 5 s) y procesar async si es pesado.

Configuración necesaria:

Variable	Descripción	Entorno
`STRIPE_SECRET_KEY`	Clave secreta de la API (test o live)	Backend
`STRIPE_PUBLISHABLE_KEY`	Clave pública (solo cliente)	App
`STRIPE_WEBHOOK_SECRET`	Secreto para verificar firma de webhooks	Backend
`STRIPE_API_VERSION`	Versión de la API (ej. `2024-06-20`)	Backend

Entornos:

Entorno	Clave	Modo
Local (desarrollo)	`sk_test_...`	Test
CI	`sk_test_...`	Test
Staging	`sk_test_...`	Test
Producción	`sk_live_...`	Live

3.15 Reportes administrativos (Fase 2)¶

Reportes operativos del backoffice para administración y dirección. La base de datos ya contempla los agregados necesarios; las vistas y endpoints se difieren a Fase 2.

RF-052: Reporte diario de paquetes recibidos¶

Campo	Valor
Descripción	El backoffice muestra un reporte agregado diario con cantidad de paquetes recibidos, recibidos_sin_identificar, conciliados, en_incidencia, etc.
Actor	Administrador
Prioridad	Media (Fase 2)
Criterios de aceptación	- Endpoint `GET /api/v1/admin/reports/daily?date=YYYY-MM-DD` - Filtros por fecha y operador - Exportable a CSV
Trazabilidad	operaciones/kpis-reportes.md

RF-053: Reporte de ingresos por período¶

Campo	Valor
Descripción	El backoffice muestra un reporte de ingresos agregados por período (diario, semanal, mensual) desglosado por concepto (envío, almacenaje, servicios, aduana).
Actor	Administrador
Prioridad	Media (Fase 2)
Criterios de aceptación	- Endpoint `GET /api/v1/admin/reports/revenue?from=...&to=...` - Desglose por `charges.category` - Exportable a CSV/Excel
Trazabilidad	operaciones/kpis-reportes.md

RF-054: Reporte de incidencias abiertas/cerradas¶

Campo	Valor
Descripción	El backoffice muestra un reporte de incidencias con métricas de apertura, cierre, tiempo medio de resolución y distribución por tipo.
Actor	Administrador
Prioridad	Media (Fase 2)
Criterios de aceptación	- Endpoint `GET /api/v1/admin/reports/incidents?status=...&type=...` - Tiempo medio de resolución calculado - Exportable a CSV/Excel
Trazabilidad	operaciones/kpis-reportes.md, flujos/incidencias-reclamos.md

RF-055: Reporte de paquetes almacenados y próximos a vencer¶

Campo	Valor
Descripción	El backoffice muestra la ocupación actual del almacén: paquetes por zona/estante, días en almacén, próximos a vencer (≤ 3 días) y vencidos.
Actor	Operador, Administrador
Prioridad	Alta (MVP)
Criterios de aceptación	- Endpoint `GET /api/v1/admin/reports/storage` - Filtros por estado y días - Listado paginado ordenado por días descendente
Trazabilidad	operaciones/kpis-reportes.md, datos/politica-almacenamiento.md

RF-055 incluido en MVP

A diferencia de RF-052 a RF-054, este reporte es necesario en MVP para la operación diaria de almacén.

4. Requisitos no funcionales (RNF)¶

4.1 Rendimiento¶

ID	Requisito	Métrica
RNF-001	Tiempo de respuesta API móvil	< 500 ms (p95) para operaciones comunes
RNF-002	Listados paginados	Máximo 50 registros por página
RNF-003	Carga inicial de la app	< 3 s en 4G
RNF-004	Disponibilidad	≥ 99% en horario operativo (8am-8pm EST)

4.2 Seguridad¶

ID	Requisito
RNF-005	HTTPS obligatorio en toda la comunicación app-API
RNF-006	Cifrado en reposo para archivos KYC (MinIO con cifrado)
RNF-007	URLs firmadas con TTL ≤ 5 min para archivos privados
RNF-008	Log de auditoría obligatorio para acceso a KYC
RNF-009	Rate limiting: login 5/min, OTP 3/min, endpoints 60/min
RNF-010	Cifrado de secretos (contraseñas, API keys) — no en texto plano
RNF-011	Separación de roles: usuario, operador, admin, sysadmin
RNF-012	Separación de buckets: KYC, fotos, evidencias, público

4.3 Usabilidad¶

ID	Requisito
RNF-013	Mobile-first; optimización para pantallas 5"-7"
RNF-014	Tipografía clara, contraste WCAG AA mínimo
RNF-015	Textos cortos y directos, sin jerga logística
RNF-016	Acciones críticas accesibles en ≤ 2 toques desde el dashboard
RNF-017	Manejo de errores claro y accionable (no mensajes genéricos)

4.4 Mantenibilidad¶

ID	Requisito
RNF-018	Toda la lógica de negocio en `core/services/` (compartida Django + FastAPI)
RNF-019	Django es el dueño de los modelos y migraciones; FastAPI no crea tablas
RNF-020	Cobertura de tests ≥ 70% en código nuevo de construcción
RNF-021	Logs estructurados con correlation ID por request
RNF-022	Documentación actualizada por cada cambio funcional

4.5 Escalabilidad¶

ID	Requisito
RNF-023	Arquitectura stateless en API pública
RNF-024	Cache de tarifas y categorías en Redis con TTL definido
RNF-025	Locks distribuidos en Redis para procesos críticos (identificador, pago, consolidación)

4.6 Confiabilidad¶

ID	Requisito
RNF-026	Backups diarios de PostgreSQL con retención 30 días
RNF-027	Replicación de BD (master-replica)
RNF-028	Plan de recuperación documentado (RPO ≤ 24h, RTO ≤ 4h)
RNF-029	Transacciones ACID para operaciones críticas

4.7 Compatibilidad¶

ID	Requisito
RNF-030	App Android: minSdk 24 (Android 7.0), targetSdk 35
RNF-031	App iOS (Fase 2): iOS 15+
RNF-032	Navegadores soportados (backoffice): Chrome, Firefox, Safari últimas versiones

4.8 Internacionalización¶

ID	Requisito
RNF-033	Idioma: español (Cuba) en MVP
RNF-034	Zona horaria: EST (UTC-5) por defecto
RNF-035	Moneda: USD como base

4.9 Procesos en background¶

ID	Requisito
RNF-036	Notificaciones push vía jobs (no bloquean requests)
RNF-037	Job diario de vencimiento de almacenaje (9am EST)
RNF-038	Expiración de OTP: 5 minutos
RNF-039	Expiración de crédito: job diario
RNF-040	Recálculo de niveles: cada hora

4.10 Experiencia offline¶

ID	Requisito
RNF-041	Si el token expira, redirigir a login sin perder contexto
RNF-042	Subida de foto fallida: encolar localmente y reintentar
RNF-043	Sin internet: mostrar estado offline; acciones se encolan localmente
RNF-044	Permiso de cámara denegado: mensaje claro con CTA a settings

5. Restricciones de diseño¶

ID	Restricción
DR-001	El modelo de datos vive en Django; FastAPI no crea tablas propias
DR-002	Lógica de negocio en `core/services/`; ni Django views ni FastAPI endpoints la duplican
DR-003	Los estados del sistema son los definidos en estados.md; no se permiten estados inventados
DR-004	Solo se registran personas en EE.UU. con teléfono +1
DR-005	El identificador de casillero se calcula con Mod-10 (no aleatorio ni secuencial sin verificación)
DR-006	Los archivos KYC nunca son públicos
DR-007	Cada cambio de estado genera evento en `package_events` con timestamp y autor
DR-008	Toda configuración operativa (tarifas, categorías, tutoriales) es administrable desde Django Admin

6. Apéndices¶

6.1 Trazabilidad de requisitos a casos de uso¶

RF	Caso de uso
RF-001 a RF-007	CU-001, CU-002, CU-003
RF-008 a RF-012	CU-004
RF-013 a RF-017	CU-005
RF-018 a RF-020	CU-009
RF-021 a RF-023	CU-006
RF-024 a RF-026	CU-007
RF-027 a RF-029	CU-008, CU-015
RF-030 a RF-032	CU-010
RF-033 a RF-034	CU-011
RF-035 a RF-037	CU-016
RF-038 a RF-040	(acciones de backoffice — no requieren CU documentado individualmente)
RF-041 a RF-045	(Fase 2 — programa de referidos — sin CU detallado)
RF-046 a RF-051	Integraciones (Fase 2+) — ver CU-014, CU-015, CU-013
RF-052 a RF-055	Reportes administrativos (Fase 2, excepto RF-055 que es MVP)

6.2 Glosario¶