feat: shipment change && version modelize

api_v1/views/shipment/serializers.py

@@ -14,6 +14,41 @@ from shipment.models import (
 )
 
 
+SHIPMENT_STAGE_MISSING_ADDRESS = "missing_address"
+SHIPMENT_STAGE_DELIVERABLE = "deliverable"
+SHIPMENT_STAGE_SCHEDULED = "scheduled"
+SHIPMENT_STAGE_DELIVERED = "delivered"
+SHIPMENT_STAGE_CANCELLED = "cancelled"
+
+SHIPMENT_STAGE_DISPLAY = {
+    SHIPMENT_STAGE_MISSING_ADDRESS: "待补地址",
+    SHIPMENT_STAGE_DELIVERABLE: "可送货",
+    SHIPMENT_STAGE_SCHEDULED: "已排车",
+    SHIPMENT_STAGE_DELIVERED: "已送达",
+    SHIPMENT_STAGE_CANCELLED: "已取消",
+}
+
+
+def resolve_shipment_stage(shipment: Shipment) -> str | None:
+    if shipment.status == ShipmentStatus.CANCELLED:
+        return SHIPMENT_STAGE_CANCELLED
+
+    delivery = getattr(shipment, "delivery", None)
+    if delivery is not None:
+        if delivery.status == ShipmentDeliveryStatus.DELIVERED:
+            return SHIPMENT_STAGE_DELIVERED
+        if delivery.status in {
+            ShipmentDeliveryStatus.PENDING,
+            ShipmentDeliveryStatus.IN_TRANSIT,
+        }:
+            return SHIPMENT_STAGE_SCHEDULED
+        return None
+
+    if (shipment.address or "").strip():
+        return SHIPMENT_STAGE_DELIVERABLE
+    return SHIPMENT_STAGE_MISSING_ADDRESS
+
+
 def _build_nested_sales_item_context(items):
     customer_ids = {item.customer_id for item in items if item.customer_id}
     printing_job_ids = {item.printing_job_id for item in items if item.printing_job_id}
@@ -128,6 +163,8 @@ class ShipmentSerializer(serializers.ModelSerializer):
     )
     approved_by_name = serializers.SerializerMethodField()
     status_display = serializers.CharField(source="get_status_display", read_only=True)
+    shipment_stage = serializers.SerializerMethodField()
+    shipment_stage_display = serializers.SerializerMethodField()
     external_finished_products_count = serializers.SerializerMethodField()
     merchant_id = serializers.IntegerField(source="merchant.id", read_only=True)
     merchant_name = serializers.CharField(source="merchant.name", read_only=True)
@@ -157,6 +194,8 @@ class ShipmentSerializer(serializers.ModelSerializer):
             "remark",
             "status",
             "status_display",
+            "shipment_stage",
+            "shipment_stage_display",
             "external_id",
             "geo_coordinates",
             "extra",
@@ -191,6 +230,13 @@ class ShipmentSerializer(serializers.ModelSerializer):
     def get_items_count(self, obj):
         return obj.items.filter(delete_at__isnull=True).count()
 
+    def get_shipment_stage(self, obj):
+        return resolve_shipment_stage(obj)
+
+    def get_shipment_stage_display(self, obj):
+        stage = resolve_shipment_stage(obj)
+        return SHIPMENT_STAGE_DISPLAY.get(stage)
+
     def get_order_description(self, obj):
         return _resolve_shipment_order_description(obj)