feat: sales return order and purchase return order

2025-12-01 16:52:59 +08:00
parent a3b4af2602
commit fae33809ac
17 changed files with 1745 additions and 6 deletions
--- a/business/ARCHITECTURE.md
+++ b/business/ARCHITECTURE.md
@@ -37,6 +37,8 @@

 - **PurchaseOrder**（采购单）：`direction=1`，`counterparty=supplier`，含库存明细。
 - **SalesOrder**（销售单）：`direction=-1`，`counterparty=customer`，含库存明细；严进严出模式需记录 `consume_detail_ids`。
+- **PurchaseReturnOrder**（采购退货单）：`direction=-1`，`counterparty=supplier`，仓库出库、供应商欠款减少，可选关联原采购单。
+- **SalesReturnOrder**（销售退货单）：`direction=1`，`counterparty=customer`，仓库入库、客户欠款减少，可选关联原销售单。
 - **PaymentOrder**（付款单）：`direction=-1`，`counterparty=supplier`，仅金额字段，不触发库存。
 - **ReceiptOrder**（收款单）：`direction=-1`，`counterparty=customer`，仅金额字段，不触发库存。
 - **SupplierBalance / CustomerBalance**：实时维护供应商应付、客户应收余额，所有审批通过的带金额单据都会写入，供查询接口和报表使用。
--- a/business/admin.py
+++ b/business/admin.py
@@ -49,6 +49,82 @@ class PurchaseOrderItemAdmin(admin.ModelAdmin):
        return obj.total_amount()


+@admin.register(models.PurchaseReturnOrder)
+class PurchaseReturnOrderAdmin(admin.ModelAdmin):
+    list_display = ('id', 'supplier', 'return_date', 'operator', 'status', '_total_amount', 'created_at')
+    search_fields = ('supplier__name',)
+    list_filter = ('operator', 'warehouse', 'status', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='总价')
+    def _total_amount(self, obj: models.PurchaseReturnOrder):
+        return obj.get_total_amount()
+
+
+@admin.register(models.PurchaseReturnOrderItem)
+class PurchaseReturnOrderItemAdmin(admin.ModelAdmin):
+    list_display = (
+        'id', 'purchase_return_order', 'product',
+        'quantity', 'unit', 'price', 'batch_number',
+        '_total_amount', 'empty_diff_percent',
+        '_real_quantity', '_diff_quantity',
+        'num_of_rolls',
+    )
+    search_fields = ('purchase_return_order__id', 'product__name')
+    list_filter = ('purchase_return_order__operator', 'purchase_return_order__warehouse', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='实际数量')
+    def _real_quantity(self, obj: models.PurchaseReturnOrderItem):
+        return obj.real_quantity()
+
+    @admin.display(description='差异数量')
+    def _diff_quantity(self, obj: models.PurchaseReturnOrderItem):
+        return obj.diff_quantity()
+
+    @admin.display(description='总金额')
+    def _total_amount(self, obj: models.PurchaseReturnOrderItem):
+        return obj.total_amount()
+
+
+@admin.register(models.SalesReturnOrder)
+class SalesReturnOrderAdmin(admin.ModelAdmin):
+    list_display = ('id', 'customer', 'return_date', 'operator', 'status', '_total_amount', 'created_at')
+    search_fields = ('customer__name',)
+    list_filter = ('operator', 'warehouse', 'status', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='总价')
+    def _total_amount(self, obj: models.SalesReturnOrder):
+        return obj.get_total_amount()
+
+
+@admin.register(models.SalesReturnOrderItem)
+class SalesReturnOrderItemAdmin(admin.ModelAdmin):
+    list_display = (
+        'id', 'sales_return_order', 'product',
+        'quantity', 'unit', 'price', 'batch_number',
+        '_total_amount', 'empty_diff_percent',
+        '_real_quantity', '_diff_quantity',
+        'num_of_rolls',
+    )
+    search_fields = ('sales_return_order__id', 'product__name')
+    list_filter = ('sales_return_order__operator', 'sales_return_order__warehouse', 'created_at')
+    ordering = ('-created_at',)
+
+    @admin.display(description='实际数量')
+    def _real_quantity(self, obj: models.SalesReturnOrderItem):
+        return obj.real_quantity()
+
+    @admin.display(description='差异数量')
+    def _diff_quantity(self, obj: models.SalesReturnOrderItem):
+        return obj.diff_quantity()
+
+    @admin.display(description='总金额')
+    def _total_amount(self, obj: models.SalesReturnOrderItem):
+        return obj.total_amount()
+
+
@admin.register(models.CustomerBalance)
 class CustomerBalancemAdmin(admin.ModelAdmin):
    list_display = ('id', 'customer', 'balance', 'created_at')
--- a/business/migrations/0014_alter_balancechangerecord_source_type_and_more.py
+++ b/business/migrations/0014_alter_balancechangerecord_source_type_and_more.py
@@ -0,0 +1,113 @@
+# Generated by Django 5.2.7 on 2025-12-01 08:22
+
+import business.models
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('basic_info', '0016_merchantsetting_type'),
+        ('business', '0013_balancechangerecord'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='balancechangerecord',
+            name='source_type',
+            field=models.IntegerField(choices=[(1, '采购单'), (2, '销售单'), (3, '付款单'), (4, '收款单'), (5, '采购退货单'), (6, '销售退货单')], verbose_name='来源业务类型'),
+        ),
+        migrations.CreateModel(
+            name='PurchaseReturnOrder',
+            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)),
+                ('return_date', models.DateField(verbose_name='退货日期')),
+                ('status', models.IntegerField(choices=[(1, '审批中'), (2, '审批通过'), (3, '作废')], default=1, verbose_name='状态')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.employee', verbose_name='经办人')),
+                ('purchase_order', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='return_orders', to='business.purchaseorder', verbose_name='原采购单')),
+                ('supplier', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.supplier', verbose_name='供应商')),
+                ('warehouse', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_orders', to='basic_info.warehouse', verbose_name='仓库')),
+            ],
+            options={
+                'verbose_name': '采购退货单',
+                'verbose_name_plural': '采购退货单',
+            },
+            bases=(business.models.OrderItemsAggregationMixin, business.models.OrderDirectionMixin, business.models.OrderCounterpartyMixin, models.Model),
+        ),
+        migrations.CreateModel(
+            name='PurchaseReturnOrderItem',
+            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)),
+                ('price', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='单价')),
+                ('color', models.CharField(blank=True, max_length=50, null=True, verbose_name='颜色')),
+                ('quantity', models.DecimalField(decimal_places=2, max_digits=10, verbose_name='数量')),
+                ('unit', models.CharField(max_length=50, verbose_name='单位')),
+                ('spec', models.CharField(blank=True, max_length=100, null=True, verbose_name='规格')),
+                ('empty_diff_percent', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='空差百分比')),
+                ('quantity_of_rolls', models.CharField(blank=True, max_length=255, null=True, verbose_name='各条数数量')),
+                ('num_of_rolls', models.PositiveIntegerField(default=1, verbose_name='条数')),
+                ('consume_detail_ids', models.CharField(blank=True, max_length=255, null=True, verbose_name='关联入库明细ID')),
+                ('batch_number', models.CharField(blank=True, max_length=100, null=True, verbose_name='批次号')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('product', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='purchase_return_order_items', to='basic_info.product', verbose_name='产品')),
+                ('purchase_return_order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='business.purchasereturnorder', verbose_name='采购退货单')),
+            ],
+            options={
+                'verbose_name': '采购退货明细',
+                'verbose_name_plural': '采购退货明细',
+            },
+        ),
+        migrations.CreateModel(
+            name='SalesReturnOrder',
+            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)),
+                ('return_date', models.DateField(verbose_name='退货日期')),
+                ('status', models.IntegerField(choices=[(1, '审批中'), (2, '审批通过'), (3, '作废')], default=1, verbose_name='状态')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('customer', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.customer', verbose_name='客户')),
+                ('merchant', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.merchant', verbose_name='所属商户')),
+                ('operator', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.employee', verbose_name='经办人')),
+                ('sales_order', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='return_orders', to='business.salesorder', verbose_name='原销售单')),
+                ('warehouse', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_orders', to='basic_info.warehouse', verbose_name='仓库')),
+            ],
+            options={
+                'verbose_name': '销售退货单',
+                'verbose_name_plural': '销售退货单',
+            },
+            bases=(business.models.OrderItemsAggregationMixin, business.models.OrderDirectionMixin, business.models.OrderCounterpartyMixin, models.Model),
+        ),
+        migrations.CreateModel(
+            name='SalesReturnOrderItem',
+            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)),
+                ('price', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='单价')),
+                ('color', models.CharField(blank=True, max_length=50, null=True, verbose_name='颜色')),
+                ('quantity', models.DecimalField(decimal_places=2, max_digits=10, verbose_name='数量')),
+                ('unit', models.CharField(max_length=50, verbose_name='单位')),
+                ('spec', models.CharField(blank=True, max_length=100, null=True, verbose_name='规格')),
+                ('empty_diff_percent', models.DecimalField(decimal_places=2, max_digits=15, verbose_name='空差百分比')),
+                ('quantity_of_rolls', models.CharField(blank=True, max_length=255, null=True, verbose_name='各条数数量')),
+                ('num_of_rolls', models.PositiveIntegerField(default=1, verbose_name='条数')),
+                ('consume_detail_ids', models.CharField(blank=True, max_length=255, null=True, verbose_name='关联入库明细ID')),
+                ('batch_number', models.CharField(blank=True, max_length=100, null=True, verbose_name='批次号')),
+                ('remarks', models.TextField(blank=True, null=True, verbose_name='备注')),
+                ('product', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='sales_return_order_items', to='basic_info.product', verbose_name='产品')),
+                ('sales_return_order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='items', to='business.salesreturnorder', verbose_name='销售退货单')),
+            ],
+            options={
+                'verbose_name': '销售退货明细',
+                'verbose_name_plural': '销售退货明细',
+            },
+        ),
+    ]
--- a/business/models.py
+++ b/business/models.py
@@ -318,6 +318,224 @@ class SalesOrderItem(ModelBase):
        return round(self.price * self.real_quantity(), 2)


+class PurchaseReturnStatusEnum(models.IntegerChoices):
+    PENDING = 1, '审批中'
+    APPROVED = 2, '审批通过'
+    CANCELLED = 3, '作废'
+
+
+class PurchaseReturnOrder(OrderItemsAggregationMixin, OrderDirectionMixin, OrderCounterpartyMixin, ModelBase):
+    """采购退货单（库存出库 + 供应商应付减少）"""
+
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='所属商户',
+    )
+    supplier = models.ForeignKey(
+        basic_info_models.Supplier,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='供应商',
+    )
+    purchase_order = models.ForeignKey(
+        'PurchaseOrder',
+        on_delete=models.SET_NULL,
+        related_name='return_orders',
+        null=True,
+        blank=True,
+        verbose_name='原采购单',
+    )
+    return_date = models.DateField(verbose_name='退货日期')
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='经办人',
+    )
+    warehouse = models.ForeignKey(
+        basic_info_models.WareHouse,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_orders',
+        verbose_name='仓库',
+    )
+    status = models.IntegerField(
+        choices=PurchaseReturnStatusEnum.choices,
+        default=PurchaseReturnStatusEnum.PENDING,
+        verbose_name='状态',
+    )
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '采购退货单'
+        verbose_name_plural = '采购退货单'
+
+    def __str__(self):
+        return f'采购退货 {self.id} - {self.supplier.name}'
+
+    def get_direction(self) -> int:
+        return -1
+
+    def get_counterparty_field_name(self) -> str:
+        return 'supplier'
+
+
+class PurchaseReturnOrderItem(ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    purchase_return_order = models.ForeignKey(
+        PurchaseReturnOrder,
+        on_delete=models.CASCADE,
+        related_name='items',
+        verbose_name='采购退货单',
+    )
+    product = models.ForeignKey(
+        basic_info_models.Product,
+        on_delete=models.PROTECT,
+        related_name='purchase_return_order_items',
+        verbose_name='产品',
+    )
+    price = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='单价')
+    color = models.CharField(max_length=50, null=True, blank=True, verbose_name='颜色')
+    quantity = models.DecimalField(max_digits=10, decimal_places=2, verbose_name='数量')
+    unit = models.CharField(max_length=50, verbose_name='单位')
+    spec = models.CharField(max_length=100, null=True, blank=True, verbose_name='规格')
+    empty_diff_percent = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='空差百分比')
+    quantity_of_rolls = models.CharField(max_length=255, null=True, blank=True, verbose_name='各条数数量')
+    num_of_rolls = models.PositiveIntegerField(default=1, verbose_name='条数')
+    consume_detail_ids = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        verbose_name='关联入库明细ID',
+    )
+    batch_number = models.CharField(null=True, blank=True, max_length=100, verbose_name='批次号')
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '采购退货明细'
+        verbose_name_plural = '采购退货明细'
+
+    def real_quantity(self):
+        return round(self.quantity * (1 - self.empty_diff_percent / 100), 2)
+
+    def diff_quantity(self):
+        return round(self.quantity * (self.empty_diff_percent / 100), 2)
+
+    def total_amount(self):
+        return round(self.price * self.real_quantity(), 2)
+
+
+class SalesReturnStatusEnum(models.IntegerChoices):
+    PENDING = 1, '审批中'
+    APPROVED = 2, '审批通过'
+    CANCELLED = 3, '作废'
+
+
+class SalesReturnOrder(OrderItemsAggregationMixin, OrderDirectionMixin, OrderCounterpartyMixin, ModelBase):
+    """销售退货单（库存入库 + 客户应收减少）"""
+
+    id = models.BigAutoField(primary_key=True)
+    merchant = models.ForeignKey(
+        basic_info_models.Merchant,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='所属商户',
+    )
+    customer = models.ForeignKey(
+        basic_info_models.Customer,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='客户',
+    )
+    sales_order = models.ForeignKey(
+        'SalesOrder',
+        on_delete=models.SET_NULL,
+        related_name='return_orders',
+        null=True,
+        blank=True,
+        verbose_name='原销售单',
+    )
+    return_date = models.DateField(verbose_name='退货日期')
+    operator = models.ForeignKey(
+        basic_info_models.Employee,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='经办人',
+    )
+    warehouse = models.ForeignKey(
+        basic_info_models.WareHouse,
+        on_delete=models.PROTECT,
+        related_name='sales_return_orders',
+        verbose_name='仓库',
+    )
+    status = models.IntegerField(
+        choices=SalesReturnStatusEnum.choices,
+        default=SalesReturnStatusEnum.PENDING,
+        verbose_name='状态',
+    )
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '销售退货单'
+        verbose_name_plural = '销售退货单'
+
+    def __str__(self):
+        return f'销售退货 {self.id} - {self.customer.name}'
+
+    def get_direction(self) -> int:
+        return 1
+
+    def get_counterparty_field_name(self) -> str:
+        return 'customer'
+
+
+class SalesReturnOrderItem(ModelBase):
+    id = models.BigAutoField(primary_key=True)
+    sales_return_order = models.ForeignKey(
+        SalesReturnOrder,
+        on_delete=models.CASCADE,
+        related_name='items',
+        verbose_name='销售退货单',
+    )
+    product = models.ForeignKey(
+        basic_info_models.Product,
+        on_delete=models.PROTECT,
+        related_name='sales_return_order_items',
+        verbose_name='产品',
+    )
+    price = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='单价')
+    color = models.CharField(max_length=50, null=True, blank=True, verbose_name='颜色')
+    quantity = models.DecimalField(max_digits=10, decimal_places=2, verbose_name='数量')
+    unit = models.CharField(max_length=50, verbose_name='单位')
+    spec = models.CharField(max_length=100, null=True, blank=True, verbose_name='规格')
+    empty_diff_percent = models.DecimalField(max_digits=15, decimal_places=2, verbose_name='空差百分比')
+    quantity_of_rolls = models.CharField(max_length=255, null=True, blank=True, verbose_name='各条数数量')
+    num_of_rolls = models.PositiveIntegerField(default=1, verbose_name='条数')
+    consume_detail_ids = models.CharField(
+        max_length=255,
+        null=True,
+        blank=True,
+        verbose_name='关联入库明细ID',
+    )
+    batch_number = models.CharField(null=True, blank=True, max_length=100, verbose_name='批次号')
+    remarks = models.TextField(blank=True, null=True, verbose_name='备注')
+
+    class Meta:
+        verbose_name = '销售退货明细'
+        verbose_name_plural = '销售退货明细'
+
+    def real_quantity(self):
+        return round(self.quantity * (1 - self.empty_diff_percent / 100), 2)
+
+    def diff_quantity(self):
+        return round(self.quantity * (self.empty_diff_percent / 100), 2)
+
+    def total_amount(self):
+        return round(self.price * self.real_quantity(), 2)
+
+
 class PaymentOrderStatusEnum(models.IntegerChoices):
    PENDING = 1, '审批中'
    APPROVED = 2, '审批通过'
@@ -474,6 +692,8 @@ class BalanceChangeSourceEnum(models.IntegerChoices):
    SALES_ORDER = 2, '销售单'
    PAYMENT_ORDER = 3, '付款单'
    RECEIPT_ORDER = 4, '收款单'
+    PURCHASE_RETURN_ORDER = 5, '采购退货单'
+    SALES_RETURN_ORDER = 6, '销售退货单'


 class BalanceChangeDirectionEnum(models.IntegerChoices):
--- a/business/services.py
+++ b/business/services.py
@@ -17,6 +17,8 @@ from . import models
 from .tasks import (
    create_purchase_order_stock_entries,
    create_sales_order_stock_entries,
+    create_purchase_return_order_stock_entries,
+    create_sales_return_order_stock_entries,
 )
 class BalanceService:
    @staticmethod
@@ -292,6 +294,150 @@ def create_sales_order(
    return sales_order


+def create_purchase_return_order(
+    *,
+    merchant: basic_info_models.Merchant,
+    supplier: basic_info_models.Supplier,
+    return_date,
+    warehouse: basic_info_models.WareHouse,
+    operator: basic_info_models.Employee,
+    items: List[Dict[str, Any]],
+    remarks: str | None = '',
+    purchase_order: models.PurchaseOrder | None = None,
+    purchase_order_id: int | None = None,
+    created_by=None,
+) -> models.PurchaseReturnOrder:
+    """
+    创建采购退货单，出库并冲减供应商欠款。
+    """
+    if not items:
+        raise ValueError('items 不能为空')
+
+    normalized_date = _normalize_order_date(return_date)
+    normalized_items, _ = _normalize_order_items(
+        merchant=merchant,
+        warehouse=warehouse,
+        items=items,
+        is_outgoing=True,
+    )
+
+    resolved_purchase_order = purchase_order
+    if resolved_purchase_order is None and purchase_order_id:
+        resolved_purchase_order = models.PurchaseOrder.objects.filter(
+            id=purchase_order_id,
+            merchant=merchant,
+        ).first()
+        if resolved_purchase_order is None:
+            raise ValueError('关联的采购单不存在或不属于当前商户')
+    if resolved_purchase_order and resolved_purchase_order.supplier_id != supplier.id:
+        raise ValueError('采购退货单的供应商必须与原采购单一致')
+
+    with transaction.atomic():
+        return_order = models.PurchaseReturnOrder.objects.create(
+            merchant=merchant,
+            supplier=supplier,
+            purchase_order=resolved_purchase_order,
+            return_date=normalized_date,
+            operator=operator,
+            warehouse=warehouse,
+            remarks=remarks,
+        )
+        bulk_objects = [
+            models.PurchaseReturnOrderItem(
+                purchase_return_order=return_order,
+                product=item_data['product'],
+                price=item_data['price'],
+                color=item_data.get('color'),
+                quantity=item_data['quantity'],
+                unit=item_data['unit'],
+                spec=item_data.get('spec'),
+                empty_diff_percent=item_data['empty_diff_percent'],
+                quantity_of_rolls=item_data.get('quantity_of_rolls'),
+                num_of_rolls=item_data['num_of_rolls'],
+                consume_detail_ids=item_data.get('consume_detail_ids'),
+                batch_number=item_data.get('batch_number'),
+                remarks=item_data.get('remarks'),
+            )
+            for item_data in normalized_items
+        ]
+        models.PurchaseReturnOrderItem.objects.bulk_create(bulk_objects)
+
+    return_order.refresh_from_db()
+    return return_order
+
+
+def create_sales_return_order(
+    *,
+    merchant: basic_info_models.Merchant,
+    customer: basic_info_models.Customer,
+    return_date,
+    warehouse: basic_info_models.WareHouse,
+    operator: basic_info_models.Employee,
+    items: List[Dict[str, Any]],
+    remarks: str | None = '',
+    sales_order: models.SalesOrder | None = None,
+    sales_order_id: int | None = None,
+    created_by=None,
+) -> models.SalesReturnOrder:
+    """
+    创建销售退货单，入库并冲减客户欠款。
+    """
+    if not items:
+        raise ValueError('items 不能为空')
+
+    normalized_date = _normalize_order_date(return_date)
+    normalized_items, _ = _normalize_order_items(
+        merchant=merchant,
+        warehouse=warehouse,
+        items=items,
+        is_outgoing=False,
+    )
+
+    resolved_sales_order = sales_order
+    if resolved_sales_order is None and sales_order_id:
+        resolved_sales_order = models.SalesOrder.objects.filter(
+            id=sales_order_id,
+            merchant=merchant,
+        ).first()
+        if resolved_sales_order is None:
+            raise ValueError('关联的销售单不存在或不属于当前商户')
+    if resolved_sales_order and resolved_sales_order.customer_id != customer.id:
+        raise ValueError('销售退货单的客户必须与原销售单一致')
+
+    with transaction.atomic():
+        return_order = models.SalesReturnOrder.objects.create(
+            merchant=merchant,
+            customer=customer,
+            sales_order=resolved_sales_order,
+            return_date=normalized_date,
+            operator=operator,
+            warehouse=warehouse,
+            remarks=remarks,
+        )
+        bulk_objects = [
+            models.SalesReturnOrderItem(
+                sales_return_order=return_order,
+                product=item_data['product'],
+                price=item_data['price'],
+                color=item_data.get('color'),
+                quantity=item_data['quantity'],
+                unit=item_data['unit'],
+                spec=item_data.get('spec'),
+                empty_diff_percent=item_data['empty_diff_percent'],
+                quantity_of_rolls=item_data.get('quantity_of_rolls'),
+                num_of_rolls=item_data['num_of_rolls'],
+                consume_detail_ids=item_data.get('consume_detail_ids'),
+                batch_number=item_data.get('batch_number'),
+                remarks=item_data.get('remarks'),
+            )
+            for item_data in normalized_items
+        ]
+        models.SalesReturnOrderItem.objects.bulk_create(bulk_objects)
+
+    return_order.refresh_from_db()
+    return return_order
+
+
 def create_payment_order(
    *,
    merchant: basic_info_models.Merchant,
@@ -409,6 +555,58 @@ def review_sales_order(
    return _cancel_sales_order(order)


+def review_purchase_return_order(
+    *,
+    purchase_return_order: models.PurchaseReturnOrder | None = None,
+    purchase_return_order_id: int | None = None,
+    target_status: models.PurchaseReturnStatusEnum,
+    reviewed_by=None,
+) -> models.PurchaseReturnOrder:
+    order = _resolve_purchase_return_order_instance(purchase_return_order, purchase_return_order_id)
+
+    if target_status not in {
+        models.PurchaseReturnStatusEnum.APPROVED,
+        models.PurchaseReturnStatusEnum.CANCELLED,
+    }:
+        raise ValueError('target_status 只能是 APPROVED 或 CANCELLED')
+
+    if order.status == target_status:
+        return order
+
+    if target_status == models.PurchaseReturnStatusEnum.APPROVED:
+        if order.status == models.PurchaseReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的采购退货单无法再次审批')
+        return _approve_purchase_return_order(order, reviewed_by)
+
+    return _cancel_purchase_return_order(order)
+
+
+def review_sales_return_order(
+    *,
+    sales_return_order: models.SalesReturnOrder | None = None,
+    sales_return_order_id: int | None = None,
+    target_status: models.SalesReturnStatusEnum,
+    reviewed_by=None,
+) -> models.SalesReturnOrder:
+    order = _resolve_sales_return_order_instance(sales_return_order, sales_return_order_id)
+
+    if target_status not in {
+        models.SalesReturnStatusEnum.APPROVED,
+        models.SalesReturnStatusEnum.CANCELLED,
+    }:
+        raise ValueError('target_status 只能是 APPROVED 或 CANCELLED')
+
+    if order.status == target_status:
+        return order
+
+    if target_status == models.SalesReturnStatusEnum.APPROVED:
+        if order.status == models.SalesReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的销售退货单无法再次审批')
+        return _approve_sales_return_order(order, reviewed_by)
+
+    return _cancel_sales_return_order(order)
+
+
 def review_payment_order(
    *,
    payment_order: models.PaymentOrder | None = None,
@@ -746,6 +944,128 @@ def _cancel_sales_order(sales_order: models.SalesOrder) -> models.SalesOrder:
    return locked


+def _approve_purchase_return_order(
+    purchase_return_order: models.PurchaseReturnOrder,
+    reviewed_by,
+) -> models.PurchaseReturnOrder:
+    with transaction.atomic():
+        locked_order = models.PurchaseReturnOrder.objects.select_related(
+            'merchant', 'warehouse', 'supplier'
+        ).prefetch_related('items').select_for_update().get(id=purchase_return_order.id)
+
+        if locked_order.status == models.PurchaseReturnStatusEnum.APPROVED:
+            return locked_order
+        if locked_order.status == models.PurchaseReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的采购退货单无法再次审批')
+
+        stock_flow_items = _build_stock_flow_items_from_order(locked_order)
+
+        locked_order.status = models.PurchaseReturnStatusEnum.APPROVED
+        locked_order.save(update_fields=['status', 'updated_at'])
+        BalanceService.adjust_supplier_balance(
+            merchant=locked_order.merchant,
+            supplier=locked_order.supplier,
+            delta=-locked_order.get_total_amount(),
+            source_type=models.BalanceChangeSourceEnum.PURCHASE_RETURN_ORDER,
+            source_id=locked_order.id,
+        )
+
+    created_by_id = getattr(reviewed_by, 'id', None)
+    if _auto_stock_task_enabled(locked_order.merchant):
+        logger.info('审批通过采购退货单 %s，触发出库任务', locked_order.id)
+        create_purchase_return_order_stock_entries.delay(
+            purchase_return_order_id=locked_order.id,
+            warehouse_id=locked_order.warehouse_id,
+            items=stock_flow_items,
+            created_by_id=created_by_id,
+        )
+
+    locked_order.refresh_from_db(fields=['status', 'updated_at'])
+    return locked_order
+
+
+def _cancel_purchase_return_order(
+    purchase_return_order: models.PurchaseReturnOrder,
+) -> models.PurchaseReturnOrder:
+    with transaction.atomic():
+        locked = models.PurchaseReturnOrder.objects.select_related('merchant').select_for_update().get(
+            id=purchase_return_order.id
+        )
+        if locked.status == models.PurchaseReturnStatusEnum.APPROVED:
+            raise ValueError('已审批的采购退货单无法作废')
+        if _order_has_stock_records(
+            merchant_id=locked.merchant_id,
+            source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+            source_id=locked.id,
+        ):
+            raise ValueError('采购退货单已生成出入库记录，无法作废')
+        locked.status = models.PurchaseReturnStatusEnum.CANCELLED
+        locked.save(update_fields=['status', 'updated_at'])
+    locked.refresh_from_db(fields=['status', 'updated_at'])
+    return locked
+
+
+def _approve_sales_return_order(
+    sales_return_order: models.SalesReturnOrder,
+    reviewed_by,
+) -> models.SalesReturnOrder:
+    with transaction.atomic():
+        locked_order = models.SalesReturnOrder.objects.select_related(
+            'merchant', 'warehouse', 'customer'
+        ).prefetch_related('items').select_for_update().get(id=sales_return_order.id)
+
+        if locked_order.status == models.SalesReturnStatusEnum.APPROVED:
+            return locked_order
+        if locked_order.status == models.SalesReturnStatusEnum.CANCELLED:
+            raise ValueError('作废状态的销售退货单无法再次审批')
+
+        stock_flow_items = _build_stock_flow_items_from_order(locked_order)
+
+        locked_order.status = models.SalesReturnStatusEnum.APPROVED
+        locked_order.save(update_fields=['status', 'updated_at'])
+        BalanceService.adjust_customer_balance(
+            merchant=locked_order.merchant,
+            customer=locked_order.customer,
+            delta=-locked_order.get_total_amount(),
+            source_type=models.BalanceChangeSourceEnum.SALES_RETURN_ORDER,
+            source_id=locked_order.id,
+        )
+
+    created_by_id = getattr(reviewed_by, 'id', None)
+    if _auto_stock_task_enabled(locked_order.merchant):
+        logger.info('审批通过销售退货单 %s，触发入库任务', locked_order.id)
+        create_sales_return_order_stock_entries.delay(
+            sales_return_order_id=locked_order.id,
+            warehouse_id=locked_order.warehouse_id,
+            items=stock_flow_items,
+            created_by_id=created_by_id,
+        )
+
+    locked_order.refresh_from_db(fields=['status', 'updated_at'])
+    return locked_order
+
+
+def _cancel_sales_return_order(
+    sales_return_order: models.SalesReturnOrder,
+) -> models.SalesReturnOrder:
+    with transaction.atomic():
+        locked = models.SalesReturnOrder.objects.select_related('merchant').select_for_update().get(
+            id=sales_return_order.id
+        )
+        if locked.status == models.SalesReturnStatusEnum.APPROVED:
+            raise ValueError('已审批的销售退货单无法作废')
+        if _order_has_stock_records(
+            merchant_id=locked.merchant_id,
+            source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+            source_id=locked.id,
+        ):
+            raise ValueError('销售退货单已生成出入库记录，无法作废')
+        locked.status = models.SalesReturnStatusEnum.CANCELLED
+        locked.save(update_fields=['status', 'updated_at'])
+    locked.refresh_from_db(fields=['status', 'updated_at'])
+    return locked
+
+
 def create_purchase_order_stock_entries_sync(
    *,
    purchase_order_id: int,
@@ -826,6 +1146,90 @@ def create_sales_order_stock_entries_sync(
    return payload


+def create_purchase_return_order_stock_entries_sync(
+    *,
+    purchase_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    """
+    根据采购退货单生成出库记录。
+    """
+    try:
+        purchase_return_order = models.PurchaseReturnOrder.objects.select_related('merchant').get(
+            id=purchase_return_order_id
+        )
+    except models.PurchaseReturnOrder.DoesNotExist:
+        logger.error('PurchaseReturnOrder %s 不存在，无法创建出库单', purchase_return_order_id)
+        return {'error': 'purchase_return_order_not_found', 'purchase_return_order_id': purchase_return_order_id}
+
+    merchant = purchase_return_order.merchant
+
+    created_by = None
+    if created_by_id:
+        UserModel = get_user_model()
+        created_by = UserModel.objects.filter(id=created_by_id).first()
+
+    service = StockFlowService(merchant=merchant, created_by=created_by)
+    record, details, created_count = service.stock_out(
+        warehouse_id=warehouse_id,
+        source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+        source_id=purchase_return_order.id,
+        items=items,
+    )
+
+    payload = {
+        'purchase_return_order_id': purchase_return_order.id,
+        'stock_change_record_id': getattr(record, 'id', None),
+        'created_details_count': created_count,
+    }
+    logger.info('采购退货单 %s 出库任务完成: %s', purchase_return_order.id, payload)
+    return payload
+
+
+def create_sales_return_order_stock_entries_sync(
+    *,
+    sales_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    """
+    根据销售退货单生成入库记录。
+    """
+    try:
+        sales_return_order = models.SalesReturnOrder.objects.select_related('merchant').get(
+            id=sales_return_order_id
+        )
+    except models.SalesReturnOrder.DoesNotExist:
+        logger.error('SalesReturnOrder %s 不存在，无法创建入库单', sales_return_order_id)
+        return {'error': 'sales_return_order_not_found', 'sales_return_order_id': sales_return_order_id}
+
+    merchant = sales_return_order.merchant
+
+    created_by = None
+    if created_by_id:
+        UserModel = get_user_model()
+        created_by = UserModel.objects.filter(id=created_by_id).first()
+
+    service = StockFlowService(merchant=merchant, created_by=created_by)
+    record, details, created_count = service.stock_in(
+        warehouse_id=warehouse_id,
+        source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+        source_id=sales_return_order.id,
+        items=items,
+    )
+
+    payload = {
+        'sales_return_order_id': sales_return_order.id,
+        'stock_change_record_id': getattr(record, 'id', None),
+        'created_details_count': created_count,
+    }
+    logger.info('销售退货单 %s 入库任务完成: %s', sales_return_order.id, payload)
+    return payload
+
+
 def _build_stock_flow_items_from_order(order) -> List[Dict[str, Any]]:
    """
    根据订单明细还原 StockFlowService 所需的 items 结构。
@@ -925,6 +1329,36 @@ def _resolve_sales_order_instance(
    )


+def _resolve_purchase_return_order_instance(
+    purchase_return_order: models.PurchaseReturnOrder | None,
+    purchase_return_order_id: int | None,
+) -> models.PurchaseReturnOrder:
+    if purchase_return_order is None and purchase_return_order_id is None:
+        raise ValueError('必须提供 purchase_return_order 或 purchase_return_order_id')
+
+    if purchase_return_order is not None:
+        purchase_return_order_id = purchase_return_order.id
+
+    return models.PurchaseReturnOrder.objects.select_related('merchant', 'warehouse').prefetch_related('items').get(
+        id=purchase_return_order_id
+    )
+
+
+def _resolve_sales_return_order_instance(
+    sales_return_order: models.SalesReturnOrder | None,
+    sales_return_order_id: int | None,
+) -> models.SalesReturnOrder:
+    if sales_return_order is None and sales_return_order_id is None:
+        raise ValueError('必须提供 sales_return_order 或 sales_return_order_id')
+
+    if sales_return_order is not None:
+        sales_return_order_id = sales_return_order.id
+
+    return models.SalesReturnOrder.objects.select_related('merchant', 'warehouse').prefetch_related('items').get(
+        id=sales_return_order_id
+    )
+
+
 def _resolve_payment_order_instance(
    payment_order: models.PaymentOrder | None,
    payment_order_id: int | None,
--- a/business/tasks.py
+++ b/business/tasks.py
@@ -42,3 +42,41 @@ def create_sales_order_stock_entries(
    payload['task_id'] = self.request.id
    return payload

+
+@shared_task(bind=True)
+def create_purchase_return_order_stock_entries(
+    self,
+    *,
+    purchase_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    payload = business_services.create_purchase_return_order_stock_entries_sync(
+        purchase_return_order_id=purchase_return_order_id,
+        warehouse_id=warehouse_id,
+        items=items,
+        created_by_id=created_by_id,
+    )
+    payload['task_id'] = self.request.id
+    return payload
+
+
+@shared_task(bind=True)
+def create_sales_return_order_stock_entries(
+    self,
+    *,
+    sales_return_order_id: int,
+    warehouse_id: int,
+    items: List[Dict[str, Any]],
+    created_by_id: int | None = None,
+) -> Dict[str, Any]:
+    payload = business_services.create_sales_return_order_stock_entries_sync(
+        sales_return_order_id=sales_return_order_id,
+        warehouse_id=warehouse_id,
+        items=items,
+        created_by_id=created_by_id,
+    )
+    payload['task_id'] = self.request.id
+    return payload
+
--- a/business/tests.py
+++ b/business/tests.py
@@ -437,6 +437,202 @@ class SalesOrderServiceTestCase(TestCase):
                created_by=self.user,
            )

+
+class PurchaseReturnServiceTestCase(TestCase):
+    def setUp(self):
+        (
+            self.merchant,
+            self.supplier,
+            self.warehouse_strict,
+            self.warehouse_relaxed,
+            self.product,
+            self.operator,
+        ) = create_basic_fixtures()
+        self.warehouse_strict_out = basic_models.WareHouse.objects.create(
+            merchant=self.merchant,
+            name='采退严出仓',
+            mode=basic_models.WareHouseModeEnum.RESTRICT_IN_OUT,
+        )
+        User = get_user_model()
+        self.user = User.objects.create_user(username='purchase-return', password='pass123')
+        self.strict_items = [
+            {'product_id': self.product.id, 'numbers': [4, 2], 'price': '11.5', 'unit': '米'}
+        ]
+        self.strict_out_items = [
+            {
+                'product_id': self.product.id,
+                'consume_detail_ids': [10, 11],
+                'quantity': 30,
+                'price': '12.0',
+                'unit': '米',
+            }
+        ]
+
+    def test_create_purchase_return_order_success(self):
+        order = services.create_purchase_return_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_strict,
+            operator=self.operator,
+            items=self.strict_items,
+            created_by=self.user,
+        )
+        self.assertEqual(order.status, business_models.PurchaseReturnStatusEnum.PENDING)
+        self.assertEqual(order.items.count(), 1)
+
+    def test_review_purchase_return_order_triggers_task_and_balance(self):
+        order = services.create_purchase_return_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 40, 'num_of_rolls': 2, 'price': '10.0'}],
+            created_by=self.user,
+        )
+        with patch('business.services.create_purchase_return_order_stock_entries.delay') as mock_delay:
+            reviewed = services.review_purchase_return_order(
+                purchase_return_order=order,
+                target_status=business_models.PurchaseReturnStatusEnum.APPROVED,
+                reviewed_by=self.user,
+            )
+        self.assertEqual(reviewed.status, business_models.PurchaseReturnStatusEnum.APPROVED)
+        mock_delay.assert_called_once()
+        balance = business_models.SupplierBalance.objects.get(
+            merchant=self.merchant,
+            supplier=self.supplier,
+        )
+        self.assertEqual(balance.balance, Decimal('-400.00'))
+        record = business_models.BalanceChangeRecord.objects.get(
+            merchant=self.merchant,
+            source_type=business_models.BalanceChangeSourceEnum.PURCHASE_RETURN_ORDER,
+            source_id=order.id,
+        )
+        self.assertEqual(record.direction, business_models.BalanceChangeDirectionEnum.DECREASE)
+
+    def test_purchase_return_cancel_blocked_after_stock_created(self):
+        order = services.create_purchase_return_order(
+            merchant=self.merchant,
+            supplier=self.supplier,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 20, 'num_of_rolls': 2, 'price': '9.5'}],
+        )
+        stock_models.StockChangeRecord.objects.create(
+            merchant=self.merchant,
+            type=stock_models.StockChangeTypeEnum.REMOVE,
+            warehouse=self.warehouse_relaxed,
+            source_type=stock_models.StockChangeSourceEnum.PURCHASE_RETURN,
+            source_id=order.id,
+        )
+        with self.assertRaises(ValueError):
+            services.review_purchase_return_order(
+                purchase_return_order=order,
+                target_status=business_models.PurchaseReturnStatusEnum.CANCELLED,
+            )
+
+    def test_purchase_return_strict_out_requires_consume_ids(self):
+        payload = [
+            {
+                'product_id': self.product.id,
+                'quantity': 10,
+                'price': '8.5',
+                'unit': '米',
+            }
+        ]
+        with self.assertRaises(ValueError):
+            services.create_purchase_return_order(
+                merchant=self.merchant,
+                supplier=self.supplier,
+                return_date=timezone.now().date(),
+                warehouse=self.warehouse_strict_out,
+                operator=self.operator,
+                items=payload,
+            )
+
+
+class SalesReturnServiceTestCase(TestCase):
+    def setUp(self):
+        (
+            self.merchant,
+            self.customer,
+            self.warehouse_strict,
+            self.warehouse_relaxed,
+            self.warehouse_strict_out,
+            self.product,
+            self.operator,
+        ) = create_sales_fixtures()
+        User = get_user_model()
+        self.user = User.objects.create_user(username='sales-return', password='pass123')
+        self.strict_items = [
+            {'product_id': self.product.id, 'numbers': [6, 2], 'price': '20.0', 'unit': '米'}
+        ]
+
+    def test_create_sales_return_order_success(self):
+        order = services.create_sales_return_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 50, 'num_of_rolls': 2, 'price': '19.5'}],
+        )
+        self.assertEqual(order.status, business_models.SalesReturnStatusEnum.PENDING)
+
+    def test_review_sales_return_order_updates_balance(self):
+        order = services.create_sales_return_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_strict,
+            operator=self.operator,
+            items=self.strict_items,
+            created_by=self.user,
+        )
+        with patch('business.services.create_sales_return_order_stock_entries.delay') as mock_delay:
+            reviewed = services.review_sales_return_order(
+                sales_return_order=order,
+                target_status=business_models.SalesReturnStatusEnum.APPROVED,
+                reviewed_by=self.user,
+            )
+        self.assertEqual(reviewed.status, business_models.SalesReturnStatusEnum.APPROVED)
+        mock_delay.assert_called_once()
+        balance = business_models.CustomerBalance.objects.get(
+            merchant=self.merchant,
+            customer=self.customer,
+        )
+        self.assertLess(balance.balance, Decimal('0'))
+        record = business_models.BalanceChangeRecord.objects.get(
+            merchant=self.merchant,
+            source_type=business_models.BalanceChangeSourceEnum.SALES_RETURN_ORDER,
+            source_id=order.id,
+        )
+        self.assertEqual(record.direction, business_models.BalanceChangeDirectionEnum.DECREASE)
+
+    def test_sales_return_cancel_blocked_after_stock_created(self):
+        order = services.create_sales_return_order(
+            merchant=self.merchant,
+            customer=self.customer,
+            return_date=timezone.now().date(),
+            warehouse=self.warehouse_relaxed,
+            operator=self.operator,
+            items=[{'product_id': self.product.id, 'quantity': 15, 'num_of_rolls': 1, 'price': '18.0'}],
+        )
+        stock_models.StockChangeRecord.objects.create(
+            merchant=self.merchant,
+            type=stock_models.StockChangeTypeEnum.ADD,
+            warehouse=self.warehouse_relaxed,
+            source_type=stock_models.StockChangeSourceEnum.SALES_RETURN,
+            source_id=order.id,
+        )
+        with self.assertRaises(ValueError):
+            services.review_sales_return_order(
+                sales_return_order=order,
+                target_status=business_models.SalesReturnStatusEnum.CANCELLED,
+            )
+
 class PaymentReceiptServiceTestCase(TestCase):
    def setUp(self):
        (