/// Submissions Repository
///
/// Repository interface for project submissions operations.
library;

import 'package:worker/features/projects/data/models/project_submission_request.dart';
import 'package:worker/features/projects/domain/entities/project_progress.dart';
import 'package:worker/features/projects/domain/entities/project_status.dart';
import 'package:worker/features/projects/domain/entities/project_submission.dart';

/// Submissions Repository
///
/// Defines contract for project submissions data operations.
abstract class SubmissionsRepository {
  /// Get list of available project statuses
  ///
  /// Uses cache-first pattern:
  /// - Returns cached data if available
  /// - Fetches from API and updates cache
  /// - [forceRefresh] bypasses cache and fetches fresh data
  Future<List<ProjectStatus>> getProjectStatusList({
    bool forceRefresh = false,
  });

  /// Get list of construction progress stages
  ///
  /// Uses cache-first pattern:
  /// - Returns cached data if available
  /// - Fetches from API and updates cache
  /// - [forceRefresh] bypasses cache and fetches fresh data
  Future<List<ProjectProgress>> getProjectProgressList({
    bool forceRefresh = false,
  });

  /// Get all project submissions for the current user
  Future<List<ProjectSubmission>> getSubmissions({
    int limitStart = 0,
    int limitPageLength = 0,
  });

  /// Get project detail by name
  /// Returns the full project detail as entity for form prefilling
  Future<ProjectSubmission> getSubmissionDetail(String name);

  /// Save (create/update) a project submission
  /// Returns the project name (ID) from the API response
  Future<String> saveSubmission(ProjectSubmissionRequest request);

  /// Upload a file for a project submission
  /// [projectName] is the project ID returned from saveSubmission
  /// [filePath] is the local path to the file
  /// Returns the uploaded file URL
  Future<String> uploadProjectFile({
    required String projectName,
    required String filePath,
  });

  /// Delete a file from a project submission
  /// [fileId] is the file ID to delete
  /// [projectName] is the project name (docname)
  Future<void> deleteProjectFile({
    required String fileId,
    required String projectName,
  });
}
