feat: error_code + api doc + printing-job fields

api_v1/tasks.py

@@ -743,6 +743,10 @@ def _upload_product_image(product, image_payload: dict):
     product.save(update_fields=['image', 'updated_at'])
 
 
+def _external_product_allows_missing_image(external_product_name: str) -> bool:
+    return '白布' in str(external_product_name or '').strip()
+
+
 @shared_task(bind=True)
 def backfill_external_product_images(
     self,
@@ -811,23 +815,38 @@ def _ensure_external_product(*, merchant, external_product_name: str, category):
     if not normalized:
         raise RuntimeError('外部产品名为空，无法创建/绑定产品')
 
+    allows_missing_image = _external_product_allows_missing_image(normalized)
     existing_product = (
         basic_models.Product.objects.filter(merchant=merchant, name=normalized)
         .order_by('id')
         .first()
     )
     if existing_product:
+        if existing_product.image:
+            return existing_product, False
+        if allows_missing_image:
+            return existing_product, False
+        image_payload = _fetch_external_product_image(normalized)
+        _upload_product_image(existing_product, image_payload)
         return existing_product, False
 
-    image_payload = _fetch_external_product_image(normalized)
     product = basic_models.Product.objects.create(
         merchant=merchant,
         category=category,
         name=normalized,
     )
     try:
+        image_payload = _fetch_external_product_image(normalized)
         _upload_product_image(product, image_payload)
-    except Exception:
+    except Exception as exc:
+        if allows_missing_image:
+            logger.warning(
+                '外部白布产品图片缺失，已创建无图 Product: product_id=%s product_name=%s error=%s',
+                product.id,
+                normalized,
+                exc,
+            )
+            return product, True
         if product.image:
             try:
                 product.image.delete(save=False)
@@ -1876,14 +1895,14 @@ def sync_mdy_plate_orders_for_merchant(
 
 
 @shared_task(bind=True)
-def sync_external_printing_records(self, limit: int = 100):
+def sync_external_printing_records(self, limit: int = 100, advance_cursor: bool = True):
     """
     从外部 records 接口增量同步印染订单/任务。
 
     策略：
     - 拉取时强制 update_cursor=false
     - 按外部 record.ID 处理失败并记录
-    - 本批处理结束后无论是否有部分失败，都推进远端 cursor
+    - 默认在本批处理结束后推进远端 cursor；本地检查可传 advance_cursor=False 禁止推进
     """
     limit = max(1, int(limit or 100))
     sync_user = _get_printing_sync_user()
@@ -1908,7 +1927,7 @@ def sync_external_printing_records(self, limit: int = 100):
         )
 
         cursor_payload = None
-        if last_record_id is not None:
+        if advance_cursor and last_record_id is not None:
             cursor_payload = _advance_external_printing_cursor(cursor_value=int(last_record_id))
     else:
         batch_result = {
@@ -1947,6 +1966,7 @@ def sync_external_printing_records(self, limit: int = 100):
         'cursor_before': payload.get('cursor_before'),
         'cursor_after': payload.get('cursor_after'),
         'cursor_updated': bool(cursor_payload),
+        'advance_cursor': bool(advance_cursor),
         'group_count': batch_result['group_count'],
     }
     logger.info('外部印染 records 同步完成: %s', result)