xiaoshu-app/docs/migration/payroll-sync-rollout.md

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

本次代码只在三类旧系统数据（预约 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 月旧库对账数据均是正式验收的必要条件。