docs: 更新 API.md 和 mediabot-api-migration.md，补充快照接口和两阶段发布说明\n\n1. API.md 新增 2.6 站点快照接口（/snapshots/{siteId}、/check）\n2. API.md 补充 ?preview 参数说明\n3. API.md 新增 SiteSnapshot 数据结构\n4. API.md 更新 4.3 工作流程为两阶段发布\n5. mediabot-api-migration.md 补充 preview 参数说明\n6. mediabot-api-migration.md 新增第六章：预览模式与两阶段发布\n7. mediabot-api-migration.md 补充 checksum 字段到 Bundle JSON 结构"

docs/mediabot-api-migration.md

@@ -25,6 +25,12 @@
 
 **用途**: 获取站点完整配置快照（一站式获取脚本 + 页面配置 + 风险规则）
 
+**查询参数**:
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `preview` | boolean | `false` | `false`=仅正式版（published），`true`=预览版优先（draft → published fallback） |
+
 **请求头**:
 ```
 If-None-Match: {上次返回的 ETag checksum}
@@ -235,6 +241,7 @@ MediaBot 启动 / 定时任务:
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `siteId` | string | 站点标识 |
+| `checksum` | string | 完整内容 SHA-256（用于 ETag） |
 | `generatedAt` | string | 快照生成时间 (ISO 8601) |
 | `script` | string | Groovy 脚本完整源码 |
 | `scriptVersion` | string | 脚本版本号 |
@@ -247,13 +254,52 @@ MediaBot 启动 / 定时任务:
 
 ---
 
-## 六、鉴权说明
+## 六、预览模式与两阶段发布
+
+### 预览版 vs 正式版
+
+PAR 快照分为两个状态：
+
+| 状态 | 说明 | 谁可见 |
+|------|------|--------|
+| **预览版 (draft)** | 管理员保存后生效，未上传 CDN | MediaBot 带 `?preview=true` 可见 |
+| **正式版 (published)** | 管理员发布后生效，已上传 CDN | 所有请求默认可见 |
+
+### 两阶段发布工作流
+
+```
+开发者提交配置 → 管理员审核通过 → 自动生成预览版
+                                    ↓
+                    管理员保存预览版（savePreview）
+                                    ↓
+            MediaBot 通过 ?preview=true 验证预览版效果
+                                    ↓
+                    管理员发布正式版（publish）
+                                    ↓
+               快照写入 CDN，所有 MediaBot 自动获取最新版
+```
+
+### MediaBot 如何使用预览版
+
+```bash
+# 正常获取正式版（默认）
+curl http://par:9012/api/v1/snapshots/pthome
+
+# 获取预览版（用于开发/测试环境验证新配置）
+curl "http://par:9012/api/v1/snapshots/pthome?preview=true"
+```
+
+> 💡 建议 MediaBot 在开发/测试环境使用 `?preview=true`，生产环境使用默认（正式版）。
+
+---
+
+## 七、鉴权说明
 
 **无变化**。所有配置读取接口（snapshot、manifest、script、pages、risk-rules）均为**公开接口**，无需鉴权。提交类接口需 HMAC/PSK 或 JWT 认证。
 
 ---
 
-## 七、迁移时间线建议
+## 八、迁移时间线建议
 
 | 阶段 | 时间 | 操作 |
 |------|------|------|
@@ -263,7 +309,7 @@ MediaBot 启动 / 定时任务:
 
 ---
 
-## 八、FAQ
+## 九、FAQ
 
 **Q: 旧接口会下线吗？**  
 A: 短期内不会。但建议尽快迁移到 snapshot 接口以获得更好的性能和可用性。