feat: shipment change && version modelize

docs/api_v1_shipment_stage_query_2026-07-09.md

@@ -0,0 +1,113 @@
+# Shipment 逻辑状态查询 API
+
+## 接口
+
+```http
+GET /api/v1/shipment/shipments/
+```
+
+该接口为出货单列表接口，支持分页。本文只说明逻辑状态查询字段 `shipment_stage`。
+
+## 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `shipment_stage` | string | 否 | 出货单逻辑状态 |
+| `limit` | integer | 否 | 分页大小 |
+| `offset` | integer | 否 | 分页偏移 |
+
+`shipment_stage` 不使用原有 `status` 字段，避免和出货单自身状态冲突。
+
+## shipment_stage 枚举
+
+| 值 | 展示文案 | 过滤规则 |
+| --- | --- | --- |
+| `missing_address` | 待补地址 | 出货单未取消、未绑定送货单、`address` 为空 |
+| `deliverable` | 可送货 | 出货单未取消、未绑定送货单、`address` 非空 |
+| `scheduled` | 已排车 | 出货单未取消、已绑定送货单，且送货单状态为 `待送货` 或 `送货中` |
+| `delivered` | 已送达 | 出货单未取消、已绑定送货单，且送货单状态为 `已送达` |
+| `cancelled` | 已取消 | 出货单自身状态为 `已取消` |
+
+## 请求示例
+
+查询待补地址：
+
+```http
+GET /api/v1/shipment/shipments/?shipment_stage=missing_address&limit=20&offset=0
+```
+
+查询可送货：
+
+```http
+GET /api/v1/shipment/shipments/?shipment_stage=deliverable&limit=20&offset=0
+```
+
+查询已排车：
+
+```http
+GET /api/v1/shipment/shipments/?shipment_stage=scheduled&limit=20&offset=0
+```
+
+查询已送达：
+
+```http
+GET /api/v1/shipment/shipments/?shipment_stage=delivered&limit=20&offset=0
+```
+
+查询已取消：
+
+```http
+GET /api/v1/shipment/shipments/?shipment_stage=cancelled&limit=20&offset=0
+```
+
+## 返回字段
+
+列表结果中每条出货单新增：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `shipment_stage` | string/null | 逻辑状态枚举值 |
+| `shipment_stage_display` | string/null | 逻辑状态展示文案 |
+
+示例：
+
+```json
+{
+  "count": 1,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "id": 123,
+      "status": 5,
+      "status_display": "已审核",
+      "shipment_stage": "scheduled",
+      "shipment_stage_display": "已排车",
+      "delivery_id": 88,
+      "address": "绍兴市测试路 8 号"
+    }
+  ]
+}
+```
+
+## 错误响应
+
+如果 `shipment_stage` 不是支持的枚举值，返回 `400`。
+
+示例：
+
+```http
+GET /api/v1/shipment/shipments/?shipment_stage=unknown
+```
+
+```json
+{
+  "shipment_stage": "shipment_stage 必须是 cancelled, deliverable, delivered, missing_address, scheduled 之一"
+}
+```
+
+## 说明
+
+- `status` 仍表示出货单自身状态，不表示逻辑状态。
+- `shipment_stage` 是根据出货单地址、送货单绑定关系、送货单状态动态计算出来的逻辑状态。
+- 过滤在数据库查询阶段完成，因此分页 `count` 和 `results` 都是过滤后的结果。

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