FCD App (Flutter)

Aplicación mobile-first de Fraternidad del Círculo Dorado, construida en Flutter y orientada a iPhone, iPad y teléfonos/tabletas Android.

Tabla de contenido

• Estado actual
• Stack principal
• Funcionalidades implementadas
• Navegación principal
• Backend y configuración
• Requisitos
• Instalación y ejecución
• Comandos útiles
• Calidad y pruebas
• Estructura principal
• Documentación adicional
• Limitaciones actuales
• Licencia

Estado actual (mayo 2026)

El proyecto está en operación con autenticación real, consumo de backend productivo, cursos/lecciones, reproducción multimedia, descargas locales, favoritos por usuario, asistente IA, registro y cuenta.

Stack principal

• Flutter + Dart (^3.11.4).
• Dio para HTTP, descargas y refresh de tokens.
• Provider + ChangeNotifier para estado global de sesión.
• FlutterSecureStorage para credenciales (tokens y contraseña).
• local_auth para autenticación biométrica o del dispositivo.
• better_player_plus / just_audio para video y audio.
• webview_flutter para documentos (Google Docs Viewer).
• shared_preferences para favoritos y progreso local.

Funcionalidades implementadas

Sesión, registro y autenticación

• Login real contra backend (POST /login).
• Registro de usuarios (POST /user) desde la app.
• Restauración de sesión con refresh token (POST /refresh).
• Bootstrap de sesión al iniciar (SessionController.bootstrap).
• Logout y limpieza de sesión persistida.
• Quick-login con biometría o autenticación del dispositivo.
• Manejo automático de refresh de token en ApiClient ante 401/403.

Cursos y aprendizaje

• Listado de cursos del usuario (GET /course/MyCourses/{userId}).
• Catálogo general (GET /course/All/0) con búsqueda por texto y filtros por categoría.
• Detalle de curso (GET /course/0/{courseId}).
• Carga de temario del curso con límite alto para evitar truncamientos (GET /lesson/course-lessons/{courseId}/{maxLessons}).
• Marcado de lección completada y lectura de progreso:
  • POST /lesson/setLessonUserStatus
  • GET /lesson/getCompletedLessonsByUser/{userId}/{courseId}

Reproductor de lecciones

• Video con better_player_plus (controles avanzados y caché).
• Audio con just_audio.
• Documentos con WebView + visor de Google Docs.
• Navegación lección a lección y continuidad de progreso.
• Persistencia de posición multimedia para retomar contenido.

IA

• Carga de prompts por categoría (GET /prompts).
• Historial de conversaciones (GET /chats/{userId}).
• Persistencia de mensajes (POST /chats/{chatId}/messages).
• Respuesta de asistente (POST /chatAI/chatBot).
• Control de acceso por plan o trial:
  • GET /ai-plan/user-check?user_id=...
  • POST /ai-trial/check

Favoritos y descargas

• Favoritos de lecciones persistidos localmente por usuario (FavoritesStorage).
• Descarga de recursos al dispositivo (DownloadRepository).
• Historial local de descargas con limpieza de archivos faltantes.
• Apertura de archivos descargados dentro de la app.

Cuenta

• Vista de datos del usuario.
• Validación de acceso a IA.
• Logout.

Navegación principal

La app autenticada vive en HomeShell y expone 6 secciones:

• Mis Cursos
• Catálogo
• IA
• Favoritos
• Descargas
• Cuenta

Comportamiento adaptativo:

• Móvil: NavigationBar inferior.
• Tablet (shortestSide >= 600): NavigationRail lateral.

Backend y configuración

Base URL por defecto:

• https://circulo-dorado.org:6007/api

Se puede sobreescribir con --dart-define:

flutter run --dart-define=FCD_API_BASE_URL=https://tu-backend/api

Requisitos

• Flutter stable (compatible con Dart ^3.11.4).
• Android Studio / Xcode para build nativo.
• Dispositivo físico o emulador con conexión a internet.

Instalación y ejecución

Instalar dependencias:

flutter pub get

Ejecutar en dispositivo conectado:

flutter run

Comandos útiles

Generar APK o App Bundle:

flutter build apk
flutter build appbundle

Generar build iOS (requiere Xcode):

flutter build ipa

Actualizar íconos (usa assets/images/logo.jpg):

flutter pub run flutter_launcher_icons

Calidad y pruebas

flutter analyze
flutter test --no-test-assets

Estructura principal

• lib/main.dart: bootstrap inicial y provider raíz.
• lib/src/app.dart: gate de splash/login/home.
• lib/src/state/session_controller.dart: estado global de sesión.
• lib/src/core: cliente HTTP, configuración, storage, tema y utilidades.
• lib/src/features/auth: login, biometría y registro.
• lib/src/features/courses: cursos, resumen y reproductor.
• lib/src/features/catalog: catálogo completo y filtros.
• lib/src/features/ai: chat IA y validación de acceso.
• lib/src/features/favorites: vista y apertura de lecciones favoritas.
• lib/src/features/downloads: descargas e historial local.
• lib/src/features/account: datos de usuario y cierre de sesión.
• lib/src/features/home: shell de navegación adaptativa.

Documentación adicional

• docs/fcd_flutter_code_walkthrough.md: guía detallada del código.
• docs/fcd_flutter_code_walkthrough.pdf: versión PDF.

Limitaciones actuales

• Flujo de recuperación de contraseña no implementado en app.
• El contenido visible depende de permisos/compras del usuario en backend.

Licencia

Ver LICENSE.