/**
 * Issue Management Types
 *
 * Type definitions for the issue tracking feature.
 * These types align with the backend API schema for issues.
 *
 * @module features/issues/types
 */

/**
 * Issue type values (for hierarchy: Epic -> Story -> Task)
 * Matches backend: IssueType enum in app/models/syndarix/enums.py
 */
export type IssueType = 'epic' | 'story' | 'task' | 'bug';

/**
 * Issue status values
 * Matches backend: IssueStatus enum in app/models/syndarix/enums.py
 */
export type IssueStatus = 'open' | 'in_progress' | 'in_review' | 'blocked' | 'closed';

/**
 * Issue priority values
 * Matches backend: IssuePriority enum in app/models/syndarix/enums.py
 */
export type IssuePriority = 'low' | 'medium' | 'high' | 'critical';

/**
 * Sync status with external trackers
 */
export type SyncStatus = 'synced' | 'pending' | 'conflict' | 'error';

/**
 * Actor type for issue activity
 */
export type ActorType = 'agent' | 'human';

/**
 * Issue assignee
 */
export interface IssueAssignee {
  id: string;
  name: string;
  type: ActorType;
  avatar?: string;
}

/**
 * Issue label
 */
export interface IssueLabel {
  id: string;
  name: string;
  color?: string;
}

/**
 * Issue activity item
 */
export interface IssueActivity {
  id: string;
  type: 'status_change' | 'comment' | 'assignment' | 'label' | 'created' | 'branch' | 'pr';
  actor: IssueAssignee;
  message: string;
  timestamp: string;
  metadata?: Record<string, unknown>;
}

/**
 * Issue summary for list views
 */
export interface IssueSummary {
  id: string;
  number: number;
  type: IssueType;
  title: string;
  description: string;
  status: IssueStatus;
  priority: IssuePriority;
  labels: string[];
  sprint: string | null;
  assignee: IssueAssignee | null;
  created_at: string;
  updated_at: string;
  sync_status: SyncStatus;
  blocked_by?: string;
}

/**
 * Full issue detail
 */
export interface IssueDetail extends Omit<IssueSummary, 'labels'> {
  labels: IssueLabel[];
  milestone: string | null;
  story_points: number | null;
  reporter: IssueAssignee;
  due_date: string | null;
  external_url: string | null;
  branch: string | null;
  pull_request: string | null;
  activity: IssueActivity[];
}

/**
 * Issue filters
 */
export interface IssueFilters {
  search?: string;
  status?: IssueStatus | 'all';
  priority?: IssuePriority | 'all';
  sprint?: string | 'all' | 'backlog';
  assignee?: string | 'all' | 'unassigned';
  labels?: string[];
}

/**
 * Issue sort options
 */
export type IssueSortField = 'number' | 'priority' | 'updated_at' | 'created_at' | 'status';
export type IssueSortDirection = 'asc' | 'desc';

export interface IssueSort {
  field: IssueSortField;
  direction: IssueSortDirection;
}

/**
 * Bulk action types
 */
export type IssueBulkAction = 'change_status' | 'assign' | 'add_labels' | 'delete';

export interface IssueBulkActionRequest {
  action: IssueBulkAction;
  issue_ids: string[];
  payload?: {
    status?: IssueStatus;
    assignee_id?: string;
    labels?: string[];
  };
}

/**
 * Issue update request
 */
export interface IssueUpdateRequest {
  title?: string;
  description?: string;
  status?: IssueStatus;
  priority?: IssuePriority;
  assignee_id?: string | null;
  labels?: string[];
  sprint?: string | null;
  due_date?: string | null;
}

/**
 * Issue sync request
 */
export interface IssueSyncRequest {
  direction?: 'push' | 'pull' | 'bidirectional';
}

/**
 * Status workflow transition
 */
export interface StatusTransition {
  from: IssueStatus;
  to: IssueStatus;
  label: string;
}

/**
 * Status configuration
 */
export interface StatusConfig {
  label: string;
  color: string;
}

/**
 * Priority configuration
 */
export interface PriorityConfig {
  label: string;
  color: string;
}

/**
 * Paginated issues response
 */
export interface PaginatedIssuesResponse {
  data: IssueSummary[];
  pagination: {
    total: number;
    page: number;
    page_size: number;
    total_pages: number;
    has_next: boolean;
    has_prev: boolean;
  };
}
