7edbd987f0
- Add sync.py for LAN file sync with atomic writes and mtime-based change detection - Add watch.py daemon that periodically syncs files and migrates only changed tables - Add TRUNCATE mode to migrate.py (--truncate flag) to preserve table structure - Update config.yaml schema with check_interval_minutes and lan_sources - Update README with new features documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
121 lines
3.8 KiB
Markdown
121 lines
3.8 KiB
Markdown
# 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`），防止复制中断导致文件损坏
|