# 旧系统同步与工资结算上线清单

本次代码只在三类旧系统数据（预约 `54`、上课 `59`、抗遗忘 `60`）均已完成全量、增量水位追平、旧库与新库有效业务 ID 集合的 SHA-256 一致、最近成功同步不超过 120 秒且无待处理失败或冲突时，允许生成、刷新或审核工资草稿。页面上的「查询于」不是旧库同步时间。

## 上线顺序

1. 旧 SQL Server 执行 `legacy-sync-bridge/database/install.sql` 和 `verify-readonly.sql`，确认 12 个变更触发器、增量日志和 `WritesFailClosed=1`。部署只读 IIS 桥；按 `legacy-sync-bridge/README.md` 的预检、安装和签名测试完成 `/xiaoshu-sync/v1/health`、`manifest`、`changes` 验证。当前线上健康地址返回 404，在解决前不得放开结算。
2. 配置云函数环境的 `XIAOSHU_LEGACY_SYNC_BASE_URL`（IIS 应用根路径，不含 `/v1`）、`XIAOSHU_LEGACY_SYNC_KEY_ID`、`XIAOSHU_LEGACY_SYNC_SECRET`；不启用旧系统写入开关。先执行复习奖励迁移，再执行工资完整性迁移，最后发布网关与管理后台。所有密钥仅放服务端安全配置。
3. 用同步中心对 `appointments`、`lessons`、`memory-records` 分别执行全量补同步（`full=true`），直到每个数据集 `hasMore=false`；依次处理失败队列和冲突。核对三组业务 `GeneralID` 数量、SHA-256、增量水位，并抽查 9 月跨月、作废、重复课次和旧复习完成记录。
4. 以超级管理员会话启动 `scripts/run-legacy-sync-worker.mjs`（默认 5 秒）。运行器会先追平学习记录再处理抗遗忘、先追平预约再处理上课，避免缺少来源时生成不可计薪的异常凭据。仅当三组 checkpoint 均为 `healthy`、worker 健康检查为 200 且工资接口 `sourceStatus.sync.settlementReady=true` 时，按老师逐条对照旧系统 9 月完课与工资明细。若数据继续变化，重复对账。
5. 管理员在「抗遗忘工资 → 历史待核对」中逐条确认 2026-09-01 起旧系统完成、且确认没有历史发放的凭据；操作会复核任务、时间、老师、学生、来源学习记录及重复项，并写审计日志。9 月前记录保持零元。刷新工资草稿后再审核；已审核或已发放批次不得重开，差异走下期调整。

## 故障处理

- IIS 桥、同步进程或云函数配置故障时，可查看新库已有统计，但必须标明来源延迟，服务端会拒绝生成、刷新和审核。不要将「查询时间」或 `catching_up` 视作追平。
- 失败队列、冲突或主键校验和不一致时，先定位旧业务 ID 和附表写入失败，再重试同步；不得为了结算手动改 checkpoint、水位或工资凭据。
- 生产发布前复跑 `npm run test:payroll-integrity`、`npm run test:review-rewards`、`npm run cloud:validate` 和 `npm run build:admin`。旧 IIS/SQL Server 部署权限、云函数配置权限与 9 月旧库对账数据均是正式验收的必要条件。