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

157
lib/blocs/group/group_bloc.dart
View File

@@ -1,3 +1,36 @@
/// A BLoC (Business Logic Component) that manages group-related operations.
///
/// This bloc handles all group operations including creation, updates, member management,
/// and loading groups for users or trips. It provides real-time updates through streams
/// and manages the relationship between users, groups, and trips.
///
/// The bloc processes these main events:
/// - [LoadGroupsByUserId]: Loads all groups for a specific user with real-time updates
/// - [LoadGroupsByTrip]: Loads the group associated with a specific trip
/// - [CreateGroup]: Creates a new group without members
/// - [CreateGroupWithMembers]: Creates a new group with initial members
/// - [AddMemberToGroup]: Adds a member to an existing group
/// - [RemoveMemberFromGroup]: Removes a member from a group
/// - [UpdateGroup]: Updates group information
/// - [DeleteGroup]: Deletes a group
///
/// Dependencies:
/// - [GroupRepository]: Repository for group data operations
/// - [ErrorService]: Service for error logging and handling
///
/// Example usage:
/// ```dart
/// final groupBloc = GroupBloc(groupRepository);
///
/// // Load groups for a user
/// groupBloc.add(LoadGroupsByUserId('userId123'));
///
/// // Create a new group with members
/// groupBloc.add(CreateGroupWithMembers(
/// group: newGroup,
/// members: [member1, member2],
/// ));
/// ```
import 'dart:async';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:travel_mate/services/error_service.dart';
@@ -6,11 +39,24 @@ import 'group_state.dart';
import '../../repositories/group_repository.dart';
import '../../models/group.dart';
/// BLoC that manages group-related operations and state.
class GroupBloc extends Bloc<GroupEvent, GroupState> {
/// Repository for group data operations
final GroupRepository _repository;
/// Subscription to group stream for real-time updates
StreamSubscription? _groupsSubscription;
/// Service for error handling and logging
final _errorService = ErrorService();
/// Constructor for GroupBloc.
///
/// Initializes the bloc with the group repository and sets up event handlers
/// for all group-related operations.
///
/// Args:
/// [_repository]: Repository for group data operations
GroupBloc(this._repository) : super(GroupInitial()) {
on<LoadGroupsByUserId>(_onLoadGroupsByUserId);
on<_GroupsUpdated>(_onGroupsUpdated);
@@ -23,6 +69,14 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
on<DeleteGroup>(_onDeleteGroup);
}
/// Handles [LoadGroupsByUserId] events.
///
/// Loads all groups for a specific user with real-time updates via stream subscription.
/// Cancels any existing subscription before creating a new one to prevent memory leaks.
///
/// Args:
/// [event]: The LoadGroupsByUserId event containing the user ID
/// [emit]: State emitter function
Future<void> _onLoadGroupsByUserId(
LoadGroupsByUserId event,
Emitter<GroupState> emit,
@@ -44,6 +98,14 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
}
}
/// Handles [_GroupsUpdated] events.
///
/// Processes real-time updates from the group stream, either emitting
/// the updated group list or an error state if the stream encountered an error.
///
/// Args:
/// [event]: The _GroupsUpdated event containing groups or error information
/// [emit]: State emitter function
Future<void> _onGroupsUpdated(
_GroupsUpdated event,
Emitter<GroupState> emit,
@@ -56,6 +118,14 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
}
}
/// Handles [LoadGroupsByTrip] events.
///
/// Loads the group associated with a specific trip. Since each trip typically
/// has one primary group, this returns a single group or an empty list.
///
/// Args:
/// [event]: The LoadGroupsByTrip event containing the trip ID
/// [emit]: State emitter function
Future<void> _onLoadGroupsByTrip(
LoadGroupsByTrip event,
Emitter<GroupState> emit,
@@ -73,6 +143,14 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
}
}
/// Handles [CreateGroup] events.
///
/// Creates a new group without any initial members. The group creator
/// can add members later using AddMemberToGroup events.
///
/// Args:
/// [event]: The CreateGroup event containing the group data
/// [emit]: State emitter function
Future<void> _onCreateGroup(
CreateGroup event,
Emitter<GroupState> emit,
@@ -84,12 +162,21 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
members: [],
);
emit(GroupCreated(groupId: groupId));
emit(const GroupOperationSuccess('Groupe créé avec succès'));
emit(const GroupOperationSuccess('Group created successfully'));
} catch (e) {
emit(GroupError('Erreur lors de la création: $e'));
emit(GroupError('Error during creation: $e'));
}
}
/// Handles [CreateGroupWithMembers] events.
///
/// Creates a new group with an initial set of members. This is useful
/// for setting up complete groups in one operation, such as when
/// planning a trip with known participants.
///
/// Args:
/// [event]: The CreateGroupWithMembers event containing group data and member list
/// [emit]: State emitter function
Future<void> _onCreateGroupWithMembers(
CreateGroupWithMembers event,
Emitter<GroupState> emit,
@@ -102,58 +189,94 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
);
emit(GroupCreated(groupId: groupId));
} catch (e) {
emit(GroupError('Erreur lors de la création: $e'));
emit(GroupError('Error during creation: $e'));
}
}
/// Handles [AddMemberToGroup] events.
///
/// Adds a new member to an existing group. The member will be able to
/// participate in group expenses and access group features.
///
/// Args:
/// [event]: The AddMemberToGroup event containing group ID and member data
/// [emit]: State emitter function
Future<void> _onAddMemberToGroup(
AddMemberToGroup event,
Emitter<GroupState> emit,
) async {
try {
await _repository.addMember(event.groupId, event.member);
emit(const GroupOperationSuccess('Membre ajouté'));
emit(const GroupOperationSuccess('Member added'));
} catch (e) {
emit(GroupError('Erreur lors de l\'ajout: $e'));
emit(GroupError('Error during addition: $e'));
}
}
/// Handles [RemoveMemberFromGroup] events.
///
/// Removes a member from a group. This will affect expense calculations
/// and the member will no longer have access to group features.
///
/// Args:
/// [event]: The RemoveMemberFromGroup event containing group ID and user ID
/// [emit]: State emitter function
Future<void> _onRemoveMemberFromGroup(
RemoveMemberFromGroup event,
Emitter<GroupState> emit,
) async {
try {
await _repository.removeMember(event.groupId, event.userId);
emit(const GroupOperationSuccess('Membre supprimé'));
emit(const GroupOperationSuccess('Member removed'));
} catch (e) {
emit(GroupError('Erreur lors de la suppression: $e'));
emit(GroupError('Error during removal: $e'));
}
}
/// Handles [UpdateGroup] events.
///
/// Updates group information such as name, description, or settings.
/// Member lists are managed through separate add/remove member events.
///
/// Args:
/// [event]: The UpdateGroup event containing group ID and updated group data
/// [emit]: State emitter function
Future<void> _onUpdateGroup(
UpdateGroup event,
Emitter<GroupState> emit,
) async {
try {
await _repository.updateGroup(event.groupId, event.group);
emit(const GroupOperationSuccess('Groupe mis à jour'));
emit(const GroupOperationSuccess('Group updated'));
} catch (e) {
emit(GroupError('Erreur lors de la mise à jour: $e'));
emit(GroupError('Error during update: $e'));
}
}
/// Handles [DeleteGroup] events.
///
/// Permanently deletes a group and all associated data. This action
/// cannot be undone and will affect all group members and expenses.
///
/// Args:
/// [event]: The DeleteGroup event containing the trip ID to delete
/// [emit]: State emitter function
Future<void> _onDeleteGroup(
DeleteGroup event,
Emitter<GroupState> emit,
) async {
try {
await _repository.deleteGroup(event.tripId);
emit(const GroupOperationSuccess('Groupe supprimé'));
emit(const GroupOperationSuccess('Group deleted'));
} catch (e) {
emit(GroupError('Erreur lors de la suppression: $e'));
emit(GroupError('Error during deletion: $e'));
}
}
/// Cleans up resources when the bloc is closed.
///
/// Cancels the group stream subscription to prevent memory leaks
/// and ensure proper disposal of resources.
@override
Future<void> close() {
_groupsSubscription?.cancel();
@@ -161,10 +284,22 @@ class GroupBloc extends Bloc<GroupEvent, GroupState> {
}
}
/// Private event for handling real-time group updates from streams.
///
/// This internal event is used to process updates from the group stream
/// subscription and emit appropriate states based on the received data.
class _GroupsUpdated extends GroupEvent {
/// List of groups received from the stream
final List<Group> groups;
/// Error message if the stream encountered an error
final String? error;
/// Creates a _GroupsUpdated event.
///
/// Args:
/// [groups]: List of groups from the stream update
/// [error]: Optional error message if stream failed
const _GroupsUpdated(this.groups, {this.error});
@override

153
lib/blocs/group/group_event.dart
View File

@@ -1,7 +1,25 @@
/// Events for group-related operations in the GroupBloc.
///
/// This file defines all possible events that can be dispatched to the GroupBloc
/// to trigger group-related state changes and operations such as loading groups,
/// creating groups, managing members, and performing CRUD operations.
///
/// Event Categories:
/// - **Loading Events**: LoadGroupsByUserId, LoadGroupsByTrip
/// - **Creation Events**: CreateGroup, CreateGroupWithMembers
/// - **Member Management**: AddMemberToGroup, RemoveMemberFromGroup
/// - **Modification Events**: UpdateGroup, DeleteGroup
///
/// All events extend [GroupEvent] and implement [Equatable] for proper
/// equality comparison in the BLoC pattern.
import 'package:equatable/equatable.dart';
import '../../models/group.dart';
import '../../models/group_member.dart';
/// Base class for all group-related events.
///
/// All group events must extend this class and implement the [props] getter
/// for proper equality comparison in the BLoC pattern.
abstract class GroupEvent extends Equatable {
const GroupEvent();
@@ -9,41 +27,96 @@ abstract class GroupEvent extends Equatable {
List<Object?> get props => [];
}
// NOUVEAU : Charger les groupes par userId
/// Event to load all groups associated with a specific user.
///
/// This is the primary method for loading groups, as it retrieves all groups
/// where the user is a member, providing a comprehensive view of the user's
/// group memberships across different trips and activities.
///
/// Args:
/// [userId]: The unique identifier of the user whose groups should be loaded
class LoadGroupsByUserId extends GroupEvent {
/// The unique identifier of the user
final String userId;
/// Creates a LoadGroupsByUserId event.
///
/// Args:
/// [userId]: The user ID to load groups for
const LoadGroupsByUserId(this.userId);
@override
List<Object?> get props => [userId];
}
// Charger les groupes d'un voyage (conservé pour compatibilité)
// Load groups for a trip (maintained for compatibility)
/// Event to load groups associated with a specific trip.
///
/// This event is maintained for backward compatibility and specific use cases
/// where you need to load groups within the context of a particular trip.
/// Most trips have one primary group, but some may have multiple sub-groups.
///
/// Args:
/// [tripId]: The unique identifier of the trip whose groups should be loaded
class LoadGroupsByTrip extends GroupEvent {
/// The unique identifier of the trip
final String tripId;
/// Creates a LoadGroupsByTrip event.
///
/// Args:
/// [tripId]: The trip ID to load groups for
const LoadGroupsByTrip(this.tripId);
@override
List<Object?> get props => [tripId];
}
// Créer un groupe simple
// Create a simple group
/// Event to create a new group without any initial members.
///
/// This creates a basic group structure that can be populated with members
/// later using AddMemberToGroup events. Useful when setting up a group
/// before knowing all participants.
///
/// Args:
/// [group]: The group object containing basic information (name, description, etc.)
class CreateGroup extends GroupEvent {
/// The group to be created
final Group group;
/// Creates a CreateGroup event.
///
/// Args:
/// [group]: The group object to create
const CreateGroup(this.group);
@override
List<Object?> get props => [group];
}
// Créer un groupe avec ses membres
// Create a group with its members
/// Event to create a new group with an initial set of members.
///
/// This is the preferred method for group creation when you know all or most
/// of the participants upfront. It creates the group and adds all specified
/// members in a single operation, ensuring data consistency.
///
/// Args:
/// [group]: The group object containing basic information
/// [members]: List of initial members to add to the group
class CreateGroupWithMembers extends GroupEvent {
/// The group to be created
final Group group;
/// Initial members to add to the group
final List<GroupMember> members;
/// Creates a CreateGroupWithMembers event.
///
/// Args:
/// [group]: The group object to create
/// [members]: List of initial group members
const CreateGroupWithMembers({
required this.group,
required this.members,
@@ -53,43 +126,107 @@ class CreateGroupWithMembers extends GroupEvent {
List<Object?> get props => [group, members];
}
// Ajouter un membre
// Add a member
/// Event to add a new member to an existing group.
///
/// This allows for dynamic group expansion by adding users to groups after
/// creation. The new member will gain access to group features like expenses,
/// messages, and shared resources.
///
/// Args:
/// [groupId]: The unique identifier of the target group
/// [member]: The group member object containing user information and role
class AddMemberToGroup extends GroupEvent {
/// The unique identifier of the group
final String groupId;
/// The member to add to the group
final GroupMember member;
/// Creates an AddMemberToGroup event.
///
/// Args:
/// [groupId]: The group ID to add the member to
/// [member]: The group member to add
const AddMemberToGroup(this.groupId, this.member);
@override
List<Object?> get props => [groupId, member];
}
// Supprimer un membre
// Remove a member
/// Event to remove a member from a group.
///
/// This removes a user from the group, revoking their access to group features.
/// The removal will affect expense calculations and the user will no longer
/// receive group-related notifications or updates.
///
/// Args:
/// [groupId]: The unique identifier of the group
/// [userId]: The unique identifier of the user to remove
class RemoveMemberFromGroup extends GroupEvent {
/// The unique identifier of the group
final String groupId;
/// The unique identifier of the user to remove
final String userId;
/// Creates a RemoveMemberFromGroup event.
///
/// Args:
/// [groupId]: The group ID to remove the member from
/// [userId]: The user ID to remove
const RemoveMemberFromGroup(this.groupId, this.userId);
@override
List<Object?> get props => [groupId, userId];
}
// Mettre à jour un groupe
// Update a group
/// Event to update an existing group's information.
///
/// This allows modification of group properties such as name, description,
/// settings, or other metadata. Member management is handled through
/// separate add/remove member events.
///
/// Args:
/// [groupId]: The unique identifier of the group to update
/// [group]: The updated group object with new information
class UpdateGroup extends GroupEvent {
/// The unique identifier of the group to update
final String groupId;
/// The updated group object
final Group group;
/// Creates an UpdateGroup event.
///
/// Args:
/// [groupId]: The group ID to update
/// [group]: The updated group object
const UpdateGroup(this.groupId, this.group);
@override
List<Object?> get props => [groupId, group];
}
// Supprimer un groupe
// Delete a group
/// Event to permanently delete a group.
///
/// This is a destructive operation that removes the group and all associated
/// data. This action cannot be undone and will affect all group members.
/// Consider archiving instead of deleting for historical records.
///
/// Args:
/// [tripId]: The unique identifier of the trip whose group should be deleted
class DeleteGroup extends GroupEvent {
/// The unique identifier of the trip (used to identify the group)
final String tripId;
/// Creates a DeleteGroup event.
///
/// Args:
/// [tripId]: The trip ID whose group should be deleted
const DeleteGroup(this.tripId);
@override

108
lib/blocs/group/group_state.dart
View File

@@ -1,6 +1,24 @@
/// States for group-related operations in the GroupBloc.
///
/// This file defines all possible states that the GroupBloc can emit in response
/// to group-related events. The states represent different phases of group
/// operations including loading, success, error, and data states.
///
/// State Categories:
/// - **Initial State**: GroupInitial
/// - **Loading States**: GroupLoading
/// - **Success States**: GroupsLoaded, GroupLoaded, GroupCreated, GroupOperationSuccess
/// - **Error States**: GroupError
///
/// All states extend [GroupState] and implement [Equatable] for proper
/// equality comparison and state change detection in the BLoC pattern.
import 'package:equatable/equatable.dart';
import '../../models/group.dart';
/// Base class for all group-related states.
///
/// All group states must extend this class and implement the [props] getter
/// for proper equality comparison in the BLoC pattern.
abstract class GroupState extends Equatable {
const GroupState();
@@ -8,54 +26,132 @@ abstract class GroupState extends Equatable {
List<Object?> get props => [];
}
// État initial
// Initial state
/// The initial state of the GroupBloc before any operations are performed.
///
/// This is the default state when the bloc is first created and represents
/// a clean slate with no group data loaded or operations in progress.
class GroupInitial extends GroupState {}
// Chargement
// Loading
/// State indicating that a group operation is currently in progress.
///
/// This state is emitted when the bloc is performing operations like
/// loading groups, creating groups, or updating group information.
/// UI components can use this state to show loading indicators.
class GroupLoading extends GroupState {}
// Groupes chargés
// Groups loaded
/// State containing a list of successfully loaded groups.
///
/// This state is emitted when groups have been successfully retrieved
/// from the repository, either through initial loading or real-time updates.
/// The UI can use this data to display the list of available groups.
///
/// Properties:
/// [groups]: List of Group objects that were loaded
class GroupsLoaded extends GroupState {
/// The list of loaded groups
final List<Group> groups;
/// Creates a GroupsLoaded state.
///
/// Args:
/// [groups]: The list of groups to include in this state
const GroupsLoaded(this.groups);
@override
List<Object?> get props => [groups];
}
/// Alternative state for loaded groups (used in some contexts).
///
/// This state serves a similar purpose to GroupsLoaded but may be used
/// in different contexts or for backward compatibility.
///
/// Properties:
/// [groups]: List of Group objects that were loaded
class GroupLoaded extends GroupState {
/// The list of loaded groups
final List<Group> groups;
/// Creates a GroupLoaded state.
///
/// Args:
/// [groups]: The list of groups to include in this state
const GroupLoaded(this.groups);
}
/// State indicating successful group creation.
///
/// This state is emitted when a new group has been successfully created.
/// It contains the ID of the newly created group and an optional success message
/// that can be displayed to the user.
///
/// Properties:
/// [groupId]: The unique identifier of the newly created group
/// [message]: A success message to display to the user
class GroupCreated extends GroupState {
/// The unique identifier of the newly created group
final String groupId;
/// Success message for the user
final String message;
/// Creates a GroupCreated state.
///
/// Args:
/// [groupId]: The ID of the newly created group
/// [message]: Optional success message (defaults to "Group created successfully")
const GroupCreated({
required this.groupId,
this.message = 'Groupe créé avec succès',
this.message = 'Group created successfully',
});
@override
List<Object?> get props => [groupId, message];
}
// Succès d'une opération
// Operation success
/// State indicating successful completion of a group operation.
///
/// This state is emitted when operations like updating, deleting, or
/// member management have completed successfully. It contains a message
/// that can be displayed to inform the user of the successful operation.
///
/// Properties:
/// [message]: A success message describing the completed operation
class GroupOperationSuccess extends GroupState {
/// The success message to display to the user
final String message;
/// Creates a GroupOperationSuccess state.
///
/// Args:
/// [message]: The success message to display
const GroupOperationSuccess(this.message);
@override
List<Object?> get props => [message];
}
// Erreur
// Error
/// State indicating that a group operation has failed.
///
/// This state is emitted when any group operation encounters an error.
/// It contains an error message that can be displayed to the user to
/// explain what went wrong.
///
/// Properties:
/// [message]: An error message describing what went wrong
class GroupError extends GroupState {
/// The error message to display to the user
final String message;
/// Creates a GroupError state.
///
/// Args:
/// [message]: The error message to display
const GroupError(this.message);
@override