diff --git a/api_v1/management/commands/set_app_version.py b/api_v1/management/commands/set_app_version.py index 94c837f..d8cd970 100644 --- a/api_v1/management/commands/set_app_version.py +++ b/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))) diff --git a/api_v1/tasks.py b/api_v1/tasks.py index 630eee3..4264edc 100644 --- a/api_v1/tasks.py +++ b/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, diff --git a/api_v1/test_customer_address_api.py b/api_v1/test_customer_address_api.py new file mode 100644 index 0000000..2dfe341 --- /dev/null +++ b/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) diff --git a/api_v1/test_external_printing_records_sync.py b/api_v1/test_external_printing_records_sync.py index fa910b3..7602e93 100644 --- a/api_v1/test_external_printing_records_sync.py +++ b/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') diff --git a/api_v1/urls.py b/api_v1/urls.py index 5201213..d077944 100644 --- a/api_v1/urls.py +++ b/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//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//", + ShipmentDeliveryByPrintingOrderView.as_view(), + name="shipment_deliveries_by_printing_order", + ), path( "shipment/deliveries//", ShipmentDeliveryDetailView.as_view(), @@ -380,11 +397,21 @@ urlpatterns = [ ShipmentSalesItemCustomerListView.as_view(), name="sales_item_customers", ), + path( + "shipment/sales-items/by-customer//group/", + SalesItemByCustomerGroupView.as_view(), + name="sales_items_by_customer_group", + ), path( "shipment/sales-items/by-customer//", SalesItemByCustomerView.as_view(), name="sales_items_by_customer", ), + path( + "shipment/sales-items/by-printing-order//group/", + SalesItemByPrintingOrderGroupView.as_view(), + name="sales_items_by_printing_order_group", + ), path( "shipment/sales-items/by-printing-order//", SalesItemByPrintingOrderView.as_view(), diff --git a/api_v1/views/basic_info.py b/api_v1/views/basic_info.py new file mode 100644 index 0000000..5c5ddcb --- /dev/null +++ b/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) diff --git a/api_v1/views/printing/serializers.py b/api_v1/views/printing/serializers.py index 6ab3ce7..a45a868 100644 --- a/api_v1/views/printing/serializers.py +++ b/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): """印染订单创建/更新序列化器""" diff --git a/api_v1/views/printing/test_api.py b/api_v1/views/printing/test_api.py index f527d55..0bb08f2 100644 --- a/api_v1/views/printing/test_api.py +++ b/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): """测试获取订单详情""" diff --git a/api_v1/views/printing/views.py b/api_v1/views/printing/views.py index c8bf737..e9d2285 100644 --- a/api_v1/views/printing/views.py +++ b/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", diff --git a/api_v1/views/shipment/__init__.py b/api_v1/views/shipment/__init__.py index 883d125..c128986 100644 --- a/api_v1/views/shipment/__init__.py +++ b/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', diff --git a/api_v1/views/shipment/serializers.py b/api_v1/views/shipment/serializers.py index 120a399..7b1d9b6 100644 --- a/api_v1/views/shipment/serializers.py +++ b/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="车次") diff --git a/api_v1/views/shipment/test_api.py b/api_v1/views/shipment/test_api.py index 278d4f7..74a737e 100644 --- a/api_v1/views/shipment/test_api.py +++ b/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, diff --git a/api_v1/views/shipment/views.py b/api_v1/views/shipment/views.py index c59d165..1fa93b1 100644 --- a/api_v1/views/shipment/views.py +++ b/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// + """ + + 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//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//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): """ 手动创建销售品 diff --git a/api_v2/tests.py b/api_v2/tests.py index d0b6ffe..85d82cc 100644 --- a/api_v2/tests.py +++ b/api_v2/tests.py @@ -402,6 +402,25 @@ class PrintingOrderWithoutSalesOrderAPITest(TestCase): self.assertNotIn(self.active_bound_order.id, result_ids) self.assertNotIn(self.other_customer_order.id, result_ids) + def test_list_orders_returns_bianhao_kd(self): + self.unbound_order.external_order_id = 'KD20410611' + self.unbound_order.external_raw = { + 'first_record': { + 'BianHaoKD': '7.07', + 'KdRiQi': '2026-07-06T21:48:58Z', + } + } + self.unbound_order.save(update_fields=['external_order_id', 'external_raw', 'updated_at']) + + response = self.client.get(self.url, {'customer_id': self.customer.id}) + + self.assertEqual(response.status_code, 200) + by_id = {item['id']: item for item in response.data} + self.assertEqual(by_id[self.unbound_order.id]['bianhao_kd'], '7.07') + self.assertEqual(by_id[self.unbound_order.id]['kd_riqi'], '2026-07-06T21:48:58Z') + self.assertIsNone(by_id[self.legacy_unbound_order.id]['bianhao_kd']) + self.assertIsNone(by_id[self.legacy_unbound_order.id]['kd_riqi']) + def test_customer_id_is_required(self): response = self.client.get(self.url) self.assertEqual(response.status_code, 400) diff --git a/api_v2/views/printing.py b/api_v2/views/printing.py index 4c6abe1..d2de5a8 100644 --- a/api_v2/views/printing.py +++ b/api_v2/views/printing.py @@ -21,6 +21,8 @@ from api_v1.tasks import ( from api_man.serializers import ProductSerializer from api_v1.views.printing.serializers import ( PlateOrderListSerializer as PlateOrderListV1Serializer, + resolve_printing_order_bianhao_kd, + resolve_printing_order_kd_riqi, _serialize_plate_images, ) from stateflow import models as stateflow_models @@ -190,6 +192,8 @@ class PrintingOrderWithoutSalesOrderSerializer(serializers.ModelSerializer): """未关联非作废销售单的印染订单列表序列化器。""" customer_name = serializers.CharField(source='customer.name', read_only=True) + bianhao_kd = serializers.SerializerMethodField() + kd_riqi = serializers.SerializerMethodField() class Meta: model = printing_models.PrintingOrder @@ -197,6 +201,8 @@ class PrintingOrderWithoutSalesOrderSerializer(serializers.ModelSerializer): 'id', 'human_id', 'external_order_id', + 'bianhao_kd', + 'kd_riqi', 'customer', 'customer_name', 'fabric', @@ -209,6 +215,12 @@ class PrintingOrderWithoutSalesOrderSerializer(serializers.ModelSerializer): ] read_only_fields = fields + 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 PrintingOrderWithoutSalesOrderView(APIView): """ diff --git a/basic_info/admin.py b/basic_info/admin.py index f69cc75..b9cd257 100644 --- a/basic_info/admin.py +++ b/basic_info/admin.py @@ -122,6 +122,35 @@ class CustomerAdmin(AdminBase): return '0 (动态逻辑字段待实现)' +@admin.register(models.CustomerAddress) +class CustomerAddressAdmin(AdminBase): + list_display = ( + 'customer', + 'address', + 'contact_name', + 'contact_phone', + 'area', + 'is_default', + 'deleted_at', + ) + list_filter = ('is_default', 'deleted_at', 'area') + search_fields = ( + 'customer__name', + 'address', + 'contact_name', + 'contact_phone', + 'area', + ) + + def get_queryset(self, request): + qs = super().get_queryset(request).select_related('customer') + customer_qs = CustomerVisibilityService.filter_customers_for_employee( + models.Customer.objects.all(), + request.user, + ) + return qs.filter(customer__in=customer_qs) + + @admin.register(models.Employee) class EmployeeAdmin(AdminBase): list_display = ('name', 'mobile', 'status', 'position_display', 'sys_user') diff --git a/basic_info/migrations/0028_customeraddress.py b/basic_info/migrations/0028_customeraddress.py new file mode 100644 index 0000000..65b781a --- /dev/null +++ b/basic_info/migrations/0028_customeraddress.py @@ -0,0 +1,41 @@ +# Generated by Django 5.2.8 on 2026-07-07 12:30 + +import django.db.models.deletion +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('basic_info', '0027_employee_wecom_user_id'), + ] + + operations = [ + migrations.CreateModel( + name='CustomerAddress', + fields=[ + ('created_at', models.DateTimeField(auto_now_add=True, verbose_name='创建时间')), + ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')), + ('id', models.BigAutoField(primary_key=True, serialize=False)), + ('address', models.CharField(max_length=255, verbose_name='地址')), + ('contact_name', models.CharField(blank=True, default='', max_length=100, verbose_name='联系人')), + ('contact_phone', models.CharField(blank=True, default='', max_length=50, verbose_name='联系电话')), + ('area', models.CharField(blank=True, default='', max_length=100, verbose_name='地区')), + ('coordinates', models.CharField(blank=True, help_text='经纬度字符串，格式由调用方决定', max_length=100, null=True, verbose_name='经纬度')), + ('is_default', models.BooleanField(default=False, verbose_name='是否默认地址')), + ('remark', models.CharField(blank=True, default='', max_length=200, verbose_name='备注')), + ('extra', models.JSONField(blank=True, null=True, verbose_name='扩展信息')), + ('deleted_at', models.DateTimeField(blank=True, null=True, verbose_name='删除时间')), + ('created_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='created_customer_addresses', to='basic_info.employee', verbose_name='创建者')), + ('customer', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='addresses', to='basic_info.customer', verbose_name='客户')), + ('deleted_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='deleted_customer_addresses', to='basic_info.employee', verbose_name='删除者')), + ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='customer_addresses', to='basic_info.merchant', verbose_name='所属商户')), + ], + options={ + 'verbose_name': '客户地址', + 'verbose_name_plural': '客户地址', + 'ordering': ['-is_default', '-created_at', '-id'], + 'indexes': [models.Index(fields=['merchant', 'customer'], name='basic_info__merchan_d9f31e_idx'), models.Index(fields=['deleted_at'], name='basic_info__deleted_a6a24f_idx'), models.Index(fields=['is_default'], name='basic_info__is_defa_487d27_idx')], + }, + ), + ] diff --git a/basic_info/migrations/0029_customeraddress_coordinates.py b/basic_info/migrations/0029_customeraddress_coordinates.py new file mode 100644 index 0000000..b5f66db --- /dev/null +++ b/basic_info/migrations/0029_customeraddress_coordinates.py @@ -0,0 +1,12 @@ +# Generated by OpenCode on 2026-07-07 + +from django.db import migrations + + +class Migration(migrations.Migration): + + dependencies = [ + ('basic_info', '0028_customeraddress'), + ] + + operations = [] diff --git a/basic_info/models.py b/basic_info/models.py index 8a55d01..cae74fc 100644 --- a/basic_info/models.py +++ b/basic_info/models.py @@ -450,6 +450,66 @@ class Customer(ModelBase): ] +class CustomerAddress(ModelBase): + id = models.BigAutoField(primary_key=True) + merchant = models.ForeignKey( + 'Merchant', + on_delete=models.PROTECT, + related_name='customer_addresses', + verbose_name='所属商户', + ) + customer = models.ForeignKey( + 'Customer', + on_delete=models.PROTECT, + related_name='addresses', + verbose_name='客户', + ) + address = models.CharField(max_length=255, verbose_name='地址') + contact_name = models.CharField(max_length=100, blank=True, default='', verbose_name='联系人') + contact_phone = models.CharField(max_length=50, blank=True, default='', verbose_name='联系电话') + area = models.CharField(max_length=100, blank=True, default='', verbose_name='地区') + coordinates = models.CharField( + max_length=100, + null=True, + blank=True, + verbose_name='经纬度', + help_text='经纬度字符串，格式由调用方决定', + ) + is_default = models.BooleanField(default=False, verbose_name='是否默认地址') + remark = models.CharField(max_length=200, blank=True, default='', verbose_name='备注') + extra = models.JSONField(null=True, blank=True, verbose_name='扩展信息') + created_by = models.ForeignKey( + 'Employee', + on_delete=models.PROTECT, + related_name='created_customer_addresses', + null=True, + blank=True, + verbose_name='创建者', + ) + deleted_at = models.DateTimeField(null=True, blank=True, verbose_name='删除时间') + deleted_by = models.ForeignKey( + 'Employee', + on_delete=models.SET_NULL, + related_name='deleted_customer_addresses', + null=True, + blank=True, + verbose_name='删除者', + ) + + def __str__(self): + return f'{self.customer.name} - {self.address}' + + class Meta: + verbose_name = '客户地址' + verbose_name_plural = '客户地址' + ordering = ['-is_default', '-created_at', '-id'] + indexes = [ + models.Index(fields=['merchant', 'customer']), + models.Index(fields=['deleted_at']), + models.Index(fields=['is_default']), + ] + + class Employee(ModelBase): id = models.BigAutoField(primary_key=True) merchant = models.ForeignKey('Merchant', on_delete=models.PROTECT, related_name='employees', verbose_name='所属商户') diff --git a/docs/api_v1_customer_address_api_2026-07-07.md b/docs/api_v1_customer_address_api_2026-07-07.md new file mode 100644 index 0000000..67ee020 --- /dev/null +++ b/docs/api_v1_customer_address_api_2026-07-07.md @@ -0,0 +1,224 @@ +# API v1 Customer Address API + +## Scope + +客户地址 API 用于维护客户的一对多地址资料。地址归属 `basic_info.Customer`，并通过 `merchant` 做商户隔离。 + +所有接口需要登录。普通员工只能访问自己可见客户的地址；拥有 `basic_info.view_all_customers` 权限的员工可以访问本商户全部客户地址；superuser 可以访问全部数据。 + +## Data Model + +| Field | Type | Description | +| --- | --- | --- | +| `id` | integer | 客户地址 ID | +| `merchant` | integer | 所属商户 ID，创建时由后端根据客户自动写入 | +| `merchant_name` | string | 所属商户名称，只读 | +| `customer` | integer | 客户 ID | +| `customer_name` | string | 客户名称，只读 | +| `address` | string | 地址 | +| `contact_name` | string | 联系人，可为空字符串 | +| `contact_phone` | string | 联系电话，可为空字符串 | +| `area` | string | 地区，可为空字符串 | +| `coordinates` | string/null | 经纬度字符串，格式由调用方决定 | +| `is_default` | boolean | 是否默认地址 | +| `remark` | string | 备注，可为空字符串 | +| `extra` | object/null | 扩展 JSON | +| `created_by` | integer/null | 创建员工 ID，只读 | +| `created_by_name` | string/null | 创建员工姓名，只读 | +| `deleted_at` | datetime/null | 软删除时间，只读 | +| `deleted_by` | integer/null | 删除员工 ID，只读 | +| `deleted_by_name` | string/null | 删除员工姓名，只读 | +| `created_at` | datetime | 创建时间，只读 | +| `updated_at` | datetime | 更新时间，只读 | + +## Endpoints + +| Method | Path | Description | +| --- | --- | --- | +| GET | `/api/v1/customer-addresses/` | 查询客户地址列表 | +| POST | `/api/v1/customer-addresses/` | 创建客户地址 | +| GET | `/api/v1/customer-addresses/{id}/` | 查询客户地址详情 | +| PUT | `/api/v1/customer-addresses/{id}/` | 完整更新客户地址 | +| PATCH | `/api/v1/customer-addresses/{id}/` | 部分更新客户地址 | +| DELETE | `/api/v1/customer-addresses/{id}/` | 软删除客户地址 | +| POST | `/api/v1/customer-address/{id}/set-default/` | 将客户地址设为默认地址 | + +## Visibility Rules + +普通员工可访问的客户地址必须同时满足： + +- 地址所属商户等于当前员工商户。 +- 地址所属客户对当前员工可见。 + +客户可见性规则： + +- `customer.created_by == 当前员工` +- 或当前员工在 `customer.visible_employees` 中。 + +权限例外： + +- `basic_info.view_all_customers`：可访问本商户全部客户地址。 +- superuser：可访问全部客户地址。 + +创建地址时，`customer` 也必须在当前用户可访问范围内。`merchant` 不由前端传入，后端使用客户所属商户自动写入。 + +## Query Parameters + +`GET /api/v1/customer-addresses/` 支持以下查询参数： + +| Parameter | Description | +| --- | --- | +| `customer` | 按客户 ID 精确过滤 | +| `customer_name` | 按客户名称模糊过滤 | +| `address` | 按地址模糊过滤 | +| `contact_name` | 按联系人模糊过滤 | +| `contact_phone` | 按联系电话模糊过滤 | +| `area` | 按地区模糊过滤 | +| `is_default` | 按默认地址过滤，支持 `true/false/1/0/yes/no` | +| `include_deleted` | 是否包含软删除记录，支持 `true/false/1/0/yes/no` | +| `only_deleted` | 是否只查询软删除记录，支持 `true/false/1/0/yes/no` | +| `search` | 对客户名称、地址、联系人、电话、地区、备注做模糊搜索 | +| `ordering` | 排序字段，支持 `id`、`created_at`、`updated_at`、`is_default` 及其 `-` 倒序形式 | +| `limit` | 分页数量 | +| `offset` | 分页偏移 | + +默认行为： + +- 不传 `include_deleted` 和 `only_deleted` 时，只返回未删除地址。 +- `only_deleted=true` 优先于 `include_deleted=true`。 + +## Create + +`POST /api/v1/customer-addresses/` + +Request body: + +```json +{ + "customer": 3, + "address": "杭州市测试路 1 号", + "contact_name": "张三", + "contact_phone": "13800138000", + "area": "杭州", + "coordinates": "120.1,30.2", + "is_default": true, + "remark": "默认收货地址", + "extra": { + "source": "manual" + } +} +``` + +Success response: HTTP 201 + +```json +{ + "id": 10, + "merchant": 1, + "merchant_name": "测试印花厂", + "customer": 3, + "customer_name": "客户A", + "address": "杭州市测试路 1 号", + "contact_name": "张三", + "contact_phone": "13800138000", + "area": "杭州", + "coordinates": "120.1,30.2", + "is_default": true, + "remark": "默认收货地址", + "extra": { + "source": "manual" + }, + "created_by": 5, + "created_by_name": "业务员A", + "deleted_at": null, + "deleted_by": null, + "deleted_by_name": null, + "created_at": "2026-07-07T12:00:00Z", + "updated_at": "2026-07-07T12:00:00Z" +} +``` + +## Update + +`PATCH /api/v1/customer-addresses/{id}/` + +Example: + +```json +{ + "address": "杭州市更新路 2 号", + "contact_phone": "13900139000", + "coordinates": null +} +``` + +Notes: + +- 不允许修改 `customer`。 +- 不允许修改 `merchant`。 +- `created_by`、`deleted_at`、`deleted_by` 为只读字段。 + +## Default Address + +同一客户最多一个未删除默认地址。 + +以下操作会自动取消同一客户其他未删除地址的默认状态： + +- 创建地址时传 `is_default=true`。 +- 更新地址时传 `is_default=true`。 +- 调用 `set-default` 接口。 + +`POST /api/v1/customer-address/{id}/set-default/` + +Success response: HTTP 200，返回更新后的地址对象。 + +如果地址已经软删除，返回 HTTP 400。 + +## Soft Delete + +`DELETE /api/v1/customer-addresses/{id}/` + +删除是软删除，不会物理删除记录。后端会写入： + +- `deleted_at` +- `deleted_by` +- `is_default=false` + +Success response: HTTP 204。 + +查询软删除记录： + +```http +GET /api/v1/customer-addresses/?include_deleted=true +GET /api/v1/customer-addresses/?only_deleted=true +``` + +## Error Cases + +| Condition | Status | Notes | +| --- | --- | --- | +| 未登录 | 401 | 全部接口需要登录 | +| 查询不可见地址详情 | 404 | 不暴露不可见数据存在性 | +| 给不可见客户创建地址 | 400 | `customer` 字段校验失败 | +| 修改 `customer` | 400 | 不允许地址跨客户移动 | +| 已删除地址设为默认 | 400 | 通过 `set-default` 接口返回校验错误 | + +## Test Coverage + +Dedicated tests: + +```bash +docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py test api_v1.test_customer_address_api --keepdb --noinput +``` + +Covered behavior: + +- 商户隔离和客户可见性。 +- `visible_employees` 授权后可见。 +- `basic_info.view_all_customers` 可访问本商户全部客户地址。 +- 创建地址时自动写入 `merchant` 和 `created_by`。 +- 不可见客户创建地址失败。 +- 默认地址互斥。 +- `set-default` 接口互斥设置默认地址。 +- 软删除和 `include_deleted` / `only_deleted` 查询。 +- 常用过滤参数。 diff --git a/docs/api_v1_shipment_api_2026-07-08.md b/docs/api_v1_shipment_api_2026-07-08.md new file mode 100644 index 0000000..632d4e0 --- /dev/null +++ b/docs/api_v1_shipment_api_2026-07-08.md @@ -0,0 +1,826 @@ +# Shipment 模块 API v1 文档 + +面向前端对接，基于当前代码生成。接口统一前缀为 `/api/v1/`。 + +## 通用说明 + +- 认证：所有接口均要求登录认证。 +- 商户隔离：普通用户只能访问自己员工所属商户的数据；超级管理员部分接口可跨商户，具体见接口说明。 +- 分页：列表接口使用 `limit`、`offset`，分页响应一般为 `{ "count": 0, "next": null, "previous": null, "results": [] }`。 +- 错误：业务校验失败通常返回 `400 { "detail": "错误原因" }`；不存在通常返回 `404`。 + +## 枚举 + +### 出货单状态 `ShipmentStatus` + +| 值 | 含义 | +| --- | --- | +| `1` | 草稿(未发布) | +| `2` | 已发布 | +| `3` | 已取消 | +| `4` | 已驳回 | +| `5` | 已审核 | + +### 送货单状态 `ShipmentDeliveryStatus` + +| 值 | 含义 | +| --- | --- | +| `1` | 待送货 | +| `2` | 送货中 | +| `3` | 已送达 | + +### 销售品单位 `UnitChoices` + +| 值 | 含义 | +| --- | --- | +| `1` | 米 | +| `2` | 件 | +| `3` | 码 | +| `4` | 个 | + +## 公共响应结构 + +### Shipment + +```json +{ + "id": 1, + "merchant_id": 1, + "merchant_name": "测试印花厂", + "customer": 10, + "customer_name": "客户A", + "address_id": 5, + "fabric": "面料信息", + "order_description": "订单描述", + "shipment_date": "2026-01-14", + "address": "杭州市测试路 1 号", + "contact_name": "张三", + "contact_phone": "13800138000", + "area": "华东", + "coordinates": "120.1551,30.2741", + "remark": "备注", + "status": 1, + "status_display": "草稿(未发布)", + "external_id": null, + "geo_coordinates": null, + "extra": {"source": "customer_address"}, + "delivery_id": null, + "status_modified_at": null, + "cancelled_by_id": null, + "cancelled_by_name": null, + "approved_by_id": null, + "approved_by_name": null, + "items_count": 2, + "created_by_id": 1, + "created_by_name": "张三", + "external_finished_products_count": 0, + "sales_items": [], + "external_finished_products": [], + "created_at": "2026-01-14T10:00:00Z", + "updated_at": "2026-01-14T10:00:00Z" +} +``` + +字段说明： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `address_id` | integer/null | 关联客户地址 ID，只表示关联关系 | +| `address` | string | 出货单地址快照，由请求体写入 | +| `contact_name` | string | 联系人快照，由请求体写入 | +| `contact_phone` | string | 联系电话快照，由请求体写入 | +| `area` | string | 地区快照，最大 100 字符 | +| `coordinates` | string/null | 经纬度字符串，最大 100 字符 | +| `geo_coordinates` | object/array/null | 历史 Geo 字段，保留兼容老数据 | +| `extra` | object/array/null | 扩展 JSON | + +重要行为：传 `address_id` 时，后端只校验并保存关联，不会用 `CustomerAddress` 自动覆盖 `address/contact_name/contact_phone/area/coordinates/extra`。这些快照字段仍以请求体为准。 + +### SalesItem + +```json +{ + "id": 1, + "name": "销售品A", + "quantity": "100.00", + "unit": 1, + "unit_display": "米", + "position": "A1-01", + "remark": "备注", + "printing_job_id": 123, + "printing_order_id": 456, + "external_order_id": "KD20441758", + "customer_id": 10, + "customer_name": "客户A", + "shipment_id": null, + "shipment_date": null, + "merge_remark": null, + "created_at": "2026-01-14T10:00:00Z", + "created_by_id": 1, + "created_by_name": "张三" +} +``` + +详情接口额外包含： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `product_image_url` | string/null | 关联生产任务产品主图 URL | + +### ShipmentDelivery + +```json +{ + "id": 1, + "merchant_id": 1, + "merchant_name": "测试印花厂", + "driver_name": "司机A", + "vehicle_trip": "浙A12345", + "contact_phone": "13800138000", + "vehicle_capacity": "4.2米", + "remark": "备注", + "internal_remark": "内部备注", + "shipment_order_ids": [1, 2, 3], + "status": 1, + "status_display": "待送货", + "started_at": null, + "delivered_at": null, + "cancelled_at": null, + "shipments_count": 2, + "shipments": [], + "created_by_id": 1, + "created_by_name": "张三", + "operator_id": null, + "operator_name": null, + "cancelled_by_id": null, + "cancelled_by_name": null, + "created_at": "2026-01-14T10:00:00Z", + "updated_at": "2026-01-14T10:00:00Z" +} +``` + +`shipments` 内元素为送货单内出货单摘要： + +```json +{ + "id": 1, + "customer": 10, + "customer_name": "客户A", + "fabric": "面料信息", + "order_description": "订单描述", + "shipment_date": "2026-01-14", + "status": 5, + "status_display": "已审核", + "external_id": null, + "delivery_id": 1 +} +``` + +## 出货单接口 + +### 查询出货单列表 + +`GET /api/v1/shipment/shipments/` + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `customer` | integer | 否 | 客户 ID | +| `status` | integer | 否 | 出货单状态 | +| `delivery_id` | integer | 否 | 送货单 ID；空字符串、`null`、`none` 不触发过滤 | +| `delivery_isnull` | boolean | 否 | `true/1/yes` 查未绑定送货单，`false/0/no` 查已绑定送货单 | +| `external_id` | string | 否 | 外部订单号精确匹配 | +| `shipment_date_from` | date | 否 | 出货日期起始，`YYYY-MM-DD` | +| `shipment_date_to` | date | 否 | 出货日期结束，`YYYY-MM-DD` | +| `only_address_null` | boolean | 否 | `true` 查地址为空字符串，`false` 查地址非空 | +| `limit` | integer | 否 | 分页大小 | +| `offset` | integer | 否 | 分页偏移 | + +响应：分页 `Shipment[]`。 + +### 创建出货单 + +`POST /api/v1/shipment/shipments/` + +请求体： + +```json +{ + "customer": 10, + "address_id": 5, + "shipment_date": "2026-01-14", + "address": "杭州市测试路 1 号", + "contact_name": "张三", + "contact_phone": "13800138000", + "area": "华东", + "coordinates": "120.1551,30.2741", + "extra": {"source": "customer_address"}, + "remark": "备注", + "sales_items": [1, 2, 3] +} +``` + +请求字段： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `customer` | integer | 是 | 客户 ID | +| `address_id` | integer/null | 否 | 客户地址 ID；仅校验和关联 | +| `shipment_date` | date | 是 | 出货日期 | +| `address` | string | 否 | 地址快照，默认 `""`，最大 255 | +| `contact_name` | string | 否 | 联系人快照，默认 `""`，最大 100 | +| `contact_phone` | string | 否 | 联系电话快照，默认 `""`，最大 50 | +| `area` | string | 否 | 地区快照，默认 `""`，最大 100 | +| `coordinates` | string/null | 否 | 经纬度字符串，最大 100 | +| `extra` | JSON/null | 否 | 扩展信息 | +| `remark` | string | 否 | 出货单备注，默认 `""` | +| `sales_items` | integer[] | 否 | 要关联的销售品 ID 列表，默认 `[]`，后端会去重 | + +业务规则： + +- 用户必须关联商户。 +- 客户必须属于当前商户。 +- `address_id` 存在时，客户地址必须存在、未软删除、属于当前商户、属于请求中的 `customer`。 +- `sales_items` 非空时，销售品必须存在、未删除、未绑定其他出货单、属于当前商户，并且都来自同一个生产订单。 + +响应：`201 Shipment`。 + +### 创建外部出货单 + +`POST /api/v1/shipment/shipments/external/` + +用于没有内部销售品、但需要记录外部成品表的出货单。 + +请求体： + +```json +{ + "customer": 10, + "shipment_date": "2026-01-14", + "address": "杭州市测试路 1 号", + "contact_name": "张三", + "contact_phone": "13800138000", + "area": "华东", + "coordinates": "120.1551,30.2741", + "extra": {"source": "external"}, + "remark": "备注", + "external_id": "EXT-001", + "external_finished_products": [ + { + "style_name": "款式A", + "num_of_rolls": 10, + "remark": "成品备注" + } + ] +} +``` + +请求字段： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `customer` | integer | 是 | 客户 ID | +| `shipment_date` | date | 是 | 出货日期 | +| `address` | string | 否 | 地址，最大 255 | +| `contact_name` | string | 否 | 联系人，最大 100 | +| `contact_phone` | string | 否 | 联系电话，最大 50 | +| `area` | string | 否 | 地区，最大 100 | +| `coordinates` | string/null | 否 | 经纬度字符串，最大 100 | +| `extra` | JSON/null | 否 | 扩展信息 | +| `remark` | string | 否 | 备注 | +| `external_id` | string | 是 | 外部订单号，不能为空，最大 120 | +| `external_finished_products` | array | 是 | 外部成品表，不能为空 | + +`external_finished_products` 元素： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `style_name` | string | 是 | 款式名，最大 200 | +| `num_of_rolls` | integer | 是 | 卷数，最小 0 | +| `remark` | string/null | 否 | 备注，最大 200 | + +响应：`201 Shipment`。 + +### 获取出货单详情 + +`GET /api/v1/shipment/shipments/{id}/` + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | integer | 否 | 可选状态过滤；不匹配则返回 404 | + +响应：`200 Shipment`。 + +### 更新出货单 + +`PATCH /api/v1/shipment/shipments/{id}/` + +`PUT /api/v1/shipment/shipments/{id}/` + +当前 `PUT` 行为等同 `PATCH`，允许只传部分字段。 + +请求体： + +```json +{ + "customer": 10, + "shipment_date": "2026-01-15", + "address": "新地址", + "contact_name": "李四", + "contact_phone": "13900139000", + "area": "华南", + "coordinates": null, + "extra": null, + "remark": "新备注", + "external_id": "EXT-002", + "geo_coordinates": {"lng": 120.1, "lat": 30.2} +} +``` + +可更新字段： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `customer` | integer | 客户 ID | +| `shipment_date` | date | 出货日期 | +| `address` | string | 地址，最大 255 | +| `contact_name` | string | 联系人，最大 100 | +| `contact_phone` | string | 联系电话，最大 50 | +| `area` | string | 地区，最大 100 | +| `coordinates` | string/null | 经纬度字符串；传 `null` 可清空 | +| `extra` | JSON/null | 扩展信息；传 `null` 可清空 | +| `remark` | string | 备注 | +| `external_id` | string/null | 外部订单号；空字符串或 `null` 会清空 | +| `geo_coordinates` | JSON/null | 当前 serializer 接收该字段，但业务更新服务未保存它，前端不建议使用 | + +业务规则： + +- 已关联送货单的出货单不允许修改业务数据。 +- 修改客户时，新客户必须存在且属于同一商户。 + +响应：`200 Shipment`。 + +### 修改出货单状态 + +`PATCH /api/v1/shipment/shipments/{id}/status/` + +`PUT /api/v1/shipment/shipments/{id}/status/` + +请求体： + +```json +{ + "status": 5 +} +``` + +响应：`200 Shipment`。 + +## 送货单接口 + +### 查询送货单列表 + +`GET /api/v1/shipment/deliveries/` + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | integer | 否 | 送货单状态 | +| `driver_name` | string | 否 | 司机名模糊匹配 | +| `vehicle_trip` | string | 否 | 车次模糊匹配 | +| `limit` | integer | 否 | 分页大小 | +| `offset` | integer | 否 | 分页偏移 | + +响应：分页 `ShipmentDelivery[]`。 + +### 创建送货单 + +`POST /api/v1/shipment/deliveries/` + +请求体： + +```json +{ + "driver_name": "司机A", + "vehicle_trip": "浙A12345", + "contact_phone": "13800138000", + "vehicle_capacity": "4.2米", + "remark": "备注", + "internal_remark": "内部备注", + "shipment_order_ids": [3, 2, 1], + "shipments": [1, 2, 3] +} +``` + +请求字段： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `driver_name` | string | 是 | 司机名，最大 100 | +| `vehicle_trip` | string | 是 | 车次，最大 100 | +| `contact_phone` | string | 否 | 联系电话，默认 `""`，最大 50 | +| `vehicle_capacity` | string | 否 | 车辆容量，默认 `""`，最大 100 | +| `remark` | string | 否 | 备注，默认 `""`，最大 200 | +| `internal_remark` | string | 否 | 内部备注，默认 `""`，最大 200 | +| `shipment_order_ids` | array/null | 否 | 前端自管出货单排序 ID 数组，可为 `null` | +| `shipments` | integer[] | 否 | 要关联的出货单 ID 列表，默认 `[]`，后端会去重 | + +响应：`201 ShipmentDelivery`。 + +### 按生产订单查询送货单 + +`GET /api/v1/shipment/deliveries/by-printing-order/{printing_order_id}/` + +路径参数： + +- `printing_order_id` 支持内部 `PrintingOrder.id` 或 `external_order_id`。 +- 如果 `external_order_id` 匹配多个生产订单，返回 `500 { "message": "...请改用内部ID查询" }`。 + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `status` | integer | 否 | 送货单状态 | +| `driver_name` | string | 否 | 模糊匹配 | +| `vehicle_trip` | string | 否 | 模糊匹配 | +| `contact_phone` | string | 否 | 模糊匹配 | +| `vehicle_capacity` | string | 否 | 模糊匹配 | +| `remark` | string | 否 | 模糊匹配 | +| `internal_remark` | string | 否 | 模糊匹配 | +| `started_at_from` | date/datetime | 否 | 开始送货时间起 | +| `started_at_to` | date/datetime | 否 | 开始送货时间止 | +| `delivered_at_from` | date/datetime | 否 | 送达时间起 | +| `delivered_at_to` | date/datetime | 否 | 送达时间止 | +| `cancelled_at_from` | date/datetime | 否 | 取消时间起 | +| `cancelled_at_to` | date/datetime | 否 | 取消时间止 | +| `created_at_from` | date/datetime | 否 | 创建时间起 | +| `created_at_to` | date/datetime | 否 | 创建时间止 | +| `shipment_date_from` | date | 否 | 关联出货日期起 | +| `shipment_date_to` | date | 否 | 关联出货日期止 | +| `ordering` | string | 否 | 可选 `id/created_at/updated_at/started_at/delivered_at/cancelled_at/status`，支持前缀 `-` | +| `limit` | integer | 否 | 分页大小 | +| `offset` | integer | 否 | 分页偏移 | + +响应：分页 `ShipmentDelivery[]`，字段使用专用 DTO，不包含 `cancelled_by_id/cancelled_by_name`。 + +### 获取送货单详情 + +`GET /api/v1/shipment/deliveries/{id}/` + +响应：`200 ShipmentDelivery`。 + +### 更新送货单 + +`PATCH /api/v1/shipment/deliveries/{id}/` + +`PUT /api/v1/shipment/deliveries/{id}/` + +当前 `PUT` 行为等同 `PATCH`。 + +请求体： + +```json +{ + "driver_name": "司机B", + "vehicle_trip": "浙B12345", + "contact_phone": "13900139000", + "vehicle_capacity": "9.6米", + "remark": "新备注", + "internal_remark": "新内部备注", + "shipment_order_ids": [2, 1], + "shipments": [1, 2] +} +``` + +可更新字段： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `driver_name` | string | 司机名，最大 100，不允许空字符串 | +| `vehicle_trip` | string | 车次，最大 100，不允许空字符串 | +| `contact_phone` | string | 联系电话，最大 50 | +| `vehicle_capacity` | string | 车辆容量，最大 100 | +| `remark` | string | 备注，最大 200 | +| `internal_remark` | string | 内部备注，最大 200 | +| `shipment_order_ids` | array/null | 前端自管排序 ID 数组，传入即更新 | +| `shipments` | integer[] | 传入即替换当前绑定出货单 | + +响应：`200 ShipmentDelivery`。 + +### 删除送货单 + +`DELETE /api/v1/shipment/deliveries/{id}/` + +响应：`204 No Content`。 + +### 修改送货单状态 + +`POST /api/v1/shipment/deliveries/{id}/status/` + +请求体： + +```json +{ + "status": 2 +} +``` + +允许状态：`1`、`2`、`3`。 + +响应：`200 ShipmentDelivery`。 + +### 取消送货单 + +`POST /api/v1/shipment/deliveries/{id}/cancel/` + +权限：需要 `shipment.cancel_shipmentdelivery`。 + +响应：`200 ShipmentDelivery`。 + +### 追加绑定出货单到送货单 + +`POST /api/v1/shipment/deliveries/{id}/bind-shipments/` + +请求体： + +```json +{ + "shipments": [4, 5] +} +``` + +请求字段： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `shipments` | integer[] | 是 | 要追加绑定的出货单 ID，不能为空，后端会去重 | + +响应：`200 ShipmentDelivery`。 + +## 销售品接口 + +### 查询当前可出货客户 + +`GET /api/v1/shipment/sales-items/customers/` + +从未出货销售品反推出客户列表。 + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `merchant` | integer | 超级管理员必填 | 超级管理员必须传商户 ID；普通用户忽略 | +| `customer_name` | string | 否 | 客户名称模糊匹配 | +| `limit` | integer | 否 | 分页大小 | +| `offset` | integer | 否 | 分页偏移 | + +响应： + +```json +{ + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "customer_id": 10, + "customer_name": "客户A", + "mobile": "13900139000", + "area": "杭州", + "unshipped_sales_items_count": 3 + } + ] +} +``` + +### 按客户查询销售品 + +`GET /api/v1/shipment/sales-items/by-customer/{customer_id}/` + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `include_already_has_shipment` | boolean | 否 | 是否包含已关联出货单销售品，默认 `false`；只有字符串 `true` 会视为真 | +| `external_order_id` | string | 否 | 按生产订单外部订单号过滤 | +| `limit` | integer | 否 | 分页大小 | +| `offset` | integer | 否 | 分页偏移 | + +响应：分页 `SalesItem[]`。 + +### 按客户查询销售品分组 + +`GET /api/v1/shipment/sales-items/by-customer/{customer_id}/group/` + +第一层按 `external_order_id` 分组并分页，第二层按 `name` 分组。 + +查询参数同“按客户查询销售品”。 + +响应： + +```json +{ + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "external_order_id": "KD20441758", + "count": 2, + "name_groups": [ + { + "name": "销售品A", + "count": 2, + "items": [] + } + ] + } + ] +} +``` + +排序：`external_order_id = null` 排最后。 + +### 按生产订单查询销售品 + +`GET /api/v1/shipment/sales-items/by-printing-order/{printing_order_id}/` + +路径参数： + +- `printing_order_id` 支持内部 `PrintingOrder.id` 或 `external_order_id`。 +- 如果 `external_order_id` 匹配多个生产订单，此接口返回 `400 { "detail": "...请改用内部ID查询" }`。 + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `include_already_has_shipment` | boolean | 否 | 是否包含已关联出货单销售品，默认 `false`；只有字符串 `true` 会视为真 | + +响应： + +```json +{ + "count": 2, + "results": [] +} +``` + +`results` 为 `SalesItem[]`，该接口不使用标准分页。 + +### 按生产订单查询销售品分组 + +`GET /api/v1/shipment/sales-items/by-printing-order/{printing_order_id}/group/` + +按 `printing_job_id` 分组并分页。 + +查询参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `include_already_has_shipment` | boolean | 否 | 是否包含已关联出货单销售品，默认 `false` | +| `limit` | integer | 否 | 分页大小，作用于分组数量 | +| `offset` | integer | 否 | 分页偏移，作用于分组数量 | + +响应： + +```json +{ + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "printing_job_id": 123, + "count": 2, + "items": [] + } + ] +} +``` + +### 手动创建销售品 + +`POST /api/v1/shipment/sales-items/` + +请求体： + +```json +{ + "printing_job_id": 123, + "name": "销售品A", + "quantity": "100.50", + "unit": 1, + "customer_id": 10, + "remark": "备注", + "position": "A1-01", + "merge_remark": { + "merge_type": "merge", + "jobs": [1, 2], + "main_job": 1, + "quantity": "100.50", + "unit": "米", + "job_count": 2 + } +} +``` + +请求字段： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `printing_job_id` | integer | 是 | 生产任务 ID，最小 1 | +| `name` | string | 是 | 销售品名称，最大 200 | +| `quantity` | string | 是 | 数量，最大 20，支持小数 | +| `unit` | integer | 是 | 单位：`1/2/3/4` | +| `customer_id` | integer/null | 否 | 客户 ID；不传时默认从生产订单获取 | +| `remark` | string | 否 | 备注，最大 200 | +| `position` | string | 否 | 货位，最大 200 | +| `merge_remark` | object/null | 否 | 合卷备注 JSON，结构严格校验 | + +`merge_remark` 必须只包含这些字段：`merge_type`、`jobs`、`main_job`、`quantity`、`unit`、`job_count`。 + +响应：`201 SalesItem`。 + +### 获取销售品详情 + +`GET /api/v1/shipment/sales-items/{id}/` + +响应：`200 SalesItem`，包含 `product_image_url`。 + +### 更新销售品 + +`PATCH /api/v1/shipment/sales-items/{id}/` + +请求体只能包含以下字段： + +```json +{ + "quantity": "80.00", + "remark": "新备注", + "position": "B2-01" +} +``` + +可更新字段： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `quantity` | string | 数量，支持小数 | +| `remark` | string | 备注，最大 200 | +| `position` | string | 货位，最大 200 | + +如果请求包含其他字段，返回 `400`。 + +响应：`200 SalesItem`，包含 `product_image_url`。 + +### 删除销售品 + +`DELETE /api/v1/shipment/sales-items/{id}/` + +权限：需要 `shipment.soft_delete_salesitem`。 + +响应： + +```json +{ + "detail": "销售品已标记为删除" +} +``` + +### 重建销售品 + +`POST /api/v1/shipment/sales-items/{id}/rebuild/` + +仅销售品创建者可执行。 + +请求体： + +```json +{ + "new_printing_job_id": 456, + "quantity": "50.00" +} +``` + +请求字段： + +| 字段 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `new_printing_job_id` | integer | 是 | 新生产任务 ID，最小 1 | +| `quantity` | string | 否 | 新数量；不传则沿用原销售品数量 | + +响应：`200 SalesItem`。 + +## 前端重点注意 + +- 创建出货单时，`address_id` 不会自动填充地址快照。前端若选择客户地址，需要同时把地址表中的 `address/contact_name/contact_phone/area/coordinates/extra` 放入创建请求。 +- `coordinates` 是新的字符串字段，前端不要再把新数据写到 `geo_coordinates`。 +- `geo_coordinates` 是历史兼容字段，读取时可能存在旧值，但更新接口目前不保存它。 +- `area` 现在最大 100 字符，可以直接承载客户地址的 `area`。 +- `extra` 可用于承载客户地址扩展信息，允许对象、数组或 `null`。 +- 更新出货单时，传 `coordinates: null` 或 `extra: null` 可以清空对应字段；不传则不修改。 +- 按生产订单查送货单的 `external_order_id` 多匹配错误返回 `500 + message`；按生产订单查销售品的同类错误返回 `400 + detail`。 diff --git a/docs/api_v1_shipment_deliveries_by_printing_order_2026-07-08.md b/docs/api_v1_shipment_deliveries_by_printing_order_2026-07-08.md new file mode 100644 index 0000000..53cc8fd --- /dev/null +++ b/docs/api_v1_shipment_deliveries_by_printing_order_2026-07-08.md @@ -0,0 +1,198 @@ +# API v1 Shipment Deliveries By Printing Order + +## Scope + +该接口用于按生产订单查询相关送货单，也就是司机/车次相关的送货数据。 + +查询链路： + +```text +PrintingOrder -> PrintingJob -> SalesItem -> Shipment -> ShipmentDelivery +``` + +只返回已经关联到送货单的出货数据。没有绑定送货单的 `Shipment` 不会出现在结果中。 + +## Endpoint + +```http +GET /api/v1/shipment/deliveries/by-printing-order/{printing_order_id}/ +``` + +需要登录。 + +## Path Parameters + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `printing_order_id` | string | yes | 支持生产订单内部 ID，也支持 `PrintingOrder.external_order_id` | + +解析规则： + +- 如果 `printing_order_id` 是纯数字，优先按内部 `PrintingOrder.id` 查询。 +- 如果内部 ID 未命中，再按 `external_order_id` 查询。 +- 如果不是纯数字，按 `external_order_id` 查询。 +- 如果 `external_order_id` 匹配多个生产订单，返回 HTTP 500 和明确 `message`。 + +## Query Parameters + +| Parameter | Description | +| --- | --- | +| `status` | 送货单状态精确过滤 | +| `driver_name` | 司机名模糊过滤 | +| `vehicle_trip` | 车次模糊过滤 | +| `contact_phone` | 联系电话模糊过滤 | +| `vehicle_capacity` | 车辆容量模糊过滤 | +| `remark` | 备注模糊过滤 | +| `internal_remark` | 内部备注模糊过滤 | +| `started_at_from` | 开始送货时间起始 | +| `started_at_to` | 开始送货时间截止 | +| `delivered_at_from` | 送达时间起始 | +| `delivered_at_to` | 送达时间截止 | +| `cancelled_at_from` | 取消时间起始 | +| `cancelled_at_to` | 取消时间截止 | +| `created_at_from` | 送货单创建时间起始 | +| `created_at_to` | 送货单创建时间截止 | +| `shipment_date_from` | 关联出货单出货日期起始，格式 `YYYY-MM-DD` | +| `shipment_date_to` | 关联出货单出货日期截止，格式 `YYYY-MM-DD` | +| `ordering` | 排序字段 | +| `limit` | 分页数量 | +| `offset` | 分页偏移 | + +时间参数说明： + +- `*_at_from` / `*_at_to` 支持日期或 datetime 字符串。 +- 如果传日期，例如 `2026-07-01`，会按对应字段的日期部分过滤。 +- 如果传 datetime，例如 `2026-07-01T09:00:00+08:00`，会按完整时间过滤。 + +`ordering` 支持： + +```text +id +-id +created_at +-created_at +updated_at +-updated_at +started_at +-started_at +delivered_at +-delivered_at +cancelled_at +-cancelled_at +status +-status +``` + +默认排序：`-created_at, -id`。 + +## Response + +分页响应。 + +```json +{ + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "id": 12, + "merchant_id": 1, + "merchant_name": "测试印花厂", + "driver_name": "张司机", + "vehicle_trip": "KD-001", + "contact_phone": "13800138000", + "vehicle_capacity": "9.6米厢车", + "remark": "外部备注", + "internal_remark": "内部备注", + "shipment_order_ids": [101, 102], + "status": 2, + "status_display": "送货中", + "started_at": "2026-07-01T09:00:00+08:00", + "delivered_at": null, + "cancelled_at": null, + "shipments_count": 2, + "shipments": [ + { + "id": 101, + "customer": 3, + "customer_name": "客户A", + "fabric": "全棉", + "order_description": "订单描述", + "shipment_date": "2026-07-01", + "status": 5, + "status_display": "已审核", + "external_id": null, + "delivery_id": 12 + } + ], + "created_by_id": 5, + "created_by_name": "业务员A", + "operator_id": null, + "operator_name": null, + "created_at": "2026-07-01T08:00:00+08:00", + "updated_at": "2026-07-01T09:00:00+08:00" + } + ] +} +``` + +## Examples + +按内部生产订单 ID 查询： + +```http +GET /api/v1/shipment/deliveries/by-printing-order/9986/ +``` + +按外部生产订单号查询： + +```http +GET /api/v1/shipment/deliveries/by-printing-order/KD20441758/ +``` + +按司机、状态和出货日期过滤： + +```http +GET /api/v1/shipment/deliveries/by-printing-order/KD20441758/?status=2&driver_name=张&shipment_date_from=2026-07-01&shipment_date_to=2026-07-31 +``` + +分页和排序： + +```http +GET /api/v1/shipment/deliveries/by-printing-order/KD20441758/?ordering=id&limit=20&offset=0 +``` + +## Error Responses + +| Condition | Status | Response | +| --- | --- | --- | +| 未登录 | 401 | 全局认证错误结构 | +| 当前商户下找不到生产订单 | 404 | `{ "detail": "生产订单 {printing_order_id} 不存在" }` | +| `external_order_id` 匹配多个生产订单 | 500 | `{ "message": "external_order_id ... 匹配到多个生产订单，请改用内部ID查询" }` | + +## Notes + +- 普通用户只能查询自己员工所属商户下的生产订单和送货单。 +- superuser 不受商户限制。 +- 一个送货单可能通过多个销售品命中同一个生产订单，接口会对送货单去重。 +- 查询只统计未软删除的 `SalesItem`。 +- 响应使用专用 DTO：`ShipmentDeliveryByPrintingOrderSerializer`，后续可以独立调整字段，不影响普通送货单列表接口。 + +## Test Coverage + +Dedicated tests: + +```bash +docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py test api_v1.views.shipment.test_api.ShipmentDeliveryByPrintingOrderAPITestCase --keepdb --noinput +``` + +Covered behavior: + +- 按内部 `PrintingOrder.id` 查询。 +- 按 `external_order_id` 查询。 +- 司机、状态、车次、电话、车辆容量、备注、内部备注过滤。 +- 开始送货时间和出货日期范围过滤。 +- 分页和排序。 +- 送货单去重。 +- `external_order_id` 多匹配返回 HTTP 500 和明确 `message`。 diff --git a/flower-app_latest.tar.gz b/flower-app_latest.tar.gz new file mode 100644 index 0000000..426b3ca Binary files /dev/null and b/flower-app_latest.tar.gz differ diff --git a/flower/app_version.py b/flower/app_version.py index 49e59ce..991b8cc 100644 --- a/flower/app_version.py +++ b/flower/app_version.py @@ -1,5 +1,6 @@ from django.conf import settings from django.core.cache import cache +from django.utils import timezone from rest_framework.permissions import AllowAny from rest_framework.response import Response from rest_framework.views import APIView @@ -12,7 +13,19 @@ def _coerce_version_part(value) -> int: return max(0, int(value or 0)) -def build_app_version_payload(*, major, minor, build, download_url: str) -> dict: +def _coerce_publish_date(value) -> str: + return str(value or timezone.localdate().isoformat()).strip() + + +def build_app_version_payload( + *, + major, + minor, + build, + download_url: str, + force=False, + publish_date=None, +) -> dict: return { "latest_version": { "major": _coerce_version_part(major), @@ -20,6 +33,8 @@ def build_app_version_payload(*, major, minor, build, download_url: str) -> dict "build": _coerce_version_part(build), }, "download_url": str(download_url or "").strip(), + "force": bool(force), + "publish_date": _coerce_publish_date(publish_date), } @@ -33,6 +48,8 @@ def get_app_version_payload() -> dict: minor=version["minor"], build=version["build"], download_url=cached_payload.get("download_url", ""), + force=cached_payload["force"], + publish_date=cached_payload["publish_date"], ) except (KeyError, TypeError, ValueError): pass @@ -42,15 +59,27 @@ def get_app_version_payload() -> dict: minor=getattr(settings, "APP_LATEST_VERSION_MINOR", 0), build=getattr(settings, "APP_LATEST_VERSION_BUILD", 0), download_url=getattr(settings, "APP_DOWNLOAD_URL", ""), + force=getattr(settings, "APP_FORCE_UPDATE", False), + publish_date=getattr(settings, "APP_PUBLISH_DATE", None), ) -def set_cached_app_version_payload(*, major, minor, build, download_url: str) -> dict: +def set_cached_app_version_payload( + *, + major, + minor, + build, + download_url: str, + force=False, + publish_date=None, +) -> dict: payload = build_app_version_payload( major=major, minor=minor, build=build, download_url=download_url, + force=force, + publish_date=publish_date, ) cache.set(APP_VERSION_CACHE_KEY, payload, timeout=None) return payload diff --git a/flower/settings.py b/flower/settings.py index cf2333c..05df633 100644 --- a/flower/settings.py +++ b/flower/settings.py @@ -117,6 +117,8 @@ APP_LATEST_VERSION_MAJOR = env.int('APP_LATEST_VERSION_MAJOR', default=0) APP_LATEST_VERSION_MINOR = env.int('APP_LATEST_VERSION_MINOR', default=0) APP_LATEST_VERSION_BUILD = env.int('APP_LATEST_VERSION_BUILD', default=0) APP_DOWNLOAD_URL = env('APP_DOWNLOAD_URL', default='') +APP_FORCE_UPDATE = env.bool('APP_FORCE_UPDATE', default=False) +APP_PUBLISH_DATE = env('APP_PUBLISH_DATE', default='') # 定时财务同步客户列表（临时需求，直接写死不走 env） FINANCE_SYNC_CUSTOMER_NAMES: list[str] = [ diff --git a/flower/test_app_version_api.py b/flower/test_app_version_api.py index 74bc235..9c1a6cf 100644 --- a/flower/test_app_version_api.py +++ b/flower/test_app_version_api.py @@ -3,6 +3,7 @@ from io import StringIO from django.core.cache import cache from django.core.management import call_command from django.test import TestCase, override_settings +from django.utils import timezone from rest_framework.test import APIClient from flower.app_version import APP_VERSION_CACHE_KEY @@ -21,6 +22,8 @@ class AppVersionAPITest(TestCase): APP_LATEST_VERSION_MINOR=2, APP_LATEST_VERSION_BUILD=345, APP_DOWNLOAD_URL="https://example.com/app.apk", + APP_FORCE_UPDATE=True, + APP_PUBLISH_DATE="2026-07-08", ) def test_app_version_api_returns_settings_payload_without_auth(self): response = self.client.get("/api/app-version/") @@ -35,10 +38,12 @@ class AppVersionAPITest(TestCase): "build": 345, }, "download_url": "https://example.com/app.apk", + "force": True, + "publish_date": "2026-07-08", }, ) - def test_set_app_version_command_updates_cached_api_payload(self): + def test_set_app_version_command_updates_cached_api_payload_with_defaults(self): output = StringIO() call_command( "set_app_version", @@ -58,4 +63,32 @@ class AppVersionAPITest(TestCase): self.assertEqual(response.status_code, 200) self.assertEqual(response.data["latest_version"], {"major": 2, "minor": 5, "build": 1001}) self.assertEqual(response.data["download_url"], "https://example.com/latest.apk") + self.assertEqual(response.data["force"], False) + self.assertEqual(response.data["publish_date"], timezone.localdate().isoformat()) self.assertIn("'build': 1001", output.getvalue()) + + def test_set_app_version_command_accepts_force_and_publish_date(self): + output = StringIO() + call_command( + "set_app_version", + "--major", + "2", + "--minor", + "6", + "--build", + "1002", + "--download-url", + "https://example.com/force.apk", + "--force", + "--publish-date", + "2026-07-01", + stdout=output, + ) + + response = self.client.get("/api/app-version/") + + self.assertEqual(response.status_code, 200) + self.assertEqual(response.data["latest_version"], {"major": 2, "minor": 6, "build": 1002}) + self.assertEqual(response.data["download_url"], "https://example.com/force.apk") + self.assertEqual(response.data["force"], True) + self.assertEqual(response.data["publish_date"], "2026-07-01") diff --git a/printing/migrations/0040_printingorder_kd_riqi.py b/printing/migrations/0040_printingorder_kd_riqi.py new file mode 100644 index 0000000..ee982c8 --- /dev/null +++ b/printing/migrations/0040_printingorder_kd_riqi.py @@ -0,0 +1,18 @@ +# Generated by Django 5.2.8 on 2026-07-08 11:57 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('printing', '0039_printingjob_sub_id'), + ] + + operations = [ + migrations.AddField( + model_name='printingorder', + name='kd_riqi', + field=models.DateTimeField(blank=True, db_index=True, null=True, verbose_name='外部开单日期时间'), + ), + ] diff --git a/printing/models.py b/printing/models.py index eafbcce..7cd544d 100644 --- a/printing/models.py +++ b/printing/models.py @@ -388,6 +388,12 @@ class PrintingOrder(ModelBase): null=True, verbose_name='外部员工名', ) + kd_riqi = models.DateTimeField( + null=True, + blank=True, + db_index=True, + verbose_name='外部开单日期时间', + ) external_raw = models.JSONField( default=dict, blank=True, diff --git a/shipment/migrations/0026_shipment_customer_address.py b/shipment/migrations/0026_shipment_customer_address.py new file mode 100644 index 0000000..05eb8d8 --- /dev/null +++ b/shipment/migrations/0026_shipment_customer_address.py @@ -0,0 +1,20 @@ +# Generated by Django 5.2.8 on 2026-07-08 05:38 + +import django.db.models.deletion +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('basic_info', '0029_customeraddress_coordinates'), + ('shipment', '0025_alter_shipmentdelivery_options_and_more'), + ] + + operations = [ + migrations.AddField( + model_name='shipment', + name='customer_address', + field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='shipments', to='basic_info.customeraddress', verbose_name='客户地址'), + ), + ] diff --git a/shipment/migrations/0027_shipment_coordinates_shipment_extra_and_more.py b/shipment/migrations/0027_shipment_coordinates_shipment_extra_and_more.py new file mode 100644 index 0000000..e7b647c --- /dev/null +++ b/shipment/migrations/0027_shipment_coordinates_shipment_extra_and_more.py @@ -0,0 +1,28 @@ +# Generated by Django 5.2.8 on 2026-07-08 05:50 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('shipment', '0026_shipment_customer_address'), + ] + + operations = [ + migrations.AddField( + model_name='shipment', + name='coordinates', + field=models.CharField(blank=True, help_text='经纬度字符串，格式由调用方决定', max_length=100, null=True, verbose_name='经纬度'), + ), + migrations.AddField( + model_name='shipment', + name='extra', + field=models.JSONField(blank=True, null=True, verbose_name='扩展信息'), + ), + migrations.AlterField( + model_name='shipment', + name='area', + field=models.CharField(blank=True, default='', help_text='出货地区（可空字符串）', max_length=100, verbose_name='地区'), + ), + ] diff --git a/shipment/models.py b/shipment/models.py index 885ccf2..8b2fabb 100644 --- a/shipment/models.py +++ b/shipment/models.py @@ -149,6 +149,15 @@ class Shipment(ModelBase): related_name='shipments', verbose_name='客户' ) + + customer_address = models.ForeignKey( + basic_models.CustomerAddress, + on_delete=models.SET_NULL, + null=True, + blank=True, + related_name='shipments', + verbose_name='客户地址', + ) shipment_date = models.DateField( verbose_name='出货日期', @@ -177,12 +186,20 @@ class Shipment(ModelBase): ) area = models.CharField( - max_length=30, + max_length=100, blank=True, default='', verbose_name='地区', help_text='出货地区（可空字符串）', ) + + coordinates = models.CharField( + max_length=100, + null=True, + blank=True, + verbose_name='经纬度', + help_text='经纬度字符串，格式由调用方决定', + ) remark = models.TextField( blank=True, @@ -205,6 +222,12 @@ class Shipment(ModelBase): help_text='由 Geo 系统返回的坐标信息，结构由调用方决定，后端不作校验', ) + extra = models.JSONField( + null=True, + blank=True, + verbose_name='扩展信息', + ) + rejected_sales_item_ids = models.JSONField( default=list, blank=True, diff --git a/shipment/services.py b/shipment/services.py index b410e5b..559b00a 100644 --- a/shipment/services.py +++ b/shipment/services.py @@ -710,8 +710,10 @@ def update_shipment( contact_name: str | None = None, contact_phone: str | None = None, area: str | None = None, + coordinates=UNSET, remark: str | None = None, external_id: str | None = None, + extra=UNSET, ) -> Shipment: """ 更新出货单业务数据。 @@ -743,10 +745,14 @@ def update_shipment( shipment.contact_phone = contact_phone or "" if area is not None: shipment.area = (area or "").strip() + if coordinates is not UNSET: + shipment.coordinates = coordinates or None if remark is not None: shipment.remark = remark or "" if external_id is not None: shipment.external_id = (external_id or "").strip() or None + if extra is not UNSET: + shipment.extra = extra shipment.save() return shipment @@ -759,11 +765,15 @@ def create_shipment( shipment_date, sales_item_ids: List[int], created_by, + address_id: int | None = None, address: str = "", contact_name: str = "", contact_phone: str = "", remark: str = "", area: str = "", + coordinates: str | None = None, + extra: dict | list | None = None, + status: int = ShipmentStatus.DRAFT, ) -> Shipment: """ 创建出货单并关联销售品 @@ -781,7 +791,7 @@ def create_shipment( Raises: ValueError: 如果销售品不存在或已被关联到其他出货单 """ - from basic_info.models import Customer + from basic_info.models import Customer, CustomerAddress # 验证客户存在 try: @@ -798,6 +808,20 @@ def create_shipment( if customer.merchant_id != merchant.id: raise ValueError("无权限为该客户创建出货单") + customer_address = None + if address_id is not None: + try: + customer_address = CustomerAddress.objects.get(id=address_id) + except CustomerAddress.DoesNotExist: + raise ValueError(f"客户地址 {address_id} 不存在") + + if customer_address.deleted_at is not None: + raise ValueError(f"客户地址 {address_id} 已删除") + if customer_address.merchant_id != merchant.id: + raise ValueError("无权限使用该客户地址") + if customer_address.customer_id != customer.id: + raise ValueError("客户地址与客户不匹配") + # 验证销售品 if sales_item_ids: from printing.models import PrintingJob @@ -844,22 +868,20 @@ def create_shipment( f"以下销售品关联的生产任务不存在，无法创建出货单: {affected_item_ids}" ) - printing_order_ids = { - printing_job_map[item.printing_job_id] for item in sales_items_list - } - if len(printing_order_ids) > 1: - raise ValueError("出货单中的销售品必须来自同一个生产订单") - # 创建出货单 shipment = Shipment.objects.create( merchant=merchant, customer=customer, + customer_address=customer_address, shipment_date=shipment_date, address=address or "", contact_name=contact_name or "", contact_phone=contact_phone or "", area=(area or "").strip(), + coordinates=coordinates or None, remark=remark, + extra=extra, + status=status, created_by=created_by, ) @@ -996,6 +1018,8 @@ def create_external_shipment( contact_phone: str = "", remark: str = "", area: str = "", + coordinates: str | None = None, + extra: dict | list | None = None, ) -> Shipment: """ 创建出货单（external 版），并批量写入外部成品表并关联到出货单。 @@ -1035,7 +1059,9 @@ def create_external_shipment( contact_name=contact_name or "", contact_phone=contact_phone or "", area=(area or "").strip(), + coordinates=coordinates or None, remark=remark, + extra=extra, created_by=created_by, external_id=external_id, )