Xeewy/TravelMate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance model and service documentation with detailed comments and descriptions

Browse Source 
- Updated Group, Trip, User, and other model classes to include comprehensive documentation for better understanding and maintainability.
- Improved error handling and logging in services, including AuthService, ErrorService, and StorageService.
- Added validation and business logic explanations in ExpenseService and TripService.
- Refactored method comments to follow a consistent format across the codebase.
- Translated error messages and comments from French to English for consistency.
This commit is contained in:
Dayron
2025-10-30 15:56:17 +01:00
parent 1eeea6997e
commit 2faf37f145
46 changed files with 2656 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
lib/blocs/auth/auth_bloc.dart
View File

@@ -1,11 +1,38 @@
/// Business Logic Component for managing authentication state.
///
/// The [AuthBloc] handles authentication-related events and manages the
/// authentication state throughout the application. It coordinates with
/// the [AuthRepository] to perform authentication operations and emits
/// appropriate states based on the results.
///
/// Supported authentication methods:
/// - Email and password authentication
/// - Google Sign-In
/// - Apple Sign-In
/// - Password reset functionality
///
/// This bloc handles the following events:
/// - [AuthCheckRequested]: Verifies current authentication status
/// - [AuthSignInRequested]: Processes email/password sign-in
/// - [AuthSignUpRequested]: Processes user registration
/// - [AuthGoogleSignInRequested]: Processes Google authentication
/// - [AuthAppleSignInRequested]: Processes Apple authentication
/// - [AuthSignOutRequested]: Processes user sign-out
/// - [AuthPasswordResetRequested]: Processes password reset requests
import 'package:flutter_bloc/flutter_bloc.dart';
import '../../repositories/auth_repository.dart';
import 'auth_event.dart';
import 'auth_state.dart';
/// BLoC for managing authentication state and operations.
class AuthBloc extends Bloc<AuthEvent, AuthState> {
/// Repository for authentication operations.
final AuthRepository _authRepository;
/// Creates an [AuthBloc] with the provided [authRepository].
///
/// The bloc starts in the [AuthInitial] state and registers event handlers
/// for all supported authentication events.
AuthBloc({required AuthRepository authRepository})
: _authRepository = authRepository,
super(AuthInitial()) {
@@ -18,6 +45,10 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
on<AuthPasswordResetRequested>(_onPasswordResetRequested);
}
/// Handles [AuthCheckRequested] events.
///
/// Checks if a user is currently authenticated and emits the appropriate state.
/// If a user is found, attempts to fetch user data from Firestore.
Future<void> _onAuthCheckRequested(
AuthCheckRequested event,
Emitter<AuthState> emit,
@@ -28,7 +59,7 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
final currentUser = _authRepository.currentUser;
if (currentUser != null) {
// Récupérer les données utilisateur depuis Firestore
// Fetch user data from Firestore
final user = await _authRepository.getUserFromFirestore(currentUser.uid);
if (user != null) {
@@ -44,6 +75,10 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
}
}
/// Handles [AuthSignInRequested] events.
///
/// Attempts to sign in a user with the provided email and password.
/// Emits [AuthAuthenticated] on success or [AuthError] on failure.
Future<void> _onSignInRequested(
AuthSignInRequested event,
Emitter<AuthState> emit,
@@ -59,13 +94,17 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
if (user != null) {
emit(AuthAuthenticated(user: user));
} else {
emit(const AuthError(message: 'Email ou mot de passe incorrect'));
emit(const AuthError(message: 'Invalid email or password'));
}
} catch (e) {
emit(AuthError(message: e.toString()));
}
}
/// Handles [AuthSignUpRequested] events.
///
/// Attempts to create a new user account with the provided information.
/// Emits [AuthAuthenticated] on success or [AuthError] on failure.
Future<void> _onSignUpRequested(
AuthSignUpRequested event,
Emitter<AuthState> emit,
@@ -83,13 +122,17 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
if (user != null) {
emit(AuthAuthenticated(user: user));
} else {
emit(const AuthError(message: 'Erreur lors de l\'inscription'));
emit(const AuthError(message: 'Registration failed'));
}
} catch (e) {
emit(AuthError(message: e.toString()));
}
}
/// Handles [AuthGoogleSignInRequested] events.
///
/// Attempts to sign in the user using Google authentication.
/// Emits [AuthAuthenticated] on success or [AuthError] on failure.
Future<void> _onGoogleSignInRequested(
AuthGoogleSignInRequested event,
Emitter<AuthState> emit,
@@ -102,13 +145,17 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
if (user != null) {
emit(AuthAuthenticated(user: user));
} else {
emit(const AuthError(message: 'Connexion Google annulée'));
emit(const AuthError(message: 'Google sign-in cancelled'));
}
} catch (e) {
emit(AuthError(message: e.toString()));
}
}
/// Handles [AuthAppleSignInRequested] events.
///
/// Attempts to sign in the user using Apple authentication.
/// Emits [AuthAuthenticated] on success or [AuthError] on failure.
Future<void> _onAppleSignInRequested(
AuthAppleSignInRequested event,
Emitter<AuthState> emit,
@@ -121,13 +168,16 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
if (user != null) {
emit(AuthAuthenticated(user: user));
} else {
emit(const AuthError(message: 'Connexion Apple annulée'));
emit(const AuthError(message: 'Apple sign-in cancelled'));
}
} catch (e) {
emit(AuthError(message: e.toString()));
}
}
/// Handles [AuthSignOutRequested] events.
///
/// Signs out the current user and emits [AuthUnauthenticated].
Future<void> _onSignOutRequested(
AuthSignOutRequested event,
Emitter<AuthState> emit,
@@ -136,6 +186,10 @@ class AuthBloc extends Bloc<AuthEvent, AuthState> {
emit(AuthUnauthenticated());
}
/// Handles [AuthPasswordResetRequested] events.
///
/// Sends a password reset email to the specified email address.
/// Emits [AuthPasswordResetSent] on success or [AuthError] on failure.
Future<void> _onPasswordResetRequested(
AuthPasswordResetRequested event,
Emitter<AuthState> emit,

51
lib/blocs/auth/auth_event.dart
View File

@@ -1,18 +1,37 @@
import 'package:equatable/equatable.dart';
/// Abstract base class for all authentication-related events.
///
/// This class extends [Equatable] to enable value equality for event comparison.
/// All authentication events in the application should inherit from this class.
abstract class AuthEvent extends Equatable {
/// Creates a new [AuthEvent].
const AuthEvent();
@override
List<Object?> get props => [];
}
/// Event to check the current authentication status.
///
/// This event is typically dispatched when the app starts to determine
/// if a user is already authenticated.
class AuthCheckRequested extends AuthEvent {}
/// Event to request user sign-in with email and password.
///
/// This event contains the user's credentials and triggers the authentication
/// process when dispatched to the [AuthBloc].
class AuthSignInRequested extends AuthEvent {
/// The user's email address.
final String email;
/// The user's password.
final String password;
/// Creates a new [AuthSignInRequested] event.
///
/// Both [email] and [password] are required parameters.
const AuthSignInRequested({
required this.email,
required this.password,
@@ -22,12 +41,26 @@ class AuthSignInRequested extends AuthEvent {
List<Object?> get props => [email, password];
}
/// Event to request user registration with email, password, and personal information.
///
/// This event contains all necessary information to create a new user account
/// and triggers the registration process when dispatched to the [AuthBloc].
class AuthSignUpRequested extends AuthEvent {
/// The user's email address.
final String email;
/// The user's password.
final String password;
/// The user's last name.
final String nom;
/// The user's first name.
final String prenom;
/// Creates a new [AuthSignUpRequested] event.
///
/// All parameters are required for user registration.
const AuthSignUpRequested({
required this.email,
required this.password,
@@ -39,15 +72,33 @@ class AuthSignUpRequested extends AuthEvent {
List<Object?> get props => [email, password, nom, prenom];
}
/// Event to request user sign-in using Google authentication.
///
/// This event triggers the Google sign-in flow when dispatched to the [AuthBloc].
class AuthGoogleSignInRequested extends AuthEvent {}
/// Event to request user sign-in using Apple authentication.
///
/// This event triggers the Apple sign-in flow when dispatched to the [AuthBloc].
class AuthAppleSignInRequested extends AuthEvent {}
/// Event to request user sign-out.
///
/// This event triggers the sign-out process and clears the user session
/// when dispatched to the [AuthBloc].
class AuthSignOutRequested extends AuthEvent {}
/// Event to request a password reset for a user account.
///
/// This event triggers the password reset process by sending a reset email
/// to the specified email address.
class AuthPasswordResetRequested extends AuthEvent {
/// The email address to send the password reset link to.
final String email;
/// Creates a new [AuthPasswordResetRequested] event.
///
/// The [email] parameter is required.
const AuthPasswordResetRequested({required this.email});
@override

35
lib/blocs/auth/auth_state.dart
View File

@@ -1,40 +1,75 @@
import 'package:equatable/equatable.dart';
import '../../models/user.dart';
/// Abstract base class for all authentication states.
///
/// This class extends [Equatable] to enable value equality for state comparison.
/// All authentication states in the application should inherit from this class.
abstract class AuthState extends Equatable {
/// Creates a new [AuthState].
const AuthState();
@override
List<Object?> get props => [];
}
/// Initial state of the authentication bloc.
///
/// This state represents the initial state before any authentication
/// actions have been performed.
class AuthInitial extends AuthState {}
/// State indicating that an authentication operation is in progress.
///
/// This state is used to show loading indicators during authentication
/// processes like sign-in, sign-up, or sign-out.
class AuthLoading extends AuthState {}
/// State indicating that a user is successfully authenticated.
///
/// This state contains the authenticated user's information and is
/// used throughout the app to access user data.
class AuthAuthenticated extends AuthState {
/// The authenticated user.
final User user;
/// Creates an [AuthAuthenticated] state with the given [user].
const AuthAuthenticated({required this.user});
@override
List<Object?> get props => [user];
}
/// State indicating that no user is currently authenticated.
///
/// This state is used when a user is not signed in or has signed out
/// of the application.
class AuthUnauthenticated extends AuthState {}
/// State indicating that an authentication error has occurred.
///
/// This state contains an error message that can be displayed to the user
/// when authentication operations fail.
class AuthError extends AuthState {
/// The error message describing what went wrong.
final String message;
/// Creates an [AuthError] state with the given error [message].
const AuthError({required this.message});
@override
List<Object?> get props => [message];
}
/// State indicating that a password reset email has been sent.
///
/// This state is used to confirm to the user that a password reset
/// email has been successfully sent to their email address.
class AuthPasswordResetSent extends AuthState {
/// The email address to which the reset link was sent.
final String email;
/// Creates an [AuthPasswordResetSent] state with the given [email].
const AuthPasswordResetSent({required this.email});
@override