feat: add AI recommendations flow for tenders

Implement company AI onboarding/recommendation models, services, repository, and tender UI integration with supporting tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

lib/view_models/ai_recommendations_view_model.dart

@@ -0,0 +1,132 @@
+import 'package:flutter/foundation.dart';
+import 'package:tm_app/core/network/app_exceptions.dart';
+import 'package:tm_app/core/utils/result.dart';
+import 'package:tm_app/data/repositories/company_ai_repository.dart';
+import 'package:tm_app/data/repositories/home_repository.dart';
+import 'package:tm_app/data/services/model/recommend_response/recommend_response.dart';
+import 'package:tm_app/data/services/model/recommendation_item/recommendation_item.dart';
+import 'package:tm_app/data/services/model/recommended_tenders_response/recommended_tenders_response.dart';
+import 'package:tm_app/data/services/model/tender_data/tender_data.dart';
+
+/// Drives the "Recommended" (AI) tab in the tenders section.
+///
+/// Calls `POST /api/v1/recommend`. When the AI service is unavailable (503) it
+/// falls back to the legacy CPV/keyword list (`GET /api/v1/tenders/recommend`),
+/// and when the AI returns no results shortly after onboarding it surfaces a
+/// "still learning" hint instead of an empty error.
+class AiRecommendationsViewModel with ChangeNotifier {
+  AiRecommendationsViewModel({
+    required CompanyAiRepository companyAiRepository,
+    required HomeRepository homeRepository,
+  }) : _companyAiRepository = companyAiRepository,
+       _homeRepository = homeRepository;
+
+  final CompanyAiRepository _companyAiRepository;
+  final HomeRepository _homeRepository;
+
+  /// How long after onboarding an empty result is treated as "still learning".
+  static const Duration _stillLearningWindow = Duration(minutes: 30);
+  static const int _fallbackPageSize = 20;
+
+  bool _isLoading = false;
+  String? _errorMessage;
+  List<RecommendationItem> _items = const [];
+  List<TenderData> _fallbackTenders = const [];
+  bool _usingFallback = false;
+  bool _stillLearning = false;
+  bool _hasLoaded = false;
+
+  bool get isLoading => _isLoading;
+  String? get errorMessage => _errorMessage;
+  List<RecommendationItem> get items => _items;
+  List<TenderData> get fallbackTenders => _fallbackTenders;
+  bool get usingFallback => _usingFallback;
+  bool get stillLearning => _stillLearning;
+
+  /// True once a load has completed (used to distinguish "no results" from
+  /// "not loaded yet").
+  bool get hasLoaded => _hasLoaded;
+
+  /// True when there is nothing to show and we're not loading or erroring.
+  bool get isEmpty =>
+      !_isLoading &&
+      _errorMessage == null &&
+      _items.isEmpty &&
+      _fallbackTenders.isEmpty;
+
+  /// Loads recommendations if they haven't been loaded yet this session.
+  Future<void> loadIfNeeded() async {
+    if (_hasLoaded || _isLoading) {
+      return;
+    }
+    await loadRecommendations();
+  }
+
+  /// Loads AI recommendations, applying the 503 fallback and empty-state logic.
+  Future<void> loadRecommendations() async {
+    _isLoading = true;
+    _errorMessage = null;
+    _usingFallback = false;
+    _stillLearning = false;
+    notifyListeners();
+
+    final result = await _companyAiRepository.getRecommendations();
+
+    switch (result) {
+      case Ok<RecommendResponse>():
+        _items = result.value.data ?? const [];
+        _fallbackTenders = const [];
+        if (_items.isEmpty) {
+          _stillLearning = _onboardingWasRecent();
+        }
+      case Error<RecommendResponse>():
+        await _handleError(result.error);
+    }
+
+    _isLoading = false;
+    _hasLoaded = true;
+    notifyListeners();
+  }
+
+  /// Pull-to-refresh: always re-fetches.
+  Future<void> refresh() => loadRecommendations();
+
+  Future<void> _handleError(Exception error) async {
+    // 503 means the AI service isn't configured/available — fall back to the
+    // legacy recommend list rather than showing an error.
+    if (error is AppException && error.statusCode == 503) {
+      await _loadFallback();
+      return;
+    }
+    _items = const [];
+    _fallbackTenders = const [];
+    _errorMessage = error.toString();
+  }
+
+  Future<void> _loadFallback() async {
+    final result = await _homeRepository.getHomeRecommendedTenders(
+      limit: _fallbackPageSize,
+      offset: 0,
+    );
+
+    switch (result) {
+      case Ok<RecommendedTendersResponse>():
+        _items = const [];
+        _fallbackTenders =
+            result.value.data?.tenders.whereType<TenderData>().toList() ??
+            const [];
+        _usingFallback = true;
+      case Error<RecommendedTendersResponse>():
+        _errorMessage = result.error.toString();
+    }
+  }
+
+  bool _onboardingWasRecent() {
+    final startedAt = _companyAiRepository.lastOnboardingStartedAt();
+    if (startedAt == null) {
+      return false;
+    }
+    final elapsed = DateTime.now().millisecondsSinceEpoch - startedAt;
+    return elapsed >= 0 && elapsed <= _stillLearningWindow.inMilliseconds;
+  }
+}

lib/view_models/profile_view_model.dart

@@ -1,5 +1,8 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:tm_app/data/repositories/auth_repository.dart';
+import 'package:tm_app/data/repositories/company_ai_repository.dart';
 import 'package:tm_app/data/services/model/company_profile_data/company_profile_data.dart';
 import 'package:tm_app/data/services/model/company_profile_response/company_profile_response.dart';
 import 'package:tm_app/data/services/model/profile_data/profile_data.dart';
@@ -12,12 +15,15 @@ import '../data/services/model/profile_response/profile_response.dart';
 class ProfileViewModel with ChangeNotifier {
   final ProfileRepository _profileRepository;
   final AuthRepository _authRepository;
+  final CompanyAiRepository _companyAiRepository;
 
   ProfileViewModel({
     required ProfileRepository profileRepository,
     required AuthRepository authRepository,
+    required CompanyAiRepository companyAiRepository,
   }) : _profileRepository = profileRepository,
-       _authRepository = authRepository;
+       _authRepository = authRepository,
+       _companyAiRepository = companyAiRepository;
 
   bool _isLoading = false;
   String? _errorMessage;
@@ -62,6 +68,7 @@ class ProfileViewModel with ChangeNotifier {
     switch (result) {
       case Ok<CompanyProfileResponse>():
         _companyProfileData = result.value.data;
+        _maybeStartAiOnboarding(_companyProfileData);
         break;
       case Error<CompanyProfileResponse>():
         _errorMessage = result.error.toString();
@@ -73,6 +80,22 @@ class ProfileViewModel with ChangeNotifier {
     notifyListeners();
   }
 
+  /// Best-effort AI onboarding once the company profile is ready. Fire-and-
+  /// forget: onboarding is asynchronous on the AI side and the fingerprint
+  /// guard in [CompanyAiRepository] keeps it from re-running unnecessarily, so
+  /// the profile screen never blocks or surfaces errors for it.
+  void _maybeStartAiOnboarding(CompanyProfileData? company) {
+    if (company == null) {
+      return;
+    }
+    unawaited(
+      _companyAiRepository.maybeStartOnboarding(
+        documentFileIds: company.documentFileIds ?? const [],
+        website: company.website,
+      ),
+    );
+  }
+
   Future<void> logout() async {
     _errorMessage = null;
     notifyListeners();