feat(database): integrate Supabase PostgreSQL with SQLAlchemy models and Alembic migrations

backend/alembic/env.py

@@ -0,0 +1,120 @@
+"""
+Alembic Environment Configuration for CodeGuard AI.
+
+Este archivo configura Alembic para detectar todos los modelos ORM
+y generar migraciones automáticamente contra Supabase PostgreSQL.
+"""
+
+import os
+import sys
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+
+from alembic import context
+
+# ------------------------------------------------------------------------
+# 1. Configuración de Rutas (Path)
+# ------------------------------------------------------------------------
+# Agregamos el directorio padre (backend/) al path de Python
+# para que Alembic pueda encontrar la carpeta 'src'
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+# ------------------------------------------------------------------------
+# 2. Importación de Modelos y Configuración
+# ------------------------------------------------------------------------
+# Importamos la Base declarativa y TODOS los modelos
+# IMPORTANTE: Cada modelo debe ser importado para que Alembic lo detecte
+from src.models import (
+    Base,
+    UserEntity,
+    CodeReviewEntity,
+    AgentFindingEntity,
+    ReviewStatus,
+    SeverityEnum,
+    UserRole,
+)
+
+# Configuración de la base de datos
+# Intentamos cargar desde settings, con fallback a variables de entorno
+try:
+    from src.core.config.settings import settings
+    db_url = settings.DATABASE_URL
+except ImportError:
+    from dotenv import load_dotenv
+    load_dotenv()
+    db_url = os.getenv("DATABASE_URL")
+
+if not db_url:
+    raise ValueError(
+        "DATABASE_URL no está configurada. "
+        "Configúrala en .env o en src/core/config/settings.py"
+    )
+
+# ------------------------------------------------------------------------
+# 3. Configuración de Alembic
+# ------------------------------------------------------------------------
+config = context.config
+
+# Interpretar el archivo de configuración para el logging
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Asignar la metadata de los modelos para que Alembic pueda "ver" las tablas
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """
+    Ejecuta migraciones en modo 'offline'.
+
+    Configura el contexto con solo una URL, sin crear un Engine.
+    Útil para generar scripts SQL sin conexión a la BD.
+    """
+    context.configure(
+        url=db_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        # Comparar tipos para detectar cambios en columnas
+        compare_type=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """
+    Ejecuta migraciones en modo 'online'.
+
+    Crea un Engine y se conecta a la base de datos Supabase.
+    """
+    # Obtenemos la configuración de alembic.ini
+    configuration = config.get_section(config.config_ini_section)
+
+    # Inyectar la URL de la base de datos desde el entorno
+    configuration["sqlalchemy.url"] = db_url
+
+    connectable = engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            # Comparar tipos para detectar cambios en columnas
+            compare_type=True,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,33 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+
+
+
+
+
+    ${downgrades if downgrades else "pass"}

backend/alembic/versions/ba48c1bb8e18_create_initial_tables_users_code_.py

@@ -0,0 +1,97 @@
+"""create_initial_tables_users_code_reviews_findings
+
+Revision ID: ba48c1bb8e18
+Revises: 
+Create Date: 2025-11-27 02:43:54.598631
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = 'ba48c1bb8e18'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('users',
+    sa.Column('id', sa.String(length=255), nullable=False),
+    sa.Column('email', sa.String(length=255), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=True),
+    sa.Column('avatar_url', sa.String(length=500), nullable=True),
+    sa.Column('role', sa.Enum('DEVELOPER', 'ADMIN', name='userrole'), nullable=False),
+    sa.Column('daily_analysis_count', sa.Integer(), nullable=False),
+    sa.Column('last_analysis_date', sa.Date(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_users_email'), 'users', ['email'], unique=True)
+    op.create_index(op.f('ix_users_role'), 'users', ['role'], unique=False)
+    op.create_table('code_reviews',
+    sa.Column('id', sa.UUID(), nullable=False),
+    sa.Column('user_id', sa.String(length=255), nullable=False),
+    sa.Column('filename', sa.String(length=500), nullable=False),
+    sa.Column('code_content', sa.LargeBinary(), nullable=False),
+    sa.Column('quality_score', sa.Integer(), nullable=True),
+    sa.Column('status', sa.Enum('PENDING', 'PROCESSING', 'COMPLETED', 'FAILED', name='reviewstatus'), nullable=False),
+    sa.Column('total_findings', sa.Integer(), nullable=True),
+    sa.Column('error_message', sa.Text(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=True),
+    sa.Column('completed_at', sa.DateTime(), nullable=True),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_code_reviews_created_at'), 'code_reviews', ['created_at'], unique=False)
+    op.create_index(op.f('ix_code_reviews_status'), 'code_reviews', ['status'], unique=False)
+    op.create_index(op.f('ix_code_reviews_user_id'), 'code_reviews', ['user_id'], unique=False)
+    op.create_table('agent_findings',
+    sa.Column('id', sa.UUID(), nullable=False),
+    sa.Column('review_id', sa.UUID(), nullable=False),
+    sa.Column('agent_type', sa.String(length=100), nullable=False),
+    sa.Column('severity', sa.Enum('CRITICAL', 'HIGH', 'MEDIUM', 'LOW', name='severityenum'), nullable=False),
+    sa.Column('issue_type', sa.String(length=200), nullable=False),
+    sa.Column('line_number', sa.Integer(), nullable=False),
+    sa.Column('code_snippet', sa.Text(), nullable=True),
+    sa.Column('message', sa.Text(), nullable=False),
+    sa.Column('suggestion', sa.Text(), nullable=True),
+    sa.Column('metrics', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.Column('ai_explanation', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.Column('mcp_references', postgresql.ARRAY(sa.Text()), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['review_id'], ['code_reviews.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_agent_findings_agent_type'), 'agent_findings', ['agent_type'], unique=False)
+    op.create_index(op.f('ix_agent_findings_review_id'), 'agent_findings', ['review_id'], unique=False)
+    op.create_index(op.f('ix_agent_findings_severity'), 'agent_findings', ['severity'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+
+
+
+
+
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_agent_findings_severity'), table_name='agent_findings')
+    op.drop_index(op.f('ix_agent_findings_review_id'), table_name='agent_findings')
+    op.drop_index(op.f('ix_agent_findings_agent_type'), table_name='agent_findings')
+    op.drop_table('agent_findings')
+    op.drop_index(op.f('ix_code_reviews_user_id'), table_name='code_reviews')
+    op.drop_index(op.f('ix_code_reviews_status'), table_name='code_reviews')
+    op.drop_index(op.f('ix_code_reviews_created_at'), table_name='code_reviews')
+    op.drop_table('code_reviews')
+    op.drop_index(op.f('ix_users_role'), table_name='users')
+    op.drop_index(op.f('ix_users_email'), table_name='users')
+    op.drop_table('users')
+    # ### end Alembic commands ###

backend/src/models/__init__.py

@@ -0,0 +1,28 @@
+"""
+SQLAlchemy ORM Models para CodeGuard AI.
+
+Este módulo exporta todas las entidades de base de datos para facilitar imports.
+"""
+
+from src.models.base import Base
+from src.models.code_review import CodeReviewEntity
+
+# Enums
+from src.models.enums.review_status import ReviewStatus
+from src.models.enums.severity_enum import SeverityEnum
+from src.models.enums.user_role import UserRole
+from src.models.finding import AgentFindingEntity
+from src.models.user import UserEntity
+
+__all__ = [
+    # Base
+    "Base",
+    # Entities
+    "UserEntity",
+    "CodeReviewEntity",
+    "AgentFindingEntity",
+    # Enums
+    "ReviewStatus",
+    "SeverityEnum",
+    "UserRole",
+]

backend/src/models/base.py

@@ -17,6 +17,9 @@ class Base(DeclarativeBase):
     comparado con la función antigua `declarative_base()`.
 
     Todas las entidades (ej. `CodeReviewEntity`) deben heredar de esta clase.
+
+    __allow_unmapped__ = True permite usar anotaciones de tipo sin Mapped[]
+    para mantener compatibilidad con el código existente.
     """
 
-    pass
+    __allow_unmapped__ = True

backend/src/models/code_review.py

@@ -1,29 +1,84 @@
+"""
+Entidad ORM para code reviews.
+Alineado con tabla 'code_reviews' en PostgreSQL (Supabase).
+"""
+
 import uuid
 from datetime import datetime
+from typing import TYPE_CHECKING, List
 
-from sqlalchemy import Column, DateTime, Enum, Integer, LargeBinary, String
+from sqlalchemy import Column, DateTime, Enum, ForeignKey, Integer, LargeBinary, String, Text
 from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
 
 from src.models.base import Base
 from src.models.enums.review_status import ReviewStatus
 
+if TYPE_CHECKING:
+    from src.models.finding import AgentFindingEntity
+    from src.models.user import UserEntity
+
 
 class CodeReviewEntity(Base):
     """
     Entidad ORM que representa la tabla 'code_reviews' en la base de datos.
+
+    Attributes:
+        id: UUID del análisis
+        user_id: FK a users (Clerk user_id)
+        filename: Nombre del archivo analizado
+        code_content: Contenido encriptado con AES-256 (BYTEA)
+        quality_score: Puntuación de calidad (0-100)
+        status: PENDING, PROCESSING, COMPLETED, FAILED
+        total_findings: Número total de hallazgos
+        error_message: Mensaje de error si falló
+        created_at: Timestamp de creación
+        completed_at: Timestamp de finalización
     """
 
     __tablename__ = "code_reviews"
 
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    user_id = Column(String, nullable=False, index=True)
-    filename = Column(String, nullable=False)
+    user_id = Column(
+        String(255), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    filename = Column(String(500), nullable=False)
 
     # RN16: code_content se almacena como bytes encriptados (BYTEA)
     code_content = Column(LargeBinary, nullable=False)
 
-    quality_score = Column(Integer, nullable=False)
-    status = Column(Enum(ReviewStatus), nullable=False, index=True)
+    quality_score = Column(Integer, nullable=True)
+    status = Column(Enum(ReviewStatus), default=ReviewStatus.PENDING, nullable=False, index=True)
     total_findings = Column(Integer, default=0)
+    error_message = Column(Text, nullable=True)
     created_at = Column(DateTime, default=datetime.utcnow, index=True)
     completed_at = Column(DateTime, nullable=True)
+
+    # Relationships
+    user: "UserEntity" = relationship("UserEntity", back_populates="code_reviews")
+
+    findings: List["AgentFindingEntity"] = relationship(
+        "AgentFindingEntity",
+        back_populates="code_review",
+        cascade="all, delete-orphan",
+        lazy="dynamic",
+    )
+
+    def __repr__(self) -> str:
+        return (
+            f"<CodeReviewEntity("
+            f"id={self.id}, "
+            f"filename={self.filename}, "
+            f"status={self.status}"
+            f")>"
+        )
+
+    def calculate_quality_score(self) -> int:
+        """
+        Calcula el quality score basado en los findings.
+
+        Formula: score = max(0, 100 - sum(penalties))
+        """
+
+        total_penalty = sum(f.penalty for f in self.findings)
+        return max(0, 100 - total_penalty)