User Taps "Save"
       ↓
Generate UUID (once — never regenerated on retry)
       ↓
Serialize payload → JSON string
       ↓
Store in Hive queue
       ↓
Send request + Idempotency-Key header
       ↓
        Success (2xx)?
       ┌──────┴──────┐
      Yes             No (network error)
       ↓                    ↓
Remove from queue    Increment retryCount in Hive
                     Retry on next reconnect
                     (max 5 attempts)

# pubspec.yaml
dependencies:
  flutter_riverpod: ^2.5.1
  hive_flutter: ^1.1.0
  uuid: ^4.3.3
  dio: ^5.4.3
  internet_connection_checker: ^1.0.0+1  # connectivity_plus alone is not enough

dev_dependencies:
  hive_generator: ^2.0.1
  build_runner: ^2.4.9

import 'dart:convert';
import 'package:hive/hive.dart';

part 'pending_operation.g.dart';

@HiveType(typeId: 0)
class PendingOperation extends HiveObject {

  @HiveField(0)
  late String id;              // the idempotency key — generated once, never changed on retry

  @HiveField(1)
  late String endpoint;        // e.g. '/api/v1/farms'

  @HiveField(2)
  late String payloadJson;     // JSON string — NOT Map<String, dynamic> (Hive adapter limitation)

  @HiveField(3)
  late DateTime createdAt;

  @HiveField(4)
  late int retryCount;

  // Convenience getter so callers don't have to decode manually
  Map<String, dynamic> get payload => jsonDecode(payloadJson) as Map<String, dynamic>;
}

class OfflineQueueService {
  static const _boxName = 'pending_ops';

  Future<Box<PendingOperation>> get _box async =>
      await Hive.openBox<PendingOperation>(_boxName);

  // Call this BEFORE making any network request.
  Future<PendingOperation> enqueue(
    String endpoint,
    Map<String, dynamic> payload,
  ) async {
    final op = PendingOperation()
      ..id = const Uuid().v4()           // one UUID per user intent — never recreated
      ..endpoint = endpoint
      ..payloadJson = jsonEncode(payload) // serialize to string for Hive compatibility
      ..createdAt = DateTime.now()
      ..retryCount = 0;

    final box = await _box;
    await box.put(op.id, op);            // key by idempotency key for direct lookup
    return op;
  }

  Future<void> dequeue(String operationId) async {
    final box = await _box;
    await box.delete(operationId);
  }

  Future<List<PendingOperation>> getPending() async {
    final box = await _box;
    return box.values.toList();
  }
}

class FarmRepository {
  final Dio _dio;
  final OfflineQueueService _queue;

  FarmRepository(this._dio, this._queue);

  // Called on first submission — generates the UUID and enqueues.
  Future<void> saveFarm(Map<String, dynamic> farmData) async {
    final op = await _queue.enqueue('/api/v1/farms', farmData);
    await _sendOperation(op);
  }

  // Called by the retry sweep — reuses the ORIGINAL UUID. Never generates a new one.
  Future<void> retryOperation(PendingOperation op) async {
    await _sendOperation(op);
  }

  Future<void> _sendOperation(PendingOperation op) async {
    try {
      await _dio.post(
        op.endpoint,
        data: op.payload,
        options: Options(headers: {
          // Same key on every attempt — server deduplicates on this value.
          'Idempotency-Key': op.id,
        }),
      );

      // Dio throws on non-2xx by default, so reaching this line means
      // the server returned 200, 201, 202, or 204 — any successful 2xx.
      await _queue.dequeue(op.id);

    } on DioException catch (e) {
      if (e.response != null) {
        // Got a real HTTP error (4xx/5xx) — not a network issue.
        // Remove from queue: retrying a bad request won't help.
        await _queue.dequeue(op.id);
        rethrow;
      }

      // Network failure — leave in Hive and increment the retry counter.
      op.retryCount++;
      await op.save();
    }
  }
}

final farmRepositoryProvider = Provider((ref) => FarmRepository(
  ref.read(dioProvider),
  ref.read(offlineQueueServiceProvider),
));

final saveFarmProvider =
    StateNotifierProvider<SaveFarmNotifier, AsyncValue<void>>(
  (ref) => SaveFarmNotifier(ref.read(farmRepositoryProvider)),
);

class SaveFarmNotifier extends StateNotifier<AsyncValue<void>> {
  final FarmRepository _repo;

  SaveFarmNotifier(this._repo) : super(const AsyncData(null));

  Future<void> save(Map<String, dynamic> farmData) async {
    // Guard against double-taps within the same session.
    if (state is AsyncLoading) return;

    state = const AsyncLoading();
    state = await AsyncValue.guard(() => _repo.saveFarm(farmData));
  }
}

ElevatedButton(
  onPressed: state is AsyncLoading
      ? null
      : () => ref.read(saveFarmProvider.notifier).save(farmData),
  child: state is AsyncLoading
      ? const CircularProgressIndicator()
      : const Text('Save Farm'),
)

class ConnectivityRetryService {
  final OfflineQueueService _queue;
  final FarmRepository _repo;

  ConnectivityRetryService(this._queue, this._repo);

  void listen() {
    Connectivity().onConnectivityChanged.listen((result) async {
      if (result == ConnectivityResult.none) return;

      // Connectivity ≠ internet. Probe a real host before retrying.
      final hasInternet = await InternetConnectionChecker().hasConnection;
      if (!hasInternet) return;

      final pending = await _queue.getPending();

      for (final op in pending) {
        // Hard cap — after 5 failures, surface an error instead of retrying forever.
        if (op.retryCount >= 5) {
          // TODO: emit a notification or a Riverpod state so the UI can prompt the user.
          continue;
        }

        // Use retryOperation — NOT saveFarm — to preserve the original UUID.
        await _repo.retryOperation(op);
      }
    });
  }
}

// Spring Boot — same concept applies in NestJS
@PostMapping("/api/v1/farms")
public ResponseEntity<?> createFarm(
    @RequestHeader("Idempotency-Key") String idempotencyKey,
    @RequestBody FarmRequest request
) {
    // Return the already-created record instead of inserting a duplicate.
    if (farmRepo.existsByIdempotencyKey(idempotencyKey)) {
        return ResponseEntity.ok(farmRepo.findByIdempotencyKey(idempotencyKey));
    }
    return ResponseEntity.status(201).body(farmService.create(request, idempotencyKey));
}