04a 销售计划导入流程

状态：✅ 已实现 | ⚙️ 配置驱动

1. 操作入口

方式	入口
GUI	导航栏「计划导入」→ ImportPage → 选择 Excel 文件
CLI	certflow import-sales-plan <file> [options]

2. 涉及配置

配置文件	关键字段	说明
config/import.yaml	create_placeholder_dirs	占位目录预建（B0-4，默认 OFF）
config/sales_importer.yaml	列映射 / 表头行 / 数据范围	Excel 解析参数
config/field_rules.yaml	字段校验规则	导入时校验
config/quarantine.yaml	隔离规则	异常记录入队
config/vba_import.yaml	VBA 字段映射	兼容旧系统

3. 涉及代码文件

层	文件	职责
View	views/import_page.py	导入页面
View	views/import_dialog.py	参数设置对话框
View	views/import_confirm_dialog.py	导入前确认
Controller	controllers/import_controller.py	编排
Service	services/sale_plan_service.py	销售计划 CRUD
Service	services/import_gate_service.py	撞键策略、重复检测
Service	services/correction_queue_service.py	异常隔离
Service	services/db_source_adapter.py	VBA 数据源适配
Handler	handlers/styled_excel_importer.py	Excel 读取（python-calamine）
Model	models/sale_plan.py	销售计划表
Model	models/quarantine_sale_plan.py	隔离队列表

4. 逐步流程

4.1 GUI 流程

1. 选择文件：在 ImportPage 选择销售计划 Excel

2. 设置参数（ImportDialog）：

   • scope（导入范围）

   • 月份

   • 行选择（起止行）

   • 表头行号

   • 列映射（覆盖 sales_importer.yaml 默认值）

   • 撞键策略（skip/overwrite/merge）

   • 试运行（dry-run）

3. 预览（ImportConfirmDialog）：展示将要导入的记录数、重复数、异常数

4. 确认导入：

   • ImportController 调用 SalePlanService

   • StyledExcelImporter 读取 Excel（python-calamine 引擎）

   • ImportGateService 应用撞键策略

   • 校验失败的记录经 CorrectionQueueService 入隔离队列

   • 成功记录写入 sale_plan 表

5. 查看结果：导入结果区显示统计

4.2 CLI 流程

certflow import-sales-plan /path/to/plan.xlsx \
  --scope all \
  --month 202608 \
  --header-row 3 \
  --dry-run

CLI 参数与 GUI 完全对齐（见 cli/commands/import_sales_plan.py）。

5. 占位目录（B0-4）

若 config/import.yaml 中 create_placeholder_dirs: true：

• 导入期按订单组（计划日期 + 订货单位 + 项目名称）预建 VBA 风格占位项目文件夹

• 命名模板：{ym}/{rq}/{customer}/{project}（见 config/models.py:130-137）

• 项目名称为空时使用兜底文本 【空白项目名称】

6. 异常处理

情况	处理
Excel 列缺失	按 sales_importer.yaml 默认映射补齐
字段校验失败	记录入隔离队列（quarantine_sale_plan 表）
撞键（重复）	按撞键策略处理（skip/overwrite/merge）
文件路径不可访问	启动时 check_data_sources() warning

7. 常见问题

• Windows 路径无法访问：.env 中 VALVE_SALES_PLAN_PATH 若为 K:\... 或含 MyPortableDev，start.sh 会 warning

• 空库首次启动：自动播种基础字典（材质/型号压力/口径），无需手动初始化