# 外部订单产品补图

本文档说明“外部印染订单产品补图”的手动命令、共享逻辑与定时任务配置。

## 背景

系统中有一类 `PrintingJob` 来自外部印染订单，同步后：

- `printing_order.external_order_id` 有值
- `product.image` 为空
- `job.external_raw.YanSe` 或 `job.external_product_name` 中包含可用于外部图片接口查询的名称

为了让产品图片逐步补齐，项目提供：

1. 手动 management command
2. 可复用的共享函数
3. 每小时一次的 Celery 定时任务

## 处理规则

补图任务只处理满足以下条件的数据：

1. `printing_order.external_order_id` 非空
2. `product.image` 为空
3. 能从以下字段提取请求名：
   - 优先：`external_raw.YanSe`
   - 回退：`external_product_name`

并且同一个 `product` 在单次运行中只会处理一次，避免重复请求外部图片接口。

## 共享逻辑

共享逻辑已抽到：

- [api_v1/external_product_image_backfill.py](/home/f/coding/flower/api_v1/external_product_image_backfill.py)

其中：

- `extract_request_name(job)`
- `run_external_product_image_backfill(...)`

management command 与 Celery task 都复用这套逻辑，避免出现双份实现。

## 手动运行

命令位置：

- [api_v1/management/commands/backfill_external_product_images.py](/home/f/coding/flower/api_v1/management/commands/backfill_external_product_images.py)

### 示例

处理指定商户：

```bash
python manage.py backfill_external_product_images --merchant-id 1
```

限制本次最多处理 50 条：

```bash
python manage.py backfill_external_product_images --merchant-id 1 --limit 50
```

只预览、不实际写库：

```bash
python manage.py backfill_external_product_images --merchant-id 1 --dry-run
```

仅处理指定产品：

```bash
python manage.py backfill_external_product_images --product-id 123
```

### 参数

| 参数 | 说明 |
|------|------|
| `--merchant-id` | 仅处理指定商户的产品 |
| `--product-id` | 仅处理指定产品 |
| `--limit` | 最多处理多少条符合条件的产品 |
| `--dry-run` | 仅输出将处理的产品，不实际请求外部 API 或写库 |

## Celery Task

Task 位置：

- [api_v1/tasks.py](/home/f/coding/flower/api_v1/tasks.py)

Task 名称：

- `api_v1.tasks.backfill_external_product_images`

支持参数：

- `merchant_id`
- `product_id`
- `limit`
- `dry_run`

默认建议：

- `limit=500`
- `dry_run=False`

## 定时任务

已接入 `CELERY_BEAT_SCHEDULE`：

- key: `backfill_external_product_images_hourly`
- schedule: `crontab(minute=17)`
- kwargs:
  - `limit=500`
  - `dry_run=False`

也就是说：

- 每小时第 `17` 分钟运行一次
- 采用错峰策略，避免和若干整点/五分钟任务撞在一起

配置位置：

- [flower/settings.py](/home/f/coding/flower/flower/settings.py)

## 输出与结果

无论是 command 还是 task，最终都会产出统一统计结果，包含：

- `scanned`
- `selected`
- `success`
- `failed`
- `skipped_with_image`
- `skipped_without_request_name`
- `skipped_duplicate_product`

Celery task 还会额外带：

- `task_id`

## 风险与建议

1. 这是外部接口依赖任务，若外部图片接口不稳定，`failed` 可能升高
2. 每小时一次已足够，`limit=500` 对“补漏”场景比较合适
3. 如果后续发现积压较多，可以只调大 `limit`，不必提高调度频率
4. 若未来需要追踪失败明细，可考虑像外部印染同步那样补失败落库；当前版本仅记录日志