Merge branch 'feat/option-group-and-period-validation'

# Conflicts:
#	app/admin_api/test/shop/products_api_test.py

Author: MU-Software

app/admin_api/serializers/shop/products.py

@@ -9,6 +9,7 @@
     NestedFieldSpec,
     NestedModelSerializer,
 )
+from core.util.timespan import TimeSpan
 from file.models import PublicFile
 from rest_framework import serializers
 from shop.product.models import Category, CategoryGroup, Option, OptionGroup, Product, Tag
@@ -83,6 +84,11 @@ class Meta:
             "name_en",
             "min_quantity_per_product",
             "max_quantity_per_product",
+            "max_quantity_per_user",
+            "visible_starts_at",
+            "visible_ends_at",
+            "orderable_starts_at",
+            "orderable_ends_at",
             "is_custom_response",
             "custom_response_pattern",
             "response_modifiable_ends_at",
@@ -114,8 +120,65 @@ def validate(self, attrs: dict) -> dict:
             raise serializers.ValidationError(
                 {"custom_response_pattern": "is_custom_response=True 일 때 custom_response_pattern 은 필수입니다."}
             )
+
+        if errors := self._validate_period(attrs):
+            raise serializers.ValidationError(errors)
         return attrs
 
+    # 메시지 템플릿 — visible / orderable 둘 다 같은 구조라 label 만 치환.
+    _GROUP_PERIOD_LABELS = (("visible", "노출"), ("orderable", "판매"))
+
+    def _validate_period(self, attrs: dict) -> dict[str, str]:
+        merged = {**attrs}
+        for field in (
+            "visible_starts_at",
+            "visible_ends_at",
+            "orderable_starts_at",
+            "orderable_ends_at",
+            "min_quantity_per_product",
+            "product",
+        ):
+            if self.instance is not None:
+                merged.setdefault(field, getattr(self.instance, field, None))
+
+        product: Product = merged["product"]
+        min_qty = merged.get("min_quantity_per_product") or 0
+
+        errors: dict[str, str] = {}
+        for kind, label in self._GROUP_PERIOD_LABELS:
+            span = TimeSpan(merged.get(f"{kind}_starts_at"), merged.get(f"{kind}_ends_at"))
+            parent = getattr(product, f"{kind}_period")
+            errors.update(self._check_group_span(span, parent, kind=kind, label=label))
+            if min_qty >= 1:
+                # 필수 옵션 그룹은 상품 기간과 동기되어야 한다 — 그룹 starts_at 이 늦거나 ends_at 이 일찍이면
+                # 상품은 노출/판매되는데 필수 옵션을 채울 수 없는 죽은 구간이 생기므로 그룹 단위 윈도우 지정 금지.
+                if span.starts_at is not None:
+                    msg = f"필수 옵션 그룹의 {label} 시작은 별도로 지정할 수 없습니다 (상품 기준)."
+                    errors[f"{kind}_starts_at"] = msg
+                if span.ends_at is not None:
+                    msg = f"필수 옵션 그룹의 {label} 종료는 별도로 지정할 수 없습니다 (상품 기준)."
+                    errors[f"{kind}_ends_at"] = msg
+
+        return errors
+
+    @staticmethod
+    def _check_group_span(span: TimeSpan, parent: TimeSpan, *, kind: str, label: str) -> dict[str, str]:
+        # 그룹의 visible/orderable 윈도우 검증 — 자기 inverted + 상품 윈도우 안 포함 + 한 boundary fallback inverted.
+        errors: dict[str, str] = {}
+        if span.is_inverted:
+            errors[f"{kind}_starts_at"] = f"옵션 그룹의 {label} 시작은 {label} 종료 이전이어야 합니다."
+        if span.starts_before(parent):
+            errors[f"{kind}_starts_at"] = f"옵션 그룹의 {label} 시작은 상품 {label} 시작 이후여야 합니다."
+        if span.ends_after(parent):
+            errors[f"{kind}_ends_at"] = f"옵션 그룹의 {label} 종료는 상품 {label} 종료 이전이어야 합니다."
+        # 한 쪽 boundary 만 명시하면 model effective_*_period (None → product fallback) 가 inverted 될 수 있다.
+        # 예: product=[2020,2099], group ends_at=2019 → effective=[2020,2019]. admin 이 잡는다.
+        if span.ends_at and span.ends_at < parent.effective_starts_at:
+            errors[f"{kind}_ends_at"] = f"옵션 그룹의 {label} 종료는 상품 {label} 시작 이후여야 합니다."
+        if span.starts_at and span.starts_at > parent.effective_ends_at:
+            errors[f"{kind}_starts_at"] = f"옵션 그룹의 {label} 시작은 상품 {label} 종료 이전이어야 합니다."
+        return errors
+
 
 class ProductAdminSerializer(BaseAbstractSerializer, JsonSchemaSerializer, serializers.ModelSerializer):
     option_groups = OptionGroupAdminSerializer(many=True, read_only=True)
@@ -158,22 +221,27 @@ class Meta:
         )
 
     def validate(self, attrs: dict) -> dict:
+        if errors := self._validate_period(attrs):
+            raise serializers.ValidationError(errors)
+        return attrs
+
+    def _validate_period(self, attrs: dict) -> dict[str, str]:
+        """visible/orderable 윈도우 검증 — partial update 대비 merged 패턴."""
         merged = {**attrs}
         if self.instance is not None:
             for field in ("visible_starts_at", "visible_ends_at", "orderable_starts_at", "orderable_ends_at"):
                 merged.setdefault(field, getattr(self.instance, field, None))
 
-        v_start = merged.get("visible_starts_at")
-        v_end = merged.get("visible_ends_at")
-        o_start = merged.get("orderable_starts_at")
-        o_end = merged.get("orderable_ends_at")
+        visible = TimeSpan(merged.get("visible_starts_at"), merged.get("visible_ends_at"))
+        orderable = TimeSpan(merged.get("orderable_starts_at"), merged.get("orderable_ends_at"))
 
         errors: dict[str, str] = {}
-        if v_start and o_start and o_start < v_start:
+        if visible.is_inverted:
+            errors["visible_starts_at"] = "노출 시작은 노출 종료 이전이어야 합니다."
+        if orderable.is_inverted:
+            errors["orderable_starts_at"] = "판매 시작은 판매 종료 이전이어야 합니다."
+        if orderable.starts_before(visible):
             errors["orderable_starts_at"] = "판매 시작은 노출 시작 이후여야 합니다."
-        if v_end and o_end and o_end > v_end:
+        if orderable.ends_after(visible):
             errors["orderable_ends_at"] = "판매 종료는 노출 종료 이전이어야 합니다."
-
-        if errors:
-            raise serializers.ValidationError(errors)
-        return attrs
+        return errors

app/admin_api/test/shop/products_api_test.py

@@ -9,7 +9,7 @@
     HTTP_403_FORBIDDEN,
 )
 from shop.conftest import FAR_FUTURE, FAR_PAST
-from shop.product.models import Category, CategoryGroup, Product, Tag
+from shop.product.models import Category, CategoryGroup, OptionGroup, Product, Tag
 from shop.test.helpers import CategoryGroupsAdminApi, OptionGroupsAdminApi, ProductsAdminApi, TagsAdminApi
 
 
@@ -95,6 +95,27 @@ def test_admin_product_partial_update_validates_orderable_before_visible_end(api
     assert "orderable_ends_at" in str(response.json())
 
 
+@pytest.mark.django_db
+def test_admin_product_partial_update_rejects_inverted_visible_window(api_client, product):
+    # visible_starts_at(2100) > visible_ends_at(fixture default FAR_FUTURE=2099) → 400.
+    response = ProductsAdminApi(http_client=api_client).update(
+        product.id, {"visible_starts_at": datetime(2100, 1, 1, tzinfo=timezone.utc).isoformat()}
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert "visible_starts_at" in str(response.json())
+
+
+@pytest.mark.django_db
+def test_admin_product_partial_update_rejects_inverted_orderable_window(api_client, product):
+    # orderable_starts_at(2098) > orderable_ends_at(fixture default FAR_FUTURE=2099) 인 케이스를 만들기 위해
+    # ends_at 을 starts_at 보다 앞으로 patch — orderable_ends_at(2010) < orderable_starts_at(FAR_PAST=2020).
+    response = ProductsAdminApi(http_client=api_client).update(
+        product.id, {"orderable_ends_at": datetime(2010, 1, 1, tzinfo=timezone.utc).isoformat()}
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert "orderable_starts_at" in str(response.json())
+
+
 @pytest.mark.django_db
 def test_admin_product_partial_update_merged_uses_instance_value_for_missing_field(api_client, product):
     # patch 에 visible_starts_at 만 보내고 orderable_* 미포함 → merged 가 instance 값 fallback 사용 → 성공.
@@ -159,6 +180,183 @@ def test_admin_option_group_create_rejects_invalid_regex_pattern(api_client, pro
     assert "custom_response_pattern" in str(response.json())
 
 
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_orderable_starts_before_product_starts(api_client, product):
+    # product.orderable_starts_at(FAR_PAST=2020) 보다 앞 (2019) → 거절.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "얼리버드",
+            "name_en": "Earlybird",
+            "orderable_starts_at": datetime(2019, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert "orderable_starts_at" in str(response.json())
+
+
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_orderable_ends_after_product_ends(api_client, product):
+    # product.orderable_ends_at(FAR_FUTURE=2099) 보다 뒤 (2100) → 거절.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "후반",
+            "name_en": "Late",
+            "orderable_ends_at": datetime(2100, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert "orderable_ends_at" in str(response.json())
+
+
+@pytest.mark.parametrize("kind", ["visible", "orderable"])
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_inverted_window(api_client, product, kind):
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "옵션",
+            "name_en": "Opt",
+            f"{kind}_starts_at": datetime(2050, 1, 1, tzinfo=timezone.utc).isoformat(),
+            f"{kind}_ends_at": datetime(2030, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert f"{kind}_starts_at" in str(response.json())
+
+
+@pytest.mark.parametrize("kind", ["visible", "orderable"])
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_starts_before_product_starts(api_client, product, kind):
+    # group_starts_at < product_starts_at (FAR_PAST=2020) → 거절. visible / orderable 동일 분기.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "옵션",
+            "name_en": "Opt",
+            f"{kind}_starts_at": datetime(2019, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert f"{kind}_starts_at" in str(response.json())
+
+
+@pytest.mark.parametrize("kind", ["visible", "orderable"])
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_ends_after_product_ends(api_client, product, kind):
+    # group_ends_at > product_ends_at (FAR_FUTURE=2099) → 거절.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "옵션",
+            "name_en": "Opt",
+            f"{kind}_ends_at": datetime(2100, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert f"{kind}_ends_at" in str(response.json())
+
+
+@pytest.mark.django_db
+def test_admin_option_group_create_allows_period_within_product_window(api_client, product):
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "얼리버드",
+            "name_en": "Earlybird",
+            "orderable_starts_at": datetime(2030, 1, 1, tzinfo=timezone.utc).isoformat(),
+            "orderable_ends_at": datetime(2031, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_201_CREATED
+
+
+@pytest.mark.parametrize(
+    "window_field",
+    ["visible_starts_at", "visible_ends_at", "orderable_starts_at", "orderable_ends_at"],
+)
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_required_group_with_explicit_window(api_client, product, window_field):
+    # min_quantity_per_product >= 1 인 필수 그룹은 visible/orderable starts_at/ends_at 을 별도 지정할 수 없음 —
+    # 그룹 윈도우가 상품과 어긋나면 필수 옵션이 비어 상품을 살 수 없는 죽은 구간이 생긴다.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "필수옵션",
+            "name_en": "Required",
+            "min_quantity_per_product": 1,
+            window_field: datetime(2030, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert window_field in str(response.json())
+
+
+@pytest.mark.parametrize(
+    "window_field",
+    ["visible_starts_at", "visible_ends_at", "orderable_starts_at", "orderable_ends_at"],
+)
+@pytest.mark.django_db
+def test_admin_option_group_partial_update_rejects_setting_min_quantity_when_window_already_set(
+    api_client, product, window_field
+):
+    # 역방향 — 윈도우가 이미 설정된 그룹을 min_quantity_per_product>=1 로 patch → merged 가 instance 윈도우를 사용해 거절.
+    group = OptionGroup.objects.create(
+        product=product, name="기간옵션", **{window_field: datetime(2030, 1, 1, tzinfo=timezone.utc)}
+    )
+    response = OptionGroupsAdminApi(http_client=api_client).update(group.id, {"min_quantity_per_product": 1})
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert window_field in str(response.json())
+
+
+@pytest.mark.parametrize("kind", ["visible", "orderable"])
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_ends_at_before_product_starts_at(api_client, product, kind):
+    # P2-A: 한 쪽 boundary 만 명시 — starts_at=None → product fallback(FAR_PAST=2020), ends_at=2019.
+    # admin 이 model effective_*_period 의 inverted 케이스를 차단해야 함.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "옵션",
+            "name_en": "Opt",
+            f"{kind}_ends_at": datetime(2019, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert f"{kind}_ends_at" in str(response.json())
+
+
+@pytest.mark.parametrize("kind", ["visible", "orderable"])
+@pytest.mark.django_db
+def test_admin_option_group_create_rejects_starts_at_after_product_ends_at(api_client, product, kind):
+    # P2-A: starts_at=2100 > product.*_ends_at(FAR_FUTURE=2099) → effective inverted.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "옵션",
+            "name_en": "Opt",
+            f"{kind}_starts_at": datetime(2100, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_400_BAD_REQUEST
+    assert f"{kind}_starts_at" in str(response.json())
+
+
+@pytest.mark.django_db
+def test_admin_option_group_create_allows_non_required_group_with_explicit_window(api_client, product):
+    # 비필수 그룹(min_quantity_per_product=0) 은 starts_at 명시 가능.
+    response = OptionGroupsAdminApi(http_client=api_client).create(
+        {
+            "product": str(product.id),
+            "name_ko": "선택옵션",
+            "name_en": "Optional",
+            "orderable_starts_at": datetime(2030, 1, 1, tzinfo=timezone.utc).isoformat(),
+        }
+    )
+    assert response.status_code == HTTP_201_CREATED
+
+
 @pytest.mark.parametrize("status", list(Product.CurrentStatus))
 @pytest.mark.django_db
 def test_admin_product_list_filters_by_status(api_client, products_by_status, status):

app/core/const/shop_error_messages.py

@@ -40,6 +40,8 @@ class OptionGroupNotOrderableErrorMessages:
     SOLDOUT = "{} 상품의 필수 구매 옵션인 '{}' 옵션이 매진되어 상품을 구매하실 수 없습니다."
     NOT_ENOUGH_OPTION = "{} 상품의 필수 구매 옵션인 '{}' 옵션을 선택해주세요."
     TOO_MUCH_OPTION = "{} 상품의 '{}' 옵션을 너무 많이 선택하셨습니다."
+    ALREADY_ORDERED_TOO_MUCH = "{} 상품 '{}' 옵션 그룹의 인당 최대 선택 수량 초과로 구매하실 수 없습니다."
+    NOT_ORDERABLE_TIME = "{} 상품의 '{}' 옵션 그룹은 현재 구매하실 수 없습니다."
 
 
 class OptionNotOrderableErrorMessages: