feat: app verion && some field modify (printing & shipment)

api_v1/management/commands/set_app_version.py

@@ -1,4 +1,6 @@
-from django.core.management.base import BaseCommand
+from datetime import date
+
+from django.core.management.base import BaseCommand, CommandError
 
 from flower.app_version import set_cached_app_version_payload
 
@@ -11,12 +13,26 @@ class Command(BaseCommand):
         parser.add_argument("--minor", type=int, required=True)
         parser.add_argument("--build", type=int, required=True)
         parser.add_argument("--download-url", required=True)
+        parser.add_argument("--force", action="store_true", default=False)
+        parser.add_argument(
+            "--publish-date",
+            help="发布日期，格式 YYYY-MM-DD；不传则使用当前日期",
+        )
 
     def handle(self, *args, **options):
+        publish_date = options.get("publish_date")
+        if publish_date:
+            try:
+                date.fromisoformat(publish_date)
+            except ValueError as exc:
+                raise CommandError("publish-date 必须是 YYYY-MM-DD 格式") from exc
+
         payload = set_cached_app_version_payload(
             major=options["major"],
             minor=options["minor"],
             build=options["build"],
             download_url=options["download_url"],
+            force=options["force"],
+            publish_date=publish_date,
         )
         self.stdout.write(self.style.SUCCESS(str(payload)))

api_v1/tasks.py

@@ -897,6 +897,7 @@ def _build_external_order_data(
         'rolling_warn': str(first.get('BeiZhu') or '').strip() or None,
         'curve': str(first.get('MeoA') or '').strip() or None,
         'position': str(first.get('FidJ') or '').strip() or None,
+        'kd_riqi': _parse_external_datetime(first.get('KdRiQi')),
         'outgoing_date': _parse_external_datetime(first.get('KdRiQi')),
         'created_by': created_by_user,
         'external_order_id': external_order_id,

api_v1/test_customer_address_api.py

@@ -0,0 +1,242 @@
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Permission
+from django.test import TestCase
+from rest_framework import status
+from rest_framework.test import APIClient
+
+from basic_info import models as basic_models
+
+User = get_user_model()
+
+
+class CustomerAddressAPITestCase(TestCase):
+    def setUp(self):
+        self.client = APIClient()
+        self.merchant = basic_models.Merchant.objects.create(
+            name="客户地址商户", type=basic_models.MerchantTypeEnum.FACTORY
+        )
+        self.other_merchant = basic_models.Merchant.objects.create(
+            name="其它客户地址商户", type=basic_models.MerchantTypeEnum.FACTORY
+        )
+
+        self.user = User.objects.create_user(username="addr-user", password="testpass123")
+        self.employee = basic_models.Employee.objects.create(
+            sys_user=self.user,
+            merchant=self.merchant,
+            name="地址员工",
+            status=basic_models.EmployeeStatusEnum.ACTIVE,
+        )
+        self.other_user = User.objects.create_user(
+            username="addr-other-user", password="testpass123"
+        )
+        self.other_employee = basic_models.Employee.objects.create(
+            sys_user=self.other_user,
+            merchant=self.merchant,
+            name="其它地址员工",
+            status=basic_models.EmployeeStatusEnum.ACTIVE,
+        )
+        self.foreign_user = User.objects.create_user(
+            username="addr-foreign-user", password="testpass123"
+        )
+        self.foreign_employee = basic_models.Employee.objects.create(
+            sys_user=self.foreign_user,
+            merchant=self.other_merchant,
+            name="外部地址员工",
+            status=basic_models.EmployeeStatusEnum.ACTIVE,
+        )
+
+        self.visible_customer = basic_models.Customer.objects.create(
+            merchant=self.merchant,
+            name="可见客户",
+            mobile="13800138000",
+            area="杭州",
+            created_by=self.employee,
+        )
+        self.invisible_customer = basic_models.Customer.objects.create(
+            merchant=self.merchant,
+            name="不可见客户",
+            mobile="13800138001",
+            area="绍兴",
+            created_by=self.other_employee,
+        )
+        self.foreign_customer = basic_models.Customer.objects.create(
+            merchant=self.other_merchant,
+            name="外部客户",
+            mobile="13800138002",
+            area="苏州",
+            created_by=self.foreign_employee,
+        )
+
+        self.visible_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.merchant,
+            customer=self.visible_customer,
+            address="杭州市测试路1号",
+            contact_name="张三",
+            contact_phone="13800138000",
+            area="杭州",
+            coordinates="120.1,30.2",
+            is_default=True,
+            remark="一号仓",
+            extra={"source": "test"},
+            created_by=self.employee,
+        )
+        self.invisible_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.merchant,
+            customer=self.invisible_customer,
+            address="绍兴市测试路2号",
+            contact_name="李四",
+            contact_phone="13900139000",
+            area="绍兴",
+            created_by=self.other_employee,
+        )
+        self.foreign_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.other_merchant,
+            customer=self.foreign_customer,
+            address="苏州市测试路3号",
+            contact_name="王五",
+            contact_phone="13700137000",
+            area="苏州",
+            created_by=self.foreign_employee,
+        )
+
+        self.client.force_authenticate(user=self.user)
+
+    def test_list_only_visible_customer_addresses(self):
+        resp = self.client.get("/api/v1/customer-addresses/")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        ids = {item["id"] for item in resp.json()["results"]}
+        self.assertIn(self.visible_address.id, ids)
+        self.assertNotIn(self.invisible_address.id, ids)
+        self.assertNotIn(self.foreign_address.id, ids)
+
+    def test_visible_employees_can_see_customer_address(self):
+        self.invisible_customer.visible_employees.add(self.employee)
+
+        resp = self.client.get("/api/v1/customer-addresses/")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        ids = {item["id"] for item in resp.json()["results"]}
+        self.assertIn(self.invisible_address.id, ids)
+
+    def test_view_all_customers_permission_sees_same_merchant_addresses(self):
+        permission = Permission.objects.get(codename="view_all_customers")
+        self.user.user_permissions.add(permission)
+
+        resp = self.client.get("/api/v1/customer-addresses/")
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        ids = {item["id"] for item in resp.json()["results"]}
+        self.assertIn(self.visible_address.id, ids)
+        self.assertIn(self.invisible_address.id, ids)
+        self.assertNotIn(self.foreign_address.id, ids)
+
+    def test_create_address_for_visible_customer_sets_merchant_and_creator(self):
+        payload = {
+            "customer": self.visible_customer.id,
+            "address": "杭州市新增地址",
+            "contact_name": "赵六",
+            "contact_phone": "13600136000",
+            "area": "杭州",
+            "coordinates": "120.2,30.3",
+            "is_default": False,
+            "remark": "新增备注",
+            "extra": {"tag": "new"},
+        }
+
+        resp = self.client.post("/api/v1/customer-addresses/", payload, format="json")
+
+        self.assertEqual(resp.status_code, status.HTTP_201_CREATED)
+        data = resp.json()
+        self.assertEqual(data["merchant"], self.merchant.id)
+        self.assertEqual(data["created_by"], self.employee.id)
+        self.assertEqual(data["coordinates"], "120.2,30.3")
+        self.assertEqual(data["extra"], {"tag": "new"})
+
+    def test_create_address_for_invisible_customer_is_rejected(self):
+        payload = {
+            "customer": self.invisible_customer.id,
+            "address": "不可见客户地址",
+        }
+
+        resp = self.client.post("/api/v1/customer-addresses/", payload, format="json")
+
+        self.assertEqual(resp.status_code, status.HTTP_400_BAD_REQUEST)
+
+    def test_default_address_is_unique_per_customer(self):
+        old_default = self.visible_address
+
+        resp = self.client.post(
+            "/api/v1/customer-addresses/",
+            {
+                "customer": self.visible_customer.id,
+                "address": "新的默认地址",
+                "is_default": True,
+            },
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_201_CREATED)
+        old_default.refresh_from_db()
+        self.assertFalse(old_default.is_default)
+        self.assertTrue(
+            basic_models.CustomerAddress.objects.get(id=resp.json()["id"]).is_default
+        )
+
+    def test_set_default_address_endpoint_unsets_other_default_addresses(self):
+        new_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.merchant,
+            customer=self.visible_customer,
+            address="待设默认地址",
+            created_by=self.employee,
+        )
+
+        resp = self.client.post(
+            f"/api/v1/customer-address/{new_address.id}/set-default/"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.visible_address.refresh_from_db()
+        new_address.refresh_from_db()
+        self.assertFalse(self.visible_address.is_default)
+        self.assertTrue(new_address.is_default)
+        self.assertTrue(resp.json()["is_default"])
+
+    def test_delete_soft_deletes_address_and_query_deleted_records(self):
+        resp = self.client.delete(f"/api/v1/customer-addresses/{self.visible_address.id}/")
+
+        self.assertEqual(resp.status_code, status.HTTP_204_NO_CONTENT)
+        self.visible_address.refresh_from_db()
+        self.assertIsNotNone(self.visible_address.deleted_at)
+        self.assertEqual(self.visible_address.deleted_by, self.employee)
+        self.assertFalse(self.visible_address.is_default)
+
+        default_resp = self.client.get("/api/v1/customer-addresses/")
+        default_ids = {item["id"] for item in default_resp.json()["results"]}
+        self.assertNotIn(self.visible_address.id, default_ids)
+
+        include_resp = self.client.get("/api/v1/customer-addresses/?include_deleted=true")
+        include_ids = {item["id"] for item in include_resp.json()["results"]}
+        self.assertIn(self.visible_address.id, include_ids)
+
+        only_resp = self.client.get("/api/v1/customer-addresses/?only_deleted=true")
+        only_ids = {item["id"] for item in only_resp.json()["results"]}
+        self.assertEqual(only_ids, {self.visible_address.id})
+
+    def test_filters(self):
+        query = (
+            f"/api/v1/customer-addresses/?customer={self.visible_customer.id}"
+            "&customer_name=可见&address=测试路&contact_name=张"
+            "&contact_phone=138&area=杭州&is_default=true&search=一号仓"
+        )
+        resp = self.client.get(query)
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(data["results"][0]["id"], self.visible_address.id)
+
+    def test_retrieve_invisible_address_returns_404(self):
+        resp = self.client.get(f"/api/v1/customer-addresses/{self.invisible_address.id}/")
+
+        self.assertEqual(resp.status_code, status.HTTP_404_NOT_FOUND)

api_v1/test_external_printing_records_sync.py

@@ -164,6 +164,7 @@ class ExternalPrintingRecordsSyncTaskTest(TestCase):
         self.assertEqual(job.printing_order.position, r'\\fw\\2026年-LWQ15\\2026\\H鸿烨\\Tj1712#')
         self.assertEqual(job.printing_order.fabric, '120克本白四面弹单定')
         self.assertEqual(job.printing_order.area, '周边')
+        self.assertEqual(job.printing_order.kd_riqi.isoformat(), '2026-01-26T20:00:52+00:00')
 
     @patch('api_v1.tasks._advance_external_printing_cursor')
     @patch('api_v1.tasks._fetch_external_product_image')

api_v1/urls.py

@@ -32,14 +32,18 @@ from .views.products import ProductQuickViewSet
 from .views.parameters import StateParameterViewSet
 from .views.users import CreateUserWithProfileView
 from .views.mingdaoyun import MDYPlateOrderStagingViewSet
+from .views.basic_info import CustomerAddressViewSet
 from .views.shipment import (
     SalesItemDetailView,
     SalesItemRebuildView,
+    SalesItemByCustomerGroupView,
     SalesItemByCustomerView,
+    SalesItemByPrintingOrderGroupView,
     SalesItemByPrintingOrderView,
     SalesItemCreateView,
     ShipmentStatusUpdateView,
     ShipmentDeliveryBindShipmentsView,
+    ShipmentDeliveryByPrintingOrderView,
     ShipmentDeliveryCancelView,
     ShipmentDeliveryDetailView,
     ShipmentDeliveryListCreateView,
@@ -69,6 +73,9 @@ main_router.register(r"plate-orders", PlateOrderViewSet, basename="plate-order")
 main_router.register(r"upload", UploadFileViewSet, basename="upload")
 main_router.register(r"products/quick", ProductQuickViewSet, basename="product-quick")
 main_router.register(r"parameters", StateParameterViewSet, basename="parameter")
+main_router.register(
+    r"customer-addresses", CustomerAddressViewSet, basename="customer-address"
+)
 main_router.register(
     r"mdy-plate-order-staging",
     MDYPlateOrderStagingViewSet,
@@ -76,6 +83,11 @@ main_router.register(
 )
 
 urlpatterns = [
+    path(
+        "customer-address/<int:pk>/set-default/",
+        CustomerAddressViewSet.as_view({"post": "set_default"}),
+        name="customer_address_set_default",
+    ),
     # 库存变动相关API
     path(
         "stock-snapshots/", StockSnapshotListView.as_view(), name="list_stock_snapshots"
@@ -355,6 +367,11 @@ urlpatterns = [
         ShipmentDeliveryListCreateView.as_view(),
         name="shipment_delivery_list_create",
     ),
+    path(
+        "shipment/deliveries/by-printing-order/<str:printing_order_id>/",
+        ShipmentDeliveryByPrintingOrderView.as_view(),
+        name="shipment_deliveries_by_printing_order",
+    ),
     path(
         "shipment/deliveries/<int:pk>/",
         ShipmentDeliveryDetailView.as_view(),
@@ -380,11 +397,21 @@ urlpatterns = [
         ShipmentSalesItemCustomerListView.as_view(),
         name="sales_item_customers",
     ),
+    path(
+        "shipment/sales-items/by-customer/<int:customer_id>/group/",
+        SalesItemByCustomerGroupView.as_view(),
+        name="sales_items_by_customer_group",
+    ),
     path(
         "shipment/sales-items/by-customer/<int:customer_id>/",
         SalesItemByCustomerView.as_view(),
         name="sales_items_by_customer",
     ),
+    path(
+        "shipment/sales-items/by-printing-order/<str:printing_order_id>/group/",
+        SalesItemByPrintingOrderGroupView.as_view(),
+        name="sales_items_by_printing_order_group",
+    ),
     path(
         "shipment/sales-items/by-printing-order/<str:printing_order_id>/",
         SalesItemByPrintingOrderView.as_view(),

api_v1/views/basic_info.py

@@ -0,0 +1,247 @@
+from django.db import transaction
+from django.db.models import Q
+from django.utils import timezone
+from rest_framework import serializers
+from rest_framework.exceptions import PermissionDenied, ValidationError
+from rest_framework import filters
+from rest_framework.response import Response
+
+from flower.viewsets import LimitedModelViewSet
+from basic_info import models as basic_models
+from basic_info.services import CustomerVisibilityService
+
+
+def _parse_bool(value: str | None) -> bool | None:
+    if value is None:
+        return None
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y"}:
+        return True
+    if normalized in {"0", "false", "no", "n"}:
+        return False
+    return None
+
+
+class CustomerAddressSerializer(serializers.ModelSerializer):
+    merchant_name = serializers.CharField(source="merchant.name", read_only=True)
+    customer_name = serializers.CharField(source="customer.name", read_only=True)
+    created_by_name = serializers.CharField(source="created_by.name", read_only=True, allow_null=True)
+    deleted_by_name = serializers.CharField(source="deleted_by.name", read_only=True, allow_null=True)
+
+    class Meta:
+        model = basic_models.CustomerAddress
+        fields = [
+            "id",
+            "merchant",
+            "merchant_name",
+            "customer",
+            "customer_name",
+            "address",
+            "contact_name",
+            "contact_phone",
+            "area",
+            "coordinates",
+            "is_default",
+            "remark",
+            "extra",
+            "created_by",
+            "created_by_name",
+            "deleted_at",
+            "deleted_by",
+            "deleted_by_name",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = [
+            "id",
+            "merchant",
+            "merchant_name",
+            "customer_name",
+            "created_by",
+            "created_by_name",
+            "deleted_at",
+            "deleted_by",
+            "deleted_by_name",
+            "created_at",
+            "updated_at",
+        ]
+
+    def validate_customer(self, customer):
+        request = self.context["request"]
+        view = self.context["view"]
+
+        if self.instance is not None and customer.id != self.instance.customer_id:
+            raise serializers.ValidationError("不允许修改客户")
+
+        if not view.can_access_customer(customer, request.user):
+            raise serializers.ValidationError("客户不存在或不可见")
+        return customer
+
+
+class CustomerAddressViewSet(LimitedModelViewSet):
+    """
+    客户地址 CRUD。
+
+    查询参数:
+    - customer: 客户ID
+    - customer_name: 客户名称模糊查询
+    - address: 地址模糊查询
+    - contact_name: 联系人模糊查询
+    - contact_phone: 联系电话模糊查询
+    - area: 地区模糊查询
+    - is_default: 是否默认地址 true/false
+    - include_deleted: 是否包含软删除记录 true/false
+    - only_deleted: 是否仅查询软删除记录 true/false
+    - search: 客户名/地址/联系人/电话/地区/备注模糊搜索
+    - ordering: id/-id/created_at/-created_at/updated_at/-updated_at/is_default/-is_default
+    """
+
+    queryset = basic_models.CustomerAddress.objects.all()
+    serializer_class = CustomerAddressSerializer
+    filter_backends = [filters.OrderingFilter]
+    ordering_fields = ["id", "created_at", "updated_at", "is_default"]
+    ordering = ["-is_default", "-created_at", "-id"]
+
+    def get_employee(self):
+        return getattr(self.request.user, "employee", None)
+
+    def can_view_all_customers(self, user) -> bool:
+        return user.is_superuser or user.has_perm("basic_info.view_all_customers")
+
+    def can_access_customer(self, customer, user) -> bool:
+        if user.is_superuser:
+            return True
+
+        emp = getattr(user, "employee", None)
+        if emp is None or emp.merchant_id != customer.merchant_id:
+            return False
+
+        if user.has_perm("basic_info.view_all_customers"):
+            return True
+
+        return CustomerVisibilityService.is_customer_visible_to_employee(customer, user)
+
+    def get_queryset(self):
+        queryset = (
+            super()
+            .get_queryset()
+            .select_related("merchant", "customer", "created_by", "deleted_by")
+        )
+        user = self.request.user
+
+        if not user.is_superuser:
+            emp = self.get_employee()
+            if emp is None or emp.merchant_id is None:
+                return queryset.none()
+
+            queryset = queryset.filter(merchant=emp.merchant)
+            if not user.has_perm("basic_info.view_all_customers"):
+                customer_queryset = CustomerVisibilityService.filter_customers_for_employee(
+                    basic_models.Customer.objects.filter(merchant=emp.merchant),
+                    user,
+                )
+                queryset = queryset.filter(customer__in=customer_queryset)
+
+        only_deleted = _parse_bool(self.request.query_params.get("only_deleted"))
+        include_deleted = _parse_bool(self.request.query_params.get("include_deleted"))
+        if only_deleted:
+            queryset = queryset.filter(deleted_at__isnull=False)
+        elif not include_deleted:
+            queryset = queryset.filter(deleted_at__isnull=True)
+
+        customer = self.request.query_params.get("customer")
+        if customer:
+            if not customer.strip().isdigit():
+                return queryset.none()
+            queryset = queryset.filter(customer_id=customer)
+
+        customer_name = (self.request.query_params.get("customer_name") or "").strip()
+        if customer_name:
+            queryset = queryset.filter(customer__name__icontains=customer_name)
+
+        address = (self.request.query_params.get("address") or "").strip()
+        if address:
+            queryset = queryset.filter(address__icontains=address)
+
+        contact_name = (self.request.query_params.get("contact_name") or "").strip()
+        if contact_name:
+            queryset = queryset.filter(contact_name__icontains=contact_name)
+
+        contact_phone = (self.request.query_params.get("contact_phone") or "").strip()
+        if contact_phone:
+            queryset = queryset.filter(contact_phone__icontains=contact_phone)
+
+        area = (self.request.query_params.get("area") or "").strip()
+        if area:
+            queryset = queryset.filter(area__icontains=area)
+
+        is_default = _parse_bool(self.request.query_params.get("is_default"))
+        if is_default is not None:
+            queryset = queryset.filter(is_default=is_default)
+
+        search = (self.request.query_params.get("search") or "").strip()
+        if search:
+            queryset = queryset.filter(
+                Q(customer__name__icontains=search)
+                | Q(address__icontains=search)
+                | Q(contact_name__icontains=search)
+                | Q(contact_phone__icontains=search)
+                | Q(area__icontains=search)
+                | Q(remark__icontains=search)
+            )
+
+        return queryset.distinct()
+
+    def _unset_other_default_addresses(self, address: basic_models.CustomerAddress):
+        if not address.is_default or address.deleted_at is not None:
+            return
+        basic_models.CustomerAddress.objects.filter(
+            merchant=address.merchant,
+            customer=address.customer,
+            deleted_at__isnull=True,
+            is_default=True,
+        ).exclude(id=address.id).update(is_default=False)
+
+    @transaction.atomic
+    def perform_create(self, serializer):
+        customer = serializer.validated_data["customer"]
+        emp = self.get_employee()
+        if not self.request.user.is_superuser and emp is None:
+            raise PermissionDenied("当前用户未绑定员工")
+
+        address = serializer.save(
+            merchant=customer.merchant,
+            created_by=emp,
+        )
+        self._unset_other_default_addresses(address)
+
+    @transaction.atomic
+    def perform_update(self, serializer):
+        address = serializer.save()
+        self._unset_other_default_addresses(address)
+
+    @transaction.atomic
+    def perform_destroy(self, instance):
+        if instance.deleted_at is not None:
+            return
+
+        emp = self.get_employee()
+        if not self.request.user.is_superuser and emp is None:
+            raise PermissionDenied("当前用户未绑定员工")
+
+        instance.deleted_at = timezone.now()
+        instance.deleted_by = emp
+        instance.is_default = False
+        instance.save(update_fields=["deleted_at", "deleted_by", "is_default", "updated_at"])
+
+    @transaction.atomic
+    def set_default(self, request, pk: int):
+        address = self.get_object()
+        if address.deleted_at is not None:
+            raise ValidationError("已删除的客户地址不能设为默认地址")
+
+        address.is_default = True
+        address.save(update_fields=["is_default", "updated_at"])
+        self._unset_other_default_addresses(address)
+        serializer = self.get_serializer(address)
+        return Response(serializer.data)

api_v1/views/printing/serializers.py

@@ -33,6 +33,30 @@ def _build_absolute_media_url(url: str | None, request):
     return build_public_media_url(url, request=request)
 
 
+def _resolve_printing_order_external_first_record_field(obj, field_name):
+    if not getattr(obj, 'external_order_id', None):
+        return None
+    try:
+        raw = obj.external_raw or {}
+        first_record = raw.get('first_record') or {}
+        value = first_record.get(field_name)
+    except AttributeError:
+        return None
+    value = str(value or '').strip()
+    return value or None
+
+
+def resolve_printing_order_bianhao_kd(obj):
+    return _resolve_printing_order_external_first_record_field(obj, 'BianHaoKD')
+
+
+def resolve_printing_order_kd_riqi(obj):
+    value = getattr(obj, 'kd_riqi', None)
+    if value is not None:
+        return serializers.DateTimeField().to_representation(value)
+    return _resolve_printing_order_external_first_record_field(obj, 'KdRiQi')
+
+
 def _serialize_plate_images(raw_value, request):
     if not raw_value:
         return []
@@ -163,6 +187,8 @@ class PrintingOrderListSerializer(serializers.ModelSerializer):
     external_customer_id = serializers.CharField(read_only=True)
     external_customer_name = serializers.CharField(read_only=True)
     external_employee_name = serializers.CharField(read_only=True)
+    bianhao_kd = serializers.SerializerMethodField()
+    kd_riqi = serializers.SerializerMethodField()
     
     class Meta:
         model = models.PrintingOrder
@@ -172,7 +198,7 @@ class PrintingOrderListSerializer(serializers.ModelSerializer):
             'is_fabric_received', 'outgoing_date', 'is_invalid', 'new_curve',
             'process', 'process_name', 'progress', 'position', 'print_count',
             'jobs_status_summary', 'jobs_last_status_summary',
-            'external_order_id', 'external_customer_id', 'external_customer_name', 'external_employee_name',
+            'external_order_id', 'bianhao_kd', 'kd_riqi', 'external_customer_id', 'external_customer_name', 'external_employee_name',
             'created_by', 'created_by_name',
             'created_at', 'updated_at',
         ]
@@ -260,6 +286,12 @@ class PrintingOrderListSerializer(serializers.ModelSerializer):
         emp = getattr(user, 'employee', None)
         return getattr(emp, 'name', None)
 
+    def get_bianhao_kd(self, obj):
+        return resolve_printing_order_bianhao_kd(obj)
+
+    def get_kd_riqi(self, obj):
+        return resolve_printing_order_kd_riqi(obj)
+
 
 class PrintingOrderDetailSerializer(serializers.ModelSerializer):
     """印染订单详情序列化器"""
@@ -274,6 +306,8 @@ class PrintingOrderDetailSerializer(serializers.ModelSerializer):
     external_customer_id = serializers.CharField(read_only=True)
     external_customer_name = serializers.CharField(read_only=True)
     external_employee_name = serializers.CharField(read_only=True)
+    bianhao_kd = serializers.SerializerMethodField()
+    kd_riqi = serializers.SerializerMethodField()
     
     class Meta:
         model = models.PrintingOrder
@@ -283,7 +317,7 @@ class PrintingOrderDetailSerializer(serializers.ModelSerializer):
             'is_fabric_received', 'craft', 'description', 'outgoing_date',
             'curve', 'new_curve', 'position', 'created_by_name',
             'printing_warn', 'rolling_warn', 'production_warn',
-            'external_order_id', 'external_customer_id', 'external_customer_name', 'external_employee_name',
+            'external_order_id', 'bianhao_kd', 'kd_riqi', 'external_customer_id', 'external_customer_name', 'external_employee_name',
             'is_invalid', 'process', 'process_name', 'progress', 'print_count',
             'created_at', 'updated_at'
         ]
@@ -297,6 +331,12 @@ class PrintingOrderDetailSerializer(serializers.ModelSerializer):
         emp = getattr(user, 'employee', None)
         return getattr(emp, 'name', None)
 
+    def get_bianhao_kd(self, obj):
+        return resolve_printing_order_bianhao_kd(obj)
+
+    def get_kd_riqi(self, obj):
+        return resolve_printing_order_kd_riqi(obj)
+
 
 class PrintingOrderCreateUpdateSerializer(serializers.ModelSerializer):
     """印染订单创建/更新序列化器"""

api_v1/views/printing/test_api.py

@@ -1,7 +1,7 @@
 """
 PrintingOrder API 测试
 """
-from datetime import datetime
+from datetime import datetime, timezone as dt_timezone
 from django.test import TestCase
 from django.db import connection
 from django.conf import settings
@@ -260,6 +260,12 @@ class PrintingOrderAPITestCase(TestCase):
             external_customer_id='KH00991',
             external_customer_name='李泽柔',
             external_employee_name='丽容',
+            external_raw={
+                'first_record': {
+                    'BianHaoKD': '7.07',
+                    'KdRiQi': '2026-07-06T21:48:58Z',
+                }
+            },
         )
         printing_models.PrintingOrder.objects.create(
             merchant=self.merchant,
@@ -277,11 +283,65 @@ class PrintingOrderAPITestCase(TestCase):
         self.assertEqual(item['external_customer_id'], 'KH00991')
         self.assertEqual(item['external_customer_name'], '李泽柔')
         self.assertEqual(item['external_employee_name'], '丽容')
+        self.assertEqual(item['bianhao_kd'], '7.07')
+        self.assertEqual(item['kd_riqi'], '2026-07-06T21:48:58Z')
 
         detail = self.client.get(f'/api/v1/printing-orders/{order1.id}/')
         self.assertEqual(detail.status_code, status.HTTP_200_OK)
         self.assertEqual(detail.data['external_order_id'], 'KD20410611')
         self.assertEqual(detail.data['external_customer_id'], 'KH00991')
+        self.assertEqual(detail.data['bianhao_kd'], '7.07')
+        self.assertEqual(detail.data['kd_riqi'], '2026-07-06T21:48:58Z')
+
+    def test_bianhao_kd_returns_null_without_external_order_id(self):
+        order = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric='普通订单',
+            width='150cm',
+            external_raw={'first_record': {'BianHaoKD': '7.07'}},
+        )
+
+        response = self.client.get(f'/api/v1/printing-orders/{order.id}/')
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertIsNone(response.data['bianhao_kd'])
+        self.assertIsNone(response.data['kd_riqi'])
+
+    def test_filter_and_order_by_kd_riqi(self):
+        older = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric='旧开单时间',
+            width='150cm',
+            external_order_id='KD-OLDER',
+            kd_riqi=datetime(2026, 7, 1, 10, 0, tzinfo=dt_timezone.utc),
+        )
+        newer = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric='新开单时间',
+            width='150cm',
+            external_order_id='KD-NEWER',
+            kd_riqi=datetime(2026, 7, 2, 10, 0, tzinfo=dt_timezone.utc),
+        )
+        printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric='范围外开单时间',
+            width='150cm',
+            external_order_id='KD-OUTSIDE',
+            kd_riqi=datetime(2026, 7, 3, 10, 0, tzinfo=dt_timezone.utc),
+        )
+
+        response = self.client.get(
+            '/api/v1/printing-orders/?kd_riqi_from=2026-07-01&kd_riqi_to=2026-07-02&ordering=kd_riqi'
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        result_ids = [item['id'] for item in response.data['results']]
+        self.assertEqual(result_ids, [older.id, newer.id])
+        self.assertEqual(response.data['results'][0]['kd_riqi'], '2026-07-01T18:00:00+08:00')
     
     def test_retrieve_printing_order(self):
         """测试获取订单详情"""

api_v1/views/printing/views.py

@@ -90,6 +90,8 @@ class PrintingOrderFilterSet(django_filters.FilterSet):
     area = django_filters.CharFilter(lookup_expr="icontains")
     outgoing_date_from = django_filters.CharFilter(method="filter_outgoing_date_from")
     outgoing_date_to = django_filters.CharFilter(method="filter_outgoing_date_to")
+    kd_riqi_from = django_filters.CharFilter(method="filter_kd_riqi_from")
+    kd_riqi_to = django_filters.CharFilter(method="filter_kd_riqi_to")
     created_date_from = django_filters.DateFilter(
         field_name="created_at", lookup_expr="gte"
     )
@@ -196,6 +198,21 @@ class PrintingOrderFilterSet(django_filters.FilterSet):
         # 日期时间：按“<=”包含到秒
         return queryset.filter(outgoing_date__lte=dt)
 
+    def filter_kd_riqi_from(self, queryset, name, value):
+        dt, _has_time = self._parse_date_or_datetime(value)
+        if dt is None:
+            raise ValidationError("kd_riqi_from 必须是日期或日期时间")
+        return queryset.filter(kd_riqi__gte=dt)
+
+    def filter_kd_riqi_to(self, queryset, name, value):
+        dt, has_time = self._parse_date_or_datetime(value)
+        if dt is None:
+            raise ValidationError("kd_riqi_to 必须是日期或日期时间")
+
+        if not has_time:
+            return queryset.filter(kd_riqi__lt=dt + timedelta(days=1))
+        return queryset.filter(kd_riqi__lte=dt)
+
     def filter_created_date_to(self, queryset, name, value):
         """
         过滤 created_at <= 指定日期的 23:59:59.999999
@@ -234,6 +251,8 @@ class PrintingOrderViewSet(CustomerVisibilityFilterMixin, LimitedModelViewSet):
     - area: 地区（模糊查询）
     - outgoing_date_from: 出货日期起始
     - outgoing_date_to: 出货日期结束
+    - kd_riqi_from: 外部开单日期时间起始
+    - kd_riqi_to: 外部开单日期时间结束
     - created_date_from: 创建日期起始
     - created_date_to: 创建日期结束
     - search: 全文搜索（客户名称、面料、地区、工艺）
@@ -266,6 +285,7 @@ class PrintingOrderViewSet(CustomerVisibilityFilterMixin, LimitedModelViewSet):
         "created_at",
         "updated_at",
         "outgoing_date",
+        "kd_riqi",
         "is_urgent",
         "is_fabric_received",
         "is_invalid",

api_v1/views/shipment/__init__.py

@@ -6,11 +6,14 @@ Shipment API 模块
 from .views import (
     SalesItemDetailView,
     SalesItemRebuildView,
+    SalesItemByCustomerGroupView,
     SalesItemByCustomerView,
+    SalesItemByPrintingOrderGroupView,
     SalesItemByPrintingOrderView,
     SalesItemCreateView,
     ShipmentStatusUpdateView,
     ShipmentDeliveryBindShipmentsView,
+    ShipmentDeliveryByPrintingOrderView,
     ShipmentDeliveryDetailView,
     ShipmentDeliveryListCreateView,
     ShipmentDeliveryCancelView,
@@ -24,11 +27,14 @@ from .views import (
 __all__ = [
     'SalesItemDetailView',
     'SalesItemRebuildView',
+    'SalesItemByCustomerGroupView',
     'SalesItemByCustomerView',
+    'SalesItemByPrintingOrderGroupView',
     'SalesItemByPrintingOrderView',
     'SalesItemCreateView',
     'ShipmentStatusUpdateView',
     'ShipmentDeliveryBindShipmentsView',
+    'ShipmentDeliveryByPrintingOrderView',
     'ShipmentDeliveryDetailView',
     'ShipmentDeliveryListCreateView',
     'ShipmentDeliveryCancelView',

api_v1/views/shipment/serializers.py

@@ -111,6 +111,9 @@ class ShipmentSerializer(serializers.ModelSerializer):
     """
 
     customer_name = serializers.CharField(source="customer.name", read_only=True)
+    address_id = serializers.IntegerField(
+        source="customer_address.id", read_only=True, allow_null=True
+    )
     created_by_id = serializers.IntegerField(
         source="created_by.id", read_only=True, allow_null=True
     )
@@ -142,6 +145,7 @@ class ShipmentSerializer(serializers.ModelSerializer):
             "merchant_name",
             "customer",
             "customer_name",
+            "address_id",
             "fabric",
             "order_description",
             "shipment_date",
@@ -149,11 +153,13 @@ class ShipmentSerializer(serializers.ModelSerializer):
             "contact_name",
             "contact_phone",
             "area",
+            "coordinates",
             "remark",
             "status",
             "status_display",
             "external_id",
             "geo_coordinates",
+            "extra",
             "delivery_id",
             "status_modified_at",
             "cancelled_by_id",
@@ -277,6 +283,12 @@ class ShipmentCreateNormalSerializer(serializers.Serializer):
         allow_blank=True,
         help_text="地址（可选）",
     )
+    address_id = serializers.IntegerField(
+        required=False,
+        allow_null=True,
+        min_value=1,
+        help_text="客户地址ID（可选）",
+    )
     contact_name = serializers.CharField(
         max_length=100,
         required=False,
@@ -292,15 +304,35 @@ class ShipmentCreateNormalSerializer(serializers.Serializer):
         help_text="联系电话（可选）",
     )
     area = serializers.CharField(
-        max_length=30,
+        max_length=100,
         required=False,
         default="",
         allow_blank=True,
         help_text="出货地区（可选）",
     )
+    coordinates = serializers.CharField(
+        max_length=100,
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        default=None,
+        help_text="经纬度字符串（可选）",
+    )
+    extra = serializers.JSONField(
+        required=False,
+        allow_null=True,
+        default=None,
+        help_text="扩展信息（可选）",
+    )
     remark = serializers.CharField(
         required=False, default="", allow_blank=True, help_text="备注"
     )
+    status = serializers.ChoiceField(
+        choices=ShipmentStatus.choices,
+        required=False,
+        default=ShipmentStatus.DRAFT,
+        help_text="出货单状态（可选，默认 1=草稿）",
+    )
     sales_items = serializers.ListField(
         child=serializers.IntegerField(),
         required=False,
@@ -357,12 +389,26 @@ class ShipmentCreateExternalSerializer(serializers.Serializer):
         help_text="联系电话（可选）",
     )
     area = serializers.CharField(
-        max_length=30,
+        max_length=100,
         required=False,
         default="",
         allow_blank=True,
         help_text="出货地区（可选）",
     )
+    coordinates = serializers.CharField(
+        max_length=100,
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        default=None,
+        help_text="经纬度字符串（可选）",
+    )
+    extra = serializers.JSONField(
+        required=False,
+        allow_null=True,
+        default=None,
+        help_text="扩展信息（可选）",
+    )
     remark = serializers.CharField(
         required=False, default="", allow_blank=True, help_text="备注"
     )
@@ -404,7 +450,19 @@ class ShipmentUpdateSerializer(serializers.Serializer):
         max_length=50, required=False, allow_blank=True, help_text="联系电话（可选）"
     )
     area = serializers.CharField(
-        max_length=30, required=False, allow_blank=True, help_text="出货地区（可选）"
+        max_length=100, required=False, allow_blank=True, help_text="出货地区（可选）"
+    )
+    coordinates = serializers.CharField(
+        max_length=100,
+        required=False,
+        allow_blank=True,
+        allow_null=True,
+        help_text="经纬度字符串（可选）",
+    )
+    extra = serializers.JSONField(
+        required=False,
+        allow_null=True,
+        help_text="扩展信息（可选）",
     )
     remark = serializers.CharField(
         required=False, allow_blank=True, help_text="备注（可选）"
@@ -650,6 +708,74 @@ class ShipmentDeliverySerializer(serializers.ModelSerializer):
         ).data
 
 
+class ShipmentDeliveryByPrintingOrderSerializer(serializers.ModelSerializer):
+    """
+    按生产订单查询送货单的专用 DTO。
+
+    当前字段基本对齐送货单列表，后续可按该查询场景独立调整。
+    """
+
+    status_display = serializers.CharField(source="get_status_display", read_only=True)
+    merchant_id = serializers.IntegerField(source="merchant.id", read_only=True)
+    merchant_name = serializers.CharField(source="merchant.name", read_only=True)
+    created_by_id = serializers.IntegerField(
+        source="created_by.id", read_only=True, allow_null=True
+    )
+    created_by_name = serializers.SerializerMethodField()
+    operator_id = serializers.IntegerField(
+        source="operator.id", read_only=True, allow_null=True
+    )
+    operator_name = serializers.CharField(source="operator.name", read_only=True, allow_null=True)
+    shipments_count = serializers.SerializerMethodField()
+    shipments = serializers.SerializerMethodField()
+
+    class Meta:
+        model = ShipmentDelivery
+        fields = [
+            "id",
+            "merchant_id",
+            "merchant_name",
+            "driver_name",
+            "vehicle_trip",
+            "contact_phone",
+            "vehicle_capacity",
+            "remark",
+            "internal_remark",
+            "shipment_order_ids",
+            "status",
+            "status_display",
+            "started_at",
+            "delivered_at",
+            "cancelled_at",
+            "shipments_count",
+            "shipments",
+            "created_by_id",
+            "created_by_name",
+            "operator_id",
+            "operator_name",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = fields
+
+    def get_created_by_name(self, obj):
+        if obj.created_by:
+            employee = getattr(obj.created_by, "employee", None)
+            if employee:
+                return employee.name
+            return obj.created_by.username
+        return None
+
+    def get_shipments_count(self, obj):
+        return obj.shipments.count()
+
+    def get_shipments(self, obj):
+        return ShipmentDeliveryShipmentSummarySerializer(
+            obj.shipments.order_by("id"),
+            many=True,
+        ).data
+
+
 class ShipmentDeliveryCreateSerializer(serializers.Serializer):
     driver_name = serializers.CharField(max_length=100, help_text="司机名")
     vehicle_trip = serializers.CharField(max_length=100, help_text="车次")

api_v1/views/shipment/test_api.py

@@ -295,6 +295,81 @@ class SalesItemByPrintingOrderAPITestCase(TestCase):
         self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
         self.assertIn("匹配到多个生产订单", response.json()["detail"])
 
+    def test_get_sales_items_by_printing_order_group_groups_by_printing_job(self):
+        url = (
+            f"/api/v1/shipment/sales-items/by-printing-order/{self.printing_order.id}/"
+            "group/"
+        )
+        response = self.client.get(url)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        data = response.json()
+
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(len(data["results"]), 1)
+
+        group = data["results"][0]
+        self.assertEqual(group["printing_job_id"], self.printing_job1.id)
+        self.assertEqual(group["count"], 2)
+        self.assertEqual(
+            {item["id"] for item in group["items"]},
+            {self.sales_item1.id, self.sales_item2.id},
+        )
+
+    def test_get_sales_items_by_printing_order_group_supports_external_order_id(self):
+        response = self.client.get(
+            "/api/v1/shipment/sales-items/by-printing-order/EXT-PO-001/group/"
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        data = response.json()
+
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(data["results"][0]["printing_job_id"], self.printing_job1.id)
+
+    def test_get_sales_items_by_printing_order_group_paginates_printing_job_groups(self):
+        url = (
+            f"/api/v1/shipment/sales-items/by-printing-order/{self.printing_order.id}/"
+            "group/?include_already_has_shipment=true&limit=1&offset=1"
+        )
+        response = self.client.get(url)
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        data = response.json()
+
+        self.assertEqual(data["count"], 2)
+        self.assertEqual(len(data["results"]), 1)
+        self.assertEqual(data["results"][0]["printing_job_id"], self.printing_job2.id)
+        self.assertEqual(data["results"][0]["count"], 1)
+        self.assertEqual(data["results"][0]["items"][0]["id"], self.sales_item3.id)
+
+    def test_get_sales_items_by_printing_order_group_multiple_external_matches(self):
+        printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="测试面料3",
+            width="160cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-DUPLICATED-GROUP",
+        )
+        printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="测试面料4",
+            width="170cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-DUPLICATED-GROUP",
+        )
+
+        response = self.client.get(
+            "/api/v1/shipment/sales-items/by-printing-order/EXT-DUPLICATED-GROUP/group/"
+        )
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("匹配到多个生产订单", response.json()["detail"])
+
     def test_get_sales_items_printing_order_not_found(self):
         """测试生产订单不存在"""
         url = "/api/v1/shipment/sales-items/by-printing-order/99999/"
@@ -351,6 +426,252 @@ class SalesItemByPrintingOrderAPITestCase(TestCase):
         self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)
 
 
+class ShipmentDeliveryByPrintingOrderAPITestCase(TestCase):
+    """测试按生产订单查询送货单 API"""
+
+    def setUp(self):
+        self.client = APIClient()
+        self.merchant = basic_models.Merchant.objects.create(
+            name="送货查询商户", type=basic_models.MerchantTypeEnum.FACTORY
+        )
+        self.other_merchant = basic_models.Merchant.objects.create(
+            name="其它送货查询商户", type=basic_models.MerchantTypeEnum.FACTORY
+        )
+        self.user = User.objects.create_user(
+            username="delivery_by_order_user", password="testpass123"
+        )
+        self.employee = basic_models.Employee.objects.create(
+            sys_user=self.user,
+            merchant=self.merchant,
+            name="送货查询员工",
+            status=basic_models.EmployeeStatusEnum.ACTIVE,
+        )
+        self.customer = basic_models.Customer.objects.create(
+            merchant=self.merchant,
+            name="送货查询客户",
+            created_by=self.employee,
+        )
+        self.state = stateflow_models.State.objects.create(name="待送货查询")
+        self.process = stateflow_models.Process.objects.create(name="送货查询流程")
+        self.process.replace_nodes([self.state])
+        self.product = basic_models.Product.objects.create(
+            merchant=self.merchant,
+            category=basic_models.ProductCategory.objects.create(
+                merchant=self.merchant,
+                name="送货查询分类",
+            ),
+            name="送货查询产品",
+        )
+        self.printing_order = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="送货查询面料",
+            width="150cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-DELIVERY-001",
+        )
+        self.printing_job1 = printing_models.PrintingJob.objects.create(
+            merchant=self.merchant,
+            printing_order=self.printing_order,
+            product=self.product,
+            quantity=100,
+            unit="米",
+            created_by=self.user,
+        )
+        self.printing_job2 = printing_models.PrintingJob.objects.create(
+            merchant=self.merchant,
+            printing_order=self.printing_order,
+            product=self.product,
+            quantity=80,
+            unit="米",
+            created_by=self.user,
+        )
+        self.delivery1 = shipment_models.ShipmentDelivery.objects.create(
+            merchant=self.merchant,
+            driver_name="张司机",
+            vehicle_trip="KD-001",
+            contact_phone="13800138000",
+            vehicle_capacity="9.6米厢车",
+            remark="外部备注A",
+            internal_remark="内部备注A",
+            status=shipment_models.ShipmentDeliveryStatus.IN_TRANSIT,
+            started_at=timezone.datetime(2026, 7, 1, 9, 0, tzinfo=timezone.get_current_timezone()),
+            created_by=self.user,
+        )
+        self.delivery2 = shipment_models.ShipmentDelivery.objects.create(
+            merchant=self.merchant,
+            driver_name="李司机",
+            vehicle_trip="KD-002",
+            contact_phone="13900139000",
+            vehicle_capacity="13米高栏",
+            remark="外部备注B",
+            internal_remark="内部备注B",
+            status=shipment_models.ShipmentDeliveryStatus.DELIVERED,
+            delivered_at=timezone.datetime(2026, 7, 3, 18, 0, tzinfo=timezone.get_current_timezone()),
+            created_by=self.user,
+        )
+        self.shipment1 = shipment_models.Shipment.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            shipment_date="2026-07-01",
+            delivery=self.delivery1,
+            created_by=self.user,
+        )
+        self.shipment2 = shipment_models.Shipment.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            shipment_date="2026-07-03",
+            delivery=self.delivery2,
+            created_by=self.user,
+        )
+        self.sales_item1 = shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="送货销售品1",
+            quantity=Decimal("10.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=self.printing_job1.id,
+            shipment=self.shipment1,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+        self.sales_item2 = shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="送货销售品2",
+            quantity=Decimal("20.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=self.printing_job1.id,
+            shipment=self.shipment1,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+        self.sales_item3 = shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="送货销售品3",
+            quantity=Decimal("30.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=self.printing_job2.id,
+            shipment=self.shipment2,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+        other_order = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="其它面料",
+            width="160cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-OTHER-DELIVERY",
+        )
+        other_job = printing_models.PrintingJob.objects.create(
+            merchant=self.merchant,
+            printing_order=other_order,
+            product=self.product,
+            quantity=50,
+            unit="米",
+            created_by=self.user,
+        )
+        other_delivery = shipment_models.ShipmentDelivery.objects.create(
+            merchant=self.merchant,
+            driver_name="王司机",
+            vehicle_trip="KD-999",
+            created_by=self.user,
+        )
+        other_shipment = shipment_models.Shipment.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            shipment_date="2026-07-04",
+            delivery=other_delivery,
+            created_by=self.user,
+        )
+        shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="其它订单销售品",
+            quantity=Decimal("40.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=other_job.id,
+            shipment=other_shipment,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+        self.client.force_authenticate(user=self.user)
+
+    def test_list_deliveries_by_internal_printing_order_id(self):
+        resp = self.client.get(
+            f"/api/v1/shipment/deliveries/by-printing-order/{self.printing_order.id}/"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 2)
+        ids = {item["id"] for item in data["results"]}
+        self.assertEqual(ids, {self.delivery1.id, self.delivery2.id})
+
+    def test_list_deliveries_by_external_order_id(self):
+        resp = self.client.get(
+            "/api/v1/shipment/deliveries/by-printing-order/EXT-DELIVERY-001/"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 2)
+        self.assertEqual(data["results"][0]["driver_name"], "李司机")
+
+    def test_list_deliveries_filters_driver_status_and_time_ranges(self):
+        resp = self.client.get(
+            f"/api/v1/shipment/deliveries/by-printing-order/{self.printing_order.id}/"
+            "?status=2&driver_name=张&vehicle_trip=KD-001&contact_phone=138"
+            "&vehicle_capacity=9.6&remark=外部备注A&internal_remark=内部备注A"
+            "&started_at_from=2026-07-01&started_at_to=2026-07-01"
+            "&shipment_date_from=2026-07-01&shipment_date_to=2026-07-01"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(data["results"][0]["id"], self.delivery1.id)
+
+    def test_list_deliveries_supports_pagination_and_ordering(self):
+        resp = self.client.get(
+            f"/api/v1/shipment/deliveries/by-printing-order/{self.printing_order.id}/"
+            "?ordering=id&limit=1&offset=1"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 2)
+        self.assertEqual(len(data["results"]), 1)
+        self.assertEqual(data["results"][0]["id"], self.delivery2.id)
+
+    def test_list_deliveries_duplicate_external_order_id_returns_500(self):
+        printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="重复面料1",
+            width="150cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-DELIVERY-DUP",
+        )
+        printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="重复面料2",
+            width="150cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-DELIVERY-DUP",
+        )
+
+        resp = self.client.get(
+            "/api/v1/shipment/deliveries/by-printing-order/EXT-DELIVERY-DUP/"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_500_INTERNAL_SERVER_ERROR)
+        self.assertIn("匹配到多个生产订单", resp.json()["message"])
+
+
 class ShipmentSalesItemCustomersAPITestCase(TestCase):
     """测试由未出货销售品汇总客户 API"""
 
@@ -483,6 +804,39 @@ class ShipmentSalesItemCustomersAPITestCase(TestCase):
         self.assertEqual(len(data["results"]), 1)
         self.assertEqual(data["results"][0]["customer_id"], self.customer2.id)
 
+    def test_list_customers_with_unshipped_sales_items_filters_by_customer_name(self):
+        resp = self.client.get(
+            "/api/v1/shipment/sales-items/customers/?customer_name=客户A"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(data["results"][0]["customer_id"], self.customer1.id)
+        self.assertEqual(data["results"][0]["unshipped_sales_items_count"], 2)
+
+    def test_list_customers_with_unshipped_sales_items_filters_by_missing_customer_name(self):
+        resp = self.client.get(
+            "/api/v1/shipment/sales-items/customers/?customer_name=不存在"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+
+        self.assertEqual(data["count"], 0)
+        self.assertEqual(data["results"], [])
+
+    def test_list_customers_with_unshipped_sales_items_ignores_blank_customer_name(self):
+        resp = self.client.get(
+            "/api/v1/shipment/sales-items/customers/?customer_name=++"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+
+        self.assertEqual(data["count"], 2)
+
     def test_list_customers_with_unshipped_sales_items_unauthenticated(self):
         self.client.logout()
 
@@ -684,6 +1038,141 @@ class SalesItemByCustomerAPITestCase(TestCase):
         self.assertEqual(set(result_ids), {self.sales_item1.id, self.sales_item2.id})
         self.assertNotIn(other_sales_item.id, result_ids)
 
+    def test_get_sales_items_by_customer_group_groups_by_external_order_id_and_name(self):
+        duplicate_sales_item = shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="销售品1",
+            quantity=Decimal("11.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=self.printing_job.id,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+
+        resp = self.client.get(
+            f"/api/v1/shipment/sales-items/by-customer/{self.customer.id}/group/"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(len(data["results"]), 1)
+
+        external_group = data["results"][0]
+        self.assertEqual(external_group["external_order_id"], "EXT-CUST-001")
+        self.assertEqual(external_group["count"], 3)
+
+        by_name = {group["name"]: group for group in external_group["name_groups"]}
+        self.assertEqual(by_name["销售品1"]["count"], 2)
+        self.assertEqual(by_name["销售品2"]["count"], 1)
+        self.assertEqual(
+            {item["id"] for item in by_name["销售品1"]["items"]},
+            {self.sales_item1.id, duplicate_sales_item.id},
+        )
+
+    def test_get_sales_items_by_customer_group_paginates_external_order_id_groups_with_null_last(self):
+        other_printing_order = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="其它面料",
+            width="160cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-CUST-OTHER",
+        )
+        other_printing_job = printing_models.PrintingJob.objects.create(
+            merchant=self.merchant,
+            printing_order=other_printing_order,
+            product=self.product,
+            quantity=50,
+            unit="米",
+            created_by=self.user,
+        )
+        shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="其它外部订单销售品",
+            quantity=Decimal("66.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=other_printing_job.id,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+        shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="无外部订单销售品",
+            quantity=Decimal("77.00"),
+            unit=shipment_models.UnitChoices.METER,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+
+        first_page = self.client.get(
+            f"/api/v1/shipment/sales-items/by-customer/{self.customer.id}/group/"
+            "?limit=1&offset=0"
+        )
+        second_page = self.client.get(
+            f"/api/v1/shipment/sales-items/by-customer/{self.customer.id}/group/"
+            "?limit=1&offset=1"
+        )
+        third_page = self.client.get(
+            f"/api/v1/shipment/sales-items/by-customer/{self.customer.id}/group/"
+            "?limit=1&offset=2"
+        )
+
+        self.assertEqual(first_page.status_code, status.HTTP_200_OK)
+        self.assertEqual(second_page.status_code, status.HTTP_200_OK)
+        self.assertEqual(third_page.status_code, status.HTTP_200_OK)
+        self.assertEqual(first_page.json()["count"], 3)
+        self.assertEqual(
+            first_page.json()["results"][0]["external_order_id"], "EXT-CUST-001"
+        )
+        self.assertEqual(
+            second_page.json()["results"][0]["external_order_id"], "EXT-CUST-OTHER"
+        )
+        self.assertIsNone(third_page.json()["results"][0]["external_order_id"])
+
+    def test_get_sales_items_by_customer_group_supports_external_order_id_filter(self):
+        other_printing_order = printing_models.PrintingOrder.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            fabric="其它面料",
+            width="160cm",
+            process=self.process,
+            created_by=self.user,
+            external_order_id="EXT-CUST-OTHER",
+        )
+        other_printing_job = printing_models.PrintingJob.objects.create(
+            merchant=self.merchant,
+            printing_order=other_printing_order,
+            product=self.product,
+            quantity=50,
+            unit="米",
+            created_by=self.user,
+        )
+        other_sales_item = shipment_models.SalesItem.objects.create(
+            merchant=self.merchant,
+            name="其它外部订单销售品",
+            quantity=Decimal("66.00"),
+            unit=shipment_models.UnitChoices.METER,
+            printing_job_id=other_printing_job.id,
+            customer_id=self.customer.id,
+            created_by=self.user,
+        )
+
+        resp = self.client.get(
+            f"/api/v1/shipment/sales-items/by-customer/{self.customer.id}/group/"
+            "?external_order_id=EXT-CUST-OTHER"
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        data = resp.json()
+        self.assertEqual(data["count"], 1)
+        self.assertEqual(data["results"][0]["external_order_id"], "EXT-CUST-OTHER")
+        self.assertEqual(
+            data["results"][0]["name_groups"][0]["items"][0]["id"],
+            other_sales_item.id,
+        )
+
     def test_get_sales_items_by_customer_not_found(self):
         resp = self.client.get("/api/v1/shipment/sales-items/by-customer/99999/")
 
@@ -1283,7 +1772,9 @@ class ShipmentCreateAPITestCase(TestCase):
             "address": "杭州市测试路 1 号",
             "contact_name": "张三",
             "contact_phone": "13800138000",
-            "area": "华东",
+            "area": "华东" * 25,
+            "coordinates": "120.1551,30.2741",
+            "extra": {"source": "customer_address", "tags": ["snapshot"]},
             "remark": "测试备注",
             "sales_items": [self.sales_item1.id, self.sales_item2.id],
         }
@@ -1301,7 +1792,9 @@ class ShipmentCreateAPITestCase(TestCase):
         self.assertEqual(result["address"], "杭州市测试路 1 号")
         self.assertEqual(result["contact_name"], "张三")
         self.assertEqual(result["contact_phone"], "13800138000")
-        self.assertEqual(result.get("area", ""), "华东")
+        self.assertEqual(result.get("area", ""), "华东" * 25)
+        self.assertEqual(result["coordinates"], "120.1551,30.2741")
+        self.assertEqual(result["extra"], {"source": "customer_address", "tags": ["snapshot"]})
         self.assertEqual(result["remark"], "测试备注")
         self.assertEqual(result["status"], shipment_models.ShipmentStatus.DRAFT)
         self.assertEqual(result["status_display"], "草稿(未发布)")
@@ -1314,6 +1807,105 @@ class ShipmentCreateAPITestCase(TestCase):
         self.assertEqual(self.sales_item1.shipment_id, result["id"])
         self.assertEqual(self.sales_item2.shipment_id, result["id"])
 
+    def test_create_shipment_with_address_id_keeps_address_snapshot(self):
+        customer_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            address="客户地址表地址",
+            contact_name="地址联系人",
+            contact_phone="13900139000",
+            area="地址地区",
+            created_by=self.employee,
+        )
+        data = {
+            "customer": self.customer.id,
+            "address_id": customer_address.id,
+            "shipment_date": "2026-01-14",
+            "address": "出货单快照地址",
+            "contact_name": "快照联系人",
+            "contact_phone": "13800138000",
+            "area": "快照地区",
+            "coordinates": "121.0000,31.0000",
+            "extra": {"floor": "3F"},
+            "sales_items": [self.sales_item1.id, self.sales_item2.id],
+        }
+
+        response = self.client.post("/api/v1/shipment/shipments/", data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        result = response.json()
+        self.assertEqual(result["address_id"], customer_address.id)
+        self.assertEqual(result["address"], "出货单快照地址")
+        self.assertEqual(result["contact_name"], "快照联系人")
+        self.assertEqual(result["contact_phone"], "13800138000")
+        self.assertEqual(result["area"], "快照地区")
+        self.assertEqual(result["coordinates"], "121.0000,31.0000")
+        self.assertEqual(result["extra"], {"floor": "3F"})
+
+        shipment = shipment_models.Shipment.objects.get(id=result["id"])
+        self.assertEqual(shipment.customer_address_id, customer_address.id)
+        self.assertEqual(shipment.coordinates, "121.0000,31.0000")
+        self.assertEqual(shipment.extra, {"floor": "3F"})
+
+    def test_create_shipment_accepts_status(self):
+        data = {
+            "customer": self.customer.id,
+            "shipment_date": "2026-01-14",
+            "status": shipment_models.ShipmentStatus.APPROVED,
+        }
+
+        response = self.client.post("/api/v1/shipment/shipments/", data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        result = response.json()
+        self.assertEqual(result["status"], shipment_models.ShipmentStatus.APPROVED)
+        self.assertEqual(result["status_display"], "已审核")
+
+        shipment = shipment_models.Shipment.objects.get(id=result["id"])
+        self.assertEqual(shipment.status, shipment_models.ShipmentStatus.APPROVED)
+
+    def test_create_shipment_rejects_mismatched_address_id(self):
+        other_customer = basic_models.Customer.objects.create(
+            merchant=self.merchant,
+            name="其它客户",
+        )
+        customer_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.merchant,
+            customer=other_customer,
+            address="其它客户地址",
+            created_by=self.employee,
+        )
+        data = {
+            "customer": self.customer.id,
+            "address_id": customer_address.id,
+            "shipment_date": "2026-01-14",
+        }
+
+        response = self.client.post("/api/v1/shipment/shipments/", data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("客户地址与客户不匹配", response.json()["detail"])
+
+    def test_create_shipment_rejects_deleted_address_id(self):
+        customer_address = basic_models.CustomerAddress.objects.create(
+            merchant=self.merchant,
+            customer=self.customer,
+            address="已删除客户地址",
+            deleted_at=timezone.now(),
+            deleted_by=self.employee,
+            created_by=self.employee,
+        )
+        data = {
+            "customer": self.customer.id,
+            "address_id": customer_address.id,
+            "shipment_date": "2026-01-14",
+        }
+
+        response = self.client.post("/api/v1/shipment/shipments/", data, format="json")
+
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn("已删除", response.json()["detail"])
+
     @override_settings(TESTING=False, SHIPMENT_CREATED_WECOM_NOTIFY_ENABLED=True)
     def test_create_shipment_enqueues_wecom_notification_task(self):
         """测试创建出货单后投递企业微信通知任务"""
@@ -1387,8 +1979,8 @@ class ShipmentCreateAPITestCase(TestCase):
         self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
         self.assertIn("已关联", response.json()["detail"])
 
-    def test_create_shipment_rejects_sales_items_from_different_printing_orders(self):
-        """测试销售品来自不同生产订单时拒绝创建"""
+    def test_create_shipment_allows_sales_items_from_different_printing_orders(self):
+        """测试销售品可以来自不同生产订单"""
         data = {
             "customer": self.customer.id,
             "shipment_date": "2026-01-14",
@@ -1397,8 +1989,14 @@ class ShipmentCreateAPITestCase(TestCase):
 
         response = self.client.post("/api/v1/shipment/shipments/", data, format="json")
 
-        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
-        self.assertIn("同一个生产订单", response.json()["detail"])
+        self.assertEqual(response.status_code, status.HTTP_201_CREATED)
+        result = response.json()
+        self.assertEqual(result["items_count"], 2)
+
+        self.sales_item1.refresh_from_db()
+        self.sales_item_other_order.refresh_from_db()
+        self.assertEqual(self.sales_item1.shipment_id, result["id"])
+        self.assertEqual(self.sales_item_other_order.shipment_id, result["id"])
 
     def test_create_shipment_rejects_sales_item_without_printing_job(self):
         """测试销售品缺少生产任务时拒绝创建"""
@@ -1846,6 +2444,8 @@ class ShipmentQueryAPITestCase(TestCase):
         self.assertEqual(result["id"], self.shipment1.id)
         self.assertIn("area", result)
         self.assertEqual(result["area"], "A1")
+        self.assertIn("coordinates", result)
+        self.assertIn("extra", result)
         self.assertEqual(result["status"], shipment_models.ShipmentStatus.DRAFT)
         self.assertEqual(result["status_display"], "草稿(未发布)")
         self.assertIn("sales_items", result)
@@ -1865,6 +2465,8 @@ class ShipmentQueryAPITestCase(TestCase):
                 "address": "宁波市滨海路 9 号",
                 "contact_name": "王五",
                 "contact_phone": "13700137000",
+                "coordinates": "120.2000,30.3000",
+                "extra": {"dock": "A"},
             },
             format="json",
         )
@@ -1875,12 +2477,16 @@ class ShipmentQueryAPITestCase(TestCase):
         self.assertEqual(result["address"], "宁波市滨海路 9 号")
         self.assertEqual(result["contact_name"], "王五")
         self.assertEqual(result["contact_phone"], "13700137000")
+        self.assertEqual(result["coordinates"], "120.2000,30.3000")
+        self.assertEqual(result["extra"], {"dock": "A"})
 
         self.shipment1.refresh_from_db()
         self.assertEqual(getattr(self.shipment1, "area", ""), "更新地区")
         self.assertEqual(self.shipment1.address, "宁波市滨海路 9 号")
         self.assertEqual(self.shipment1.contact_name, "王五")
         self.assertEqual(self.shipment1.contact_phone, "13700137000")
+        self.assertEqual(self.shipment1.coordinates, "120.2000,30.3000")
+        self.assertEqual(self.shipment1.extra, {"dock": "A"})
 
     def test_patch_shipment_allows_approved_shipment_without_delivery(self):
         """
@@ -1911,6 +2517,24 @@ class ShipmentQueryAPITestCase(TestCase):
         self.shipment1.refresh_from_db()
         self.assertEqual(self.shipment1.area, "审核后可修改")
 
+    def test_patch_shipment_allows_cancelled_shipment_without_delivery(self):
+        self.shipment1.status = shipment_models.ShipmentStatus.CANCELLED
+        self.shipment1.save(update_fields=["status", "updated_at"])
+
+        resp = self.client.patch(
+            f"/api/v1/shipment/shipments/{self.shipment1.id}/",
+            data={"area": "取消后可修改"},
+            format="json",
+        )
+
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.json()["area"], "取消后可修改")
+        self.assertEqual(resp.json()["status"], shipment_models.ShipmentStatus.CANCELLED)
+
+        self.shipment1.refresh_from_db()
+        self.assertEqual(self.shipment1.area, "取消后可修改")
+        self.assertEqual(self.shipment1.status, shipment_models.ShipmentStatus.CANCELLED)
+
     def test_patch_shipment_rejects_when_bound_to_delivery(self):
         delivery = shipment_models.ShipmentDelivery.objects.create(
             merchant=self.merchant1,

api_v1/views/shipment/views.py

@@ -8,6 +8,7 @@ from rest_framework.mixins import ListModelMixin, RetrieveModelMixin
 from rest_framework.permissions import IsAuthenticated
 from rest_framework.response import Response
 from rest_framework.views import APIView
+from django.utils.dateparse import parse_date, parse_datetime
 
 from flower.viewsets import LimitedLimitOffsetPagination
 from shipment.models import Shipment, ShipmentDelivery
@@ -19,6 +20,7 @@ from .serializers import (
     SalesItemUpdateSerializer,
     ShipmentStatusUpdateSerializer,
     ShipmentDeliveryBindShipmentsSerializer,
+    ShipmentDeliveryByPrintingOrderSerializer,
     ShipmentDeliveryCreateSerializer,
     ShipmentDeliverySerializer,
     ShipmentDeliveryStatusUpdateSerializer,
@@ -210,11 +212,15 @@ class ShipmentListCreateView(ListModelMixin, GenericAPIView):
                 shipment_date=data["shipment_date"],
                 sales_item_ids=data["sales_items"],
                 created_by=request.user,
+                address_id=data.get("address_id"),
                 address=data.get("address", ""),
                 contact_name=data.get("contact_name", ""),
                 contact_phone=data.get("contact_phone", ""),
                 remark=data.get("remark", ""),
                 area=data.get("area", ""),
+                coordinates=data.get("coordinates"),
+                extra=data.get("extra"),
+                status=data.get("status"),
             )
         except ValueError as e:
             return Response({"detail": str(e)}, status=status.HTTP_400_BAD_REQUEST)
@@ -274,7 +280,7 @@ class ShipmentDetailView(RetrieveModelMixin, GenericAPIView):
             return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
         data = serializer.validated_data
 
-        from shipment.services import update_shipment
+        from shipment.services import UNSET, update_shipment
 
         try:
             shipment = update_shipment(
@@ -285,8 +291,10 @@ class ShipmentDetailView(RetrieveModelMixin, GenericAPIView):
                 contact_name=data.get("contact_name"),
                 contact_phone=data.get("contact_phone"),
                 area=data.get("area"),
+                coordinates=data["coordinates"] if "coordinates" in data else UNSET,
                 remark=data.get("remark"),
                 external_id=data.get("external_id"),
+                extra=data["extra"] if "extra" in data else UNSET,
             )
         except ValueError as e:
             return Response({"detail": str(e)}, status=status.HTTP_400_BAD_REQUEST)
@@ -444,6 +452,172 @@ class ShipmentDeliveryListCreateView(ListModelMixin, GenericAPIView):
         )
 
 
+class ShipmentDeliveryByPrintingOrderView(GenericAPIView):
+    """
+    按生产订单查询相关送货单。
+
+    GET /api/v1/shipment/deliveries/by-printing-order/<printing_order_id>/
+    """
+
+    permission_classes = [IsAuthenticated]
+    serializer_class = ShipmentDeliveryByPrintingOrderSerializer
+    pagination_class = LimitedLimitOffsetPagination
+
+    ordering_fields = {
+        "id",
+        "created_at",
+        "updated_at",
+        "started_at",
+        "delivered_at",
+        "cancelled_at",
+        "status",
+    }
+
+    def _get_merchant_limited_printing_orders(self):
+        from printing.models import PrintingOrder
+
+        queryset = PrintingOrder.objects.all()
+        user = self.request.user
+        if getattr(user, "is_superuser", False):
+            return queryset
+
+        emp = getattr(user, "employee", None)
+        merchant = getattr(emp, "merchant", None) if emp else None
+        if not merchant:
+            return queryset.none()
+        return queryset.filter(merchant=merchant)
+
+    def _resolve_printing_order(self, printing_order_id: str):
+        raw_value = str(printing_order_id).strip()
+        base_queryset = self._get_merchant_limited_printing_orders()
+
+        if raw_value.isdigit():
+            printing_order = base_queryset.filter(id=int(raw_value)).first()
+            if printing_order is not None:
+                return printing_order, None
+
+        matched_orders = list(
+            base_queryset.filter(external_order_id=raw_value).only("id", "merchant_id")[:2]
+        )
+        if len(matched_orders) > 1:
+            return None, Response(
+                {
+                    "message": (
+                        f"external_order_id {raw_value} 匹配到多个生产订单，"
+                        "请改用内部ID查询"
+                    )
+                },
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            )
+        if len(matched_orders) == 1:
+            return matched_orders[0], None
+        return None, Response(
+            {"detail": f"生产订单 {printing_order_id} 不存在"},
+            status=status.HTTP_404_NOT_FOUND,
+        )
+
+    def _apply_datetime_range(self, queryset, field_name: str, from_param: str, to_param: str):
+        start_value = (self.request.query_params.get(from_param) or "").strip()
+        if start_value:
+            if "T" in start_value or ":" in start_value:
+                parsed = parse_datetime(start_value)
+                if parsed is not None:
+                    queryset = queryset.filter(**{f"{field_name}__gte": parsed})
+            else:
+                parsed = parse_date(start_value)
+                if parsed is not None:
+                    queryset = queryset.filter(**{f"{field_name}__date__gte": parsed})
+
+        end_value = (self.request.query_params.get(to_param) or "").strip()
+        if end_value:
+            if "T" in end_value or ":" in end_value:
+                parsed = parse_datetime(end_value)
+                if parsed is not None:
+                    queryset = queryset.filter(**{f"{field_name}__lte": parsed})
+            else:
+                parsed = parse_date(end_value)
+                if parsed is not None:
+                    queryset = queryset.filter(**{f"{field_name}__date__lte": parsed})
+        return queryset
+
+    def _apply_filters(self, queryset):
+        status_val = self.request.query_params.get("status")
+        if status_val:
+            queryset = queryset.filter(status=status_val)
+
+        for field_name in [
+            "driver_name",
+            "vehicle_trip",
+            "contact_phone",
+            "vehicle_capacity",
+            "remark",
+            "internal_remark",
+        ]:
+            value = (self.request.query_params.get(field_name) or "").strip()
+            if value:
+                queryset = queryset.filter(**{f"{field_name}__icontains": value})
+
+        queryset = self._apply_datetime_range(
+            queryset, "started_at", "started_at_from", "started_at_to"
+        )
+        queryset = self._apply_datetime_range(
+            queryset, "delivered_at", "delivered_at_from", "delivered_at_to"
+        )
+        queryset = self._apply_datetime_range(
+            queryset, "cancelled_at", "cancelled_at_from", "cancelled_at_to"
+        )
+        queryset = self._apply_datetime_range(
+            queryset, "created_at", "created_at_from", "created_at_to"
+        )
+
+        shipment_date_from = (self.request.query_params.get("shipment_date_from") or "").strip()
+        if shipment_date_from:
+            queryset = queryset.filter(shipments__shipment_date__gte=shipment_date_from)
+        shipment_date_to = (self.request.query_params.get("shipment_date_to") or "").strip()
+        if shipment_date_to:
+            queryset = queryset.filter(shipments__shipment_date__lte=shipment_date_to)
+
+        ordering = (self.request.query_params.get("ordering") or "").strip()
+        if ordering:
+            normalized = ordering[1:] if ordering.startswith("-") else ordering
+            if normalized in self.ordering_fields:
+                return queryset.order_by(ordering, "-id").distinct()
+
+        return queryset.order_by("-created_at", "-id").distinct()
+
+    def get(self, request, printing_order_id: str):
+        printing_order, error_response = self._resolve_printing_order(printing_order_id)
+        if error_response is not None:
+            return error_response
+
+        from printing.models import PrintingJob
+
+        printing_job_ids = list(
+            PrintingJob.objects.filter(printing_order=printing_order).values_list(
+                "id", flat=True
+            )
+        )
+        if not printing_job_ids:
+            queryset = ShipmentDelivery.objects.none()
+        else:
+            queryset = (
+                ShipmentDelivery.objects.filter(
+                    merchant=printing_order.merchant,
+                    shipments__items__printing_job_id__in=printing_job_ids,
+                    shipments__items__delete_at__isnull=True,
+                )
+                .select_related("merchant", "created_by", "operator", "cancelled_by")
+                .prefetch_related("shipments", "shipments__customer")
+            )
+            queryset = self._apply_filters(queryset)
+
+        page = self.paginate_queryset(queryset)
+        serializer = self.get_serializer(page if page is not None else queryset, many=True)
+        if page is not None:
+            return self.get_paginated_response(serializer.data)
+        return Response(serializer.data)
+
+
 class ShipmentDeliveryDetailView(RetrieveModelMixin, GenericAPIView):
     """
     送货单详情 / 修改 / 删除
@@ -712,6 +886,8 @@ class ShipmentExternalCreateView(APIView):
                 contact_phone=data.get("contact_phone", ""),
                 remark=data.get("remark", ""),
                 area=data.get("area", ""),
+                coordinates=data.get("coordinates"),
+                extra=data.get("extra"),
             )
         except ValueError as e:
             return Response({"detail": str(e)}, status=status.HTTP_400_BAD_REQUEST)
@@ -753,7 +929,15 @@ class ShipmentSalesItemCustomerListView(GenericAPIView):
 
         from shipment.services import get_customers_with_unshipped_sales_items
 
-        return get_customers_with_unshipped_sales_items(merchant=merchant)
+        qs = get_customers_with_unshipped_sales_items(merchant=merchant)
+
+        customer_name = self.request.query_params.get("customer_name")
+        if customer_name:
+            customer_name = customer_name.strip()
+            if customer_name:
+                qs = qs.filter(name__icontains=customer_name)
+
+        return qs
 
     def get(self, request):
         queryset = self.get_queryset()
@@ -872,6 +1056,134 @@ class SalesItemByPrintingOrderView(APIView):
         return Response({"count": len(serializer.data), "results": serializer.data})
 
 
+class SalesItemByPrintingOrderGroupView(SalesItemByPrintingOrderView):
+    """
+    通过生产订单查询销售品，并按 printing_job_id 分组分页。
+
+    GET /api/v1/shipment/sales-items/by-printing-order/<printing_order_id>/group/
+    """
+
+    pagination_class = LimitedLimitOffsetPagination
+
+    @property
+    def paginator(self):
+        if not hasattr(self, "_paginator"):
+            self._paginator = self.pagination_class()
+        return self._paginator
+
+    def paginate_queryset(self, queryset):
+        return self.paginator.paginate_queryset(queryset, self.request, view=self)
+
+    def get_paginated_response(self, data):
+        return self.paginator.get_paginated_response(data)
+
+    def get(self, request, printing_order_id):
+        from printing.models import PrintingOrder
+
+        user = request.user
+        if getattr(user, "is_superuser", False):
+            base_queryset = PrintingOrder.objects.all()
+        else:
+            emp = getattr(user, "employee", None)
+            merchant = getattr(emp, "merchant", None) if emp else None
+            if not merchant:
+                return Response(
+                    {"detail": f"生产订单 {printing_order_id} 不存在"},
+                    status=status.HTTP_404_NOT_FOUND,
+                )
+            base_queryset = PrintingOrder.objects.filter(merchant=merchant)
+
+        printing_order = None
+        if printing_order_id.isdigit():
+            printing_order = base_queryset.filter(id=int(printing_order_id)).first()
+
+        if printing_order is None:
+            matched_orders = list(
+                base_queryset.filter(external_order_id=printing_order_id).only("id")[:2]
+            )
+            if len(matched_orders) > 1:
+                return Response(
+                    {
+                        "detail": (
+                            f"external_order_id {printing_order_id} 匹配到多个生产订单，"
+                            "请改用内部ID查询"
+                        )
+                    },
+                    status=status.HTTP_400_BAD_REQUEST,
+                )
+            if len(matched_orders) == 1:
+                printing_order = matched_orders[0]
+
+        if printing_order is None:
+            return Response(
+                {"detail": f"生产订单 {printing_order_id} 不存在"},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+
+        include_already_has_shipment = (
+            request.query_params.get("include_already_has_shipment", "false").lower()
+            == "true"
+        )
+
+        from shipment.services import get_sales_items_by_printing_order
+
+        queryset = get_sales_items_by_printing_order(
+            printing_order_id=printing_order_id,
+            include_already_has_shipment=include_already_has_shipment,
+            merchant=printing_order.merchant,
+        )
+        all_items = list(queryset)
+        printing_job_ids = []
+        seen_printing_job_ids = set()
+        for item in all_items:
+            group_key = item.printing_job_id
+            if group_key not in seen_printing_job_ids:
+                seen_printing_job_ids.add(group_key)
+                printing_job_ids.append(group_key)
+        printing_job_ids.sort(key=lambda value: (value is None, value or 0))
+
+        page_printing_job_ids = self.paginate_queryset(printing_job_ids)
+        selected_printing_job_ids = (
+            page_printing_job_ids
+            if page_printing_job_ids is not None
+            else printing_job_ids
+        )
+        selected_printing_job_id_set = set(selected_printing_job_ids)
+
+        selected_items = [
+            item
+            for item in all_items
+            if item.printing_job_id in selected_printing_job_id_set
+        ]
+        serializer = SalesItemSerializer(
+            selected_items,
+            many=True,
+            context=_build_sales_item_serializer_context(selected_items),
+        )
+
+        grouped_by_printing_job_id = {
+            printing_job_id: {
+                "printing_job_id": printing_job_id,
+                "count": 0,
+                "items": [],
+            }
+            for printing_job_id in selected_printing_job_ids
+        }
+        for item in serializer.data:
+            printing_job_id = item["printing_job_id"]
+            group = grouped_by_printing_job_id[printing_job_id]
+            group["count"] += 1
+            group["items"].append(item)
+
+        groups = [
+            grouped_by_printing_job_id[printing_job_id]
+            for printing_job_id in selected_printing_job_ids
+        ]
+        if page_printing_job_ids is not None:
+            return self.get_paginated_response(groups)
+        return Response(groups)
+
+
 class SalesItemByCustomerView(GenericAPIView):
     """
     通过客户查询销售品。
@@ -931,6 +1243,117 @@ class SalesItemByCustomerView(GenericAPIView):
         return Response(serializer.data)
 
 
+class SalesItemByCustomerGroupView(SalesItemByCustomerView):
+    """
+    通过客户查询销售品，并按 external_order_id、name 分组。
+
+    GET /api/v1/shipment/sales-items/by-customer/<customer_id>/group/
+    """
+
+    def get(self, request, customer_id: int):
+        from basic_info.models import Customer
+
+        user = request.user
+        if getattr(user, "is_superuser", False):
+            customer = Customer.objects.filter(id=customer_id).first()
+        else:
+            emp = getattr(user, "employee", None)
+            merchant = getattr(emp, "merchant", None) if emp else None
+            if not merchant:
+                return Response(
+                    {"detail": f"客户 {customer_id} 不存在"},
+                    status=status.HTTP_404_NOT_FOUND,
+                )
+            customer = Customer.objects.filter(id=customer_id, merchant=merchant).first()
+
+        if customer is None:
+            return Response(
+                {"detail": f"客户 {customer_id} 不存在"},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+
+        include_already_has_shipment = (
+            request.query_params.get("include_already_has_shipment", "false").lower()
+            == "true"
+        )
+        external_order_id = (request.query_params.get("external_order_id") or "").strip()
+
+        from shipment.services import get_sales_items_by_customer
+
+        queryset = get_sales_items_by_customer(
+            merchant=customer.merchant,
+            customer_id=customer.id,
+            include_already_has_shipment=include_already_has_shipment,
+            external_order_id=external_order_id or None,
+        )
+        all_items = list(queryset)
+        serializer_context = _build_sales_item_serializer_context(all_items)
+        serialized_items = self.get_serializer(
+            all_items,
+            many=True,
+            context=serializer_context,
+        ).data
+
+        external_order_ids = []
+        seen_external_order_ids = set()
+        for item in serialized_items:
+            group_key = item["external_order_id"]
+            if group_key not in seen_external_order_ids:
+                seen_external_order_ids.add(group_key)
+                external_order_ids.append(group_key)
+        external_order_ids.sort(key=lambda value: (value is None, value or ""))
+
+        page_external_order_ids = self.paginate_queryset(external_order_ids)
+        selected_external_order_ids = (
+            page_external_order_ids
+            if page_external_order_ids is not None
+            else external_order_ids
+        )
+        selected_external_order_id_set = set(selected_external_order_ids)
+
+        grouped_by_external_order_id = {
+            external_order_id: {
+                "external_order_id": external_order_id,
+                "count": 0,
+                "name_groups": [],
+            }
+            for external_order_id in selected_external_order_ids
+        }
+        name_group_maps = {
+            external_order_id: {} for external_order_id in selected_external_order_ids
+        }
+
+        for item in serialized_items:
+            external_order_id = item["external_order_id"]
+            if external_order_id not in selected_external_order_id_set:
+                continue
+
+            external_group = grouped_by_external_order_id[external_order_id]
+            external_group["count"] += 1
+
+            name = item["name"]
+            name_group_map = name_group_maps[external_order_id]
+            if name not in name_group_map:
+                name_group_map[name] = {
+                    "name": name,
+                    "count": 0,
+                    "items": [],
+                }
+                external_group["name_groups"].append(name_group_map[name])
+
+            name_group = name_group_map[name]
+            name_group["count"] += 1
+            name_group["items"].append(item)
+
+        groups = [
+            grouped_by_external_order_id[external_order_id]
+            for external_order_id in selected_external_order_ids
+        ]
+        if page_external_order_ids is not None:
+            return self.get_paginated_response(groups)
+        return Response(groups)
+
+
 class SalesItemCreateView(APIView):
     """
     手动创建销售品