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. **配置包导入自洽**：
   ```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 段落、不补真实结构。