refactor

2026-04-24 17:10:02 +03:00
parent 216c5ca4be
commit a69446473b
34 changed files with 5220 additions and 5446 deletions
--- a/backend/src/models/dataset_review_pkg/_enums.py
+++ b/backend/src/models/dataset_review_pkg/_enums.py
@@ -0,0 +1,463 @@
+# [DEF:DatasetReviewEnums:Module]
+# @COMPLEXITY: 2
+# @PURPOSE: All enumeration types for the dataset review domain, grouped for stable cross-module reuse.
+# @LAYER: Domain
+# @INVARIANT: Enum values are string-based for JSON serialization compatibility.
+
+import enum
+
+
+# [DEF:SessionStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Lifecycle status of a dataset review session.
+class SessionStatus(str, enum.Enum):
+    ACTIVE = "active"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    ARCHIVED = "archived"
+    CANCELLED = "cancelled"
+
+
+# [/DEF:SessionStatus:Class]
+
+
+# [DEF:SessionPhase:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Ordered phase progression for dataset review orchestration.
+class SessionPhase(str, enum.Enum):
+    INTAKE = "intake"
+    RECOVERY = "recovery"
+    REVIEW = "review"
+    SEMANTIC_REVIEW = "semantic_review"
+    CLARIFICATION = "clarification"
+    MAPPING_REVIEW = "mapping_review"
+    PREVIEW = "preview"
+    LAUNCH = "launch"
+    POST_RUN = "post_run"
+
+
+# [/DEF:SessionPhase:Class]
+
+
+# [DEF:ReadinessState:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Granular readiness indicator driving the recommended-action UX flow.
+class ReadinessState(str, enum.Enum):
+    EMPTY = "empty"
+    IMPORTING = "importing"
+    REVIEW_READY = "review_ready"
+    SEMANTIC_SOURCE_REVIEW_NEEDED = "semantic_source_review_needed"
+    CLARIFICATION_NEEDED = "clarification_needed"
+    CLARIFICATION_ACTIVE = "clarification_active"
+    MAPPING_REVIEW_NEEDED = "mapping_review_needed"
+    COMPILED_PREVIEW_READY = "compiled_preview_ready"
+    PARTIALLY_READY = "partially_ready"
+    RUN_READY = "run_ready"
+    RUN_IN_PROGRESS = "run_in_progress"
+    COMPLETED = "completed"
+    RECOVERY_REQUIRED = "recovery_required"
+
+
+# [/DEF:ReadinessState:Class]
+
+
+# [DEF:RecommendedAction:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Next-action guidance derived from the current readiness state.
+class RecommendedAction(str, enum.Enum):
+    IMPORT_FROM_SUPERSET = "import_from_superset"
+    REVIEW_DOCUMENTATION = "review_documentation"
+    APPLY_SEMANTIC_SOURCE = "apply_semantic_source"
+    START_CLARIFICATION = "start_clarification"
+    ANSWER_NEXT_QUESTION = "answer_next_question"
+    APPROVE_MAPPING = "approve_mapping"
+    GENERATE_SQL_PREVIEW = "generate_sql_preview"
+    COMPLETE_REQUIRED_VALUES = "complete_required_values"
+    LAUNCH_DATASET = "launch_dataset"
+    RESUME_SESSION = "resume_session"
+    EXPORT_OUTPUTS = "export_outputs"
+
+
+# [/DEF:RecommendedAction:Class]
+
+
+# [DEF:SessionCollaboratorRole:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: RBAC role for session collaborators.
+class SessionCollaboratorRole(str, enum.Enum):
+    VIEWER = "viewer"
+    REVIEWER = "reviewer"
+    APPROVER = "approver"
+
+
+# [/DEF:SessionCollaboratorRole:Class]
+
+
+# [DEF:BusinessSummarySource:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Provenance of the dataset business summary text.
+class BusinessSummarySource(str, enum.Enum):
+    CONFIRMED = "confirmed"
+    IMPORTED = "imported"
+    INFERRED = "inferred"
+    AI_DRAFT = "ai_draft"
+    MANUAL_OVERRIDE = "manual_override"
+
+
+# [/DEF:BusinessSummarySource:Class]
+
+
+# [DEF:ConfidenceState:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Confidence level for dataset profile completeness.
+class ConfidenceState(str, enum.Enum):
+    CONFIRMED = "confirmed"
+    MOSTLY_CONFIRMED = "mostly_confirmed"
+    MIXED = "mixed"
+    LOW_CONFIDENCE = "low_confidence"
+    UNRESOLVED = "unresolved"
+
+
+# [/DEF:ConfidenceState:Class]
+
+
+# [DEF:FindingArea:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Domain area classification for validation findings.
+class FindingArea(str, enum.Enum):
+    SOURCE_INTAKE = "source_intake"
+    DATASET_PROFILE = "dataset_profile"
+    SEMANTIC_ENRICHMENT = "semantic_enrichment"
+    CLARIFICATION = "clarification"
+    FILTER_RECOVERY = "filter_recovery"
+    TEMPLATE_MAPPING = "template_mapping"
+    COMPILED_PREVIEW = "compiled_preview"
+    LAUNCH = "launch"
+    AUDIT = "audit"
+
+
+# [/DEF:FindingArea:Class]
+
+
+# [DEF:FindingSeverity:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Severity classification for validation findings.
+class FindingSeverity(str, enum.Enum):
+    BLOCKING = "blocking"
+    WARNING = "warning"
+    INFORMATIONAL = "informational"
+
+
+# [/DEF:FindingSeverity:Class]
+
+
+# [DEF:ResolutionState:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Resolution status for validation findings and clarification items.
+class ResolutionState(str, enum.Enum):
+    OPEN = "open"
+    RESOLVED = "resolved"
+    APPROVED = "approved"
+    SKIPPED = "skipped"
+    DEFERRED = "deferred"
+    EXPERT_REVIEW = "expert_review"
+
+
+# [/DEF:ResolutionState:Class]
+
+
+# [DEF:SemanticSourceType:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Classification of semantic enrichment source origins.
+class SemanticSourceType(str, enum.Enum):
+    UPLOADED_FILE = "uploaded_file"
+    CONNECTED_DICTIONARY = "connected_dictionary"
+    REFERENCE_DATASET = "reference_dataset"
+    NEIGHBOR_DATASET = "neighbor_dataset"
+    AI_GENERATED = "ai_generated"
+
+
+# [/DEF:SemanticSourceType:Class]
+
+
+# [DEF:TrustLevel:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Trust classification for semantic source reliability.
+class TrustLevel(str, enum.Enum):
+    TRUSTED = "trusted"
+    RECOMMENDED = "recommended"
+    CANDIDATE = "candidate"
+    GENERATED = "generated"
+
+
+# [/DEF:TrustLevel:Class]
+
+
+# [DEF:SemanticSourceStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Lifecycle status for semantic source application.
+class SemanticSourceStatus(str, enum.Enum):
+    AVAILABLE = "available"
+    SELECTED = "selected"
+    APPLIED = "applied"
+    REJECTED = "rejected"
+    PARTIAL = "partial"
+    FAILED = "failed"
+
+
+# [/DEF:SemanticSourceStatus:Class]
+
+
+# [DEF:FieldKind:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Kind classification for semantic field entries.
+class FieldKind(str, enum.Enum):
+    COLUMN = "column"
+    METRIC = "metric"
+    FILTER_DIMENSION = "filter_dimension"
+    PARAMETER = "parameter"
+
+
+# [/DEF:FieldKind:Class]
+
+
+# [DEF:FieldProvenance:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Provenance tracking for semantic field value origin.
+class FieldProvenance(str, enum.Enum):
+    DICTIONARY_EXACT = "dictionary_exact"
+    REFERENCE_IMPORTED = "reference_imported"
+    FUZZY_INFERRED = "fuzzy_inferred"
+    AI_GENERATED = "ai_generated"
+    MANUAL_OVERRIDE = "manual_override"
+    UNRESOLVED = "unresolved"
+
+
+# [/DEF:FieldProvenance:Class]
+
+
+# [DEF:CandidateMatchType:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Match type classification for semantic candidates.
+class CandidateMatchType(str, enum.Enum):
+    EXACT = "exact"
+    REFERENCE = "reference"
+    FUZZY = "fuzzy"
+    GENERATED = "generated"
+
+
+# [/DEF:CandidateMatchType:Class]
+
+
+# [DEF:CandidateStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Lifecycle status for semantic candidate proposals.
+class CandidateStatus(str, enum.Enum):
+    PROPOSED = "proposed"
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    SUPERSEDED = "superseded"
+
+
+# [/DEF:CandidateStatus:Class]
+
+
+# [DEF:FilterSource:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Origin classification for imported filters.
+class FilterSource(str, enum.Enum):
+    SUPERSET_NATIVE = "superset_native"
+    SUPERSET_URL = "superset_url"
+    SUPERSET_PERMALINK = "superset_permalink"
+    SUPERSET_NATIVE_FILTERS_KEY = "superset_native_filters_key"
+    MANUAL = "manual"
+    INFERRED = "inferred"
+
+
+# [/DEF:FilterSource:Class]
+
+
+# [DEF:FilterConfidenceState:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Confidence classification for imported filter values.
+class FilterConfidenceState(str, enum.Enum):
+    CONFIRMED = "confirmed"
+    IMPORTED = "imported"
+    INFERRED = "inferred"
+    AI_DRAFT = "ai_draft"
+    UNRESOLVED = "unresolved"
+
+
+# [/DEF:FilterConfidenceState:Class]
+
+
+# [DEF:FilterRecoveryStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Recovery quality status for imported filters.
+class FilterRecoveryStatus(str, enum.Enum):
+    RECOVERED = "recovered"
+    PARTIAL = "partial"
+    MISSING = "missing"
+    CONFLICTED = "conflicted"
+
+
+# [/DEF:FilterRecoveryStatus:Class]
+
+
+# [DEF:VariableKind:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Kind classification for template variables.
+class VariableKind(str, enum.Enum):
+    NATIVE_FILTER = "native_filter"
+    PARAMETER = "parameter"
+    DERIVED = "derived"
+    UNKNOWN = "unknown"
+
+
+# [/DEF:VariableKind:Class]
+
+
+# [DEF:MappingStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Lifecycle status for template variable mapping.
+class MappingStatus(str, enum.Enum):
+    UNMAPPED = "unmapped"
+    PROPOSED = "proposed"
+    APPROVED = "approved"
+    OVERRIDDEN = "overridden"
+    INVALID = "invalid"
+
+
+# [/DEF:MappingStatus:Class]
+
+
+# [DEF:MappingMethod:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Method classification for execution mapping creation.
+class MappingMethod(str, enum.Enum):
+    DIRECT_MATCH = "direct_match"
+    HEURISTIC_MATCH = "heuristic_match"
+    SEMANTIC_MATCH = "semantic_match"
+    MANUAL_OVERRIDE = "manual_override"
+
+
+# [/DEF:MappingMethod:Class]
+
+
+# [DEF:MappingWarningLevel:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Warning severity for execution mapping quality indicators.
+class MappingWarningLevel(str, enum.Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+# [/DEF:MappingWarningLevel:Class]
+
+
+# [DEF:ApprovalState:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Approval lifecycle for execution mapping gate checks.
+class ApprovalState(str, enum.Enum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    NOT_REQUIRED = "not_required"
+
+
+# [/DEF:ApprovalState:Class]
+
+
+# [DEF:ClarificationStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Lifecycle status for clarification sessions.
+class ClarificationStatus(str, enum.Enum):
+    PENDING = "pending"
+    ACTIVE = "active"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+
+
+# [/DEF:ClarificationStatus:Class]
+
+
+# [DEF:QuestionState:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: State machine for individual clarification questions.
+class QuestionState(str, enum.Enum):
+    OPEN = "open"
+    ANSWERED = "answered"
+    SKIPPED = "skipped"
+    EXPERT_REVIEW = "expert_review"
+    SUPERSEDED = "superseded"
+
+
+# [/DEF:QuestionState:Class]
+
+
+# [DEF:AnswerKind:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Classification of clarification answer types.
+class AnswerKind(str, enum.Enum):
+    SELECTED = "selected"
+    CUSTOM = "custom"
+    SKIPPED = "skipped"
+    EXPERT_REVIEW = "expert_review"
+
+
+# [/DEF:AnswerKind:Class]
+
+
+# [DEF:PreviewStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Lifecycle status for compiled SQL previews.
+class PreviewStatus(str, enum.Enum):
+    PENDING = "pending"
+    READY = "ready"
+    FAILED = "failed"
+    STALE = "stale"
+
+
+# [/DEF:PreviewStatus:Class]
+
+
+# [DEF:LaunchStatus:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Outcome status for dataset launch handoff.
+class LaunchStatus(str, enum.Enum):
+    STARTED = "started"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+# [/DEF:LaunchStatus:Class]
+
+
+# [DEF:ArtifactType:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Type classification for export artifacts.
+class ArtifactType(str, enum.Enum):
+    DOCUMENTATION = "documentation"
+    VALIDATION_REPORT = "validation_report"
+    RUN_SUMMARY = "run_summary"
+
+
+# [/DEF:ArtifactType:Class]
+
+
+# [DEF:ArtifactFormat:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Format classification for export artifact output.
+class ArtifactFormat(str, enum.Enum):
+    JSON = "json"
+    MARKDOWN = "markdown"
+    CSV = "csv"
+    PDF = "pdf"
+
+
+# [/DEF:ArtifactFormat:Class]
+
+
+# [/DEF:DatasetReviewEnums:Module]