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

131
lib/components/account/account_content.dart
View File

@@ -1,3 +1,23 @@
/// A widget that displays the account content page for the travel expense app.
///
/// This component manages the display of user accounts (groups) and provides
/// navigation to group expense management. It handles loading account data,
/// error states, and navigation to the group expenses page.
///
/// Features:
/// - **Account Loading**: Automatically loads accounts for the current user
/// - **Error Handling**: Displays error states with retry functionality
/// - **Navigation**: Navigates to group expense management pages
/// - **Real-time Updates**: Uses BLoC pattern for reactive state management
/// - **Pull to Refresh**: Allows users to refresh account data
///
/// Dependencies:
/// - [UserBloc]: For current user state management
/// - [AccountBloc]: For account data management
/// - [GroupRepository]: For group data operations
///
/// The component automatically loads account data when initialized and
/// provides a clean interface for managing group-based expenses.
import 'package:flutter/material.dart';
import 'package:travel_mate/blocs/user/user_bloc.dart';
import '../../models/account.dart';
@@ -10,6 +30,7 @@ import '../../blocs/user/user_state.dart' as user_state;
import '../../repositories/group_repository.dart'; // Ajouter cet import
import 'group_expenses_page.dart'; // Ajouter cet import
/// Widget that displays the account content page with account management functionality.
class AccountContent extends StatefulWidget {
const AccountContent({super.key});
@@ -17,19 +38,25 @@ class AccountContent extends StatefulWidget {
State<AccountContent> createState() => _AccountContentState();
}
/// State class for AccountContent that manages account loading and navigation.
class _AccountContentState extends State<AccountContent> {
/// Repository for group data operations used for navigation
final _groupRepository = GroupRepository(); // Ajouter cette ligne
@override
void initState() {
super.initState();
// Charger immédiatement sans attendre le prochain frame
// Load immediately without waiting for the next frame
WidgetsBinding.instance.addPostFrameCallback((_) {
_loadInitialData();
});
}
/// Loads the initial account data for the current user.
///
/// Retrieves the current user from UserBloc and loads their accounts
/// using the AccountBloc. Handles errors gracefully with error display.
void _loadInitialData() {
try {
final userState = context.read<UserBloc>().state;
@@ -38,20 +65,27 @@ class _AccountContentState extends State<AccountContent> {
final userId = userState.user.id;
context.read<AccountBloc>().add(LoadAccountsByUserId(userId));
} else {
throw Exception('Utilisateur non connecté');
throw Exception('User not connected');
}
} catch (e) {
ErrorContent(
message: 'Erreur lors du chargement des comptes: $e',
message: 'Error loading accounts: $e',
onRetry: () {},
);
}
}
// Nouvelle méthode pour naviguer vers la page des dépenses de groupe
/// Navigates to the group expenses page for a specific account.
///
/// Retrieves the group associated with the account and navigates to
/// the group expenses management page. Shows error messages if the
/// group cannot be found or if navigation fails.
///
/// Args:
/// [account]: The account to navigate to for expense management
Future<void> _navigateToGroupExpenses(Account account) async {
try {
// Récupérer le groupe associé au compte
// Retrieve the group associated with the account
final group = await _groupRepository.getGroupByTripId(account.tripId);
if (group != null && mounted) {
@@ -68,7 +102,7 @@ class _AccountContentState extends State<AccountContent> {
if (mounted) {
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(
content: Text('Groupe non trouvé pour ce compte'),
content: Text('Group not found for this account'),
backgroundColor: Colors.red,
),
);
@@ -78,7 +112,7 @@ class _AccountContentState extends State<AccountContent> {
if (mounted) {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(
content: Text('Erreur lors du chargement du groupe: $e'),
content: Text('Error loading group: $e'),
backgroundColor: Colors.red,
),
);
@@ -86,6 +120,15 @@ class _AccountContentState extends State<AccountContent> {
}
}
/// Builds the main widget for the account content page.
///
/// Creates a responsive UI that handles different user and account states:
/// - Shows loading indicator for user authentication
/// - Displays error content for user errors
/// - Builds account content based on account loading states
///
/// Returns:
/// Widget representing the complete account page UI
@override
Widget build(BuildContext context) {
return BlocBuilder<UserBloc, user_state.UserState>(
@@ -98,14 +141,14 @@ class _AccountContentState extends State<AccountContent> {
if (userState is user_state.UserError) {
return ErrorContent(
message: 'Erreur utilisateur: ${userState.message}',
message: 'User error: ${userState.message}',
onRetry: () {},
);
}
if (userState is! user_state.UserLoaded) {
return const Scaffold(
body: Center(child: Text('Utilisateur non connecté')),
body: Center(child: Text('User not connected')),
);
}
final user = userState.user;
@@ -114,7 +157,7 @@ class _AccountContentState extends State<AccountContent> {
listener: (context, accountState) {
if (accountState is AccountError) {
ErrorContent(
message: 'Erreur de chargement des comptes: ${accountState.message}',
message: 'Account loading error: ${accountState.message}',
onRetry: () {
context.read<AccountBloc>().add(LoadAccountsByUserId(user.id));
},
@@ -131,6 +174,19 @@ class _AccountContentState extends State<AccountContent> {
);
}
/// Builds the main content based on the current account state.
///
/// Handles different account loading states and renders appropriate UI:
/// - Loading: Shows circular progress indicator with loading message
/// - Error: Displays error content with retry functionality
/// - Loaded: Renders the accounts list or empty state message
///
/// Args:
/// [accountState]: Current state of account loading
/// [userId]: ID of the current user for reload operations
///
/// Returns:
/// Widget representing the account content UI
Widget _buildContent(AccountState accountState, String userId) {
if (accountState is AccountLoading) {
return const Center(
@@ -139,7 +195,7 @@ class _AccountContentState extends State<AccountContent> {
children: [
CircularProgressIndicator(),
SizedBox(height: 16),
Text('Chargement des comptes...'),
Text('Loading accounts...'),
],
),
);
@@ -147,7 +203,7 @@ class _AccountContentState extends State<AccountContent> {
if (accountState is AccountError) {
return ErrorContent(
message: 'Erreur de chargement des comptes...',
message: 'Account loading error...',
onRetry: () {
context.read<AccountBloc>().add(LoadAccountsByUserId(userId));
},
@@ -165,19 +221,27 @@ class _AccountContentState extends State<AccountContent> {
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
const Text('État inconnu'),
const Text('Unknown state'),
const SizedBox(height: 16),
ElevatedButton(
onPressed: () {
context.read<AccountBloc>().add(LoadAccountsByUserId(userId));
},
child: const Text('Charger les comptes'),
child: const Text('Load accounts'),
),
],
),
);
}
/// Builds the empty state widget when no accounts are found.
///
/// Displays a user-friendly message explaining that accounts are
/// automatically created when trips are created. Shows an icon
/// and informative text to guide the user.
///
/// Returns:
/// Widget representing the empty accounts state
Widget _buildEmptyState() {
return Center(
child: Padding(
@@ -188,12 +252,12 @@ class _AccountContentState extends State<AccountContent> {
const Icon(Icons.account_balance_wallet, size: 80, color: Colors.grey),
const SizedBox(height: 16),
const Text(
'Aucun compte trouvé',
'No accounts found',
style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
),
const SizedBox(height: 8),
const Text(
'Les comptes sont créés automatiquement lorsque vous créez un voyage',
'Accounts are automatically created when you create a trip',
style: TextStyle(fontSize: 14, color: Colors.grey),
textAlign: TextAlign.center,
),
@@ -203,6 +267,18 @@ class _AccountContentState extends State<AccountContent> {
);
}
/// Builds a scrollable list of user accounts with pull-to-refresh functionality.
///
/// Creates a RefreshIndicator-wrapped ListView that displays all user accounts
/// in card format. Includes a header with title and description, and renders
/// each account using the _buildSimpleAccountCard method.
///
/// Args:
/// [accounts]: List of accounts to display
/// [userId]: Current user ID for refresh operations
///
/// Returns:
/// Widget containing the accounts list with pull-to-refresh capability
Widget _buildAccountsList(List<Account> accounts, String userId) {
return RefreshIndicator(
onRefresh: () async {
@@ -213,12 +289,12 @@ class _AccountContentState extends State<AccountContent> {
padding: const EdgeInsets.all(16),
children: [
const Text(
'Mes comptes',
'My accounts',
style: TextStyle(fontSize: 28, fontWeight: FontWeight.bold),
),
const SizedBox(height: 8),
Text(
'Gérez vos comptes de voyage',
'Manage your travel accounts',
style: TextStyle(fontSize: 14, color: Colors.grey[600]),
),
const SizedBox(height: 24),
@@ -234,12 +310,25 @@ class _AccountContentState extends State<AccountContent> {
);
}
/// Builds an individual account card with account information.
///
/// Creates a Material Design card displaying account details including:
/// - Account name with color-coded avatar
/// - Member count and member names (up to 2 displayed)
/// - Navigation capability to group expenses
/// - Error handling for card rendering issues
///
/// Args:
/// [account]: Account object containing account details
///
/// Returns:
/// Widget representing a single account card
Widget _buildSimpleAccountCard(Account account) {
try {
final colors = [Colors.blue, Colors.purple, Colors.green, Colors.orange];
final color = colors[account.name.hashCode.abs() % colors.length];
String memberInfo = '${account.members.length} membre${account.members.length > 1 ? 's' : ''}';
String memberInfo = '${account.members.length} member${account.members.length > 1 ? 's' : ''}';
if(account.members.isNotEmpty){
final names = account.members
@@ -262,7 +351,7 @@ class _AccountContentState extends State<AccountContent> {
),
subtitle: Text(memberInfo),
trailing: const Icon(Icons.chevron_right),
onTap: () => _navigateToGroupExpenses(account), // Modifier cette ligne
onTap: () => _navigateToGroupExpenses(account), // Navigate to group expenses
),
);
} catch (e) {
@@ -270,7 +359,7 @@ class _AccountContentState extends State<AccountContent> {
color: Colors.red,
child: const ListTile(
leading: Icon(Icons.error, color: Colors.red),
title: Text('Erreur d\'affichage'),
title: Text('Display error'),
)
);
}

21
lib/components/error/error_content.dart
View File

@@ -1,16 +1,35 @@
import 'package:flutter/material.dart';
/// A reusable error display component.
///
/// This widget provides a consistent way to display error messages throughout
/// the application. It supports customizable titles, messages, icons, and
/// action buttons for retry and close operations.
class ErrorContent extends StatelessWidget {
/// The error title to display
final String title;
/// The error message to display
final String message;
/// Optional callback for retry action
final VoidCallback? onRetry;
/// Optional callback for close action
final VoidCallback? onClose;
/// Icon to display with the error
final IconData icon;
/// Color of the error icon
final Color? iconColor;
/// Creates a new [ErrorContent] widget.
///
/// [message] is required, other parameters are optional with sensible defaults.
const ErrorContent({
super.key,
this.title = 'Une erreur est survenue',
this.title = 'An error occurred',
required this.message,
this.onRetry,
this.onClose,

54
lib/components/group/chat_group_content.dart
View File

@@ -8,9 +8,26 @@ import '../../blocs/message/message_state.dart';
import '../../models/group.dart';
import '../../models/message.dart';
/// Chat group content widget for group messaging functionality.
///
/// This widget provides a complete chat interface for group members to
/// communicate within a travel group. Features include:
/// - Real-time message loading and sending
/// - Message editing and deletion
/// - Message reactions (like/unlike)
/// - Scroll-to-bottom functionality
/// - Message status indicators
///
/// The widget integrates with MessageBloc for state management and
/// handles various message operations through the bloc pattern.
class ChatGroupContent extends StatefulWidget {
/// The group for which to display the chat interface
final Group group;
/// Creates a chat group content widget.
///
/// Args:
/// [group]: The group object containing group details and ID
const ChatGroupContent({
super.key,
required this.group,
@@ -21,14 +38,19 @@ class ChatGroupContent extends StatefulWidget {
}
class _ChatGroupContentState extends State<ChatGroupContent> {
/// Controller for the message input field
final _messageController = TextEditingController();
/// Controller for managing scroll position in the message list
final _scrollController = ScrollController();
/// Currently selected message for editing (null if not editing)
Message? _editingMessage;
@override
void initState() {
super.initState();
// Charger les messages au démarrage
// Load messages when the widget initializes
context.read<MessageBloc>().add(LoadMessages(widget.group.id));
}
@@ -39,12 +61,20 @@ class _ChatGroupContentState extends State<ChatGroupContent> {
super.dispose();
}
/// Sends a new message or updates an existing message.
///
/// Handles both sending new messages and editing existing ones based
/// on the current editing state. Validates input and clears the input
/// field after successful submission.
///
/// Args:
/// [currentUser]: The user sending or editing the message
void _sendMessage(user_state.UserModel currentUser) {
final messageText = _messageController.text.trim();
if (messageText.isEmpty) return;
if (_editingMessage != null) {
// Mode édition
// Edit mode - update existing message
context.read<MessageBloc>().add(
UpdateMessage(
groupId: widget.group.id,
@@ -54,7 +84,7 @@ class _ChatGroupContentState extends State<ChatGroupContent> {
);
_cancelEdit();
} else {
// Mode envoi
// Send mode - create new message
context.read<MessageBloc>().add(
SendMessage(
groupId: widget.group.id,
@@ -68,6 +98,13 @@ class _ChatGroupContentState extends State<ChatGroupContent> {
_messageController.clear();
}
/// Initiates editing mode for a selected message.
///
/// Sets the message as the currently editing message and populates
/// the input field with the message text for modification.
///
/// Args:
/// [message]: The message to edit
void _editMessage(Message message) {
setState(() {
_editingMessage = message;
@@ -75,6 +112,10 @@ class _ChatGroupContentState extends State<ChatGroupContent> {
});
}
/// Cancels the current editing operation.
///
/// Resets the editing state and clears the input field,
/// returning to normal message sending mode.
void _cancelEdit() {
setState(() {
_editingMessage = null;
@@ -82,6 +123,13 @@ class _ChatGroupContentState extends State<ChatGroupContent> {
});
}
/// Deletes a message from the group chat.
///
/// Sends a delete event to the MessageBloc to remove the specified
/// message from the group's message history.
///
/// Args:
/// [messageId]: The ID of the message to delete
void _deleteMessage(String messageId) {
context.read<MessageBloc>().add(
DeleteMessage(

37
lib/components/home/create_trip_content.dart
View File

@@ -20,8 +20,29 @@ import '../../repositories/group_repository.dart';
import 'package:http/http.dart' as http;
import 'package:flutter_dotenv/flutter_dotenv.dart';
/// Create trip content widget for trip creation and editing functionality.
///
/// This widget provides a comprehensive form interface for creating new trips
/// or editing existing ones. Key features include:
/// - Trip creation with validation
/// - Location search with autocomplete
/// - Date selection for trip duration
/// - Budget planning and management
/// - Group creation and member management
/// - Account setup for expense tracking
/// - Integration with mapping services for location selection
///
/// The widget handles both creation and editing modes based on the
/// provided tripToEdit parameter.
class CreateTripContent extends StatefulWidget {
/// Optional trip to edit. If null, creates a new trip
final Trip? tripToEdit;
/// Creates a create trip content widget.
///
/// Args:
/// [tripToEdit]: Optional trip to edit. If provided, the form will
/// be populated with existing trip data for editing
const CreateTripContent({
super.key,
this.tripToEdit,
@@ -32,30 +53,44 @@ class CreateTripContent extends StatefulWidget {
}
class _CreateTripContentState extends State<CreateTripContent> {
/// Service for handling and displaying errors
final _errorService = ErrorService();
/// Form validation key
final _formKey = GlobalKey<FormState>();
/// Text controllers for form fields
final _titleController = TextEditingController();
final _descriptionController = TextEditingController();
final _locationController = TextEditingController();
final _budgetController = TextEditingController();
final _participantController = TextEditingController();
/// Services for user and group operations
final _userService = UserService();
final _groupRepository = GroupRepository();
/// Trip date variables
DateTime? _startDate;
DateTime? _endDate;
/// Loading and state management variables
bool _isLoading = false;
String? _createdTripId;
/// Google Maps API key for location services
static final String _apiKey = dotenv.env['GOOGLE_MAPS_API_KEY'] ?? '';
/// Participant management
final List<String> _participants = [];
final _participantController = TextEditingController();
/// Location autocomplete functionality
List<PlaceSuggestion> _placeSuggestions = [];
bool _isLoadingSuggestions = false;
OverlayEntry? _suggestionsOverlay;
final LayerLink _layerLink = LayerLink();
/// Determines if the widget is in editing mode
bool get isEditing => widget.tripToEdit != null;
@override

22
lib/components/home/home_content.dart
View File

@@ -9,7 +9,20 @@ import '../../blocs/trip/trip_state.dart';
import '../../blocs/trip/trip_event.dart';
import '../../models/trip.dart';
/// Home content widget for the main application dashboard.
///
/// This widget serves as the primary content area of the home screen,
/// displaying user trips and providing navigation to trip management
/// features. Key functionality includes:
/// - Loading and displaying user trips
/// - Creating new trips
/// - Viewing trip details
/// - Managing trip state with proper user authentication
///
/// The widget maintains state persistence using AutomaticKeepAliveClientMixin
/// to preserve content when switching between tabs.
class HomeContent extends StatefulWidget {
/// Creates a home content widget.
const HomeContent({super.key});
@override
@@ -17,20 +30,27 @@ class HomeContent extends StatefulWidget {
}
class _HomeContentState extends State<HomeContent> with AutomaticKeepAliveClientMixin {
/// Preserves widget state when switching between tabs
@override
bool get wantKeepAlive => true;
/// Flag to prevent duplicate trip loading operations
bool _hasLoadedTrips = false;
@override
void initState() {
super.initState();
// MODIFIÉ : Utiliser addPostFrameCallback pour attendre que le widget tree soit prêt
// Use addPostFrameCallback to wait for the widget tree to be ready
WidgetsBinding.instance.addPostFrameCallback((_) {
_loadTripsIfUserLoaded();
});
}
/// Loads trips if a user is currently loaded and trips haven't been loaded yet.
///
/// Checks the current user state and initiates trip loading if the user is
/// authenticated and trips haven't been loaded previously. This prevents
/// duplicate loading operations.
void _loadTripsIfUserLoaded() {
if (!_hasLoadedTrips && mounted) {
final userState = context.read<UserBloc>().state;