ProcurementVisibilityHub_DataSync

采购执行情况即时数据同步服务。将 169 共享盘上的 Excel（采购执行情况即时数据.xlsx）同步写入两个目标库：

• SQL Server（114 / CompanyDB，schema procurementVisibilityHub，表 请购执行）
• Access 生产库（ProcurementVisibilityHub.accdb，表 procurementVisibilityHub_请购执行）

采用全量覆盖策略：SQL Server 端 TRUNCATE + INSERT，Access 端 DELETE + INSERT，并写入统一的「导入时间」。

---

目录结构

路径	说明
config/config.yaml	运行配置（含 DB 凭据，已被 .gitignore 忽略）
src/config_loader.py	读取 YAML 配置、构造 ODBC 连接串
src/source_watcher.py	源文件变化检测（mtime/size）+ 下载到 data/
src/excel_parser.py	解析 xlsx → 行字典，含字段映射与类型转换
src/sync_writer.py	全量写入 SQL Server + Access
src/runner.py	主入口：服务循环 / 单次 / 本地联调 / dry-run
data/	源文件历史副本（运行时生成，已忽略）
logs/sync.log	运行日志（运行时生成，已忽略）

---

环境要求

• Python 3.10+
• 目标主机需安装 ODBC 驱动：
  • ODBC Driver 17 for SQL Server（连 114 SQL Server）
  • Microsoft Access Driver (*.mdb, *.accdb)（连 Access 生产库）
• 依赖见 requirements.txt：PyYAML、openpyxl、pyodbc

---

安装

# 1. 创建并激活虚拟环境（项目内）
python -m venv .venv
.\.venv\Scripts\activate        # Windows
# source .venv/bin/activate     # Linux/macOS

# 2. 安装依赖
pip install -r requirements.txt

# 3. 准备配置（从模板复制后填入真实凭据）
cp config/config.yaml.example config/config.yaml   # 若无模板，直接新建 config/config.yaml

⚠️ config/config.yaml 含数据库账号密码，不纳入版本管理。如需团队共享，请提交一份 config/config.yaml.example（占位凭据），真实配置留本地。

---

配置说明（config/config.yaml 关键字段）

字段	说明
source.unc_path	源 Excel 的 UNC 路径（169 共享盘）
source.local_cache_dir	本地历史副本目录（默认 data）
scan.interval_seconds	服务循环扫描间隔（秒）
sql_server.*	SQL Server 连接信息（server/port/database/user/password…）
access.*	Access 库路径与表名（DBQ/table）
field_map	Excel 列名 → 数据库字段名（仅列名不同者）
auto_fields	数据库自动生成字段：id_field（自增不写）、import_time_field（=同步时刻）
sync.strategy	同步策略，当前固定 full
sync.batch_size	批量插入大小（默认 1000）
logging	日志级别与目录

---

使用方式

# 服务循环模式（默认，配合 NSSM 部署为 Windows 服务）
python -m src.runner

# 单次运行后退出
python -m src.runner --once

# 用本地文件作源（跳过 169 下载，便于联调）
python -m src.runner --local X.xlsx

# 仅解析并打印，不写库
python -m src.runner --local X.xlsx --dry-run

# 指定配置文件
python -m src.runner --config config/config.yaml

运行逻辑：检测源 Excel 是否变化（mtime/size），无变化则跳过；有变化则下载副本 → 解析 → 全量写入两个目标库。

---

运行流程

169 共享 Excel
      │  source_watcher 检测变化 + 下载到 data/
      ▼
excel_parser 解析（字段映射 + 类型转换：float/datetime/int/text）
      ▼
sync_writer 全量写入
   ├─ SQL Server：TRUNCATE + 分批 INSERT（fast_executemany，事务提交）
   └─ Access：     DELETE  + 分批 INSERT（autocommit）
      ▼
logs/sync.log 记录全过程

---

部署（NSSM 服务）

以 Windows 服务常驻运行（主机 114），由 NSSM 拉起 python -m src.runner 进入循环模式。日志统一写入 logs/sync.log。

---

常见问题

• 连不上 SQL Server：确认 ODBC Driver 17 已装、114:1433 可达、账号密码正确（Encrypt/TrustServerCertificate 与服务器端匹配）。
• Access 写入失败：确认目标主机装了 Microsoft Access Driver，且 access.dbq 路径存在、有写权限。
• 源无变化不执行：属正常行为（基于 mtime/size 的增量跳过）；想强制全量可用 --local 指定当前文件或删除 data/.source_meta.json 基准。