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

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