/**
 * ========================================
 * 랭킹(Ranking) 관련 타입 정의
 * ========================================
 *
 * @description
 * - 실제 사용되는 타입만 정의
 * - POST /cow/ranking API 요청/응답
 */

// ========================================
// 1. 랭킹 조건
// ========================================

/**
 * 형질 기반 랭킹 조건
 *
 * @description 선발지수 계산용 형질별 가중치
 * @example { traitNm: "도체중", weight: 2.0 }
 */
export interface TraitRankingCondition {
  traitNm: string                  // 형질명 (예: "도체중", "등심단면적")
  weight?: number                  // 가중치 (기본값: 1)
}

/**
 * 필터 조건
 *
 * @description WHERE 조건 (현재 사용 안 함, 향후 확장용)
 */
export interface FilterCondition {
  field: string                    // 컬럼명
  operator: string                 // 연산자 (eq, gt, lt 등)
  value: any                       // 비교값
}

// ========================================
// 2. 랭킹 옵션
// ========================================

/**
 * 필터 엔진 옵션
 *
 * @description 필터링 옵션 (현재 farmNo만 사용)
 * @usage filterOptions: { farmNo: 1 }
 */
export interface FilterEngineOptions {
  farmNo?: number                  // 농장 번호 필터
  filters?: FilterCondition[]      // 추가 필터 조건 (향후 확장용)
}

/**
 * 랭킹 옵션
 *
 * @description 순위 계산 설정
 * @usage
 * {
 *   criteriaType: 'GENOME',
 *   traitConditions: [{ traitNm: "도체중", weight: 2 }]
 * }
 */
export interface RankingOptions {
  criteriaType: 'GENE' | 'GENOME'  // 유전자 또는 유전체 기반
  traitConditions?: TraitRankingCondition[]  // 형질 조건 배열
  limit?: number                   // 결과 개수 제한 (향후 확장용)
  offset?: number                  // 시작 위치 (향후 확장용)
}

// ========================================
// 3. 랭킹 요청 DTO
// ========================================

/**
 * 랭킹 요청
 *
 * @description POST /cow/ranking 요청 바디
 * @example
 * {
 *   filterOptions: { farmNo: 1 },
 *   rankingOptions: {
 *     criteriaType: "GENOME",
 *     traitConditions: [
 *       { traitNm: "도체중", weight: 2 },
 *       { traitNm: "근내지방도", weight: 3 }
 *     ]
 *   }
 * }
 */
export interface RankingRequestDto {
  filterOptions?: FilterEngineOptions  // 필터링 옵션
  rankingOptions: RankingOptions       // 랭킹 계산 옵션
}

// ========================================
// 4. 타입 별칭
// ========================================

/**
 * @description 실제 사용 중인 별칭
 */
export type RankingRequest = RankingRequestDto
