superport/lib/domain/repositories/company_repository.dart

import 'package:dartz/dartz.dart';
import '../../core/errors/failures.dart';
import '../../models/company_model.dart';
import '../../data/models/common/paginated_response.dart';

/// 회사 관리 Repository 인터페이스
/// 회사 및 지점 정보 관리를 위한 CRUD 기능을 담당
abstract class CompanyRepository {
  /// 회사 목록 조회
  /// [page] 페이지 번호 (기본값: 1)
  /// [limit] 페이지당 항목 수 (기본값: 20)
  /// [search] 검색어 (회사명, 담당자명 등)
  /// [companyType] 회사 유형 필터 (고객사, 파트너사)
  /// [sortBy] 정렬 기준 ('name', 'createdAt' 등)
  /// [sortOrder] 정렬 순서 ('asc', 'desc')
  /// Returns: 페이지네이션된 회사 목록
  Future<Either<Failure, PaginatedResponse<Company>>> getCompanies({
    int? page,
    int? limit,
    String? search,
    CompanyType? companyType,
    String? sortBy,
    String? sortOrder,
  });

  /// 회사 상세 정보 조회
  /// [id] 회사 고유 식별자
  /// Returns: 지점 정보를 포함한 회사 상세 정보
  Future<Either<Failure, Company>> getCompanyById(int id);

  /// 회사 생성
  /// [company] 생성할 회사 정보
  /// Returns: 생성된 회사 정보 (ID 포함)
  Future<Either<Failure, Company>> createCompany(Company company);

  /// 회사 정보 수정
  /// [id] 수정할 회사 고유 식별자
  /// [company] 수정할 회사 정보
  /// Returns: 수정된 회사 정보
  Future<Either<Failure, Company>> updateCompany(int id, Company company);

  /// 회사 삭제
  /// [id] 삭제할 회사 고유 식별자
  /// Returns: 삭제 성공/실패 여부
  Future<Either<Failure, void>> deleteCompany(int id);

  /// 회사 복구 (Soft Delete 복원)
  /// [id] 복구할 회사 고유 식별자
  /// Returns: 복구된 회사 정보
  Future<Either<Failure, Company>> restoreCompany(int id);

  /// 회사 상태 토글 (활성화/비활성화)
  /// [id] 상태를 변경할 회사 고유 식별자
  /// Returns: 상태 변경된 회사 정보
  Future<Either<Failure, Company>> toggleCompanyStatus(int id);

  /// 지점 생성
  /// [companyId] 지점을 추가할 회사 ID
  /// [branch] 생성할 지점 정보
  /// Returns: 생성된 지점 정보 (ID 포함)
  Future<Either<Failure, Branch>> createBranch(int companyId, Branch branch);

  /// 지점 정보 수정
  /// [companyId] 회사 ID
  /// [branchId] 수정할 지점 ID
  /// [branch] 수정할 지점 정보
  /// Returns: 수정된 지점 정보
  Future<Either<Failure, Branch>> updateBranch(int companyId, int branchId, Branch branch);

  /// 지점 삭제
  /// [companyId] 회사 ID
  /// [branchId] 삭제할 지점 ID
  /// Returns: 삭제 성공/실패 여부
  Future<Either<Failure, void>> deleteBranch(int companyId, int branchId);

  /// 회사명으로 검색 (자동완성용)
  /// [query] 검색 쿼리
  /// [limit] 결과 제한 수 (기본값: 10)
  /// Returns: 일치하는 회사명 목록
  Future<Either<Failure, List<String>>> searchCompanyNames(String query, {int? limit});

  /// 회사 유형별 개수 통계
  /// Returns: 회사 유형별 개수 (고객사, 파트너사)
  Future<Either<Failure, Map<CompanyType, int>>> getCompanyCountByType();

  /// 회사에 연결된 사용자 존재 여부 확인
  /// [companyId] 확인할 회사 ID
  /// Returns: 연결된 사용자 존재 여부 (삭제 가능 여부 판단용)
  Future<Either<Failure, bool>> hasLinkedUsers(int companyId);

  /// 회사에 연결된 장비 존재 여부 확인
  /// [companyId] 확인할 회사 ID
  /// Returns: 연결된 장비 존재 여부 (삭제 가능 여부 판단용)
  Future<Either<Failure, bool>> hasLinkedEquipment(int companyId);

  /// 중복 회사명 체크
  /// [name] 체크할 회사명
  /// [excludeId] 체크에서 제외할 회사 ID (수정 시 현재 회사 제외용)
  /// Returns: 중복 여부 (true: 중복됨, false: 중복되지 않음)
  Future<Either<Failure, bool>> isDuplicateCompanyName(String name, {int? excludeId});

  // 계층 구조 관련 메서드들

  /// 전체 회사 계층 구조 조회
  /// [includeInactive] 비활성 회사 포함 여부
  /// Returns: 전체 계층 구조 트리
  Future<Either<Failure, List<Company>>> getCompanyHierarchy({
    bool includeInactive = false,
  });

  /// 특정 회사의 자식 회사 목록 조회
  /// [companyId] 부모 회사 ID
  /// [recursive] 재귀적으로 모든 자손 포함 여부
  /// Returns: 자식 회사 목록
  Future<Either<Failure, List<Company>>> getChildrenCompanies(
    int companyId, {
    bool recursive = false,
  });

  /// 특정 회사의 부모 경로 조회
  /// [companyId] 회사 ID
  /// Returns: 루트부터 현재 회사까지의 경로
  Future<Either<Failure, List<Company>>> getAncestorPath(int companyId);

  /// 회사의 부모 변경
  /// [companyId] 변경할 회사 ID
  /// [newParentId] 새로운 부모 회사 ID (null이면 루트로 변경)
  /// Returns: 업데이트된 회사 정보
  Future<Either<Failure, Company>> updateParentCompany(
    int companyId,
    int? newParentId,
  );

  /// 회사가 자식을 가지고 있는지 확인
  /// [companyId] 확인할 회사 ID
  /// Returns: 자식 회사 존재 여부
  Future<Either<Failure, bool>> hasChildrenCompanies(int companyId);

  /// 계층 구조 유효성 검증
  /// [companyId] 검증할 회사 ID
  /// [newParentId] 새로운 부모 회사 ID
  /// Returns: 유효성 검증 결과 (순환 참조, 깊이 제한 등)
  Future<Either<Failure, bool>> validateHierarchyChange(
    int companyId,
    int? newParentId,
  );
}