706b9c33db
- Add architecture section describing Capture/Apply/Cleanup pipeline - Document service vs one-shot full-sync commands - Add full-sync usage examples (--db/--table/--clear-change-log) - Add FAQ for -1102 lock contention and pyodbc/pydantic ABI mismatch
51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
# 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 之间的漂移。会**清空目标表再全量写入**，绕开增量队列：
|
||
|
||
```bash
|
||
.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`。
|