# 小树陪练旧系统同步桥

该服务部署在能访问旧 SQL Server 的受控网络内，只提供三类窄接口：

- `GET /xiaoshu-sync/v1/manifest`：返回同一时间点的数据集数量。
- `GET /xiaoshu-sync/v1/changes?dataset=...&cursor=...`：按旧业务主键断点续传，返回经白名单转换的 Parse 投影。
- `POST /xiaoshu-sync/v1/commands/{operation}`：携带幂等键、操作人和原因调用旧系统正式业务逻辑。

请求必须包含 `X-Xiaoshu-Key-Id`、`X-Xiaoshu-Timestamp`、`X-Xiaoshu-Nonce` 和 `X-Xiaoshu-Signature`。签名原文为：

```text
METHOD\nPATH_AND_QUERY\nTIMESTAMP\nNONCE\nSHA256_HEX(BODY)
```

返回字段严格白名单化，不查询、不返回 `UserPwd`、`PayPassWord`、`Question`、`Answer`、Cookie 或 Session。

## 部署

1. 在 SQL Server 执行 `database/install.sql`，再把允许的写操作对接到旧站实际 BLL。对接前写入会安全拒绝，不会退化为无补偿双写。
2. 通过环境变量或 IIS 配置提供 `ConnectionStrings__LegacySqlServer`、`XiaoshuSync__KeyId`、`XiaoshuSync__Secret` 和 `XiaoshuSync__AllowedIps__0`。
3. 执行 `dotnet publish -c Release`，将发布目录部署为独立 IIS 应用。密钥不得写入仓库。
4. 在新云函数设置 `XIAOSHU_LEGACY_SYNC_BASE_URL`、`XIAOSHU_LEGACY_SYNC_KEY_ID`、`XIAOSHU_LEGACY_SYNC_SECRET`。

首次全量投影使用数字主键游标。生产环境还需启用 SQL Server Change Tracking，并配合每日主键集合/字段哈希对账来捕捉硬删除和原地更新。