# 详细工作流

本文档详细说明 Excel 数据导入的完整工作流程。

## 1. 准备阶段

### 1.1 准备源数据文件

确保源数据文件符合以下要求：
- 文件格式：.xlsx 或 .xlsm
- 包含明确的表头行
- 数据格式规范（无空白行、无合并单元格）
- 关键字段（如身份证号）无重复

### 1.2 准备目标模板文件

确保目标模板文件符合以下要求：
- 文件格式：.xlsx 或 .xlsm
- 包含明确的表头行
- 可以有合并单元格（多层表头）
- 预留数据区域

### 1.3 创建配置文件

根据实际需求创建 YAML 配置文件，参考 `example_config.yaml`。

## 2. 配置阶段

### 2.1 定义源数据配置

```yaml
source:
  file_path: "path/to/source.xlsx"  # 源数据文件路径
  sheet_name: "Sheet1"               # 工作表名称
  header_row: 1                      # 表头行号
  key_field: "身份证号"              # 用于匹配的关键字段
```

**重要说明**：
- `file_path`: 可以是相对路径或绝对路径
- `sheet_name`: 必须与 Excel 文件中的工作表名称完全一致
- `header_row`: 表头所在的行号（从1开始计数）
- `key_field`: 用于匹配源数据和目标数据的关键字段名

### 2.2 定义目标模板配置

```yaml
target:
  file_path: "path/to/template.xlsx"  # 目标模板文件路径
  sheet_name: "人员信息"               # 目标工作表名称
  header_row: 2                       # 表头行号（可能是多行表头）
  data_start_row: 3                   # 数据起始行
  output_path: "path/to/output.xlsx"  # 输出文件路径
```

**重要说明**：
- `header_row`: 目标表的表头行号（如果有多个表头行，通常是最后一行）
- `data_start_row`: 数据写入的起始行号
- `output_path`: 导入结果的保存路径

### 2.3 定义字段映射

字段映射定义了源数据字段到目标模板字段的对应关系。

```yaml
field_mappings:
  - source: "姓名"          # 源字段名
    target: "员工姓名"      # 目标字段名
    required: true          # 是否必填
    transform: "strip"      # 数据转换函数
    default: "未知"         # 默认值（可选）
```

**字段映射选项**：
- `source`: 源数据表的字段名（必填）
- `target`: 目标模板的字段名（必填）
- `required`: 是否为必填字段（可选，默认 false）
- `default`: 默认值，当源字段为空时使用（可选）
- `transform`: 数据转换函数（可选）
- `validate`: 验证规则（可选）

## 3. 执行阶段

### 3.1 运行导入

```bash
cd /home/aqbjqtd/.claude/tmp/excel-data-import
python scripts/excel_import.py assets/examples/example_config.yaml
```

### 3.2 导入过程

导入过程包含以下步骤：

1. **备份目标文件**（如果启用）
   - 自动备份到指定目录
   - 备份文件名包含时间戳

2. **加载工作簿**
   - 加载源数据文件
   - 加载目标模板文件

3. **分析工作表结构**
   - 识别表头和数据区域
   - 识别合并单元格

4. **执行数据导入**
   - 根据关键字段匹配数据
   - 应用字段映射
   - 应用数据转换
   - 验证数据

5. **保存结果**
   - 保存导入结果
   - 生成验证报告
   - 记录错误日志

### 3.3 查看进度

导入过程中会显示进度信息：
```
开始执行导入任务: 人员信息导入
时间: 2024-01-20 10:30:00
------------------------------------------------------------
✓ 已备份目标文件: backup/test_template_备份_20240120_103000.xlsx
✓ 已加载源数据: assets/examples/test_source.xlsx
✓ 已加载目标模板: assets/examples/test_template.xlsx
✓ 源数据表分析完成: 共 100 行
✓ 目标模板分析完成: 共 50 行
✓ 发现 5 个合并单元格区域
------------------------------------------------------------
开始导入数据...
  已处理: 10/100
  已处理: 20/100
  ...
✓ 数据导入完成: 共处理 100 条记录
✓ 结果已保存: assets/examples/test_output.xlsx
✓ 导入报告已保存: assets/examples/import_report.json
------------------------------------------------------------
✅ 导入完成！
总记录数: 100
成功: 95
失败: 5
```

## 4. 验证阶段

### 4.1 查看结果文件

打开输出文件，检查数据是否正确导入：
- 数据是否完整
- 格式是否正确
- 合并单元格是否保持

### 4.2 查看验证报告

验证报告是一个 JSON 文件，包含详细的导入统计信息。

**报告内容**：
```json
{
  "task_name": "人员信息导入",
  "timestamp": "2024-01-20T10:30:00",
  "summary": {
    "total_records": 100,
    "successful": 95,
    "failed": 5,
    "skipped": 0
  },
  "errors": [
    {
      "row": 10,
      "field": "身份证号",
      "value": "123456",
      "error": "格式错误"
    }
  ]
}
```

### 4.3 查看错误日志

如果有错误，查看错误日志了解详细错误信息。

**日志位置**: `logs/import_errors.log`

**日志内容**：
```
导入错误日志
时间: 2024-01-20 10:30:00
============================================================

错误 (5 条):
[2024-01-20T10:30:15] 行 10: 身份证号格式错误
[2024-01-20T10:30:16] 行 25: 必填字段 姓名 为空
...
```

## 5. 常见场景

### 场景1: 新增数据

如果目标模板为空，所有源数据都会作为新行添加。

**配置**：
- 不需要特殊配置
- 数据会从 `data_start_row` 开始添加

### 场景2: 更新数据

如果目标模板已有数据，会根据 `key_field` 匹配并更新对应行。

**配置**：
- 确保 `key_field` 配置正确
- 源数据和目标数据的关键字段值必须一致

### 场景3: 混合模式

既有新增又有更新：
- 匹配到的行：更新
- 未匹配到的行：新增

## 6. 故障排除

### 问题1: 找不到匹配的行

**原因**：
- `key_field` 配置错误
- 源数据和目标数据的关键字段值不一致

**解决**：
- 检查配置文件中的 `key_field` 是否正确
- 检查源数据和目标数据的关键字段值是否一致（注意空格）

### 问题2: 数据格式错误

**原因**：
- 数据类型不匹配
- 数据格式不符合要求

**解决**：
- 使用 `transform` 转换数据格式
- 使用 `validate` 验证数据

### 问题3: 合并单元格格式被破坏

**原因**：
- `preserve_formatting` 设置为 `false`

**解决**：
- 确保 `options.preserve_formatting` 设置为 `true`

## 7. 最佳实践

### 7.1 数据准备

1. **清理源数据**：删除空白行、空格、重复数据
2. **规范字段名**：使用清晰、一致的字段名
3. **验证关键字段**：确保关键字段（如身份证号）无重复、无缺失

### 7.2 配置优化

1. **使用默认值**：为可选字段设置合理的默认值
2. **启用数据验证**：配置验证规则确保数据质量
3. **启用备份**：避免意外覆盖原文件

### 7.3 批量导入

1. **分批导入**：大数据量可以分批导入
2. **测试先行**：先用少量数据测试配置
3. **验证结果**：每次导入后仔细验证结果

---

**相关文档**：
- [配置文件完整说明](configuration.md)
- [API 参考](api_reference.md)
- [使用示例](examples.md)
- [故障排除](troubleshooting.md)