feat: choices API에서 필터링을 위한 meta 추가

Author: MU-Software

app/admin_api/test/shop/categories_api_test.py

@@ -9,6 +9,7 @@
 
 LIST_URL = reverse("v1:admin-shop-category-list")
 CHOICES_URL = LIST_URL + "choices/"
+JSON_SCHEMA_URL = LIST_URL + "json-schema/"
 
 
 @pytest.fixture
@@ -51,6 +52,28 @@ def test_category_choices_returns_group_and_event(api_client, category_fixtures)
     assert str(category_fixtures["event"].id) in {c["const"] for c in data["event"]}
 
 
+@pytest.mark.django_db
+def test_category_choices_include_meta_for_event(api_client, category_fixtures):
+    # Event 모델이 choices_meta_schema/get_choice_meta 를 정의하므로 event choice 에 meta 가 붙어야 한다.
+    response = api_client.get(CHOICES_URL)
+    assert response.status_code == HTTP_200_OK
+    event_choices = {c["const"]: c for c in response.json()["event"] if c["const"] is not None}
+    event_meta = event_choices[str(category_fixtures["event"].id)]["meta"]
+    assert event_meta["organization"] == "Org"
+    assert event_meta["started_at"] == "2026-08-01"
+
+
+@pytest.mark.django_db
+def test_category_json_schema_exposes_choice_meta_schema(api_client, category_fixtures):
+    response = api_client.get(JSON_SCHEMA_URL)
+    assert response.status_code == HTTP_200_OK
+    ui_schema = response.json()["ui_schema"]
+    meta_schema = ui_schema["event"]["ui:options"]["choiceMetaSchema"]
+    assert meta_schema["organization"]["label"] == "조직"
+    # meta 정의가 없는 대상(CategoryGroup)에는 choiceMetaSchema 가 붙지 않는다.
+    assert "choiceMetaSchema" not in ui_schema.get("group", {}).get("ui:options", {})
+
+
 @pytest.mark.django_db
 def test_category_filter_by_group(api_client, category_fixtures):
     response = api_client.get(LIST_URL, {"group": str(category_fixtures["g2026"].id)})

app/core/models.py

@@ -43,6 +43,7 @@ def get_choices_queryset(self) -> typing.Self:
 
 class BaseAbstractModel(models.Model):
     choices_select_related: typing.ClassVar[tuple[str, ...]] = ()
+    choices_meta_schema: typing.ClassVar[dict[str, dict[str, str]]] = {}
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
 

app/core/openapi/ui_hints.py

@@ -1,13 +1,19 @@
 from core.models import MarkdownField
 from django.db.models.fields import TextField
 from django.db.models.fields.files import FileField
-from django.db.models.fields.related import ManyToManyField
+from django.db.models.fields.related import ForeignKey, ManyToManyField
 from modeltranslation.fields import TranslationField
 
 
-def ui_hints_for_model_field(model_field: object) -> dict[str, str]:
+def ui_hints_for_model_field(model_field: object) -> dict:
+    hints: dict = {}
+
+    if isinstance(model_field, (ForeignKey, ManyToManyField)):
+        if meta_schema := getattr(model_field.related_model, "choices_meta_schema", None):
+            hints["ui:options"] = {"choiceMetaSchema": meta_schema}
+
     if isinstance(model_field, ManyToManyField):
-        return {"ui:field": "m2m_select"}
+        return hints | {"ui:field": "m2m_select"}
     if isinstance(model_field, FileField):
         return {"ui:field": "file"}
     if isinstance(model_field, TranslationField):
@@ -16,4 +22,4 @@ def ui_hints_for_model_field(model_field: object) -> dict[str, str]:
         return {"ui:widget": "textarea", "ui:field": "markdown"}
     if isinstance(model_field, TextField):
         return {"ui:widget": "textarea"}
-    return {}
+    return hints

app/core/viewset/json_schema_viewset.py

@@ -21,8 +21,8 @@ def __new__(cls, *args: tuple, **kwargs: dict) -> JsonSchemaViewSet:
         return super().__new__(cls)
 
     @staticmethod
-    def _get_choices_from_queryset(qs: QuerySet, is_nullable: bool) -> list[dict[str, str]]:
-        choices: list[dict[str, str]] = [{"const": None, "title": "빈 값"}] if is_nullable else []
+    def _get_choices_from_queryset(qs: QuerySet, is_nullable: bool) -> list[dict]:
+        choices: list[dict] = [{"const": None, "title": "빈 값"}] if is_nullable else []
 
         if hasattr(qs, "get_choices_queryset"):
             qs = qs.get_choices_queryset()
@@ -33,7 +33,10 @@ def _get_choices_from_queryset(qs: QuerySet, is_nullable: bool) -> list[dict[str
             qs = qs.filter(is_active=True)
 
         for row in qs:
-            choices.append({"const": str(row.pk), "title": str(row)})
+            item: dict = {"const": str(row.pk), "title": str(row)}
+            if hasattr(row, "get_choice_meta") and (meta := row.get_choice_meta()):
+                item["meta"] = meta
+            choices.append(item)
 
         return choices
 
@@ -74,8 +77,8 @@ def _get_related_field_info(self) -> list[tuple[str, object, serializers.Field,
 
         return result
 
-    def get_choices(self) -> dict[str, list[dict[str, str]]]:
-        choices: dict[str, list[dict[str, str]]] = {}
+    def get_choices(self) -> dict[str, list[dict]]:
+        choices: dict[str, list[dict]] = {}
 
         for field_name, field, serializer_field, is_m2m in self._get_related_field_info():
             if is_m2m:

app/event/models.py

@@ -1,11 +1,20 @@
+import typing
+
 from core.models import BaseAbstractModel
 from django.core.exceptions import ValidationError
 from django.db import models
+from django.utils import timezone
 from file.models import PublicFile
 from user.models.organization import Organization
 
 
 class Event(BaseAbstractModel):
+    choices_select_related = ("organization",)
+    choices_meta_schema: typing.ClassVar[dict] = {
+        "organization": {"label": "조직", "type": "string", "filter": "select"},
+        "started_at": {"label": "시작일", "type": "string", "filter": "search"},
+    }
+
     organization = models.ForeignKey(Organization, on_delete=models.PROTECT, related_name="events")
     name = models.CharField(max_length=256)
     logo = models.ForeignKey(PublicFile, on_delete=models.PROTECT, null=True, blank=True, related_name="+")
@@ -28,6 +37,12 @@ class Meta:
     def __str__(self):
         return f"{self.name} by {self.organization}"
 
+    def get_choice_meta(self) -> dict:
+        return {
+            "organization": str(self.organization),
+            "started_at": timezone.localtime(self.event_start_at).date().isoformat() if self.event_start_at else None,
+        }
+
     def clean(self) -> None:
         super().clean()
         if self.event_start_at and self.event_end_at and self.event_start_at > self.event_end_at:

app/event/presentation/models.py

@@ -3,7 +3,7 @@
 import datetime
 import uuid
 from contextlib import suppress
-from typing import Self
+from typing import ClassVar, Self
 
 from core.models import BaseAbstractModel, BaseAbstractModelQuerySet, MarkdownField
 from django.contrib.auth import get_user_model
@@ -81,7 +81,11 @@ def __str__(self) -> str:
 
 
 class Presentation(BaseAbstractModel):
-    choices_select_related = ("type",)
+    choices_select_related = ("type", "type__event")
+    choices_meta_schema: ClassVar[dict] = {
+        "type": {"label": "발표 타입", "type": "string", "filter": "select"},
+        "event": {"label": "이벤트", "type": "string", "filter": "select"},
+    }
 
     type = models.ForeignKey(PresentationType, on_delete=models.PROTECT)
     title = models.CharField(max_length=256)
@@ -104,6 +108,12 @@ class Presentation(BaseAbstractModel):
     def __str__(self) -> str:
         return f"[{self.type.name}] {self.title}"
 
+    def get_choice_meta(self) -> dict:
+        return {
+            "type": self.type.name,
+            "event": self.type.event.name,
+        }
+
     def active_categories(self) -> list[PresentationCategory]:
         with suppress(AttributeError):
             return self._prefetched_active_categories

app/shop/product/models.py

@@ -33,6 +33,13 @@ def __str__(self) -> str:  # pragma: no cover
 
 
 class Category(BaseAbstractModel):
+    choices_select_related = ("group", "event", "event__organization")
+    choices_meta_schema: typing.ClassVar[dict] = {
+        "is_ticket": {"label": "티켓", "type": "boolean"},
+        "group": {"label": "그룹", "type": "string", "filter": "select"},
+        "event": {"label": "이벤트", "type": "string", "filter": "select"},
+    }
+
     group = models.ForeignKey(CategoryGroup, on_delete=models.PROTECT)
     name = models.CharField(max_length=100)
     priority = models.IntegerField(default=0)
@@ -49,6 +56,13 @@ class Meta:
     def __str__(self) -> str:  # pragma: no cover
         return f"{self.group.name} > {self.name}"
 
+    def get_choice_meta(self) -> dict:
+        return {
+            "group": self.group.name,
+            "is_ticket": self.is_ticket,
+            "event": str(self.event) if self.event_id else None,
+        }
+
 
 class Tag(BaseAbstractModel):
     name = models.CharField(max_length=100)
@@ -119,6 +133,14 @@ class CurrentStatus(models.TextChoices):
         OUT_OF_ORDERABLE_PERIOD = "out_of_orderable_period", "판매 기간 아님"
         ACTIVE = "active", "노출 중"
 
+    choices_select_related = ("category", "category__group")
+    choices_meta_schema: typing.ClassVar[dict] = {
+        "category": {"label": "카테고리", "type": "string", "filter": "select"},
+        "price": {"label": "가격", "type": "number"},
+        "stock": {"label": "재고", "type": "number"},
+        "status": {"label": "상태", "type": "string", "filter": "select"},
+    }
+
     name = models.TextField()
     description = models.TextField(null=True, blank=True)
     image = models.ForeignKey(
@@ -169,6 +191,14 @@ class Meta:
     def __str__(self) -> str:  # pragma: no cover
         return f"{self.category} > {self.name} ({self.price}원)"
 
+    def get_choice_meta(self) -> dict:
+        return {
+            "category": str(self.category),
+            "price": self.price,
+            "stock": self.stock,
+            "status": self.current_status.label,
+        }
+
     @property
     def visible_period(self) -> TimeSpan:
         return TimeSpan(self.visible_starts_at, self.visible_ends_at)

app/user/models/user.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import typing
 from uuid import uuid4
 
 from core.const.system import SYSTEM_EMAIL, SYSTEM_USERNAME
@@ -12,6 +13,13 @@ class UserExt(ScanCodeMixin, AbstractUser):
     scancode_prefix = "user"
     scancode_uuid_field = "unique_id"
 
+    choices_meta_schema: typing.ClassVar[dict] = {
+        "email": {"label": "이메일", "type": "string", "filter": "search"},
+        "nickname": {"label": "닉네임", "type": "string", "filter": "search"},
+        "is_active": {"label": "활성", "type": "boolean"},
+        "is_superuser": {"label": "스태프", "type": "boolean"},
+    }
+
     image = models.ForeignKey("file.PublicFile", on_delete=models.PROTECT, null=True, blank=True)
     nickname = models.CharField(max_length=128, null=True, blank=True)
     unique_id = models.UUIDField(unique=True, editable=False, null=False, blank=False, default=uuid4)
@@ -23,6 +31,14 @@ class Meta(AbstractUser.Meta):
     def __str__(self):
         return f"[User] {self.nickname} <{self.email}>"
 
+    def get_choice_meta(self) -> dict:
+        return {
+            "email": self.email,
+            "nickname": self.nickname,
+            "is_active": self.is_active,
+            "is_superuser": self.is_superuser,
+        }
+
     @classmethod
     def get_system_user(cls) -> UserExt:
         return cls.objects.get_or_create(username=SYSTEM_USERNAME, email=SYSTEM_EMAIL)[0]