feat: haobuye

api_v1/management/commands/sync_external_printing_records.py

@@ -0,0 +1,14 @@
+from django.core.management.base import BaseCommand
+
+from api_v1.tasks import sync_external_printing_records
+
+
+class Command(BaseCommand):
+    help = '从外部 records 接口同步印染订单/任务'
+
+    def add_arguments(self, parser):
+        parser.add_argument('--limit', type=int, default=100)
+
+    def handle(self, *args, **options):
+        payload = sync_external_printing_records.run(limit=options['limit'])
+        self.stdout.write(self.style.SUCCESS(str(payload)))

api_v1/migrations/0013_printingexternalsyncfailure_and_more.py

@@ -0,0 +1,44 @@
+# Generated by Django 5.2.8 on 2026-03-20 00:00
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('api_v1', '0012_datasync_merchant'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='PrintingExternalSyncFailure',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True, db_index=True, verbose_name='创建时间')),
+                ('updated_at', models.DateTimeField(auto_now=True, verbose_name='更新时间')),
+                ('run_date', models.DateField(db_index=True, verbose_name='任务日期')),
+                ('external_record_id', models.PositiveBigIntegerField(db_index=True, verbose_name='外部记录ID')),
+                ('external_order_id', models.CharField(blank=True, max_length=100, verbose_name='外部订单编号')),
+                ('product_name', models.CharField(blank=True, max_length=200, verbose_name='外部产品名')),
+                ('error', models.TextField(blank=True, verbose_name='错误摘要')),
+                ('raw', models.JSONField(blank=True, default=dict, verbose_name='原始数据')),
+                ('attempts', models.PositiveIntegerField(default=0, verbose_name='尝试次数')),
+                ('last_attempt_at', models.DateTimeField(blank=True, null=True, verbose_name='最后尝试时间')),
+            ],
+            options={
+                'verbose_name': '外部印染同步失败记录',
+                'verbose_name_plural': '外部印染同步失败记录',
+                'db_table': 'api_printing_external_sync_failure',
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='printingexternalsyncfailure',
+            constraint=models.UniqueConstraint(fields=('run_date', 'external_record_id'), name='uniq_printing_ext_sync_fail_run_date_record'),
+        ),
+        migrations.AlterField(
+            model_name='datasync',
+            name='table_name',
+            field=models.CharField(choices=[('product', '产品'), ('customer', '客户'), ('plate_order', '开版（明道云）'), ('printing_external_record', '印染订单（外部 records）'), ('mdy_plate_order_staging_tiia_upload', '开版暂存-腾讯图库上传')], max_length=50, verbose_name='同步目标'),
+        ),
+    ]

api_v1/models.py

@@ -93,6 +93,7 @@ class DataSync(ModelBase):
         PRODUCT = 'product', '产品'
         CUSTOMER = 'customer', '客户'
         PLATE_ORDER = 'plate_order', '开版（明道云）'
+        PRINTING_EXTERNAL_RECORD = 'printing_external_record', '印染订单（外部 records）'
         MDY_PLATE_ORDER_STAGING_TIIA_UPLOAD = 'mdy_plate_order_staging_tiia_upload', '开版暂存-腾讯图库上传'
 
     table_name = models.CharField(max_length=50, choices=TableName.choices, verbose_name='同步目标')
@@ -221,6 +222,38 @@ class MDYPlateOrderStagingTiiaUploadFailure(ModelBase):
         return f'{self.run_date} {self.mdy_rowid}'
 
 
+class PrintingExternalSyncFailure(ModelBase):
+    """
+    外部印染 records 同步失败记录。
+
+    以外部 record.ID 为追踪主键，允许同一天重复失败时累加 attempts。
+    """
+
+    run_date = models.DateField(db_index=True, verbose_name='任务日期')
+    external_record_id = models.PositiveBigIntegerField(db_index=True, verbose_name='外部记录ID')
+    external_order_id = models.CharField(max_length=100, blank=True, verbose_name='外部订单编号')
+    product_name = models.CharField(max_length=200, blank=True, verbose_name='外部产品名')
+    error = models.TextField(blank=True, verbose_name='错误摘要')
+    raw = models.JSONField(default=dict, blank=True, verbose_name='原始数据')
+    attempts = models.PositiveIntegerField(default=0, verbose_name='尝试次数')
+    last_attempt_at = models.DateTimeField(null=True, blank=True, verbose_name='最后尝试时间')
+
+    class Meta:
+        db_table = 'api_printing_external_sync_failure'
+        verbose_name = '外部印染同步失败记录'
+        verbose_name_plural = '外部印染同步失败记录'
+        ordering = ['-created_at']
+        constraints = [
+            models.UniqueConstraint(
+                fields=['run_date', 'external_record_id'],
+                name='uniq_printing_ext_sync_fail_run_date_record',
+            )
+        ]
+
+    def __str__(self):
+        return f'{self.external_record_id} @ {self.run_date}'
+
+
 class ApiAuditLog(models.Model):
     """API审计日志 - 记录创建操作的历史现场
     

api_v1/tasks.py

@@ -1,19 +1,27 @@
 import asyncio
+import base64
 import json
 import logging
+import mimetypes
 import os
+import re
 import shutil
 import subprocess
+from collections import defaultdict
 from datetime import datetime
 from decimal import Decimal, InvalidOperation
 from pathlib import Path
 
+import requests
 from celery import shared_task
 from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.core.files.base import ContentFile
 from django.utils import timezone
 
 from basic_info import models as basic_models
 from api_v1 import models as api_models
+from api_v1.views.printing.services import PrintingJobService, PrintingOrderService
 from flower.utils import (
     fetch_products_from_mingdaoyun,
     fetch_customers_from_mingdaoyun,
@@ -23,9 +31,11 @@ from api_v1.mdy_plate_order_staging_tiia_upload import (
     build_default_tiia_rate_limiter,
     upload_mdy_plate_order_staging_plate_images_to_tencent_tiia,
 )
+from printing import models as printing_models
 
 
 logger = logging.getLogger(__name__)
+User = get_user_model()
 
 
 def _ensure_backup_dir(output_dir: str | None) -> Path:
@@ -171,6 +181,417 @@ def _ensure_int(value):
             return None
 
 
+def _parse_external_datetime(value: str | None):
+    if not value:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        dt = datetime.fromisoformat(text.replace('Z', '+00:00'))
+    except ValueError:
+        return None
+    if timezone.is_naive(dt):
+        dt = timezone.make_aware(dt, timezone.get_current_timezone())
+    return dt
+
+
+def _extract_positive_int(value, *, field_name: str, allow_blank: bool = True):
+    if value is None or value == '':
+        return None if allow_blank else 0
+    try:
+        number = Decimal(str(value))
+    except (InvalidOperation, TypeError, ValueError) as exc:
+        raise RuntimeError(f'外部字段 {field_name} 无法解析为整数: {value!r}') from exc
+    if number != number.to_integral_value():
+        raise RuntimeError(f'外部字段 {field_name} 不是整数: {value!r}')
+    parsed = int(number)
+    if parsed < 0:
+        raise RuntimeError(f'外部字段 {field_name} 不能为负数: {value!r}')
+    return parsed
+
+
+def _extract_pieces(value):
+    if value is None or value == '':
+        return None
+    match = re.search(r'(\d+)', str(value))
+    if not match:
+        return None
+    return int(match.group(1))
+
+
+def _normalize_unit(value):
+    text = str(value or '').strip()
+    return text.lstrip('/').strip() or text
+
+
+def _split_fabric_source_and_craft(value: str | None):
+    text = str(value or '').strip()
+    if not text:
+        return '', ''
+    parts = re.split(r'\s+', text)
+    fabric_source = parts[0] if parts else ''
+    craft = ' '.join(parts[1:]).strip() if len(parts) > 1 else ''
+    return fabric_source, craft
+
+
+def _build_external_url(path: str) -> str:
+    base_url = str(getattr(settings, 'PRINTING_EXTERNAL_RECORDS_BASE_URL', '') or '').rstrip('/')
+    if not base_url:
+        raise RuntimeError('未配置 PRINTING_EXTERNAL_RECORDS_BASE_URL')
+    return f'{base_url}{path}'
+
+
+def _get_external_headers() -> dict[str, str]:
+    secret = str(getattr(settings, 'PRINTING_EXTERNAL_RECORDS_AUTHORIZATION', '') or '').strip()
+    if not secret:
+        raise RuntimeError('未配置 PRINTING_EXTERNAL_RECORDS_AUTHORIZATION')
+    return {'Authorization': secret}
+
+
+def _get_printing_sync_user():
+    user_id = int(getattr(settings, 'PRINTING_EXTERNAL_SYNC_USER_ID', 1) or 1)
+    user = User.objects.filter(id=user_id).select_related('employee__merchant').first()
+    if not user:
+        raise RuntimeError(f'未找到固定同步用户: {user_id}')
+    employee = getattr(user, 'employee', None)
+    merchant = getattr(employee, 'merchant', None)
+    if not merchant:
+        raise RuntimeError(f'固定同步用户 {user_id} 未绑定 employee.merchant，无法确定同步商户')
+    return user
+
+
+def _get_printing_sync_product_category(merchant):
+    category_id = getattr(settings, 'PRINTING_EXTERNAL_SYNC_PRODUCT_CATEGORY_ID', None)
+    qs = basic_models.ProductCategory.objects.filter(merchant=merchant).order_by('id')
+    if category_id:
+        qs = qs.filter(id=category_id)
+    category = qs.first()
+    if not category:
+        raise RuntimeError(
+            f'未找到用于外部印染同步的产品类别，请先创建类别或配置 '
+            f'PRINTING_EXTERNAL_SYNC_PRODUCT_CATEGORY_ID（merchant={merchant.id}）'
+        )
+    return category
+
+
+def _fetch_external_printing_records(*, limit: int = 100) -> dict:
+    url = _build_external_url('/api/v1/records')
+    response = requests.get(
+        url,
+        headers=_get_external_headers(),
+        params={'limit': max(1, int(limit)), 'update_cursor': 'false'},
+        timeout=30,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    if not isinstance(payload, dict):
+        raise RuntimeError('外部 records 接口返回格式非法：非 JSON object')
+    if not isinstance(payload.get('records', []), list):
+        raise RuntimeError('外部 records 接口返回格式非法：records 不是数组')
+    return payload
+
+
+def _advance_external_printing_cursor(*, cursor_value: int) -> dict:
+    url = _build_external_url('/api/v1/cursor/set')
+    response = requests.post(
+        url,
+        headers=_get_external_headers(),
+        json={'value': int(cursor_value)},
+        timeout=30,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    if not isinstance(payload, dict):
+        raise RuntimeError('外部 cursor/set 接口返回格式非法：非 JSON object')
+    return payload
+
+
+def _group_external_records(records: list[dict]) -> dict[str, list[dict]]:
+    grouped: dict[str, list[dict]] = defaultdict(list)
+    for record in records:
+        external_order_id = str(record.get('BianHaoID') or '').strip()
+        if not external_order_id:
+            raise RuntimeError(f'外部 record 缺少 BianHaoID: {record!r}')
+        grouped[external_order_id].append(record)
+    return grouped
+
+
+def _resolve_external_customer(*, merchant, record: dict):
+    customer_payload = record.get('customer') or {}
+    customer_name = str(customer_payload.get('KhName') or '').strip()
+    external_customer_id = str(record.get('KhID') or customer_payload.get('KhID') or '').strip()
+    if not customer_name:
+        raise RuntimeError(f'外部 record 缺少 customer.KhName: {record!r}')
+
+    customer = (
+        basic_models.Customer.objects.filter(merchant=merchant, name=customer_name)
+        .order_by('id')
+        .first()
+    )
+    if not customer:
+        raise RuntimeError(f'未找到客户: {customer_name}')
+    return customer, customer_name, external_customer_id
+
+
+def _resolve_external_employee_user(*, merchant, external_employee_name: str, sync_user):
+    normalized = str(external_employee_name or '').strip()
+    if not normalized:
+        return sync_user, ''
+
+    employee = (
+        basic_models.Employee.objects.filter(merchant=merchant, name=normalized)
+        .select_related('sys_user')
+        .order_by('id')
+        .first()
+    )
+    if employee and employee.sys_user_id:
+        return employee.sys_user, ''
+    return sync_user, normalized
+
+
+def _encode_external_image_name_b64(name: str) -> str:
+    raw = str(name or '').encode('utf-8')
+    return base64.urlsafe_b64encode(raw).decode('ascii').rstrip('=')
+
+
+def _decode_external_image_data(data: str) -> bytes:
+    text = str(data or '').strip()
+    if not text:
+        raise RuntimeError('外部图片接口返回空 data')
+    padding = '=' * (-len(text) % 4)
+    try:
+        return base64.b64decode(text + padding)
+    except Exception as exc:
+        raise RuntimeError('外部图片接口返回的 data 不是合法 base64') from exc
+
+
+def _fetch_external_product_image(external_product_name: str) -> dict:
+    url = _build_external_url('/api/v1/image')
+    response = requests.get(
+        url,
+        headers=_get_external_headers(),
+        params={'name_b64': _encode_external_image_name_b64(external_product_name)},
+        timeout=30,
+    )
+    if response.status_code == 404:
+        raise RuntimeError(f'外部图片不存在: {external_product_name}')
+    response.raise_for_status()
+    payload = response.json()
+    if not isinstance(payload, dict):
+        raise RuntimeError('外部图片接口返回格式非法：非 JSON object')
+    data = _decode_external_image_data(payload.get('data', ''))
+    content_type = str(payload.get('content_type') or '').strip() or 'application/octet-stream'
+    image_name = str(payload.get('name') or '').strip()
+    return {
+        'bytes': data,
+        'content_type': content_type,
+        'name': image_name or external_product_name,
+    }
+
+
+def _build_product_image_filename(product_name: str, image_name: str, content_type: str) -> str:
+    suffix = Path(str(image_name or '').strip()).suffix
+    if not suffix:
+        suffix = mimetypes.guess_extension(content_type or '') or '.jpg'
+    safe_name = re.sub(r'[^0-9A-Za-z._-]+', '_', str(product_name or '').strip()) or 'external_product'
+    return f'{safe_name}{suffix}'
+
+
+def _upload_product_image(product, image_payload: dict):
+    filename = _build_product_image_filename(
+        product_name=product.name,
+        image_name=image_payload.get('name', ''),
+        content_type=image_payload.get('content_type', ''),
+    )
+    content = ContentFile(image_payload['bytes'])
+    product.image.save(filename, content, save=False)
+    product.save(update_fields=['image', 'updated_at'])
+
+
+def _record_printing_external_sync_failure(*, run_date, record: dict, error: str):
+    external_record_id = _extract_positive_int(record.get('ID'), field_name='ID', allow_blank=False)
+    obj, _created = api_models.PrintingExternalSyncFailure.objects.get_or_create(
+        run_date=run_date,
+        external_record_id=external_record_id,
+        defaults={
+            'external_order_id': str(record.get('BianHaoID') or '').strip(),
+            'product_name': str(record.get('YanSe') or '').strip(),
+            'error': error or '',
+            'raw': record,
+            'attempts': 0,
+            'last_attempt_at': timezone.now(),
+        },
+    )
+    obj.external_order_id = str(record.get('BianHaoID') or '').strip()
+    obj.product_name = str(record.get('YanSe') or '').strip()
+    obj.error = error or ''
+    obj.raw = record
+    obj.attempts = int(obj.attempts or 0) + 1
+    obj.last_attempt_at = timezone.now()
+    obj.save(
+        update_fields=[
+            'external_order_id',
+            'product_name',
+            'error',
+            'raw',
+            'attempts',
+            'last_attempt_at',
+        ]
+    )
+
+
+def _ensure_external_product(*, merchant, external_product_name: str, category):
+    normalized = str(external_product_name or '').strip()
+    if not normalized:
+        raise RuntimeError('外部产品名为空，无法创建/绑定产品')
+
+    existing_product = (
+        basic_models.Product.objects.filter(merchant=merchant, name=normalized)
+        .order_by('id')
+        .first()
+    )
+    if existing_product:
+        return existing_product, False
+
+    image_payload = _fetch_external_product_image(normalized)
+    product = basic_models.Product.objects.create(
+        merchant=merchant,
+        category=category,
+        name=normalized,
+    )
+    try:
+        _upload_product_image(product, image_payload)
+    except Exception:
+        if product.image:
+            try:
+                product.image.delete(save=False)
+            except Exception:
+                logger.warning('回滚外部产品图片失败: product_id=%s', product.id, exc_info=True)
+        product.delete()
+        raise
+    return product, True
+
+
+def _build_order_external_raw(group_records: list[dict]) -> dict:
+    first = group_records[0] if group_records else {}
+    return {
+        'group_size': len(group_records),
+        'record_ids': [record.get('ID') for record in group_records],
+        'first_record': first,
+    }
+
+
+def _build_external_order_data(
+    *,
+    merchant,
+    external_order_id: str,
+    group_records: list[dict],
+    sync_user,
+):
+    first = group_records[0]
+    customer, external_customer_name, external_customer_id = _resolve_external_customer(merchant=merchant, record=first)
+    created_by_user, external_employee_name = _resolve_external_employee_user(
+        merchant=merchant,
+        external_employee_name=str(first.get('CaoZY') or '').strip(),
+        sync_user=sync_user,
+    )
+    fabric_source, craft = _split_fabric_source_and_craft(first.get('SHDZ'))
+    return {
+        'merchant': merchant,
+        'customer': customer,
+        'fabric': '',
+        'width': str(first.get('SeHao') or '').strip(),
+        'fabric_source': fabric_source or None,
+        'craft': craft or None,
+        'rolling_warn': str(first.get('BeiZhu') or '').strip() or None,
+        'curve': str(first.get('MeoA') or '').strip() or None,
+        'outgoing_date': _parse_external_datetime(first.get('KdRiQi')),
+        'created_by': created_by_user,
+        'external_order_id': external_order_id,
+        'external_customer_id': external_customer_id or None,
+        'external_customer_name': external_customer_name or None,
+        'external_employee_name': external_employee_name or None,
+        'external_raw': _build_order_external_raw(group_records),
+    }
+
+
+def _upsert_external_printing_order(*, merchant, external_order_id: str, group_records: list[dict], sync_user):
+    order_data = _build_external_order_data(
+        merchant=merchant,
+        external_order_id=external_order_id,
+        group_records=group_records,
+        sync_user=sync_user,
+    )
+    created_by_user = order_data['created_by']
+    existing_order = (
+        printing_models.PrintingOrder.objects.filter(
+            merchant=merchant,
+            external_order_id=external_order_id,
+        )
+        .order_by('id')
+        .first()
+    )
+    if existing_order:
+        success, message, order = PrintingOrderService.update_printing_order(
+            existing_order,
+            order_data,
+            created_by_user,
+        )
+        if not success:
+            raise RuntimeError(f'更新印染订单失败: {message}')
+        return order, False
+    order = PrintingOrderService.create_printing_order(order_data, created_by_user)
+    return order, True
+
+
+def _upsert_external_printing_job(*, merchant, printing_order, record: dict, sync_user, category):
+    record_id = _extract_positive_int(record.get('ID'), field_name='ID', allow_blank=False)
+    created_by_user, _external_employee_name = _resolve_external_employee_user(
+        merchant=merchant,
+        external_employee_name=str(record.get('CaoZY') or '').strip(),
+        sync_user=sync_user,
+    )
+    product, _ = _ensure_external_product(
+        merchant=merchant,
+        external_product_name=str(record.get('YanSe') or '').strip(),
+        category=category,
+    )
+    job_data = {
+        'merchant': merchant,
+        'printing_order': printing_order,
+        'product': product,
+        'quantity': _extract_positive_int(record.get('ShuLiang'), field_name='ShuLiang', allow_blank=False),
+        'unit': _normalize_unit(record.get('JiJiaDW')),
+        'size': str(record.get('ShuLiangZ') or '').strip() or None,
+        'pieces': _extract_pieces(record.get('BeiZhuC')),
+        'description': None,
+        'original_id': record_id,
+        'created_by': created_by_user,
+        'external_product_name': None,
+        'external_raw': record,
+    }
+    existing_job = (
+        printing_models.PrintingJob.objects.filter(
+            printing_order=printing_order,
+            original_id=record_id,
+        )
+        .order_by('id')
+        .first()
+    )
+    if existing_job:
+        success, message, job = PrintingJobService.update_printing_job(
+            existing_job,
+            job_data,
+            created_by_user,
+        )
+        if not success:
+            raise RuntimeError(f'更新印染任务失败: {message}')
+        return job, False
+    job = PrintingJobService.create_printing_job(job_data, created_by_user)
+    return job, True
+
+
 def _run_fetch(page: int, page_size: int):
     return asyncio.run(fetch_products_from_mingdaoyun(page=page, page_size=page_size))
 
@@ -716,6 +1137,165 @@ def sync_mdy_plate_orders_for_merchant(
     return payload
 
 
+@shared_task(bind=True)
+def sync_external_printing_records(self, limit: int = 100):
+    """
+    从外部 records 接口增量同步印染订单/任务。
+
+    策略：
+    - 拉取时强制 update_cursor=false
+    - 按外部 record.ID 处理失败并记录
+    - 本批处理结束后无论是否有部分失败，都推进远端 cursor
+    """
+    limit = max(1, int(limit or 100))
+    sync_user = _get_printing_sync_user()
+    merchant = sync_user.employee.merchant
+    category = _get_printing_sync_product_category(merchant)
+    payload = _fetch_external_printing_records(limit=limit)
+    records = payload.get('records', [])
+    last_record_id = payload.get('last_record_id')
+    run_date = timezone.localdate()
+
+    orders_created = 0
+    orders_updated = 0
+    jobs_created = 0
+    jobs_updated = 0
+    failed_record_ids: list[int] = []
+    failed_records = 0
+
+    if records:
+        grouped_records = _group_external_records(records)
+        for external_order_id, group_records in grouped_records.items():
+            successful_records: list[dict] = []
+            for record in group_records:
+                try:
+                    _ensure_external_product(
+                        merchant=merchant,
+                        external_product_name=str(record.get('YanSe') or '').strip(),
+                        category=category,
+                    )
+                except Exception as exc:
+                    error_message = str(exc)
+                    logger.warning(
+                        '外部印染记录产品处理失败: external_record_id=%s external_order_id=%s error=%s',
+                        record.get('ID'),
+                        external_order_id,
+                        error_message,
+                    )
+                    _record_printing_external_sync_failure(
+                        run_date=run_date,
+                        record=record,
+                        error=error_message,
+                    )
+                    failed_records += 1
+                    failed_record_ids.append(
+                        _extract_positive_int(record.get('ID'), field_name='ID', allow_blank=False)
+                    )
+                    continue
+                successful_records.append(record)
+
+            if not successful_records:
+                continue
+
+            try:
+                order, order_created = _upsert_external_printing_order(
+                    merchant=merchant,
+                    external_order_id=external_order_id,
+                    group_records=successful_records,
+                    sync_user=sync_user,
+                )
+                if order_created:
+                    orders_created += 1
+                else:
+                    orders_updated += 1
+            except Exception as exc:
+                error_message = str(exc)
+                logger.warning(
+                    '外部印染记录订单处理失败: external_order_id=%s error=%s',
+                    external_order_id,
+                    error_message,
+                )
+                for record in successful_records:
+                    _record_printing_external_sync_failure(
+                        run_date=run_date,
+                        record=record,
+                        error=error_message,
+                    )
+                    failed_records += 1
+                    failed_record_ids.append(
+                        _extract_positive_int(record.get('ID'), field_name='ID', allow_blank=False)
+                    )
+                continue
+
+            for record in successful_records:
+                try:
+                    _job, job_created = _upsert_external_printing_job(
+                        merchant=merchant,
+                        printing_order=order,
+                        record=record,
+                        sync_user=sync_user,
+                        category=category,
+                    )
+                    if job_created:
+                        jobs_created += 1
+                    else:
+                        jobs_updated += 1
+                except Exception as exc:
+                    error_message = str(exc)
+                    logger.warning(
+                        '外部印染记录任务处理失败: external_record_id=%s external_order_id=%s error=%s',
+                        record.get('ID'),
+                        external_order_id,
+                        error_message,
+                    )
+                    _record_printing_external_sync_failure(
+                        run_date=run_date,
+                        record=record,
+                        error=error_message,
+                    )
+                    failed_records += 1
+                    failed_record_ids.append(
+                        _extract_positive_int(record.get('ID'), field_name='ID', allow_blank=False)
+                    )
+
+        cursor_payload = None
+        if last_record_id is not None:
+            cursor_payload = _advance_external_printing_cursor(cursor_value=int(last_record_id))
+    else:
+        grouped_records = {}
+        cursor_payload = None
+
+    api_models.DataSync.objects.create(
+        table_name=api_models.DataSync.TableName.PRINTING_EXTERNAL_RECORD,
+        merchant=merchant,
+        page_index=1,
+        page_size=limit,
+        synced_rows=len(records),
+        total_count=int(payload.get('count') or 0),
+        note=f'cursor_after={payload.get("cursor_after")} last_record_id={last_record_id}',
+    )
+
+    result = {
+        'task_id': self.request.id,
+        'limit': limit,
+        'mode': payload.get('mode'),
+        'count': len(records),
+        'orders_created': orders_created,
+        'orders_updated': orders_updated,
+        'jobs_created': jobs_created,
+        'jobs_updated': jobs_updated,
+        'failed_records': failed_records,
+        'failed_record_ids': failed_record_ids,
+        'last_record_id': last_record_id,
+        'cursor_before': payload.get('cursor_before'),
+        'cursor_after': payload.get('cursor_after'),
+        'cursor_updated': bool(cursor_payload),
+        'group_count': len(grouped_records),
+    }
+    logger.info('外部印染 records 同步完成: %s', result)
+    return result
+
+
 def _record_mdy_plate_order_staging_tiia_failure(
     *,
     run_date,

api_v1/test_external_printing_records_sync.py

@@ -0,0 +1,194 @@
+from unittest.mock import patch
+
+from django.conf import settings
+from django.contrib.auth.models import User
+from django.test import TestCase
+
+from api_v1 import models as api_models
+from api_v1.tasks import sync_external_printing_records
+from basic_info import models as basic_models
+from printing import models as printing_models
+from stateflow.models import Process, State
+
+
+class ExternalPrintingRecordsSyncTaskTest(TestCase):
+    def setUp(self):
+        self.merchant = basic_models.Merchant.objects.create(
+            name='测试印染厂',
+            type=basic_models.MerchantTypeEnum.FACTORY,
+        )
+        self.sync_user = User.objects.create_user(username='sync-user', password='testpass')
+        self.sync_employee = basic_models.Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.sync_user,
+            name='同步用户',
+        )
+        self.operator_user = User.objects.create_user(username='operator-user', password='testpass')
+        self.operator_employee = basic_models.Employee.objects.create(
+            merchant=self.merchant,
+            sys_user=self.operator_user,
+            name='钰涵',
+        )
+        self.customer = basic_models.Customer.objects.create(
+            merchant=self.merchant,
+            name='鸿烨服饰',
+        )
+        self.category = basic_models.ProductCategory.objects.create(
+            merchant=self.merchant,
+            name='同步产品类',
+            product_prefix='TP',
+        )
+        self.existing_product = basic_models.Product.objects.create(
+            merchant=self.merchant,
+            category=self.category,
+            name='Tj1712#12号色-24码',
+        )
+
+        state = State.objects.create(name='待生产')
+        self.process = Process.objects.create(name='默认印染流程')
+        self.process.replace_nodes([state])
+
+        settings.PRINTING_DEFAULT_PROCESS_ID = self.process.id
+        settings.PRINTING_EXTERNAL_SYNC_USER_ID = self.sync_user.id
+        settings.PRINTING_EXTERNAL_SYNC_PRODUCT_CATEGORY_ID = self.category.id
+
+    def _build_payload(self, records):
+        return {
+            'mode': 'incremental',
+            'cursor_before': 10,
+            'cursor_after': 12,
+            'last_record_id': records[-1]['ID'],
+            'updated': False,
+            'count': len(records),
+            'records': records,
+        }
+
+    def _build_record(self, *, record_id: int, product_name: str):
+        return {
+            'BeiZhu': '手感一定要柔软',
+            'BeiZhuC': '10件',
+            'BianHaoID': 'KD20432358',
+            'BianHaoKD': '1.27',
+            'CaoZY': '钰涵',
+            'FidJ': r'\\fw\\2026年-LWQ15\\2026\\H鸿烨\\Tj1712#',
+            'ID': record_id,
+            'JiJiaDW': '/段',
+            'KdRiQi': '2026-01-26T20:00:52Z',
+            'KhID': 'KH00999',
+            'MeoA': 'LWQ15',
+            'RiQi': '2026-01-26T00:00:00Z',
+            'SHDZ': '客户布  烧花',
+            'SeHao': '1.51',
+            'ShuLiang': '10.00',
+            'ShuLiangZ': '2.68',
+            'YanSe': product_name,
+            'customer': {
+                'KhID': 'KH00999',
+                'KhName': '鸿烨服饰',
+            },
+        }
+
+    @patch('api_v1.tasks._advance_external_printing_cursor')
+    @patch('api_v1.tasks._fetch_external_product_image')
+    @patch('api_v1.tasks._fetch_external_printing_records')
+    def test_existing_product_skips_image_fetch(
+        self,
+        mock_fetch_records,
+        mock_fetch_image,
+        mock_advance_cursor,
+    ):
+        mock_fetch_records.return_value = self._build_payload(
+            [self._build_record(record_id=1000000, product_name=self.existing_product.name)]
+        )
+        mock_advance_cursor.return_value = {'updated': True}
+
+        result = sync_external_printing_records.run(limit=100)
+
+        self.assertEqual(result['jobs_created'], 1)
+        self.assertEqual(result['failed_records'], 0)
+        self.assertEqual(mock_fetch_image.call_count, 0)
+        mock_advance_cursor.assert_called_once_with(cursor_value=1000000)
+
+        job = printing_models.PrintingJob.objects.get(original_id=1000000)
+        self.assertEqual(job.product, self.existing_product)
+        self.assertIsNone(job.external_product_name)
+
+    @patch('api_v1.tasks._advance_external_printing_cursor')
+    @patch('api_v1.tasks._upload_product_image')
+    @patch('api_v1.tasks._fetch_external_product_image')
+    @patch('api_v1.tasks._fetch_external_printing_records')
+    def test_missing_product_creates_product_and_job(
+        self,
+        mock_fetch_records,
+        mock_fetch_image,
+        mock_upload_product_image,
+        mock_advance_cursor,
+    ):
+        new_product_name = 'Tj1712#12号色-25码'
+        mock_fetch_records.return_value = self._build_payload(
+            [self._build_record(record_id=1000001, product_name=new_product_name)]
+        )
+        mock_fetch_image.return_value = {
+            'bytes': b'fake-image',
+            'content_type': 'image/jpeg',
+            'name': 'abc#123.jpg',
+        }
+        mock_advance_cursor.return_value = {'updated': True}
+
+        def _fake_upload(product, image_payload):
+            product.image = 'product_images/generated.jpg'
+            product.save(update_fields=['image'])
+
+        mock_upload_product_image.side_effect = _fake_upload
+
+        result = sync_external_printing_records.run(limit=100)
+
+        self.assertEqual(result['jobs_created'], 1)
+        self.assertEqual(result['failed_records'], 0)
+        mock_fetch_image.assert_called_once_with(new_product_name)
+
+        product = basic_models.Product.objects.get(name=new_product_name, merchant=self.merchant)
+        self.assertIsNotNone(product)
+        self.assertEqual(product.category, self.category)
+
+        job = printing_models.PrintingJob.objects.get(original_id=1000001)
+        self.assertEqual(job.product, product)
+
+    @patch('api_v1.tasks._advance_external_printing_cursor')
+    @patch('api_v1.tasks._fetch_external_product_image')
+    @patch('api_v1.tasks._fetch_external_printing_records')
+    def test_partial_failure_records_external_record_id_and_advances_cursor(
+        self,
+        mock_fetch_records,
+        mock_fetch_image,
+        mock_advance_cursor,
+    ):
+        success_record = self._build_record(record_id=1000000, product_name=self.existing_product.name)
+        failed_record = self._build_record(record_id=1000001, product_name='不存在图片的产品#1')
+        mock_fetch_records.return_value = self._build_payload([success_record, failed_record])
+        mock_advance_cursor.return_value = {'updated': True}
+
+        def _fake_fetch_image(product_name):
+            raise RuntimeError(f'外部图片不存在: {product_name}')
+
+        mock_fetch_image.side_effect = _fake_fetch_image
+
+        result = sync_external_printing_records.run(limit=100)
+
+        self.assertEqual(result['jobs_created'], 1)
+        self.assertEqual(result['failed_records'], 1)
+        self.assertEqual(result['failed_record_ids'], [1000001])
+        mock_advance_cursor.assert_called_once_with(cursor_value=1000001)
+
+        self.assertTrue(
+            printing_models.PrintingJob.objects.filter(original_id=1000000).exists()
+        )
+        self.assertFalse(
+            printing_models.PrintingJob.objects.filter(original_id=1000001).exists()
+        )
+
+        failure = api_models.PrintingExternalSyncFailure.objects.get(
+            external_record_id=1000001
+        )
+        self.assertEqual(failure.external_order_id, 'KD20432358')
+        self.assertIn('外部图片不存在', failure.error)