apps/operations/models/system.py

"""
System models — system_settings, background_jobs, job_locks, distributed_locks.

Maps to AGENT.md DBML: Lines 629-657.
"""
from django.db import models

from core.models import BaseModel


class SystemSetting(models.Model):
    """Platform-wide key-value configuration store."""

    key = models.CharField(max_length=255, primary_key=True)
    value = models.TextField(blank=True, default="")
    description = models.CharField(max_length=500, blank=True, default="")
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = "system_settings"

    def __str__(self) -> str:
        return f"{self.key}={self.value[:50]}"


class BackgroundJob(BaseModel):
    """Tracks background/async jobs."""

    class Status(models.TextChoices):
        PENDING = "pending", "Pending"
        RUNNING = "running", "Running"
        COMPLETED = "completed", "Completed"
        FAILED = "failed", "Failed"

    queue = models.CharField(max_length=100, db_index=True)
    payload = models.JSONField(default=dict, blank=True)
    status = models.CharField(max_length=20, choices=Status.choices, default=Status.PENDING)
    attempts = models.PositiveIntegerField(default=0)
    max_attempts = models.PositiveIntegerField(default=3)
    error_message = models.TextField(blank=True, default="")
    run_at = models.DateTimeField(null=True, blank=True)
    failed_at = models.DateTimeField(null=True, blank=True)

    class Meta:
        db_table = "background_jobs"
        ordering = ["-created_at"]

    def __str__(self) -> str:
        return f"Job {self.pk} ({self.get_status_display()})"


class JobLock(models.Model):
    """Prevents concurrent execution of the same job."""

    lock_key = models.CharField(max_length=255, primary_key=True)
    locked_by = models.CharField(max_length=255, blank=True, default="")
    expires_at = models.DateTimeField()

    class Meta:
        db_table = "job_locks"

    def __str__(self) -> str:
        return self.lock_key


class DistributedLock(models.Model):
    """General-purpose distributed lock."""

    lock_key = models.CharField(max_length=255, primary_key=True)
    owner_id = models.CharField(max_length=255)
    acquired_at = models.DateTimeField(auto_now_add=True)
    expires_at = models.DateTimeField()

    class Meta:
        db_table = "distributed_locks"

    def __str__(self) -> str:
        return f"{self.lock_key} by {self.owner_id}"