ProductionDataBaseSync_DataMacro/README.md

ProductionDataBaseSync_DataMacro

Access → SQL Server 增量同步（数据宏驱动）。设计详见 docs/superpowers/specs/2026-07-14-access-datamacro-sync-design.md。

架构

每个 Access 库通过数据宏把变更写入本地 TableChangeLog；同步服务周期性地把这些变更搬运到 SQL Server 镜像表。单库一轮分三段：

阶段	动作	说明
Capture	SELECT 读取 TableChangeLog 中最旧的 N 条	只读 Access
Apply	调用 dbo.usp_SyncApply 写入 SQL 镜像表	按 ID 精确落库
Cleanup	DELETE 已应用的 TableChangeLog 行	按 ID 列表精确删除，遇锁自动退避重试

命令

用途	命令
增量同步服务（常驻，由 nssm 托管 DataMacroSync）	.venv/Scripts/python.exe -m sync.service
一次性全量同步（TRUNCATE + 全量 INSERT，所有库所有表）	.venv/Scripts/python.exe -m sync.fullsync config.yaml

上述命令均使用项目自带的 .venv。同步类命令由 nssm 以服务方式运行，无需手动设置环境变量。

配置

编辑 config.yaml（从 config.example.yaml 复制并填入真实凭据）。关键段：

• sql_server：SQL Server 连接串与 SyncQueue 表名。
• access：ACE ODBC 驱动名与各根目录（roots）映射。
• runtime：轮询间隔、批大小、重试与保留策略。
• files：每个 Access 文件一条映射（file / root / schema / year_suffix / exclude_tables / include_tables）。

全量同步

用于从零重建镜像表或修复 Access 与 SQL 之间的漂移。会清空目标表再全量写入，绕开增量队列：

.venv/Scripts/python.exe -m sync.fullsync config.yaml          # 全部库、全部表
.venv/Scripts/python.exe -m sync.fullsync config.yaml --db OEM.accdb   # 仅单个库
.venv/Scripts/python.exe -m sync.fullsync config.yaml --table 表壳焊接记录  # 仅单表（作用于所有库）
.venv/Scripts/python.exe -m sync.fullsync config.yaml --clear-change-log  # 同步后同时清空 TableChangeLog（谨慎）

• year_suffix 通过 FileMapping 拼到表名后（如 表壳焊接记录 → 表壳焊接记录_YEAR2026）。
• 无镜像表的目标表按设计跳过（target table missing），不报错。

常见问题

• cleanup 报 -1102 无法更新；当前被锁定：Access 是文件型数据库，cleanup 反写 DELETE 与生产客户端数据宏写日志争用页级锁。服务已对锁冲突自动退避重试（access_reader.delete_log_ids 捕获 pyodbc.Error 并判断 -1102/“被锁定”）。偶发属正常，持续刷错再排查。
• No module named 'pydantic_core' / pyodbc：venv 解释器与轮子 ABI 不匹配（常见于 Python 3.13 装到 cp310 轮子）。修复： .venv/Scripts/python.exe -m pip install --force-reinstall --no-cache-dir pyodbc pydantic。