销售计划导入工具 (CLI)¶

⚠️ 本文档对应 scripts/import_sales_plan.py（早期独立脚本）。新版 CLI 命令为 certflow import-sales-plan，详见 CLI.md。

概述¶

import_sales_plan.py 是一个命令行导入工具，无需启动 UI 即可批量导入销售计划数据到数据库。

安装¶

工具已集成在项目中，无需额外安装。

基本用法¶

uv run python scripts/import_sales_plan.py --file "D:/links/Hard/2026年销售计划.xlsx" [选项]

参数说明¶

参数	简写	说明	必填	默认值
`--file`	`-f`	Excel 文件路径	✅ 是	-
`--sheet`	`-s`	工作表名称（如 "1月"）	❌ 否	-
`--all-sheets`	`-a`	导入所有工作表	❌ 否	False
`--list-sheets`	`-l`	列出所有工作表	❌ 否	False
`--no-format`		不使用格式导入（只导入数据）	❌ 否	False

使用示例¶

1. 列出 Excel 中的所有工作表¶

uv run python scripts/import_sales_plan.py --file "D:/links/Hard/2026年销售计划.xlsx" --list-sheets

输出示例：

📋 工作表列表 (D:/links/Hard/2026年销售计划.xlsx):
1月
2月
3月
4月
5月
6月
2026年不计价
2026年计划取消

2. 导入单个工作表（带格式）¶

uv run python scripts/import_sales_plan.py --file "D:/links/Hard/2026年销售计划.xlsx" --sheet "1月"

带格式导入会保留：

单元格背景色
字体颜色
批注信息
行隐藏状态

3. 导入单个工作表（不带格式）¶

uv run python scripts/import_sales_plan.py --file "D:/links/Hard/2026年销售计划.xlsx" --sheet "1月" --no-format

4. 批量导入所有工作表¶

uv run python scripts/import_sales_plan.py --file "D:/links/Hard/2026年销售计划.xlsx" --all-sheets

输出示例：

🚀 开始导入所有工作表...
   文件: D:/links/Hard/2026年销售计划.xlsx
   工作表: ['1月', '2月', '3月', '4月', '5月', '6月', '2026年不计价', '2026年计划取消']
   带格式: True
============================================================

📄 导入工作表: 1月
   文件: D:/links/Hard/2026年销售计划.xlsx
   带格式: True
--------------------------------------------------
   ✅ 导入成功!
      新增: 817 条
      跳过: 0 条
      分组: 350 个

📄 导入工作表: 2月
...

============================================================
📊 导入汇总:
   1月: 新增 817, 跳过 0
   2月: 新增 0, 跳过 817
   3月: 新增 0, 跳过 817
   总计: 新增 817, 跳过 1634

导入规则¶

唯一键 (unique_key)¶

系统根据以下字段组合生成唯一键，用于判断重复：

客户 (customer)
项目名称 (project_name)
产品名称 (product_name)
产品型号 (product_model)
产品规格 (product_spec)
数量 (quantity)

重复处理¶

如果记录已存在且 UPDATE_ON_DUPLICATE = True，会更新字段并记录变更历史
如果记录已存在且 UPDATE_ON_DUPLICATE = False，会跳过

计划单号格式化¶

纯数字且长度 ≤ 4：补零到 4 位（如 123 → 0123）
纯数字且长度 > 4：截取右边 4 位（如 54321 → 4321）
格式化后添加 YYMM 前缀：2601_0123

日期格式化¶

所有业务日期统一格式化为 YYYY-MM-DD
支持 datetime 对象、pandas.Timestamp、多种字符串格式

输出说明¶

导入成功时¶

{
  "success": true,
  "total": 817,           // 新增记录数
  "skipped": 0,           // 跳过记录数（重复）
  "groups": 350,          // 分组数
  "status_stats": {...},  // 格式状态统计
  "records": [...]        // 前20条记录预览
}

导入失败时¶

{
  "success": false,
  "error": "错误信息"
}

常见问题¶

Q: 导入时提示"文件不存在"¶

检查文件路径是否正确，使用绝对路径：

uv run python scripts/import_sales_plan.py --file "D:/links/Hard/2026年销售计划.xlsx"

Q: 如何导入多个文件？¶

可以编写批处理脚本：

Windows (import_all.bat):

@echo off
for %%f in (D:\links\Hard\*.xlsx) do (
    uv run python scripts/import_sales_plan.py --file "%%f" --all-sheets
)

Linux/Mac (import_all.sh):

#!/bin/bash
for f in /path/to/excel/*.xlsx; do
    uv run python scripts/import_sales_plan.py --file "$f" --all-sheets
done

Q: 带格式和不带格式有什么区别？¶

特性	带格式	不带格式
读取速度	较慢	快速
背景色	✅	❌
字体色	✅	❌
批注	✅	❌
隐藏行	✅	❌
格式状态	✅	❌

Q: 导入后如何查看数据？¶

使用查询工具：

# 查看统计
uv run python scripts/quick_query.py --stats

# 查询客户订单
uv run python scripts/quick_query.py --customer "东方电气"

与其他工具对比¶

方式	优点	适用场景
UI 导入	可视化配置列映射	首次导入、需要预览
CLI 导入	可脚本化、批量处理	定期批量导入、自动化
直接数据库	最快	数据迁移、初始化