feat: shop admin API 보완 (필터/검증/재고/상태/부분환불)

MU-Software · MU-Software · commit 03416bae2493 · 2026-05-13T00:41:43.000+09:00
diff --git a/app/admin_api/filtersets/shop/products.py b/app/admin_api/filtersets/shop/products.py
@@ -0,0 +1,61 @@
+from core.filter.multi_field import MultiFieldOrCharInFilter
+from core.util.dateutil import now_aware
+from django.db.models import Q
+from django_filters import rest_framework as filters
+from shop.product.models import Product
+
+
+class ProductAdminFilterSet(filters.FilterSet):
+    id = filters.BaseInFilter(field_name="id")
+    name = MultiFieldOrCharInFilter(field_names=["name_ko", "name_en"], lookup_expr="icontains")
+    category = filters.BaseInFilter(field_name="category_id")
+    category_group = filters.BaseInFilter(field_name="category__group_id")
+    hidden = filters.BooleanFilter(field_name="hidden")
+    tag = filters.BaseInFilter(field_name="tag_set", distinct=True)
+
+    price_min = filters.NumberFilter(field_name="price", lookup_expr="gte")
+    price_max = filters.NumberFilter(field_name="price", lookup_expr="lte")
+
+    status = filters.BaseCSVFilter(method="filter_by_status")
+
+    def filter_by_status(self, queryset, name, values):
+        if not values:
+            return queryset
+
+        now = now_aware()
+        q = Q()
+        for value in values:
+            if value == Product.CurrentStatus.HIDDEN:
+                q |= Q(hidden=True)
+            elif value == Product.CurrentStatus.OUT_OF_VISIBLE_PERIOD:
+                q |= Q(hidden=False) & (Q(visible_starts_at__gt=now) | Q(visible_ends_at__lt=now))
+            elif value == Product.CurrentStatus.OUT_OF_ORDERABLE_PERIOD:
+                q |= (
+                    Q(hidden=False)
+                    & Q(visible_starts_at__lte=now)
+                    & Q(visible_ends_at__gte=now)
+                    & (Q(orderable_starts_at__gt=now) | Q(orderable_ends_at__lt=now))
+                )
+            elif value == Product.CurrentStatus.ACTIVE:
+                q |= (
+                    Q(hidden=False)
+                    & Q(visible_starts_at__lte=now)
+                    & Q(visible_ends_at__gte=now)
+                    & Q(orderable_starts_at__lte=now)
+                    & Q(orderable_ends_at__gte=now)
+                )
+        return queryset.filter(q).distinct()
+
+    class Meta:
+        model = Product
+        fields = [
+            "id",
+            "name",
+            "category",
+            "category_group",
+            "hidden",
+            "tag",
+            "price_min",
+            "price_max",
+            "status",
+        ]
diff --git a/app/admin_api/serializers/shop/orders.py b/app/admin_api/serializers/shop/orders.py
@@ -5,7 +5,6 @@
 from core.const.serializer import COMMON_ADMIN_FIELDS
 from core.serializer.base_abstract_serializer import BaseAbstractSerializer
 from core.serializer.json_schema_serializer import JsonSchemaSerializer
-from core.serializer.read_only_serializer import ReadOnlyModelSerializer
 from core.serializer.skip_none_list_serializer import SkipNoneListSerializer
 from django.conf import settings
 from notification.channels import NotificationChannel
@@ -24,7 +23,6 @@
 
 
 class OrderAdminSerializer(
-    ReadOnlyModelSerializer,
     BaseAbstractSerializer,
     JsonSchemaSerializer,
     serializers.ModelSerializer,
@@ -37,7 +35,7 @@ class Meta:
     class SimpleCustomerInfoSerializer(serializers.ModelSerializer):
         class Meta:
             model = CustomerInfo
-            read_only_fields = fields = ("name", "phone", "email", "organization")
+            fields = ("name", "phone", "email", "organization")
 
     class SimplePaymentHistorySerializer(serializers.ModelSerializer):
         class Meta:
@@ -76,7 +74,7 @@ class Meta:
             read_only_fields = ("id", "product", "price", "donation_price", "options")
 
     user = SimpleUserSerializer(read_only=True)
-    customer_info = SimpleCustomerInfoSerializer(read_only=True)
+    customer_info = SimpleCustomerInfoSerializer(required=False, allow_null=True)
     products = SimpleOrderProductRelationSerializer(many=True, read_only=True)
     payment_histories = SimplePaymentHistorySerializer(many=True, read_only=True)
     first_paid_price = serializers.IntegerField(read_only=True)
@@ -100,6 +98,21 @@ class Meta:
             "first_paid_at",
             "latest_imp_id",
         )
+        read_only_fields = ("name_ko", "name_en")
+
+    def update(self, instance: Order, validated_data: dict) -> Order:
+        customer_info_data = validated_data.pop("customer_info", None)
+        order = super().update(instance, validated_data)
+
+        if customer_info_data is not None:
+            if order.customer_info:
+                for field, value in customer_info_data.items():
+                    setattr(order.customer_info, field, value)
+                order.customer_info.save()
+            else:
+                CustomerInfo.objects.create(order=order, **customer_info_data)
+
+        return order
 
 
 class OrderExportRequestSerializer(JsonSchemaSerializer, serializers.Serializer):
diff --git a/app/admin_api/serializers/shop/products.py b/app/admin_api/serializers/shop/products.py
@@ -18,13 +18,19 @@ class CategoryAdminSerializer(BaseAbstractSerializer, JsonSchemaSerializer, Nest
         class Meta:
             model = Category
             fields = COMMON_ADMIN_FIELDS + ("group", "name", "priority")
+            # group 은 NestedFieldSpec.parent_fk_name 으로 부모 인스턴스에서 주입되므로 입력 시 생략 가능.
+            # validators=[] — auto UniqueTogetherValidator(group, name) 가 group 누락 시 required 로 막음.
+            # DB unique constraint(uq__cat__grp_nm) 가 여전히 enforce.
+            extra_kwargs = {"group": {"required": False}}
+            validators: list = []
             list_serializer_class = InstanceListSerializer
 
     categories = CategoryAdminSerializer(many=True, required=False, source="category_set")
+    category_count = serializers.IntegerField(read_only=True)
 
     class Meta:
         model = CategoryGroup
-        fields = COMMON_ADMIN_FIELDS + ("name", "priority", "categories")
+        fields = COMMON_ADMIN_FIELDS + ("name", "priority", "categories", "category_count")
         nested_fields = {
             "category_set": NestedFieldSpec(
                 related_manager_name="category_set",
@@ -35,14 +41,17 @@ class Meta:
 
 
 class TagAdminSerializer(BaseAbstractSerializer, JsonSchemaSerializer, serializers.ModelSerializer):
+    leftover_stock = serializers.IntegerField(read_only=True, allow_null=True)
+
     class Meta:
         model = Tag
-        fields = COMMON_ADMIN_FIELDS + ("name_ko", "name_en", "stock", "max_quantity_per_user")
+        fields = COMMON_ADMIN_FIELDS + ("name_ko", "name_en", "stock", "max_quantity_per_user", "leftover_stock")
 
 
 class OptionGroupAdminSerializer(BaseAbstractSerializer, JsonSchemaSerializer, NestedFieldModelSerializer):
     class OptionAdminSerializer(BaseAbstractSerializer, JsonSchemaSerializer, NestedModelSerializer):
         id = serializers.UUIDField(required=False, help_text="기존 Option 수정 시 PK 전달, 새로 추가 시 생략")
+        leftover_stock = serializers.IntegerField(read_only=True, allow_null=True)
 
         class Meta:
             model = Option
@@ -54,7 +63,10 @@ class Meta:
                 "max_quantity_per_user",
                 "additional_price",
                 "stock",
+                "leftover_stock",
             )
+            # group 은 NestedFieldSpec.parent_fk_name 으로 부모 인스턴스에서 주입되므로 입력 시 생략 가능.
+            extra_kwargs = {"group": {"required": False}}
             list_serializer_class = InstanceListSerializer
 
     options = OptionAdminSerializer(many=True, required=False)
@@ -97,6 +109,9 @@ def validate(self, attrs: dict) -> dict:
 class ProductAdminSerializer(BaseAbstractSerializer, JsonSchemaSerializer, serializers.ModelSerializer):
     option_groups = OptionGroupAdminSerializer(many=True, read_only=True)
     tag_set = serializers.PrimaryKeyRelatedField(many=True, queryset=Tag.objects.filter_active(), required=False)
+    tag_set_detail = TagAdminSerializer(many=True, read_only=True, source="tag_set")
+    leftover_stock = serializers.IntegerField(read_only=True, allow_null=True)
+    current_status = serializers.ChoiceField(choices=Product.CurrentStatus.choices, read_only=True)
 
     class Meta:
         model = Product
@@ -122,4 +137,28 @@ class Meta:
             "donation_max_price",
             "option_groups",
             "tag_set",
+            "tag_set_detail",
+            "leftover_stock",
+            "current_status",
         )
+
+    def validate(self, attrs: dict) -> dict:
+        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")
+
+        errors: dict[str, str] = {}
+        if v_start and o_start and o_start < v_start:
+            errors["orderable_starts_at"] = "판매 시작은 노출 시작 이후여야 합니다."
+        if v_end and o_end and o_end > v_end:
+            errors["orderable_ends_at"] = "판매 종료는 노출 종료 이전이어야 합니다."
+
+        if errors:
+            raise serializers.ValidationError(errors)
+        return attrs
diff --git a/app/admin_api/views/shop/orders.py b/app/admin_api/views/shop/orders.py
@@ -14,27 +14,34 @@
 from django.db import models, transaction
 from django.http.response import StreamingHttpResponse
 from drf_spectacular.utils import OpenApiParameter, OpenApiTypes, extend_schema, extend_schema_view
-from rest_framework import exceptions, parsers, request, response, status, viewsets
+from rest_framework import exceptions, mixins, parsers, request, response, status, viewsets
 from rest_framework.decorators import action
 from shop.order import exports, imports
 from shop.order.models import Order, OrderProductOptionRelation, OrderProductRelation
 from shop.payment_history.models import PURCHASED_STATUSES, REFUNDABLE_STATUSES, PaymentHistory
 from shop.product.models import Product
-from shop.serializers.refund import OrderTotalRefundSerializer
+from shop.serializers.refund import OrderProductRefundSerializer, OrderTotalRefundSerializer
 
 logger = getLogger(__name__)
 
-ADMIN_METHODS = ["list", "retrieve"]
+ADMIN_METHODS = ["list", "retrieve", "partial_update"]
 
 
 @extend_schema_view(**{m: extend_schema(tags=[OpenAPITag.ADMIN_SHOP_ORDER]) for m in ADMIN_METHODS})
-class OrderAdminViewSet(JsonSchemaViewSet, viewsets.ReadOnlyModelViewSet):
-    http_method_names = ["get", "post"]
+class OrderAdminViewSet(
+    JsonSchemaViewSet,
+    mixins.ListModelMixin,
+    mixins.RetrieveModelMixin,
+    mixins.UpdateModelMixin,
+    viewsets.GenericViewSet,
+):
+    http_method_names = ["get", "post", "patch"]
     serializer_class = OrderAdminSerializer
     filterset_class = OrderAdminFilterSet
     permission_classes = [IsSuperUser]
     queryset = (
-        Order.objects.filter_active()
+        Order.objects.filter_has_payment_histories()
+        .filter(models.Exists(OrderProductRelation.objects.filter(order=models.OuterRef("pk"))))
         .select_related_with_user("user", "customer_info")
         .prefetch_related(
             models.Prefetch(
@@ -54,7 +61,6 @@ class OrderAdminViewSet(JsonSchemaViewSet, viewsets.ReadOnlyModelViewSet):
             models.Prefetch(
                 "payment_histories",
                 queryset=PaymentHistory.objects.filter_active().order_by("-created_at"),
-                to_attr="_payment_histories_by_latest",
             ),
         )
         .annotate(
@@ -83,6 +89,33 @@ def refund(self, request: request.Request, pk: typing.Any = None) -> response.Re
         serializer.refund()
         return response.Response(status=status.HTTP_204_NO_CONTENT)
 
+    @extend_schema(
+        summary="주문 부분 환불 (환불 승인자 TOTP 필수)",
+        tags=[OpenAPITag.ADMIN_SHOP_ORDER_REFUND],
+        parameters=[OpenApiParameter(name="totp", location=OpenApiParameter.QUERY, required=True)],
+        responses={status.HTTP_204_NO_CONTENT: None},
+    )
+    @action(detail=True, methods=["post"], url_path=r"products/(?P<rel_id>[^/.]+)/refund")
+    @transaction.atomic
+    def refund_product(
+        self,
+        request: request.Request,
+        pk: typing.Any = None,
+        rel_id: typing.Any = None,
+    ) -> response.Response:
+        order_product_rel = OrderProductRelation.objects.filter(order_id=pk, id=rel_id).first()
+        if not order_product_rel:
+            raise exceptions.NotFound("OrderProductRelation not found.")
+
+        serializer = OrderProductRefundSerializer(
+            instance=order_product_rel,
+            data={"totp": request.query_params.get("totp")},
+            context={"check_refundable_date": False},
+        )
+        serializer.is_valid(raise_exception=True)
+        serializer.refund()
+        return response.Response(status=status.HTTP_204_NO_CONTENT)
+
     @extend_schema(
         summary="주문 CSV 가져오기 템플릿 다운로드",
         tags=[OpenAPITag.ADMIN_SHOP_ORDER],
diff --git a/app/admin_api/views/shop/products.py b/app/admin_api/views/shop/products.py
@@ -1,3 +1,4 @@
+from admin_api.filtersets.shop.products import ProductAdminFilterSet
 from admin_api.serializers.shop.products import (
     CategoryGroupAdminSerializer,
     OptionGroupAdminSerializer,
@@ -7,7 +8,7 @@
 from core.authz import IsSuperUser
 from core.const.tag import OpenAPITag
 from core.viewset.json_schema_viewset import JsonSchemaViewSet
-from django.db.models import Prefetch
+from django.db.models import Count, Prefetch, Q
 from drf_spectacular.utils import extend_schema, extend_schema_view
 from rest_framework import viewsets
 from shop.product.models import Category, CategoryGroup, Option, OptionGroup, Product, ProductTagRelation, Tag
@@ -27,6 +28,7 @@ class CategoryGroupAdminViewSet(JsonSchemaViewSet, viewsets.ModelViewSet):
         .prefetch_related(
             Prefetch("category_set", queryset=Category.objects.filter_active().select_related_with_user()),
         )
+        .annotate(category_count=Count("category", filter=Q(category__deleted_at__isnull=True)))
     )
 
 
@@ -43,6 +45,7 @@ class ProductAdminViewSet(JsonSchemaViewSet, viewsets.ModelViewSet):
     http_method_names = ["get", "post", "patch", "delete"]
     serializer_class = ProductAdminSerializer
     permission_classes = [IsSuperUser]
+    filterset_class = ProductAdminFilterSet
     queryset = (
         Product.objects.filter_active()
         .select_related_with_user("category", "category__group")
diff --git a/app/shop/product/models.py b/app/shop/product/models.py
@@ -5,6 +5,7 @@
 import typing
 
 from core.models import BaseAbstractModel
+from core.util.dateutil import now_aware
 from django.core.exceptions import ValidationError
 from django.db import models
 from django.db.models.manager import BaseManager
@@ -104,6 +105,12 @@ def get_user_taken_stock_count(
 
 
 class Product(BaseAbstractModel):
+    class CurrentStatus(models.TextChoices):
+        HIDDEN = "hidden", "비공개"
+        OUT_OF_VISIBLE_PERIOD = "out_of_visible_period", "노출 기간 아님"
+        OUT_OF_ORDERABLE_PERIOD = "out_of_orderable_period", "판매 기간 아님"
+        ACTIVE = "active", "노출 중"
+
     name = models.TextField()
     description = models.TextField(null=True, blank=True)
     image = models.URLField(null=True, blank=True)
@@ -138,6 +145,24 @@ class Meta:
     def __str__(self) -> str:
         return f"{self.category} > {self.name} ({self.price}원)"
 
+    @property
+    def current_status(self) -> "Product.CurrentStatus":
+        if self.hidden:
+            return self.CurrentStatus.HIDDEN
+
+        now = now_aware()
+        if (self.visible_starts_at and now < self.visible_starts_at) or (
+            self.visible_ends_at and now > self.visible_ends_at
+        ):
+            return self.CurrentStatus.OUT_OF_VISIBLE_PERIOD
+
+        if (self.orderable_starts_at and now < self.orderable_starts_at) or (
+            self.orderable_ends_at and now > self.orderable_ends_at
+        ):
+            return self.CurrentStatus.OUT_OF_ORDERABLE_PERIOD
+
+        return self.CurrentStatus.ACTIVE
+
     @functools.cached_property
     def leftover_stock(self) -> int | None:
         """해당 상품의 재고를 반환합니다."""
