# Excel to SQL Server 迁移工具

将生产执行卡 Excel 数据（压力表 PG / 温度计 TM）按年份迁移到 SQL Server `executionCard` Schema。

## 项目结构

```
Excel/
  PG/          # 压力表 Excel 文件
  TM/          # 温度计 Excel 文件
migrate.py     # 迁移脚本（一次性全量 / TRUNCATE 模式）
sync.py        # LAN 文件同步模块
watch.py       # 定时守护进程（自动同步 + 增量迁移）
config.yaml    # 配置文件（含数据库连接、LAN 路径、数据源映射）
requirements.txt
```

## 使用前准备

1. 安装依赖：

```bash
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
```

2. 确保 SQL Server 已安装 **ODBC Driver 18**

3. 复制 `config.yaml.example` 为 `config.yaml`，填入实际的数据库连接信息

> `config.yaml` 已加入 `.gitignore`，不会提交到仓库。

## 使用方式

### 一次性迁移（migrate.py）

```bash
# 激活虚拟环境
.venv/Scripts/activate

# 预览模式（不写入数据库）
python migrate.py --dry-run

# 全表迁移（默认 DROP + CREATE）
python migrate.py

# 全表迁移（TRUNCATE 模式，保留表结构）
python migrate.py --truncate

# 单表迁移
python migrate.py --table PG_2022

# 多表迁移
python migrate.py --table PG_2022 TM_2025

# 指定配置文件
python migrate.py --config /path/to/config.yaml
```

### 定时同步守护进程（watch.py）

自动从局域网 UNC 路径同步 Excel 文件到本地，仅当文件发生变化时触发对应年份表的迁移。

```bash
# 启动守护进程（默认每 30 分钟检查一次）
python watch.py

# 单次执行后退出（用于测试或手动触发）
python watch.py --once

# 自定义同步间隔（1 分钟，用于调试）
python watch.py --interval 1

# 指定配置文件
python watch.py --config /path/to/config.yaml
```

**运行逻辑：**
1. 首次运行：同步所有 LAN 文件并强制迁移全部表
2. 后续周期：仅同步有变化的文件，只迁移受影响的表
3. 使用 TRUNCATE 模式（保留表结构，清空数据后重新插入）
4. 单表迁移失败不影响其他表（错误隔离）
5. 日志同时输出到控制台和 `watch.log` 文件

## 迁移模式对比

| 模式 | 命令 | 行为 |
|------|------|------|
| DROP + CREATE | `python migrate.py` | 每次删除并重建表，适用于表结构可能变化的场景 |
| TRUNCATE | `python migrate.py --truncate` | 保留表结构仅清空数据，性能更好，`watch.py` 自动使用此模式 |

TRUNCATE 模式在检测到列名变化时会自动回退到 DROP + CREATE。

## SQL Server 表结构

- Schema: `executionCard`
- 每张表结构：`id INT IDENTITY(1,1)` + 主键 `总排号 NVARCHAR(50)` + 各年份数据列

| 表名 | 数据来源 | 行数 |
|------|---------|------|
| PG_2022 ~ PG_2026 | 压力表 Excel | ~274,623 |
| TM_2022 ~ TM_2026 | 温度计 Excel | ~56,129 |

## 配置说明（config.yaml）

- `sql_server` — 数据库连接信息
- `tables` — 目标表与 Excel 文件/工作表的映射关系，sources 中后出现的覆盖先出现的（同总排号时）
- `type_rules` — 列名到 SQL 类型的推断规则
- `column_mapping` — 列名重映射（如 `ID` → `CRM订单明细ID`）
- `check_interval_minutes` — 定时检查间隔（分钟），默认 30
- `lan_sources` — 本地相对路径到局域网 UNC 路径的映射，用于自动同步

## 注意事项

- 默认模式（无 `--truncate`）会 **DROP 并重建** 目标表，每次迁移都是全量写入
- TRUNCATE 模式保留表结构，仅在列名变化时才重建
- 多数据源合并时按主键去重，后读覆盖先读
- 非法的日期/数值会被自动转为 NULL
- `Excel/` 目录和 `watch.log` 已加入 `.gitignore`，不纳入版本控制
- 文件同步使用原子写入（先写 `.tmp` 再 `os.replace`），防止复制中断导致文件损坏