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

43
lib/blocs/user/user_bloc.dart
View File

@@ -4,10 +4,21 @@ import 'package:cloud_firestore/cloud_firestore.dart';
import 'user_event.dart' as event;
import 'user_state.dart' as state;
/// BLoC for managing user data and operations.
///
/// This BLoC handles user-related operations including loading user data,
/// updating user information, and managing user state throughout the application.
/// It coordinates with Firebase Auth and Firestore to manage user data persistence.
class UserBloc extends Bloc<event.UserEvent, state.UserState> {
/// Firebase Auth instance for authentication operations.
final FirebaseAuth _auth = FirebaseAuth.instance;
/// Firestore instance for user data operations.
final FirebaseFirestore _firestore = FirebaseFirestore.instance;
/// Creates a new [UserBloc] with initial state.
///
/// Registers event handlers for all user-related events.
UserBloc() : super(state.UserInitial()) {
on<event.UserInitialized>(_onUserInitialized);
on<event.LoadUser>(_onLoadUser);
@@ -15,6 +26,11 @@ class UserBloc extends Bloc<event.UserEvent, state.UserState> {
on<event.UserLoggedOut>(_onUserLoggedOut);
}
/// Handles [UserInitialized] events.
///
/// Initializes the current authenticated user's data by fetching it from Firestore.
/// If the user doesn't exist in Firestore, creates a default user document.
/// This is typically called when the app starts or after successful authentication.
Future<void> _onUserInitialized(
event.UserInitialized event,
Emitter<state.UserState> emit,
@@ -25,18 +41,18 @@ class UserBloc extends Bloc<event.UserEvent, state.UserState> {
final currentUser = _auth.currentUser;
if (currentUser == null) {
emit(state.UserError('Aucun utilisateur connecté'));
emit(state.UserError('No user currently authenticated'));
return;
}
// Récupérer les données utilisateur depuis Firestore
// Fetch user data from Firestore
final userDoc = await _firestore
.collection('users')
.doc(currentUser.uid)
.get();
if (!userDoc.exists) {
// Créer un utilisateur par défaut si non existant
// Create a default user if it doesn't exist
final defaultUser = state.UserModel(
id: currentUser.uid,
email: currentUser.email ?? '',
@@ -57,10 +73,14 @@ class UserBloc extends Bloc<event.UserEvent, state.UserState> {
emit(state.UserLoaded(user));
}
} catch (e) {
emit(state.UserError('Erreur lors du chargement de l\'utilisateur: $e'));
emit(state.UserError('Error loading user: $e'));
}
}
/// Handles [LoadUser] events.
///
/// Loads a specific user's data from Firestore by their user ID.
/// This is useful when you need to display information about other users.
Future<void> _onLoadUser(
event.LoadUser event,
Emitter<state.UserState> emit,
@@ -80,13 +100,18 @@ class UserBloc extends Bloc<event.UserEvent, state.UserState> {
});
emit(state.UserLoaded(user));
} else {
emit(state.UserError('Utilisateur non trouvé'));
emit(state.UserError('User not found'));
}
} catch (e) {
emit(state.UserError('Erreur lors du chargement: $e'));
emit(state.UserError('Error loading user: $e'));
}
}
/// Handles [UserUpdated] events.
///
/// Updates the current user's data in Firestore with the provided information.
/// Only updates the fields specified in the userData map, allowing for partial updates.
/// After successful update, reloads the user data to reflect changes.
Future<void> _onUserUpdated(
event.UserUpdated event,
Emitter<state.UserState> emit,
@@ -112,11 +137,15 @@ class UserBloc extends Bloc<event.UserEvent, state.UserState> {
emit(state.UserLoaded(updatedUser));
} catch (e) {
emit(state.UserError('Erreur lors de la mise à jour: $e'));
emit(state.UserError('Error updating user: $e'));
}
}
}
/// Handles [UserLoggedOut] events.
///
/// Resets the user bloc state to initial when the user logs out.
/// This clears any cached user data from the application state.
Future<void> _onUserLoggedOut(
event.UserLoggedOut event,
Emitter<state.UserState> emit,

37
lib/blocs/user/user_event.dart
View File

@@ -1,24 +1,47 @@
/// Abstract base class for all user-related events.
///
/// All user events in the application should inherit from this class.
/// This provides a common interface for user-related operations.
abstract class UserEvent {}
/// Event to initialize the current user's data.
///
/// This event is typically dispatched when the app starts or when
/// a user signs in to load their profile information from Firestore.
class UserInitialized extends UserEvent {}
class UserLoaded extends UserEvent {
/// Event to load a specific user's data by their ID.
///
/// This event is used to fetch user information from Firestore
/// when you need to display or work with a specific user's data.
class LoadUser extends UserEvent {
/// The ID of the user to load.
final String userId;
UserLoaded(this.userId);
/// Creates a [LoadUser] event with the specified [userId].
LoadUser(this.userId);
}
/// Event to update the current user's data.
///
/// This event is dispatched when the user modifies their profile
/// information and the changes need to be saved to Firestore.
class UserUpdated extends UserEvent {
/// Map containing the user data fields to update.
///
/// Only the fields present in this map will be updated in Firestore.
/// This allows for partial updates of user information.
final Map<String, dynamic> userData;
/// Creates a [UserUpdated] event with the specified [userData].
UserUpdated(this.userData);
}
/// Event to handle user logout.
///
/// This event is dispatched when the user signs out of the application,
/// clearing their data from the user bloc state.
class UserLoggedOut extends UserEvent {
/// Creates a [UserLoggedOut] event.
UserLoggedOut();
}
class LoadUser extends UserEvent {
final String userId;
LoadUser(this.userId);
}

51
lib/blocs/user/user_state.dart
View File

@@ -1,39 +1,81 @@
import 'package:equatable/equatable.dart';
/// Abstract base class for all user-related states.
///
/// This class extends [Equatable] to enable value equality for state comparison.
/// All user states in the application should inherit from this class.
abstract class UserState extends Equatable {
@override
List<Object?> get props => [];
}
/// Initial state of the user bloc.
///
/// This state represents the initial state before any user operations
/// have been performed or when the user has logged out.
class UserInitial extends UserState {}
/// State indicating that a user operation is in progress.
///
/// This state is used to show loading indicators during user data
/// operations like loading, updating, or initializing user information.
class UserLoading extends UserState {}
/// State indicating that user data has been successfully loaded.
///
/// This state contains the loaded user information and is used
/// throughout the app to access current user data.
class UserLoaded extends UserState {
/// The loaded user data.
final UserModel user;
/// Creates a [UserLoaded] state with the given [user] data.
UserLoaded(this.user);
@override
List<Object?> get props => [user];
}
/// State indicating that a user operation has failed.
///
/// This state contains an error message that can be displayed to the user
/// when user operations fail.
class UserError extends UserState {
/// The error message describing what went wrong.
final String message;
/// Creates a [UserError] state with the given error [message].
UserError(this.message);
@override
List<Object?> get props => [message];
}
// Modèle utilisateur simple
/// Simple user model for representing user data in the application.
///
/// This model contains basic user information and provides methods for
/// serialization/deserialization with Firestore operations.
/// Simple user model for representing user data in the application.
///
/// This model contains basic user information and provides methods for
/// serialization/deserialization with Firestore operations.
class UserModel {
/// Unique identifier for the user (Firebase UID).
final String id;
/// User's email address.
final String email;
/// User's first name.
final String prenom;
/// User's last name (optional).
final String? nom;
/// Creates a new [UserModel] instance.
///
/// [id], [email], and [prenom] are required fields.
/// [nom] is optional and can be null.
UserModel({
required this.id,
required this.email,
@@ -41,6 +83,10 @@ class UserModel {
this.nom,
});
/// Creates a [UserModel] instance from a JSON map.
///
/// Handles null values gracefully by providing default values.
/// [prenom] defaults to 'Voyageur' (Traveler) if not provided.
factory UserModel.fromJson(Map<String, dynamic> json) {
return UserModel(
id: json['id'] ?? '',
@@ -50,6 +96,9 @@ class UserModel {
);
}
/// Converts the [UserModel] instance to a JSON map.
///
/// Useful for storing user data in Firestore or other JSON-based operations.
Map<String, dynamic> toJson() {
return {
'id': id,