# 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 流程

```bash
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
- **空库首次启动**：自动播种基础字典（材质/型号压力/口径），无需手动初始化