feat: shipment change && version modelize

docs/printing_external_records_sync_2026-03-20.md

@@ -47,7 +47,7 @@
 | `MeoA` | 曲线 | `PrintingOrder.curve` | 原样保存 |
 | `FidJ` | 电脑位置 | `PrintingOrder.position` | 取分组首条 record 的原始值 |
 | `BeiZhu` | 滚筒注意事项 | `PrintingOrder.rolling_warn` | 原样保存 |
-| `KdRiQi` | 下单日期 | `PrintingOrder.outgoing_date` | 按 ISO 时间解析并保存 |
+| `KdRiQi` | 外部开单日期时间 | `PrintingOrder.outgoing_date` / `PrintingOrder.kd_riqi` | 按中国时间解析并保存；即使外部字符串带 `Z`，也按本地业务时间解释；`kd_riqi` 用于 API 展示、筛选和排序 |
 | 分组首条原始数据 | 外部来源快照 | `PrintingOrder.external_raw` | 保存 order 级别的原始数据，便于追溯 |
 
 补充说明：
@@ -56,6 +56,80 @@
 - 外部 `area` 直接写入 `PrintingOrder.area`；若外部未返回或为空，则统一写入空字符串
 - `BianHaoKD`、`RiQi` 等当前未单独属性化的字段，保留在 `external_raw` 中
 - `BianHaoKD` 当前样例值类似 `"1.27"`，不按日期强解析
+- 外部 `KdRiQi` 样例可能形如 `2026-07-08T17:22:22Z`，但业务语义为中国时间 `2026-07-08 17:22:22`，不能按 UTC 解释，否则 API 展示会偏移 8 小时
+
+## 历史 `kd_riqi` 回填命令
+
+新增字段 `PrintingOrder.kd_riqi` 后，新同步数据会自动写入该字段。历史数据的 `KdRiQi` 已保存在 `external_raw.first_record.KdRiQi`，可用以下 management command 批量回填。
+
+命令文件：
+
+- `printing/management/commands/backfill_printing_order_kd_riqi.py`
+
+默认处理范围：
+
+- 只处理 `PrintingOrder.kd_riqi IS NULL` 的订单
+- 从 `external_raw.first_record.KdRiQi` 提取并解析时间
+- 解析成功则批量写入 `kd_riqi`
+- 缺失或解析失败的数据跳过并计数
+- 不覆盖已有 `kd_riqi`
+- 使用 `bulk_update(['kd_riqi'])`，不会更新 `updated_at`
+
+历史错误值修正模式：
+
+- 传 `--overwrite` 后，不再限定 `kd_riqi IS NULL`
+- 所有存在 `external_raw` 且能读取 `external_raw.first_record.KdRiQi` 的订单都会重新解析并覆盖 `kd_riqi`
+- 传 `--update-outgoing-date` 后，会同时覆盖 `outgoing_date`
+- 该模式用于修正早期把外部 `KdRiQi` 误按 UTC 解析导致的 8 小时偏移
+
+推荐先 dry-run：
+
+```bash
+docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py backfill_printing_order_kd_riqi --dry-run
+```
+
+确认统计后批量执行：
+
+```bash
+docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py backfill_printing_order_kd_riqi
+```
+
+常用参数：
+
+- `--dry-run`：只统计，不写入
+- `--batch-size 1000`：批量读取和批量写入大小，默认 `1000`
+- `--limit 5000`：最多处理多少条候选记录
+- `--merchant-id 1`：限定商户
+- `--external-order-id KD20453713`：限定外部订单编号，适合单条验证
+- `--overwrite`：覆盖已有 `kd_riqi`，用于修正历史按 UTC 解析导致的偏移数据
+- `--update-outgoing-date`：同时用 `KdRiQi` 修正 `outgoing_date`
+
+输出为 JSON，典型字段：
+
+```json
+{
+  "dry_run": true,
+  "matched": 18000,
+  "updated": 0,
+  "would_update": 17800,
+  "skipped_missing": 150,
+  "skipped_invalid": 50,
+  "overwrite": false,
+  "update_outgoing_date": false
+}
+```
+
+历史偏移数据修正建议先 dry-run：
+
+```bash
+docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py backfill_printing_order_kd_riqi --overwrite --update-outgoing-date --dry-run
+```
+
+确认后执行：
+
+```bash
+docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web uv run python manage.py backfill_printing_order_kd_riqi --overwrite --update-outgoing-date
+```
 
 ### 二、单条 record -> PrintingJob