Excel-to-SQL_Server/README.md

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. 安装依赖：

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）

# 激活虚拟环境
.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 文件到本地，仅当文件发生变化时触发对应年份表的迁移。

# 启动守护进程（默认每 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），防止复制中断导致文件损坏