BLD_sync/docs/superpowers/specs/2026-06-17-remove-excel-migration-design.md

移除计划：移除 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. 配置包导入自洽：

   .venv/Scripts/python -c "import config; print(config.SYNC_MAPPING is not None)"
   

2. 所有保留脚本语法编译通过：

   .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/ 除外，但其为可再生缓存）。如需回滚：

git revert <commit-sha>

temp/ 缓存可由历史 Excel 脚本重新生成（已无意义）。

---

8. 风险与说明

• 无数据风险：不动 SQL Server 任何表与数据。
• 无运行中服务风险：run_incremental_sync.py（Access 增量）代码路径不变，导入符号均保留。
• CLAUDE.md 改动较大：因原文已与实际代码脱节，顺带修正为真实结构；如只希望"最小改动"可告知，仅删 Excel 段落、不补真实结构。