📝 docs: expand README with architecture, full-sync guide, and FAQ

- 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

README.md

@@ -1,11 +1,50 @@
 # ProductionDataBaseSync_DataMacro
 
-Access → SQL Server 增量同步（数据宏驱动）。详见 `docs/superpowers/specs/2026-07-14-access-datamacro-sync-design.md`。
+Access → SQL Server 增量同步（数据宏驱动）。设计详见 `docs/superpowers/specs/2026-07-14-access-datamacro-sync-design.md`。
 
-## 运行
-```bash
-.venv/Scripts/python.exe -m sync.service
-```
+## 架构
+
+每个 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` 复制并填入真实凭据）。
+
+编辑 `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`。