AllForCompany/BLD_sync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: remove Excel migration pipeline; keep Access-only sync

Browse Source 
Drop the Excel (.xlsm) production-execution-card pipeline now that the
project only synchronizes Access databases to SQL Server.

- Delete excel_sync_to_sql.py, migration.py, config/field_mappings.py
- Remove Excel-only config symbols (EXCEL_CONFIGS, MIGRATION_TASKS,
  EXECUTION_CARD_FIELDS, CONTRACT_DATA_*, CACHE_DIR, TEMP_DIR,
  EXCEL_SYNC_* settings) from the config package
- Drop now-unused deps from requirements.txt: pandas, sqlalchemy, openpyxl
- Update .env.example, CLAUDE.md, and the uptime_kuma_utils docstring
- Fix the tube-bending workshop Access table mapping in SYNC_MAPPING
  (source table renamed; old name no longer exists)

The three Excel-sourced tables in warehouseOutbound (executionCardData,
contractData, customerProductType) and their data are left untouched.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Misaka_Company
2026-06-17 13:09:36 +08:00
parent f9b2d3b4da
commit f6580b4994
11 changed files with 231 additions and 944 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
docs/superpowers/specs/2026-06-17-remove-excel-migration-design.md Normal file
View File

@@ -0,0 +1,168 @@
# 移除计划：移除 Excel 迁移相关内容
- **日期**: 2026-06-17
- **状态**: 待审核（通过后执行）
- **范围**: 仅代码仓库 `D:\python\BLD_sync`（不含 SQL Server 表数据）
---
## 1. 背景与目标
项目不再处理 Excel 文档（`.xlsm` 生产执行卡）的迁移工作。后续仅保留 **Access → SQL Server** 的同步链路（全量 `init_full_sync.py` + 增量 `run_incremental_sync.py`）。
目标：把所有"Excel 迁移"相关代码、配置、依赖与文档清理干净，使仓库成为一个干净、自洽的 **Access-only** 同步系统，不残留无用导入、死代码或过时说明。
### 已确认的范围决策
| 决策点 | 选择 |
|---|---|
| 清理彻底程度 | **彻底（Thorough）**：代码+配置+依赖+缓存目录+`CLAUDE.md`/文档修正 |
| Excel 写入的 3 张 SQL 表 | **保留不动**（`warehouseOutbound.executionCardData` / `contractData` / `customerProductType`，含现有数据） |
---
## 2. 方案对比（已选定 Thorough）
| 方案 | 内容 | 取舍 |
|---|---|---|
| A. 彻底清理 ✅ | 删脚本+配置+依赖+缓存，更新 CLAUDE.md/.env.example | 仓库自洽，无残留；改动面较大 |
| B. 仅核心代码+配置 | 删脚本+配置+依赖+.env.example，留 CLAUDE.md/缓存/文档 | 改动小；但 CLAUDE.md 过时、缓存占盘 |
| C. 仅代码，保留依赖 | 仅删脚本+配置符号，pandas/sqlalchemy/openpyxl 留作他用 | 最保守；依赖膨胀 |
**选定 A（彻底）**：与"项目不再处理 Excel"的意图一致，避免后续误导。
---
## 3. 受影响资产清单（已核实）
经全仓库（排除 `.venv`）grep 核实，以下符号/依赖**仅被 Excel 脚本使用**：
- `pandas`、`sqlalchemy`、`openpyxl` → 仅 `excel_sync_to_sql.py`、`migration.py` 使用
- `EXCEL_CONFIGS`、`MIGRATION_TASKS`、`TABLE_SCHEMA`、`CONTRACT_MAPPING`、`EXECUTION_CARD_FIELDS`、`CONTRACT_DATA_FIELDS`、`CONTRACT_DATA_MAPPING`、`CACHE_DIR`、`TEMP_DIR`、`EXCEL_SYNC_INTERVAL`、`EXCEL_SYNC_UPTIME_KUMA_CONFIG` → 仅被 Excel 脚本或其配置链使用
- 保留脚本（`init_full_sync.py` / `run_incremental_sync.py` / `db_utils.py` / `ntfy_utils.py` / `log_utils.py` / `uptime_kuma_utils.py` / `check_drivers.py` / `archive_existing_logs.py` / `vbareplace.py` / `vba.txt`）**不依赖**上述任何 Excel 符号 → 删除后无悬空引用。
---
## 4. 详细变更清单
### 4.1 整体删除（DELETE）
| 路径 | 说明 |
|---|---|
| `excel_sync_to_sql.py` | Excel→SQL 主同步器（`DataSynchronizer`），写 `executionCardData`、生成 `contractData` |
| `migration.py` | Excel→`warehouseOutbound.customerProductType` 迁移 |
| `config/field_mappings.py` | 仅含 `TABLE_SCHEMA`、`CONTRACT_MAPPING`（均 Excel 专用）→ 整文件删除 |
| `temp/`（未纳入 git，~180MB） | Excel 本地缓存（`.xlsm` + `sync_log.txt`）→ 删除目录 |
> `tmp/` 为空且未被代码引用，保留不动。
### 4.2 配置编辑（EDIT）
#### `config/__init__.py`
- 删除 `from .field_mappings import TABLE_SCHEMA, CONTRACT_MAPPING`（整行）
- `from .file_sources import ...` 改为仅 `SYNC_MAPPING`
- `from .app_settings import ...` 改为仅 `LOG_TABLE_CONFIG, NTFY_CONFIG, UPTIME_KUMA_CONFIG, POLL_INTERVAL, BATCH_SIZE`
- `__all__` 移除：`EXCEL_CONFIGS`、`MIGRATION_TASKS`、`TABLE_SCHEMA`、`CONTRACT_MAPPING`、`EXCEL_SYNC_UPTIME_KUMA_CONFIG`、`EXCEL_SYNC_INTERVAL`、`CACHE_DIR`、`TEMP_DIR`、`EXECUTION_CARD_FIELDS`、`CONTRACT_DATA_FIELDS`、`CONTRACT_DATA_MAPPING`
最终 `__init__.py` 导出：`SQL_SERVER_CONFIG, SQL_SERVER_CONN, DB_CONFIG, ACCESS_DRIVER, SYNC_MAPPING, LOG_TABLE_CONFIG, NTFY_CONFIG, UPTIME_KUMA_CONFIG, POLL_INTERVAL, BATCH_SIZE`
#### `config/file_sources.py`
- 删除 `EXCEL_CONFIGS`（含其上方注释 `# ================= Excel 文件配置 =================`）
- 删除 `MIGRATION_TASKS`（含其上方注释 `# ================= 迁移任务配置 =================`）
- 保留 `SYNC_MAPPING`（Access 映射，不动）
#### `config/app_settings.py`
- 删除 `EXCEL_SYNC_UPTIME_KUMA_CONFIG`
- 删除 `EXCEL_SYNC_INTERVAL`
- 删除 `CACHE_DIR`、`TEMP_DIR`（"运行参数"段仅留 `POLL_INTERVAL`、`BATCH_SIZE`）
- 删除 `EXECUTION_CARD_FIELDS`、`CONTRACT_DATA_FIELDS`、`CONTRACT_DATA_MAPPING`（"字段配置"整段）
- 保留 `LOG_TABLE_CONFIG`、`NTFY_CONFIG`、`UPTIME_KUMA_CONFIG`、`POLL_INTERVAL`、`BATCH_SIZE`
- `import os` 保留（`NTFY_CONFIG`/`UPTIME_KUMA_CONFIG` 仍用 `os.environ.get`）
### 4.3 依赖与环境（EDIT）
#### `requirements.txt`
移除：
```
pandas>=1.5.0
sqlalchemy>=2.0.0
openpyxl>=3.0.0
```
保留：`pyodbc`、`python-dotenv`、`requests`（仍被 ntfy/uptime/config 使用）
#### `.env.example`
移除行：`EXCEL_SYNC_UPTIME_KUMA_PUSH_URL=`
### 4.4 文档修正（EDIT）
#### `CLAUDE.md`
当前 CLAUDE.md 已过时（引用了不存在的 `etl_manager.py`、`sync_excel_to_sql.py`、`update_config.py`、`config.py`）。借此一并修正为真实结构（`config/` 包 + 仅 Access 脚本）：
- **Project Overview**：删除 "Excel files (.xlsm)..." 条目
- **Data Flow / 架构图**：删除 Excel 源、删除 `etl_manager.py`/`sync_excel_to_sql.py`/`migration.py` 脚本框
- **Key Components**：删除 `etl_manager.py`、`sync_excel_to_sql.py`；`config` 描述去掉 `EXCEL_CONFIGS`/`TABLE_SCHEMA`
- **Common Tasks**：删除 "Run Excel to SQL Sync" 与 `migration.py` 小节
- **Configuration Management**：删除 `update_config.py`/`EXCEL_CONFIGS`，改为描述 `config/` 包结构（`database.py`/`file_sources.py`/`app_settings.py`）
- **Database Schema**：`warehouseOutbound` 描述更新（其表为历史 Excel 写入，现不再更新）
- 删除所有 Excel 相关实现细节（MERGE 生成 contractData 等）
#### 轻量文档串修正（彻底清理）
- `uptime_kuma_utils.py` 顶部 docstring：删除"excel_sync_to_sql.py 等仍在使用"字样（向后兼容接口保留为通用工具方法，不删）
- `log_utils.py` / `archive_existing_logs.py` docstring 中 `excel_sync_...` 文件名示例：可选移除（文件名解析是通用正则，功能不受影响）
### 4.5 不在仓库内、需手动处理（仅提示，本计划不自动执行）
| 项目 | 动作 |
|---|---|
| Windows 任务计划程序 | 若存在 `AutoRun-excel_sync` 之类计划任务，手动禁用/删除（保留 `AutoRun-init_full_sync`、`AutoRun-run_incremental_sync`） |
| Uptime Kuma | 禁用/删除 Excel 同步心跳监控项（对应 `EXCEL_SYNC_UPTIME_KUMA_PUSH_URL`） |
| `.env`（已 gitignore） | 手动删除其中的 `EXCEL_SYNC_UPTIME_KUMA_PUSH_URL=...` 行 |
| SQL Server 表 | **按决策保留不动**，无需任何操作 |
---
## 5. 执行顺序
1. **删除文件**：`excel_sync_to_sql.py`、`migration.py`、`config/field_mappings.py`、`temp/`
2. **编辑配置**：`config/__init__.py` → `config/file_sources.py` → `config/app_settings.py`
3. **编辑依赖/环境**：`requirements.txt`、`.env.example`
4. **编辑文档**：`CLAUDE.md` + 上述轻量 docstring
5. **验证**（见第 6 节）
6. **提交**：单条 commit，英文信息（如 `refactor: remove Excel migration pipeline`），含删除/修改；提交后按全局规则推送到远端
> 全程在 `.venv` 内执行（遵循全局 CLAUDE.md 协议）。
---
## 6. 验证计划
执行后用仓库 `.venv` 的 Python 逐项核验：
1. **配置包导入自洽**：
```bash
.venv/Scripts/python -c "import config; print(config.SYNC_MAPPING is not None)"
```
2. **所有保留脚本语法编译通过**：
```bash
.venv/Scripts/python -m py_compile init_full_sync.py run_incremental_sync.py db_utils.py ntfy_utils.py log_utils.py uptime_kuma_utils.py check_drivers.py archive_existing_logs.py vbareplace.py config/*.py
```
3. **无悬空引用**：grep 确认仓库（排除 `.venv`）不再出现已删符号：
`EXCEL_CONFIGS|MIGRATION_TASKS|TABLE_SCHEMA|CONTRACT_MAPPING|EXECUTION_CARD_FIELDS|CONTRACT_DATA_FIELDS|CONTRACT_DATA_MAPPING|CACHE_DIR|TEMP_DIR|EXCEL_SYNC_INTERVAL|EXCEL_SYNC_UPTIME_KUMA_CONFIG|read_excel|openpyxl`
4. **增量/全量脚本可正常进入主流程**（可选冒烟）：分别运行 `run_incremental_sync.py`、`init_full_sync.py` 数秒后中断，确认无 ImportError、能连接 SQL Server。
---
## 7. 回滚
全部变更均在 git 跟踪范围内（`temp/` 除外，但其为可再生缓存）。如需回滚：
```bash
git revert <commit-sha>
```
`temp/` 缓存可由历史 Excel 脚本重新生成（已无意义）。
---
## 8. 风险与说明
- **无数据风险**：不动 SQL Server 任何表与数据。
- **无运行中服务风险**：`run_incremental_sync.py`（Access 增量）代码路径不变，导入符号均保留。
- **CLAUDE.md 改动较大**：因原文已与实际代码脱节，顺带修正为真实结构；如只希望"最小改动"可告知，仅删 Excel 段落、不补真实结构。