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.

CU-010: Completar KYC (verificación de identidad)¶

Caso de uso detallado para que el usuario complete el proceso de verificación de identidad y para que el operador lo revise.

Metadatos¶

Campo	Valor
ID	CU-010
Nombre	Completar KYC (verificación de identidad)
Actor primario	Usuario Final (carga) + Operador (revisa)
Módulo	KYC
Prioridad	Alta (MVP)
Frecuencia esperada	Baja (1 vez cada 10 años por usuario)
Trazabilidad SRS	RF-030, RF-031, RF-032

Descripción¶

El usuario, al intentar despachar por primera vez (o desde el perfil), inicia el proceso KYC: selecciona tipo de documento, sube fotos, completa dirección de residencia en EE.UU. y envía a revisión. El operador revisa y aprueba, rechaza (con motivo) o requiere más información.

Precondiciones¶

El usuario tiene cuenta activa con phone_verified = true.
El usuario aún no tiene KYC aprobado (o quiere renovarlo porque venció).

Postcondiciones¶

Aprobado: - Se crea/actualiza un KycRecord con status = aprobado, approved_at = now, expires_at = now + 10 años. - El usuario puede despachar, consolidar para envío, pagar y usar crédito. - Se registra reviewed_by (operador) y reviewed_at.

Rechazado: - status = rechazado con rejection_reason. - El usuario ve el motivo y puede corregir + reenviar.

Requiere más información: - status = requiere_mas_informacion con el campo faltante. - El usuario completa lo solicitado.

Flujo principal¶

Parte A: Usuario carga KYC¶

El usuario toca Iniciar verificación desde el banner del dashboard o el perfil.
El sistema muestra la pantalla KYC - Paso 1: Bienvenida, con explicación del proceso.
El usuario toca Comenzar.
Paso 2: Tipo de documento.
El usuario selecciona entre: Pasaporte, Carné de identidad, Licencia de conducir.
Paso 3: Foto del documento.
Frente (obligatorio).
Reverso (obligatorio si el documento lo tiene).
Paso 4: Selfie con documento.
El usuario toma una foto sosteniendo el documento abierto, con su rostro visible.
Paso 5: Datos de residencia en EE.UU..
Dirección completa.
Estado (dropdown con los 50 estados + territorios).
Código postal.
Paso 6: Confirmación.
El usuario revisa todo y toca Enviar a revisión.
El sistema:
Crea un KycRecord con status = enviado.
Sube las fotos a MinIO (bucket kyc-documents, privado, con URLs firmadas).
Registra submitted_at = now.
Notifica al equipo de revisión.
Muestra pantalla de éxito: "Estamos verificando tu identidad. Te notificaremos en 24 h."

Parte B: Operador revisa¶

El operador accede a la cola KYC pendiente de revisión en el backoffice.
Selecciona un KYC enviado.
Ve los datos del usuario y del documento.
Compara selfie con foto del documento.
Valida la dirección de residencia.
Decide:
- Aprobar:
- Estado → aprobado
- Registra reviewed_by (su user_id), reviewed_at = now
- Calcula expires_at = now + 10 años
- Push al usuario: "Tu verificación fue aprobada. Ya puedes despachar."
- Rechazar:
- Estado → rechazado
- Ingresa rejection_reason (motivo obligatorio, ej. "Documento ilegible", "Selfie no coincide con documento", "Dirección no válida")
- Push al usuario: "Tu verificación fue rechazada. Motivo: {x}. Corrige y reenvía."
- Requiere más información:
- Estado → requiere_mas_informacion
- Ingresa el campo o documento faltante
- Push al usuario: "Necesitamos información adicional: {detalle}."

Parte C: Usuario corrige (si fue rechazado o requiere más info)¶

El usuario accede al banner del dashboard o perfil.
Toca Corregir y reenviar.
El sistema muestra los pasos nuevamente, con los datos cargados (excepto los que se pidió corregir).
El usuario corrige lo necesario y reenvía.
Vuelve al paso 10 con status = enviado (nueva revisión).

Flujos alternativos¶

FA-1: KYC vencido (renovación)¶

Si el KYC aprobado tiene expires_at < now:
El estado pasa automáticamente a vencido (job diario).
El usuario ve un banner: "Tu verificación venció. Renuévala para seguir operando."
El proceso es idéntico a KYC nuevo, pero con un KycRecord actualizado en lugar de creado.

FA-2: KYC bloqueado manual¶

Si el operador bloquea manualmente al usuario (User.is_active = false):
El KYC se marca como bloqueado_manual.
El usuario no puede hacer nada en el sistema.
Solo un admin puede desbloquear.

FA-3: Foto del documento ilegible¶

Si la foto del documento está borrosa, cortada o sin reflejos no legibles:
El operador marca requiere_mas_informacion con motivo: "La foto del documento no es legible. Sube una nueva foto clara."

FA-4: Selfie no coincide¶

Si la selfie no muestra claramente el rostro o no coincide con el documento:
El operador marca requiere_mas_informacion: "La selfie no es clara o no coincide con el documento. Tómala de nuevo con ambos elementos visibles."

FA-5: Dirección no válida¶

Si la dirección no es verificable (no existe en USPS, formato incorrecto):
El operador marca requiere_mas_informacion: "La dirección no es válida. Verifica el formato y vuelve a ingresar."

FA-6: Usuario sube fotos de más de 10 MB¶

El cliente valida en el front (Fase 2 con cámara nativa) y rechaza.
Si pasa al backend, el servidor valida y devuelve FILE_TOO_LARGE.

FA-7: KYC revocado por admin¶

Un admin puede revocar un KYC aprobado (por fraude detectado, etc.).
Esto marca el KYC como bloqueado_manual y desactiva al usuario.

Excepciones¶

Excepción	Causa	Manejo
`INVALID_DOCUMENT_TYPE`	Tipo no soportado	Mostrar opciones válidas
`MISSING_REQUIRED_PHOTO`	Faltan fotos obligatorias	Bloquear envío
`FILE_TOO_LARGE`	> 10 MB	Mensaje con límite
`INVALID_FILE_FORMAT`	No es JPG/PNG/PDF	Mensaje con formatos aceptados
`KYC_ALREADY_APPROVED`	Intentar iniciar KYC nuevo con uno aprobado	Mensaje "Ya tienes KYC aprobado"
`REVIEWER_NOT_AUTHORIZED`	Operador sin permisos	Bloquear acción

Reglas de negocio aplicables¶

RN-29 (KYC no bloquea prealerta): el usuario puede reportar compras y ver paquetes sin KYC aprobado. Ver kyc.md.
RN-30 (KYC bloquea despacho): no se puede despachar, consolidar para envío, pagar ni usar crédito. Ver kyc.md.
RN-31 (Vigencia 10 años): expires_at = approved_at + 10 años. Ver kyc.md.
RN-32 (Archivos privados): KYC en bucket privado con URLs firmadas TTL 5 min. Ver almacenamiento-archivos.md.
RN-33 (Log de acceso): cada lectura de archivo KYC se registra. Ver almacenamiento-archivos.md.

Criterios de aceptación¶

El usuario puede completar el KYC en menos de 5 minutos.
Las fotos se validan en formato y tamaño antes de aceptar.
El bucket KYC es privado y solo accesible con URL firmada.
El operador puede aprobar, rechazar (con motivo) o requerir más info.
El motivo de rechazo es obligatorio.
El usuario recibe push en cada cambio de estado.
Un KYC aprobado tiene vigencia de 10 años.
Un KYC vencido bloquea el despacho pero permite la prealerta.
Los intentos de KYC duplicado se rechazan.

Diagrama de actividad¶

Parte A — Usuario¶

flowchart TD
    A["Toca 'Iniciar KYC'"] --> B["Pantalla bienvenida"]
    B --> C["Paso 2: Tipo documento"]
    C --> D["Paso 3: Fotos"]
    D --> E["Paso 4: Selfie"]
    E --> F["Paso 5: Dirección EE.UU."]
    F --> G["Paso 6: Confirmar"]
    G --> H["Crea KycRecord status=enviado"]
    H --> I["Sube fotos a MinIO privado"]
    I --> J["Notifica al equipo de revisión"]
    J --> K["Pantalla 'En revisión'"]

Parte B — Operador¶

flowchart TD
    A["Cola KYC pendiente"] --> B["Selecciona un KYC"]
    B --> C["Ve datos y fotos"]
    C --> D{"¿Aprobado?"}
    D -- Sí --> E["Status=aprobado, expires=+10años"]
    D -- No --> F["Ingresa motivo"]
    F --> G{"¿Rechazado o requiere más?"}
    G -- "Rechazado" --> H["Status=rechazado"]
    G -- "Más info" --> I["Status=requiere_mas_informacion"]
    E --> J["Push al usuario"]
    H --> J
    I --> J

Diagrama de estados (KYC)¶

stateDiagram-v2
    [*] --> sin_iniciar
    sin_iniciar --> borrador: usuario carga datos parciales
    borrador --> enviado: usuario envía
    sin_iniciar --> enviado: usuario envía completo
    enviado --> en_revision: operador toma
    en_revision --> aprobado: operador aprueba
    en_revision --> rechazado: operador rechaza
    en_revision --> requiere_mas_informacion: operador requiere
    rechazado --> enviado: usuario corrige y reenvía
    requiere_mas_informacion --> enviado: usuario completa
    aprobado --> vencido: pasan 10 años
    aprobado --> bloqueado_manual: admin bloquea
    vencido --> enviado: usuario renueva
    bloqueado_manual --> [*]
    aprobado --> [*]
    rechazado --> [*]

Pruebas asociadas¶

PT-140: Iniciar KYC nuevo
PT-141: Cargar documento (pasaporte / CI / licencia)
PT-142: Foto borrosa → operador requiere nueva foto
PT-143: Selfie no coincide → operador requiere nueva selfie
PT-144: Dirección inválida → operador requiere corrección
PT-145: Aprobación correcta con vigencia 10 años
PT-146: Rechazo con motivo → push al usuario
PT-147: Requerir más info → push al usuario
PT-148: Corrección tras rechazo → reenvío
PT-149: Renovación de KYC vencido
PT-150: Bloqueo manual por admin
PT-151: Intento de despacho con KYC vencido (debe fallar)
PT-152: Intento de prealerta con KYC vencido (debe pasar)
PT-153: Archivos KYC solo accesibles con URL firmada
PT-154: Log de acceso a archivos KYC
PT-155: Validación de tamaño y formato de archivos