✨(backend) add 10-digit PIN codes on rooms for telephony

Enable users to join rooms via SIP telephony by:
- Dialing the SIP trunk number
- Entering the room's PIN followed by '#'

The PIN code needs to be generated before the LiveKit room is created,
allowing the owner to send invites to participants in advance.

With 10-digit PINs (10^10 combinations) and a large number of rooms
(e.g., 1M), collisions become statistically inevitable. A retry mechanism
helps reduce the chance of repeated collisions but doesn't eliminate
the overall risk.

With 100K generated PINs, the probability of at least one collision exceeds
39%, due to the birthday paradox.

To scale safely, we’ll later propose using multiple trunks. Each trunk
will handle a separate PIN namespace, and the combination of trunk_id and PIN
will ensure uniqueness. Room assignment will be evenly distributed across
trunks to balance load and minimize collisions.

Following XP principles, we’ll ship the simplest working version of this
feature. The goal is to deliver value quickly without over-engineering.

We’re not solving scaling challenges we don’t currently face.
Our production load is around 10,000 rooms — well within safe limits for
the initial implementation.

Discussion points:
- The `while` loop should be reviewed. Should we add rate limiting
  for failed attempts?
- A systematic existence check before `INSERT` is more costly for a rare
  event and doesn't prevent race conditions, whereas retrying on integrity
  errors is more efficient overall.
- Should we add logging or monitoring to track and analyze collisions?

I tried to balance performance and simplicity while ensuring the
robustness of the PIN generation process.

src/backend/core/models.py

@@ -2,6 +2,7 @@
 Declare and configure the models for the Meet core application
 """
 
+import secrets
 import uuid
 from datetime import datetime, timedelta
 from logging import getLogger
@@ -382,6 +383,14 @@ class Room(Resource):
         verbose_name=_("Visio room configuration"),
         help_text=_("Values for Visio parameters to configure the room."),
     )
+    pin_code = models.CharField(
+        max_length=None,
+        unique=True,
+        blank=True,
+        null=True,
+        verbose_name=_("Room PIN code"),
+        help_text=_("Unique n-digit code that identifies this room in telephony mode."),
+    )
 
     class Meta:
         db_table = "meet_room"
@@ -392,6 +401,14 @@ class Room(Resource):
     def __str__(self):
         return capfirst(self.name)
 
+    def save(self, *args, **kwargs):
+        """Generate a unique n-digit pin code for new rooms."""
+        if settings.ROOM_TELEPHONY_ENABLED and not self.pk and not self.pin_code:
+            self.pin_code = self.generate_unique_pin_code(
+                length=settings.ROOM_TELEPHONY_PIN_LENGTH
+            )
+        super().save(*args, **kwargs)
+
     def clean_fields(self, exclude=None):
         """
         Automatically generate the slug from the name and make sure it does not look like a UUID.
@@ -406,6 +423,7 @@ class Room(Resource):
             pass
         else:
             raise ValidationError({"name": f'Room name "{self.name:s}" is reserved.'})
+
         super().clean_fields(exclude=exclude)
 
     @property
@@ -413,6 +431,31 @@ class Room(Resource):
         """Check if a room is public"""
         return self.access_level == RoomAccessLevel.PUBLIC
 
+    @staticmethod
+    def generate_unique_pin_code(length):
+        """Generate a unique n-digit PIN code"""
+
+        if length < 4:
+            raise ValueError(
+                "PIN code length must be at least 4 digits for minimal security"
+            )
+
+        max_value = 10**length
+
+        for _ in range(settings.ROOM_TELEPHONY_PIN_MAX_RETRIES):
+            pin_code = str(secrets.randbelow(max_value)).zfill(length)
+            if not Room.objects.filter(pin_code=pin_code).exists():
+                return pin_code
+
+        # Log a warning as a temporary measure until backend observability is implemented.
+        logger.warning(
+            "Failed to generate unique PIN code of length %s after %s attempts",
+            length,
+            settings.ROOM_TELEPHONY_PIN_MAX_RETRIES,
+        )
+
+        return None
+
 
 class BaseAccessManager(models.Manager):
     """Base manager for handling resource access control."""