供货类型回填工具 (CLI)¶

⚠️ 本文档对应 scripts/backfill_supply_type.py（早期独立脚本）。新版 CLI 命令为 certflow backfill-supply-type，详见 CLI.md。

概述¶

backfill_supply_type.py 是一个命令行回填工具，从"已完成工单"Excel 的月份工作表中读取"供货类型"字段，按"生产令号"匹配数据库记录，将值回填到 supply_type 字段。

核心逻辑¶

只处理月份工作表：仅读取 2026-01 ~ 2026-12 的工作表，其他表一律忽略
按列名匹配：通过 Excel 列标题（"生产令号"、"供货类型"）定位数据，不依赖列号
精确匹配：通过 production_order_no（生产令号）与数据库匹配
统一回填：同一生产令号的所有 DB 记录回填相同的供货类型
安全回填：默认仅填充空值（supply_type 为空或以 【空白 开头的占位符），不覆盖已有值

基本用法¶

python scripts/backfill_supply_type.py [选项]

参数说明¶

参数	简写	说明	必填	默认值
`--file`	`-f`	Excel 文件路径（覆盖 config.yaml 配置）	❌ 否	config.yaml 中的配置
`--dry-run`		预览模式：读取并匹配但不写入数据库	❌ 否	False
`--overwrite`		覆盖已有的 `supply_type` 值	❌ 否	False
`--no-backup`		跳过数据库备份	❌ 否	False
`--verbose`	`-v`	详细输出（DEBUG 级别日志）	❌ 否	False

使用示例¶

1. 预览模式（推荐首次使用）¶

查看将回填哪些数据，不实际写入：

python scripts/backfill_supply_type.py --dry-run --verbose

输出示例：

文件: D:\links\CertFlow-PySide6\temp\excel\已完成工单【202601--202612】.xlsx
匹配列(Excel): '生产令号' → DB字段: 'production_order_no'
来源列(Excel): '供货类型' → DB字段: 'supply_type'
模式: 预览

工作表扫描: ['本月已发', 'Sheet11', '2026-01', '2026-02', '2026-3', '2026-4', '2026-5']
  跳过非月份工作表: 本月已发
  跳过非月份工作表: Sheet11
  2026-01: 105 条有效数据 (共 105 行)
  2026-02: 83 条有效数据 (共 83 行)
  2026-3: 65 条有效数据 (共 66 行)
  2026-4: 116 条有效数据 (共 116 行)
  2026-5: 96 条有效数据 (共 96 行)

读取完成: 5 个月份工作表, 共 465 条有效数据
供货类型分布: {'自制': 174, '外购': 131, '供应': 69, '维修': 64, '库存': 17, ...}

============================================================
回填结果汇总 [预览]:
  Excel 唯一生产令号: 464
  DB 匹配记录数:     454
  DB 唯一生产令号:   454
  更新记录数:        454
  未匹配跳过:        10
  已有值跳过:        0
============================================================

预览示例 (前15个唯一生产令号):
  202506003-2           → 自制
  202506003-3           → 外购
  ...

2. 正式回填¶

确认预览结果无误后，执行正式回填：

python scripts/backfill_supply_type.py --verbose

3. 指定其他 Excel 文件¶

python scripts/backfill_supply_type.py --file "D:/links/Hard/已完成工单_backup.xlsx"

4. 覆盖已有值¶

如果某些记录的 supply_type 已有值，但仍希望覆盖：

python scripts/backfill_supply_type.py --overwrite

5. 跳过备份¶

数据库备份默认开启，如需跳过：

python scripts/backfill_supply_type.py --no-backup

供货类型值¶

从 Excel 中读取的供货类型包括：

类型	说明
自制	自行生产
外购	外部采购
供应	供应件
维修	维修件
库存	库存件
试压	试压件
返修	返修件
利用预存	利用预存库存
仅挂牌	仅挂牌

配置文件¶

工具通过 config/config.yaml 中的 completed_orders_backfill 段驱动：

completed_orders_backfill:
  # 数据源文件路径（支持环境变量语法）
  file_path: "${COMPLETED_ORDERS_PATH:temp/excel/已完成工单【202601--202612】.xlsx}"

  # Excel 列名映射
  match_field: "生产令号"          # Excel 匹配列
  source_field: "供货类型"         # Excel 来源列

  # 数据库映射
  db_match_field: "production_order_no"  # DB 匹配字段
  db_target_field: "supply_type"         # DB 目标字段

  # 选项
  overwrite_existing: false        # 是否覆盖已有值
  backup_before_update: true       # 更新前是否备份
  backup_suffix: "_before_supply_type_backfill"  # 备份文件后缀

环境变量配置¶

文件路径支持 ${ENV_VAR:default} 语法：

# 通过环境变量指定文件路径
set COMPLETED_ORDERS_PATH=D:\links\Hard\已完成工单【202601--202612】.xlsx
python scripts/backfill_supply_type.py

匹配规则¶

工作表识别¶

使用正则 ^2026[-_](\d{1,2})$ 匹配月份工作表：

✅ 2026-01、2026-02、2026-3、2026-12
❌ 本月已发、A202501、2024已完成已发货

数据匹配¶

按"生产令号"精确匹配 DB 的 production_order_no
同一生产令号的所有 DB 记录回填相同的供货类型
【空白 开头的值视为空值，允许覆盖

空值处理¶

仅填充 supply_type 为空（None/空字符串）的记录
supply_type 以 【空白 开头的占位符视为空值
已有实际值的记录默认跳过（除非使用 --overwrite）

输出说明¶

成功回填时¶

文件: D:\links\CertFlow-PySide6\temp\excel\已完成工单【202601--202612】.xlsx
模式: 写入
数据库已备份: D:\links\CertFlow-PySide6\database\certflow_before_supply_type_backfill.db
数据库更新已提交 (454 条)
============================================================
回填结果汇总 [写入]:
  Excel 唯一生产令号: 464
  DB 匹配记录数:     454
  DB 唯一生产令号:   454
  更新记录数:        454
  未匹配跳过:        10
  已有值跳过:        0
============================================================
回填完成!

统计字段说明¶

字段	说明
Excel 唯一生产令号	Excel 中读取到的唯一生产令号数量
DB 匹配记录数	数据库中找到的匹配记录数
DB 唯一生产令号	数据库中匹配到的唯一生产令号数量
更新记录数	实际更新的记录数
未匹配跳过	Excel 中存在但数据库未找到的生产令号数
已有值跳过	数据库已有值且未被覆盖的记录数

回滚恢复¶

工具会自动备份数据库，备份文件位于：

database/certflow_before_supply_type_backfill.db

如需回滚，将备份文件重命名为原数据库文件：

copy /Y database\certflow_before_supply_type_backfill.db database\certflow.db

常见问题¶

Q: 预览模式显示正常，但正式回填后数据不对？¶

先用 --dry-run --verbose 确认预览结果。正式回填会自动备份，如有问题可用备份文件恢复。

Q: 某些生产令号未匹配怎么办？¶

未匹配的生产令号会在日志中列出（verbose 模式下）。可能原因：

该生产令号在数据库中不存在
生产令号格式不一致（如多了后缀）
数据库尚未导入对应数据

Q: 同一生产令号有多条记录，供货类型不同怎么办？¶

工具会按首次出现的供货类型统一回填。实际上同一生产令号的供货类型应该是一致的。如果 Excel 中同一生产令号出现不同供货类型，建议先检查源数据。

Q: 如何回填已完成工单的 7~12 月数据？¶

等待 Excel 文件中出现对应月份工作表后，重新运行即可。工具会自动跳过已有值的记录。