//! DTOs for Source Impact Analysis operations (P3.1).
//!
//! These DTOs enable cascade impact preview before source retraction,
//! supporting the "Aha Moment #2: Cascade invalidation when source retracted."

use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

/// Response for GET /v1/sources/{hash}/impact
///
/// Shows the cascade effect of retracting a source - how many assertions
/// and agents would be affected.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct SourceImpactResponse {
    /// Hash of the source (hex-encoded, 64 chars).
    pub source_hash: String,

    /// Human-readable label (if registered in source registry).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,

    /// Current status of the source (active, deprecated, quarantined).
    pub status: String,

    /// Total number of assertions citing this source.
    pub assertion_count: usize,

    /// List of affected assertion hashes (limited to 100).
    /// Use pagination for larger result sets.
    pub affected_assertions: Vec<String>,

    /// Estimated number of queries that used this source.
    /// Best-effort from audit logs.
    pub query_count: usize,

    /// List of agent IDs that have assertions citing this source.
    pub affected_agents: Vec<String>,

    /// Human-readable summary message.
    /// Example: "This will affect 234 assertions from 12 agents"
    pub summary: String,
}

/// Request for POST /v1/sources/{hash}/quarantine
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct QuarantineSourceRequest {
    /// If true, only preview the impact without making changes.
    /// Default: false (commit the quarantine).
    #[serde(default)]
    pub preview: bool,

    /// Optional reason for quarantine (e.g., "Study retracted", "Fraudulent data").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Response for POST /v1/sources/{hash}/quarantine
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct QuarantineSourceResponse {
    /// Hash of the source (hex-encoded).
    pub source_hash: String,

    /// New status after operation (or current status if preview).
    pub status: String,

    /// Impact analysis showing affected assertions and agents.
    pub impact: SourceImpactResponse,

    /// Whether this was a preview-only operation.
    pub preview: bool,

    /// Human-readable result message.
    pub message: String,
}

/// Request for POST /v1/sources/{hash}/restore
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct RestoreSourceRequest {
    /// Optional reason for restoring (e.g., "Retraction reversed", "Cleared by review").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

/// Response for POST /v1/sources/{hash}/restore
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct RestoreSourceResponse {
    /// Hash of the source (hex-encoded).
    pub source_hash: String,

    /// New status after restoration (should be "active").
    pub status: String,

    /// Number of assertions that can now be resolved again.
    pub restored_assertions: usize,

    /// Human-readable result message.
    pub message: String,
}

// ============================================================================
// Export Types (P3.2 Cascade Flagging)
// ============================================================================

/// Query parameters for impact export endpoint.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, utoipa::IntoParams)]
pub struct ExportImpactParams {
    /// Export format: "csv" or "json" (default: "json")
    #[serde(default = "default_export_format")]
    pub format: String,
}

fn default_export_format() -> String {
    "json".to_string()
}

/// A single row in the impact export (for regulatory audit trails).
///
/// Contains essential assertion metadata for compliance documentation.
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct ImpactExportRow {
    /// Assertion hash (hex-encoded)
    pub assertion_hash: String,

    /// Subject entity
    pub subject: String,

    /// Predicate/relation
    pub predicate: String,

    /// Agent that signed the assertion (hex-encoded)
    pub agent_id: String,

    /// Creation timestamp (Unix epoch)
    pub timestamp: u64,

    /// Lifecycle stage
    pub lifecycle: String,

    /// Confidence score (0.0-1.0)
    pub confidence: f32,
}
