Krow-workspace/bugs/BUG-REPORT-2026-01-31.md

Bug Report & Technical Debt Analysis

Branch: fix/check-boris Apps Tested: Client Mobile (Android)

---

Housekeeping: Git Hygiene Issue

Problem

Several Flutter-generated ephemeral files were incorrectly committed to the repository. These files are platform-specific symlinks and generated configs that should be ignored.

Affected Files

apps/mobile/apps/*/linux/flutter/ephemeral/.plugin_symlinks/*
apps/mobile/apps/*/windows/flutter/ephemeral/.plugin_symlinks/*
apps/mobile/apps/*/macos/Flutter/ephemeral/*
apps/mobile/apps/*/ios/Flutter/ephemeral/*

Fix Applied

1. Updated .gitignore to include:

# Ephemeral files (generated by Flutter for desktop platforms)
**/linux/flutter/ephemeral/
**/windows/flutter/ephemeral/
**/macos/Flutter/ephemeral/
**/ios/Flutter/ephemeral/

2. Run these commands to remove from tracking (files stay on disk):

git rm -r --cached apps/mobile/apps/client/linux/flutter/ephemeral/
git rm -r --cached apps/mobile/apps/client/windows/flutter/ephemeral/
git rm -r --cached apps/mobile/apps/client/macos/Flutter/ephemeral/
git rm -r --cached apps/mobile/apps/client/ios/Flutter/ephemeral/
git rm -r --cached apps/mobile/apps/staff/linux/flutter/ephemeral/
git rm -r --cached apps/mobile/apps/staff/windows/flutter/ephemeral/
git rm -r --cached apps/mobile/apps/staff/ios/Flutter/ephemeral/
git rm -r --cached apps/mobile/apps/design_system_viewer/ios/Flutter/ephemeral/
git rm -r --cached apps/mobile/apps/design_system_viewer/macos/Flutter/ephemeral/

Note on strings.g.dart

The file apps/mobile/packages/core_localization/lib/src/l10n/strings.g.dart is auto-generated by Slang. It is listed in apps/mobile/.gitignore as *.g.dart but was committed before the gitignore rule existed.

Recommendation: Remove from tracking with git rm --cached and regenerate via melos run gen:all after each pull.

---

Executive Summary

This report documents critical bugs discovered during manual testing of the Client mobile application, along with architectural issues requiring immediate attention. The analysis covers authentication flow, data model design, UI state management, and error handling practices.

Priority	Issue	Severity	Effort
P0	Auth/User Sync Issue	Critical	Medium
P1	Error Handling Architecture	High	High
P1	Order Display Logic	Medium	Low
P2	Hub Delete UI Freeze	Medium	Low
P2	Hub Name vs Address Display	Low	Low

---

Bug 1: Authentication & User Sync Issue

Status: CRITICAL

Description

Users who attempt to create an account may end up in an inconsistent state where:

• Firebase Authentication has their account (email/password stored)
• PostgreSQL database does NOT have their user profile

This results in:

• "Account already exists" when trying to register again
• "Incorrect email or password" when trying to log in (even with correct credentials)

Screenshots

• 1.png - Registration attempt with boris@bwnyasse.net showing "Account already exists"
• 2.png - Login attempt showing "Incorrect email or password"
• 3.png, 4.png - Additional registration failures

Root Cause

File: apps/mobile/packages/features/client/authentication/lib/src/data/repositories_impl/auth_repository_impl.dart

The registration flow (lines 57-120) performs three sequential operations:

// Step 1: Create Firebase Auth user
final credential = await _firebaseAuth.createUserWithEmailAndPassword(...);

// Step 2: Create Business in PostgreSQL
final createBusinessResponse = await _dataConnect.createBusiness(...);

// Step 3: Create User in PostgreSQL
final createUserResponse = await _dataConnect.createUser(...);

Problem: If Step 2 or Step 3 fails AFTER Step 1 succeeds:

• The rollback firebaseUser.delete() may fail silently
• User exists in Firebase Auth but NOT in PostgreSQL
• Login fails because _getUserProfile() cannot find the user (line 142-145)

Additionally, line 100 has an incomplete TODO:

// TO-DO: Also delete the created Business if this fails

If createUser fails, the orphaned Business record remains in PostgreSQL.

Technical Flow

Registration Attempt:
├─ Firebase Auth: createUserWithEmailAndPassword() ✓ (User created)
├─ Data Connect: createBusiness() ✓ (Business created)
└─ Data Connect: createUser() ✗ (FAILS - network error, constraint violation, etc.)
    └─ Rollback: firebaseUser.delete() ✗ (May fail silently)

Result:
- Firebase Auth: User EXISTS
- PostgreSQL users table: User MISSING
- PostgreSQL businesses table: Orphaned Business record

Subsequent Login:
├─ Firebase Auth: signInWithEmailAndPassword() ✓ (Credentials valid)
└─ _getUserProfile(): getUserById() returns NULL
    └─ Throws: "Authenticated user profile not found in database."
    └─ But error shown to user: "Incorrect email or password." (misleading!)

Recommended Fix

1. Implement transactional rollback:

Future<domain.User> signUpWithEmail({...}) async {
  firebase.User? firebaseUser;
  String? businessId;

  try {
    // Step 1
    final credential = await _firebaseAuth.createUserWithEmailAndPassword(...);
    firebaseUser = credential.user;

    // Step 2
    final businessResult = await _dataConnect.createBusiness(...);
    businessId = businessResult.data?.business_insert.id;

    // Step 3
    final userResult = await _dataConnect.createUser(...);
    if (userResult.data?.user_insert == null) {
      throw Exception('User creation failed');
    }

    return _getUserProfile(...);

  } catch (e) {
    // Full rollback
    if (businessId != null) {
      await _dataConnect.deleteBusiness(id: businessId).execute();
    }
    if (firebaseUser != null) {
      await firebaseUser.delete();
    }
    rethrow;
  }
}

2. Add admin tool to reconcile orphaned accounts
3. Add retry mechanism with idempotency checks

---

Bug 2: Hub Name vs Address Display

Status: LOW PRIORITY

Description

Order cards display the hub's street address instead of the hub name, creating inconsistency with the hub management screen.

Screenshots

• 5.png - Order showing "6800 San Jose Street, Granada Hills, CA, USA"
• 6.png - Order showing "San Jose Street"
• Compare with 7.png showing hub names: "Downtown Operations Hub", "Central Operations Hub"

Root Cause

File: apps/mobile/packages/features/client/view_orders/lib/src/presentation/widgets/view_order_card.dart

Lines 213-219 display order.locationAddress instead of order.location (hub name):

Expanded(
  child: Text(
    order.locationAddress,  // Shows address, not hub name
    style: UiTypography.footnote2r.textSecondary,
    maxLines: 1,
    overflow: TextOverflow.ellipsis,
  ),
),

The data is correctly stored during order creation in client_create_order_repository_impl.dart:

• Line 104: .location(hub.name) - Hub name
• Line 105: .locationAddress(hub.address) - Address

Recommended Fix

Update view_order_card.dart to show hub name as primary, address as secondary:

Column(
  crossAxisAlignment: CrossAxisAlignment.start,
  children: [
    Text(
      order.location,  // Hub name
      style: UiTypography.body2m.textPrimary,
    ),
    Text(
      order.locationAddress,  // Address as subtitle
      style: UiTypography.footnote2r.textSecondary,
    ),
  ],
),

---

Bug 3: Hub Delete UI Freeze

Status: MEDIUM PRIORITY

Description

After attempting to delete a hub that has orders (which correctly shows an error), subsequent delete attempts on ANY hub cause the UI to freeze with a loading overlay that never disappears.

Screenshot

• 7.png - Error message "Sorry this hub has orders, it can't be deleted."

Root Cause

File: apps/mobile/packages/features/client/hubs/lib/src/presentation/blocs/client_hubs_state.dart

The copyWith method cannot reset errorMessage to null due to Dart's null-coalescing behavior:

ClientHubsState copyWith({
  String? errorMessage,
  String? successMessage,
  // ...
}) {
  return ClientHubsState(
    // BUG: null ?? this.errorMessage keeps the OLD value!
    errorMessage: errorMessage ?? this.errorMessage,
    successMessage: successMessage ?? this.successMessage,
    // ...
  );
}

Flow of the bug:

1. Delete Hub A → Error "Sorry this hub has orders..."
2. _onMessageCleared calls copyWith(errorMessage: null)
3. null ?? this.errorMessage = OLD ERROR MESSAGE (not cleared!)
4. Delete Hub B → Same error message
5. listenWhen checks: previous.errorMessage != current.errorMessage
6. Both are "Sorry this hub has orders..." → FALSE, listener not called
7. MessageCleared never sent → Status never resets → Overlay stays forever

Proof the team knows this pattern: They correctly implemented clearHubToIdentify flag (lines 45, 53-54) but forgot to do the same for messages.

Recommended Fix

File: client_hubs_state.dart

ClientHubsState copyWith({
  ClientHubsStatus? status,
  List<Hub>? hubs,
  String? errorMessage,
  String? successMessage,
  bool? showAddHubDialog,
  Hub? hubToIdentify,
  bool clearHubToIdentify = false,
  bool clearErrorMessage = false,      // ADD THIS
  bool clearSuccessMessage = false,    // ADD THIS
}) {
  return ClientHubsState(
    status: status ?? this.status,
    hubs: hubs ?? this.hubs,
    errorMessage: clearErrorMessage
        ? null
        : (errorMessage ?? this.errorMessage),
    successMessage: clearSuccessMessage
        ? null
        : (successMessage ?? this.successMessage),
    showAddHubDialog: showAddHubDialog ?? this.showAddHubDialog,
    hubToIdentify: clearHubToIdentify
        ? null
        : (hubToIdentify ?? this.hubToIdentify),
  );
}

File: client_hubs_bloc.dart - Update _onMessageCleared:

void _onMessageCleared(
  ClientHubsMessageCleared event,
  Emitter<ClientHubsState> emit,
) {
  emit(
    state.copyWith(
      clearErrorMessage: true,      // USE FLAG
      clearSuccessMessage: true,    // USE FLAG
      status: state.status == ClientHubsStatus.actionSuccess ||
              state.status == ClientHubsStatus.actionFailure
          ? ClientHubsStatus.success
          : state.status,
    ),
  );
}

---

Bug 4: Order Display Shows Positions as Separate Orders

Status: MEDIUM PRIORITY - DESIGN DECISION NEEDED

Description

When creating an order with multiple positions (e.g., 1 Cook + 1 Bartender), the Orders list shows them as separate cards instead of a single order with multiple positions.

Screenshot

• 8.png - Shows "Cook - Boris Test Order 1" and "Bartender - Boris Test Order 1" as separate cards

Analysis

This is NOT a data bug. The data model is correct:

• 1 Order → 1 Shift → N ShiftRoles (positions)

The issue is in the display logic.

File: apps/mobile/packages/features/client/view_orders/lib/src/data/repositories/view_orders_repository_impl.dart

Lines 32-89 query ShiftRoles and create one OrderItem per role:

// Query returns ShiftRoles, not Orders
final result = await _dataConnect
    .listShiftRolesByBusinessAndDateRange(...)
    .execute();

// Each ShiftRole becomes a card
return result.data.shiftRoles.map((shiftRole) {
  return domain.OrderItem(
    title: '${shiftRole.role.name} - $eventName',  // "Cook - Boris Test Order 1"
    // ...
  );
}).toList();

Options

Option A: Keep current behavior (per-position cards)

• Pros: Granular view of each position's status
• Cons: Confusing for users who think they created one order

Option B: Group by Order (recommended)

• Pros: Matches user mental model
• Cons: Requires refactoring view layer

Recommended Fix (Option B)

Future<List<domain.OrderItem>> getOrdersForRange({...}) async {
  final result = await _dataConnect
      .listShiftRolesByBusinessAndDateRange(...)
      .execute();

  // Group ShiftRoles by Order ID
  final Map<String, List<ShiftRole>> orderGroups = {};
  for (final shiftRole in result.data.shiftRoles) {
    final orderId = shiftRole.shift.order.id;
    orderGroups.putIfAbsent(orderId, () => []);
    orderGroups[orderId]!.add(shiftRole);
  }

  // Create one OrderItem per Order with positions summary
  return orderGroups.entries.map((entry) {
    final roles = entry.value;
    final firstRole = roles.first;
    final positionsSummary = roles.map((r) => r.role.name).join(', ');
    final totalWorkers = roles.fold(0, (sum, r) => sum + r.count);

    return domain.OrderItem(
      id: entry.key,
      orderId: entry.key,
      title: firstRole.shift.order.eventName ?? 'Order',
      subtitle: positionsSummary,  // "Cook, Bartender"
      workersNeeded: totalWorkers,
      // ... aggregate other fields
    );
  }).toList();
}

---

Bug 5: Mock Data in Production Views

Status: INFORMATIONAL

Description

The Coverage screen shows "Jose Salazar - Checked in at 9:00 AM" which appears to be test/mock data.

Screenshot

• 9.png - Daily Coverage showing mock worker data

Recommendation

Ensure mock data is clearly separated and not visible in builds distributed for testing. Consider adding a visual indicator (e.g., "TEST DATA" banner) when using mock repositories.

---

Architectural Issue: Error Handling

Status: HIGH PRIORITY - TECHNICAL DEBT

Description

The application exposes raw technical error messages to end users. This is unprofessional and potentially a security concern.

Evidence

Found 60+ instances of throw Exception('technical message') across the codebase:

// Examples of problematic error messages shown to users:
throw Exception('Authenticated user profile not found in database.');
throw Exception('Business creation failed after Firebase user registration.');
throw Exception('Staff profile not found for User ID: ${user.uid}');
throw Exception('Failed to fetch certificates: $e');  // Exposes stack trace!
throw Exception('Error signing out: ${e.toString()}');

Current State

• No centralized error handling system
• No custom exception classes
• Technical messages shown directly to users
• No i18n support for error messages
• No error codes for logging/tracking

Recommended Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         DOMAIN LAYER                            │
│                                                                 │
│  packages/domain/lib/src/exceptions/app_exception.dart          │
│                                                                 │
│  sealed class AppException implements Exception {               │
│    const AppException({required this.code, this.technical});    │
│    final String code;           // For logging: "AUTH_001"      │
│    final String? technical;     // For devs only                │
│    String get messageKey;       // For i18n: "errors.auth.x"    │
│  }                                                              │
│                                                                 │
│  class InvalidCredentialsException extends AuthException {      │
│    String get messageKey => 'errors.auth.invalid_credentials';  │
│  }                                                              │
│                                                                 │
│  class HubHasOrdersException extends HubException {             │
│    String get messageKey => 'errors.hub.has_orders';            │
│  }                                                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      PRESENTATION LAYER                         │
│                                                                 │
│  } on AppException catch (e) {                                  │
│    log('Error ${e.code}: ${e.technical}');  // Dev logging      │
│    emit(state.copyWith(errorKey: e.messageKey));                │
│  } catch (e) {                                                  │
│    log('Unexpected: $e');                                       │
│    emit(state.copyWith(errorKey: 'errors.generic.unknown'));    │
│  }                                                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     LOCALIZATION (i18n)                         │
│                                                                 │
│  errors:                                                        │
│    auth:                                                        │
│      invalid_credentials: "Email or password is incorrect"      │
│      account_exists: "An account with this email exists"        │
│      session_expired: "Please sign in again"                    │
│    hub:                                                         │
│      has_orders: "This hub has active orders"                   │
│    order:                                                       │
│      missing_hub: "Please select a location"                    │
│    generic:                                                     │
│      unknown: "Something went wrong. Please try again."         │
│      no_connection: "No internet connection"                    │
└─────────────────────────────────────────────────────────────────┘

Implementation Plan

Phase 1: Create Exception Classes (1 hour)

Create: packages/domain/lib/src/exceptions/app_exception.dart

/// Base sealed class for all application exceptions.
sealed class AppException implements Exception {
  const AppException({
    required this.code,
    this.technicalMessage,
  });

  /// Unique error code for logging/tracking (e.g., "AUTH_001")
  final String code;

  /// Technical details for developers (never shown to users)
  final String? technicalMessage;

  /// Returns the localization key for user-friendly message
  String get messageKey;

  @override
  String toString() => 'AppException($code): $technicalMessage';
}

// ============================================================
// AUTH EXCEPTIONS
// ============================================================

sealed class AuthException extends AppException {
  const AuthException({required super.code, super.technicalMessage});
}

class InvalidCredentialsException extends AuthException {
  const InvalidCredentialsException({String? technicalMessage})
      : super(code: 'AUTH_001', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.auth.invalid_credentials';
}

class AccountExistsException extends AuthException {
  const AccountExistsException({String? technicalMessage})
      : super(code: 'AUTH_002', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.auth.account_exists';
}

class SessionExpiredException extends AuthException {
  const SessionExpiredException({String? technicalMessage})
      : super(code: 'AUTH_003', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.auth.session_expired';
}

class UserNotFoundException extends AuthException {
  const UserNotFoundException({String? technicalMessage})
      : super(code: 'AUTH_004', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.auth.user_not_found';
}

class UnauthorizedAppException extends AuthException {
  const UnauthorizedAppException({String? technicalMessage})
      : super(code: 'AUTH_005', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.auth.unauthorized_app';
}

class WeakPasswordException extends AuthException {
  const WeakPasswordException({String? technicalMessage})
      : super(code: 'AUTH_006', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.auth.weak_password';
}

// ============================================================
// HUB EXCEPTIONS
// ============================================================

sealed class HubException extends AppException {
  const HubException({required super.code, super.technicalMessage});
}

class HubHasOrdersException extends HubException {
  const HubHasOrdersException({String? technicalMessage})
      : super(code: 'HUB_001', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.hub.has_orders';
}

class HubNotFoundException extends HubException {
  const HubNotFoundException({String? technicalMessage})
      : super(code: 'HUB_002', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.hub.not_found';
}

class HubCreationFailedException extends HubException {
  const HubCreationFailedException({String? technicalMessage})
      : super(code: 'HUB_003', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.hub.creation_failed';
}

// ============================================================
// ORDER EXCEPTIONS
// ============================================================

sealed class OrderException extends AppException {
  const OrderException({required super.code, super.technicalMessage});
}

class OrderMissingHubException extends OrderException {
  const OrderMissingHubException({String? technicalMessage})
      : super(code: 'ORDER_001', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.order.missing_hub';
}

class OrderMissingVendorException extends OrderException {
  const OrderMissingVendorException({String? technicalMessage})
      : super(code: 'ORDER_002', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.order.missing_vendor';
}

class OrderCreationFailedException extends OrderException {
  const OrderCreationFailedException({String? technicalMessage})
      : super(code: 'ORDER_003', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.order.creation_failed';
}

class ShiftCreationFailedException extends OrderException {
  const ShiftCreationFailedException({String? technicalMessage})
      : super(code: 'ORDER_004', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.order.shift_creation_failed';
}

// ============================================================
// PROFILE EXCEPTIONS
// ============================================================

sealed class ProfileException extends AppException {
  const ProfileException({required super.code, super.technicalMessage});
}

class StaffProfileNotFoundException extends ProfileException {
  const StaffProfileNotFoundException({String? technicalMessage})
      : super(code: 'PROFILE_001', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.profile.staff_not_found';
}

class BusinessNotFoundException extends ProfileException {
  const BusinessNotFoundException({String? technicalMessage})
      : super(code: 'PROFILE_002', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.profile.business_not_found';
}

// ============================================================
// NETWORK/GENERIC EXCEPTIONS
// ============================================================

class NetworkException extends AppException {
  const NetworkException({String? technicalMessage})
      : super(code: 'NET_001', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.generic.no_connection';
}

class UnknownException extends AppException {
  const UnknownException({String? technicalMessage})
      : super(code: 'UNKNOWN', technicalMessage: technicalMessage);

  @override
  String get messageKey => 'errors.generic.unknown';
}

Phase 2: Add Localization Keys (30 minutes)

Update: packages/core_localization/lib/src/l10n/strings.i18n.yaml

errors:
  auth:
    invalid_credentials: "The email or password you entered is incorrect."
    account_exists: "An account with this email already exists. Try signing in instead."
    session_expired: "Your session has expired. Please sign in again."
    user_not_found: "We couldn't find your account. Please check your email and try again."
    unauthorized_app: "This account is not authorized for this app."
    weak_password: "Please choose a stronger password with at least 8 characters."
  hub:
    has_orders: "This hub has active orders and cannot be deleted."
    not_found: "The hub you're looking for doesn't exist."
    creation_failed: "We couldn't create the hub. Please try again."
  order:
    missing_hub: "Please select a location for your order."
    missing_vendor: "Please select a vendor for your order."
    creation_failed: "We couldn't create your order. Please try again."
    shift_creation_failed: "We couldn't schedule the shift. Please try again."
  profile:
    staff_not_found: "Your profile couldn't be loaded. Please sign in again."
    business_not_found: "Your business profile couldn't be loaded. Please sign in again."
  generic:
    unknown: "Something went wrong. Please try again."
    no_connection: "No internet connection. Please check your network and try again."

Phase 3: Migrate Repositories (4-6 hours)

Example migration for auth_repository_impl.dart:

// BEFORE
if (e.code == 'invalid-credential' || e.code == 'wrong-password') {
  throw Exception('Incorrect email or password.');
}

// AFTER
if (e.code == 'invalid-credential' || e.code == 'wrong-password') {
  throw InvalidCredentialsException(
    technicalMessage: 'Firebase error: ${e.code}',
  );
}

// BEFORE
if (e.code == 'email-already-in-use') {
  throw Exception('An account already exists for that email address.');
}

// AFTER
if (e.code == 'email-already-in-use') {
  throw AccountExistsException(
    technicalMessage: 'Email: $email',
  );
}

// BEFORE
if (user == null) {
  throw Exception('Authenticated user profile not found in database.');
}

// AFTER
if (user == null) {
  throw UserNotFoundException(
    technicalMessage: 'Firebase UID: $firebaseUserId not found in users table',
  );
}

Phase 4: Update BLoCs (2-3 hours)

Example for client_hubs_bloc.dart:

// BEFORE
Future<void> _onDeleteRequested(...) async {
  emit(state.copyWith(status: ClientHubsStatus.actionInProgress));
  try {
    await _deleteHubUseCase(DeleteHubArguments(hubId: event.hubId));
    final List<Hub> hubs = await _getHubsUseCase();
    emit(state.copyWith(
      status: ClientHubsStatus.actionSuccess,
      hubs: hubs,
      successMessage: 'Hub deleted successfully',
    ));
  } catch (e) {
    emit(state.copyWith(
      status: ClientHubsStatus.actionFailure,
      errorMessage: e.toString(),  // EXPOSES TECHNICAL ERROR!
    ));
  }
}

// AFTER
Future<void> _onDeleteRequested(...) async {
  emit(state.copyWith(status: ClientHubsStatus.actionInProgress));
  try {
    await _deleteHubUseCase(DeleteHubArguments(hubId: event.hubId));
    final List<Hub> hubs = await _getHubsUseCase();
    emit(state.copyWith(
      status: ClientHubsStatus.actionSuccess,
      hubs: hubs,
      successMessageKey: 'success.hub.deleted',
    ));
  } on AppException catch (e) {
    // Log technical details for debugging
    debugPrint('Error ${e.code}: ${e.technicalMessage}');
    emit(state.copyWith(
      status: ClientHubsStatus.actionFailure,
      errorMessageKey: e.messageKey,
    ));
  } catch (e, stackTrace) {
    // Unexpected error - log full details
    debugPrint('Unexpected error: $e\n$stackTrace');
    emit(state.copyWith(
      status: ClientHubsStatus.actionFailure,
      errorMessageKey: 'errors.generic.unknown',
    ));
  }
}

Phase 5: Update UI Layer (1-2 hours)

Example for client_hubs_page.dart:

// BEFORE
listener: (context, state) {
  if (state.errorMessage != null && state.errorMessage!.isNotEmpty) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(state.errorMessage!)),
    );
    // ...
  }
}

// AFTER
listener: (context, state) {
  if (state.errorMessageKey != null) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(t[state.errorMessageKey!])),
    );
    // ...
  }
}

---

Summary of Required Changes

Immediate Fixes (This Sprint)

File	Change	Priority
client_hubs_state.dart	Add clearErrorMessage/clearSuccessMessage flags	P2
client_hubs_bloc.dart	Use clear flags in _onMessageCleared	P2
view_order_card.dart	Display location instead of locationAddress	P2

Short-term (Next Sprint)

Task	Effort
Create AppException sealed class in domain	1h
Add error localization keys	30min
Migrate auth repositories	2h
Migrate hub repositories	1h

Medium-term (Next 2-3 Sprints)

Task	Effort
Migrate all repositories to AppException	4-6h
Update all BLoCs for proper error handling	2-3h
Update all UI components for localized errors	1-2h
Add admin tool to reconcile orphaned Firebase accounts	4h

---

Appendix: Files Requiring Changes

Repositories with throw Exception() to migrate:

1. packages/features/client/authentication/lib/src/data/repositories_impl/auth_repository_impl.dart (13 instances)
2. packages/features/client/hubs/lib/src/data/repositories_impl/hub_repository_impl.dart (6 instances)
3. packages/features/client/create_order/lib/src/data/repositories_impl/client_create_order_repository_impl.dart (6 instances)
4. packages/features/client/view_orders/lib/src/data/repositories/view_orders_repository_impl.dart (2 instances)
5. packages/features/client/settings/lib/src/data/repositories_impl/settings_repository_impl.dart (1 instance)
6. packages/features/staff/authentication/lib/src/data/repositories_impl/auth_repository_impl.dart (7 instances)
7. packages/features/staff/shifts/lib/src/data/repositories_impl/shifts_repository_impl.dart (2 instances)
8. packages/features/staff/profile/lib/src/data/repositories/profile_repository_impl.dart (3 instances)
9. packages/features/staff/availability/lib/src/data/repositories_impl/availability_repository_impl.dart (2 instances)
10. packages/features/staff/clock_in/lib/src/data/repositories_impl/clock_in_repository_impl.dart (3 instances)
11. And 10+ more files in staff profile sections...

---

Report prepared for development team review.