Ceditran Club

1. Descripción Detallada del Proyecto y Objetivos del Dueño
Nombre de la App: CEDITRAN Club
Objetivo Principal: Desarrollar una aplicación web de programa de lealtad para clientes de CEDITRAN. El sistema permitirá a los clientes acumular puntos por sus compras y canjearlos por recompensas (cupones de descuento), mientras que el personal autorizado de CEDITRAN podrá gestionar el registro de nuevos clientes, la asignación de puntos y supervisar la actividad del programa.
Funcionalidades Clave Deseadas:
Acceso para Personal Autorizado:
Un sistema de login simple para el personal (inicialmente con correo/contraseña).
Panel de administrador para gestionar clientes y el programa.
Registro de Nuevos Clientes:
Formulario de registro para nuevos clientes (nombre completo, email, teléfono, fecha de nacimiento, DNI).
Formulario de registro manual para personal (con creación de contraseña para el cliente).
Opción de registro/login para clientes usando Google.
Perfil del Cliente (Visible para el Cliente y el Personal):
Visualización de datos del cliente: nombre, email, teléfono, fecha de nacimiento, DNI.
Visualización del saldo de puntos actual.
Asignación de Puntos (Realizada por el Personal):
Campo numérico para ingresar el monto de compra en PEN.
Botón para asignar puntos (regla: 1 PEN gastado = 1 punto ganado).
Canje de Puntos (Realizado por el Cliente o el Personal en nombre del Cliente):
Visualización de opciones de canje (ej. Cupón de S/X por Y puntos).
Botón para canjear puntos por cupones de descuento.
Historial de Transacciones (Visible para el Cliente y el Personal):
Lista simplificada de puntos ganados y canjeados, con fecha y descripción.
Simulación de Escaneo QR (Para Personal):
Funcionalidad para simular un escáner qr (o usar cámara) para ingresar el dni de un cliente.
Redirección al perfil del cliente correspondiente para gestionar puntos.
Portal del Cliente:
Login para clientes (correo/contraseña y Google).
Dashboard del cliente con su saldo de puntos y acceso a QR personal, canje e historial.
Visualización de su código QR personal para identificación.
Pautas de Estilo Generales:
Color Primario: Azul suave (#7AB6D6)
Color de Fondo: Azul muy claro (#F0F8FF)
Color de Acento: Naranja suave (#f9b314)
Fuente: 'PT Sans' (sans-serif) para cuerpo y titulares.
Diseño: Minimalista, claro, con divisiones bien definidas y fácil navegación. Uso de iconos simples y claros.
2. Stack Tecnológico del Prototipo Actual
El prototipo se ha desarrollado utilizando la siguiente pila tecnológica:
Framework Frontend: Next.js (versión 15.x, utilizando App Router)
Librería UI: React (versión 18.x)
Lenguaje: TypeScript
Estilos CSS: Tailwind CSS
Componentes UI: ShadCN UI (pre-configurados en components/ui)
Backend y Base de Datos: Firebase
Authentication: Para manejo de usuarios (email/contraseña y Google Sign-In).
Cloud Firestore: Como base de datos NoSQL para almacenar perfiles de usuario y transacciones de puntos.
Manejo de Formularios: react-hook-form con zod para validación.
Manejo de Fechas: date-fns
Iconos: lucide-react
3. Problemas Técnicos y Errores del Prototipo
Durante el desarrollo del prototipo, se han encontrado los siguientes problemas técnicos principales:
Error Persistente Principal: FirebaseError: Failed to get document because the client is offline

Descripción: Este error ha sido el más recurrente y bloqueante. Indica que la aplicación cliente (navegador) no puede establecer o mantener una conexión con los servidores de Cloud Firestore. Esto impide cualquier operación de lectura (ej. GetDoc para obtener datos de perfil) o escritura (ej. SetDoc, updateDoc, addDoc para registrar usuarios o transacciones) en la base de datos.
Impacto: Prácticamente todas las funcionalidades que dependen de datos dinámicos (perfiles, puntos, historial) se ven afectadas. El flujo de login y registro se interrumpe si no se puede leer/escribir el tipoUsuario o los datos del nuevo usuario en Firestore.
Causas Investigadas (sin resolución definitiva en el prototipado):
Configuración de firebaseConfig en src/lib/firebase.ts: Se verificó múltiples veces. La última configuración proporcionada por el dueño de la app coincide con la captura de pantalla de su consola de Firebase. Sin embargo, una observación importante es que la apiKey proporcionada (AIzaSyBPhKlvD2wDv9XG399xIhz2Zdz92MrDzw0) tiene un patrón que a veces es usado por Firebase como un placeholder genérico en su documentación o ejemplos. Es crítico confirmar que esta apiKey es la que la consola de Firebase genera específicamente para el proyecto ceditran-club-nsn9t y la aplicación web registrada dentro de ese proyecto. Si es un placeholder, ninguna API de Firebase funcionará.
Estado de Cloud Firestore: Se confirmó visualmente (mediante captura de pantalla) que la colección usuarios existe en la base de datos Firestore del proyecto. Se recomendó verificar el estado de la "Cloud Firestore API" en la Google Cloud Console asociada al proyecto.
Conexión a Internet del Cliente: Se asumió que el cliente tiene conexión, pero problemas de red intermitentes o locales pueden causar esto.
Firewalls, Proxies, Extensiones del Navegador: Estos elementos del entorno del cliente podrían estar bloqueando las conexiones a los dominios de Firebase/Google Cloud.
Problema Secundario: UI se Queda en Estado de "Cargando" Indefinidamente

Descripción: Como consecuencia directa del error "client is offline", las operaciones asíncronas (especialmente las llamadas a Firestore) no se resuelven. Si el manejo del estado de carga (isLoading) no contempla adecuadamente estos fallos de red persistentes, la UI puede quedarse mostrando un indicador de carga sin progresar.
Impacto: El usuario no puede interactuar con la aplicación y no recibe retroalimentación clara del problema subyacente (más allá de la consola). Se intentó mejorar esto en el código fuente añadiendo bloques finally para resetear los estados de carga, pero esto no soluciona el problema de red fundamental.
Ejemplos:
Después del login, si no se puede obtener el tipoUsuario de Firestore, la redirección al dashboard correspondiente no ocurre o la página de destino se queda cargando.
Después del registro, si no se puede guardar el documento del nuevo usuario en Firestore, la redirección o el siguiente paso en el flujo no se completa.
Error Ocasional (menos frecuente tras ajustes): FirebaseError: Firebase: Error (auth/invalid-credential)

Descripción: Este error indica que las credenciales proporcionadas durante el inicio de sesión (email/contraseña) son incorrectas, la cuenta no existe en Firebase Authentication, o la cuenta ha sido deshabilitada.
Impacto: Impide el inicio de sesión.
Causas: Puede ser un error genuino al ingresar las credenciales o también un síntoma de una firebaseConfig incorrecta (particularmente apiKey o authDomain erróneos que apuntan a un proyecto incorrecto).
4. Estado Actual del Prototipo y Funcionalidades Implementadas

Autenticación:
Flujo de login con email/contraseña: Implementado, pero afectado por el problema de Firestore para obtener el rol del usuario.
Flujo de registro de clientes con email/contraseña: Implementado (Firebase Auth funciona), pero afectado por el problema de Firestore para guardar los datos del perfil del cliente.
Login/Registro con Google: Implementado (Firebase Auth funciona), pero afectado por el problema de Firestore para guardar/recuperar los datos del perfil del cliente.
Recuperación de contraseña: Implementada.
Estructura de Navegación y Layouts:
Layouts separados para portal de cliente y panel de administrador.
Headers con navegación básica y opción de logout.
Panel de Administrador:
Dashboard principal (UI estática).
Registro manual de nuevos clientes (formulario implementado, guardado en Firestore afectado).
Escaneo/Búsqueda de clientes por dni (ui implementada, funcionalidad de cámara básica presente, obtención de datos del cliente de firestore afectada).
Perfil del cliente (vista de personal): UI implementada, carga de datos, asignación y canje de puntos dependen de Firestore y están afectados.
Visualización de puntos de todos los clientes: UI implementada, carga de datos de Firestore afectada.
Portal del Cliente:
Dashboard del cliente: UI implementada, carga de datos de Firestore afectada.
Visualización de código QR personal: Implementado (generación de qr con servicio externo basada en dni/uid del cliente, carga de datos del cliente afectada).
Canje de puntos: UI implementada, lógica de canje y actualización de puntos dependen de Firestore y están afectados.
Historial de puntos: UI implementada, carga de transacciones de Firestore afectada.
Tipos de Datos: Definidos en src/types/index.ts para Usuario (Firestore) y Customer/Transaction (UI).
5. Recomendaciones Clave para el Programador que Retome el Proyecto

Prioridad Absoluta: Diagnosticar y Resolver el Error client is offline:

Verificación Exhaustiva de firebaseConfig: Confirmar cada clave y valor en src/lib/firebase.ts con la configuración activa del proyecto Firebase del cliente. Prestar especial atención a la apiKey y projectId. Considerar la posibilidad de que la apiKey actualmente en uso sea un placeholder si el cliente no ha podido confirmar que es la específica de su app web.
Revisar el Estado de "Cloud Firestore API": Asegurar que esta API esté habilitada en la Google Cloud Console para el projectId correspondiente.
Prueba de Conexión Mínima: Crear un script o una pequeña aplicación html/js separada con la misma firebaseconfig para intentar una operación simple de lectura/escritura en firestore. Esto ayudará a aislar si el problema es del entorno del proyecto Next.js o de la configuración/red en general.
Inspección de Red: Usar las herramientas de desarrollador del navegador (pestaña Network) para ver si las solicitudes a firestore.googleapis.com se están realizando, si son bloqueadas, o si devuelven algún error específico.
Reglas de Seguridad de Firestore: Aunque el error es "offline", revisar que las reglas de seguridad no sean excesivamente restrictivas al punto de causar un comportamiento inesperado (aunque lo normal sería un "permission-denied").
Entorno de Prueba: Probar la aplicación desde diferentes redes y dispositivos si es posible para descartar problemas de red local o de la máquina de desarrollo.
Robustecer Manejo de Errores y Estados de Carga:

Una vez resuelta la conexión a Firestore, revisar todos los componentes que realizan operaciones asíncronas. Asegurar que los estados de carga (isLoading) se manejen correctamente y que se proporcione retroalimentación adecuada al usuario en caso de errores (no solo console.log).
Pruebas Exhaustivas de Flujos de Usuario:

Probar cada flujo: login (ambos roles), registro (cliente y manual por admin), asignación de puntos, canje de puntos, visualización de perfiles, historial, etc.
Consistencia de Datos:

Verificar que los datos se guardan y leen de Firestore con los tipos correctos (ej. Timestamp de Firestore vs. String ISO en el cliente).
Revisar Persistencia de Sesión y Roles:

Firebase Auth maneja la persistencia de la sesión de autenticación. Asegurar que la información del rol del usuario (tipoUsuario) y su UID se gestionen consistentemente (ej. Usando localStorage de forma segura o volviendo a consultar Firestore si es necesario tras la carga de la app).