semantic update

backend/src/models/connection.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.models.connection:Module]
 #
+# @TIER: TRIVIAL
 # @SEMANTICS: database, connection, configuration, sqlalchemy, sqlite
 # @PURPOSE:   Defines the database schema for external database connection configurations.
 # @LAYER:     Domain
@@ -15,6 +16,7 @@ import uuid
 # [/SECTION]
 
 # [DEF:ConnectionConfig:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Stores credentials for external databases used for column mapping.
 class ConnectionConfig(Base):
     __tablename__ = "connection_configs"

backend/src/models/git.py

@@ -1,4 +1,5 @@
 # [DEF:GitModels:Module]
+# @TIER: TRIVIAL
 # @SEMANTICS: git, models, sqlalchemy, database, schema
 # @PURPOSE: Git-specific SQLAlchemy models for configuration and repository tracking.
 # @LAYER: Model
@@ -26,11 +27,10 @@ class SyncStatus(str, enum.Enum):
     DIRTY = "DIRTY"
     CONFLICT = "CONFLICT"
 
+# [DEF:GitServerConfig:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Configuration for a Git server connection.
 class GitServerConfig(Base):
-    """
-    [DEF:GitServerConfig:Class]
-    Configuration for a Git server connection.
-    """
     __tablename__ = "git_server_configs"
 
     id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
@@ -41,12 +41,12 @@ class GitServerConfig(Base):
     default_repository = Column(String(255), nullable=True)
     status = Column(Enum(GitStatus), default=GitStatus.UNKNOWN)
     last_validated = Column(DateTime, default=datetime.utcnow)
+# [/DEF:GitServerConfig:Class]
 
+# [DEF:GitRepository:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Tracking for a local Git repository linked to a dashboard.
 class GitRepository(Base):
-    """
-    [DEF:GitRepository:Class]
-    Tracking for a local Git repository linked to a dashboard.
-    """
     __tablename__ = "git_repositories"
 
     id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
@@ -56,12 +56,12 @@ class GitRepository(Base):
     local_path = Column(String(255), nullable=False)
     current_branch = Column(String(255), default="main")
     sync_status = Column(Enum(SyncStatus), default=SyncStatus.CLEAN)
+# [/DEF:GitRepository:Class]
 
+# [DEF:DeploymentEnvironment:Class]
+# @TIER: TRIVIAL
+# @PURPOSE: Target Superset environments for dashboard deployment.
 class DeploymentEnvironment(Base):
-    """
-    [DEF:DeploymentEnvironment:Class]
-    Target Superset environments for dashboard deployment.
-    """
     __tablename__ = "deployment_environments"
 
     id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
@@ -69,5 +69,6 @@ class DeploymentEnvironment(Base):
     superset_url = Column(String(255), nullable=False)
     superset_token = Column(String(255), nullable=False)
     is_active = Column(Boolean, default=True)
+# [/DEF:DeploymentEnvironment:Class]
 
-# [/DEF:GitModels:Module]
+# [/DEF:GitModels:Module]

backend/src/models/mapping.py

@@ -59,6 +59,7 @@ class DatabaseMapping(Base):
 # [/DEF:DatabaseMapping:Class]
 
 # [DEF:MigrationJob:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Represents a single migration execution job.
 class MigrationJob(Base):
     __tablename__ = "migration_jobs"

backend/src/models/storage.py

@@ -1,9 +1,16 @@
+# [DEF:backend.src.models.storage:Module]
+# @TIER: TRIVIAL
+# @SEMANTICS: storage, file, model, pydantic
+# @PURPOSE: Data models for the storage system.
+# @LAYER: Domain
+
 from datetime import datetime
 from enum import Enum
 from typing import Optional
 from pydantic import BaseModel, Field
 
 # [DEF:FileCategory:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Enumeration of supported file categories in the storage system.
 class FileCategory(str, Enum):
     BACKUP = "backups"
@@ -11,6 +18,7 @@ class FileCategory(str, Enum):
 # [/DEF:FileCategory:Class]
 
 # [DEF:StorageConfig:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Configuration model for the storage system, defining paths and naming patterns.
 class StorageConfig(BaseModel):
     root_path: str = Field(default="backups", description="Absolute path to the storage root directory.")
@@ -20,6 +28,7 @@ class StorageConfig(BaseModel):
 # [/DEF:StorageConfig:Class]
 
 # [DEF:StoredFile:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Data model representing metadata for a file stored in the system.
 class StoredFile(BaseModel):
     name: str = Field(..., description="Name of the file (including extension).")
@@ -28,4 +37,6 @@ class StoredFile(BaseModel):
     created_at: datetime = Field(..., description="Creation timestamp.")
     category: FileCategory = Field(..., description="Category of the file.")
     mime_type: Optional[str] = Field(None, description="MIME type of the file.")
-# [/DEF:StoredFile:Class]
+# [/DEF:StoredFile:Class]
+
+# [/DEF:backend.src.models.storage:Module]

backend/src/models/task.py

@@ -1,5 +1,6 @@
 # [DEF:backend.src.models.task:Module]
 #
+# @TIER: TRIVIAL
 # @SEMANTICS: database, task, record, sqlalchemy, sqlite
 # @PURPOSE:   Defines the database schema for task execution records.
 # @LAYER:     Domain
@@ -8,13 +9,14 @@
 # @INVARIANT: All primary keys are UUID strings.
 
 # [SECTION: IMPORTS]
-from sqlalchemy import Column, String, DateTime, JSON, ForeignKey
+from sqlalchemy import Column, String, DateTime, JSON, ForeignKey, Text, Integer, Index
 from sqlalchemy.sql import func
 from .mapping import Base
 import uuid
 # [/SECTION]
 
 # [DEF:TaskRecord:Class]
+# @TIER: TRIVIAL
 # @PURPOSE: Represents a persistent record of a task execution.
 class TaskRecord(Base):
     __tablename__ = "task_records"
@@ -25,11 +27,35 @@ class TaskRecord(Base):
     environment_id = Column(String, ForeignKey("environments.id"), nullable=True)
     started_at = Column(DateTime(timezone=True), nullable=True)
     finished_at = Column(DateTime(timezone=True), nullable=True)
-    logs = Column(JSON, nullable=True)  # Store structured logs as JSON
+    logs = Column(JSON, nullable=True)  # Store structured logs as JSON (legacy, kept for backward compatibility)
     error = Column(String, nullable=True)
     result = Column(JSON, nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     params = Column(JSON, nullable=True)
 # [/DEF:TaskRecord:Class]
 
+# [DEF:TaskLogRecord:Class]
+# @PURPOSE: Represents a single persistent log entry for a task.
+# @TIER: CRITICAL
+# @RELATION: DEPENDS_ON -> TaskRecord
+# @INVARIANT: Each log entry belongs to exactly one task.
+class TaskLogRecord(Base):
+    __tablename__ = "task_logs"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    task_id = Column(String, ForeignKey("task_records.id", ondelete="CASCADE"), nullable=False, index=True)
+    timestamp = Column(DateTime(timezone=True), nullable=False, index=True)
+    level = Column(String(16), nullable=False)  # INFO, WARNING, ERROR, DEBUG
+    source = Column(String(64), nullable=False, default="system")  # plugin, superset_api, git, etc.
+    message = Column(Text, nullable=False)
+    metadata_json = Column(Text, nullable=True)  # JSON string for additional metadata
+
+    # Composite indexes for efficient filtering
+    __table_args__ = (
+        Index('ix_task_logs_task_timestamp', 'task_id', 'timestamp'),
+        Index('ix_task_logs_task_level', 'task_id', 'level'),
+        Index('ix_task_logs_task_source', 'task_id', 'source'),
+    )
+# [/DEF:TaskLogRecord:Class]
+
 # [/DEF:backend.src.models.task:Module]