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'),
)
);
}