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/API.md

@@ -256,7 +256,77 @@ curl -H "If-None-Match: a1b2c3d4..." http://par:9012/api/v1/manifest
 }
 ```
 
-### 2.6 Groovy 适配脚本
+### 2.6 站点快照（统一配置 Bundle）⭐ 推荐
+
+| 方法 | 路径 | 认证 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/snapshots/{siteId}` | 无 | 获取站点完整配置快照（脚本+页面+规则） |
+| GET | `/api/v1/snapshots/{siteId}/check` | 无 | 轻量级检查是否有配置更新 |
+
+#### GET /api/v1/snapshots/{siteId}
+
+**推荐使用**。一次请求获取站点的脚本 + 页面配置 + 风险规则合并快照。
+
+支持 `If-None-Match` 条件请求（ETag = checksum），无变化返回 `304 Not Modified`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `preview` | boolean | `false` | `true`=预览版优先（draft→published fallback），`false`=仅正式版 |
+
+```bash
+# 获取正式版快照
+curl http://par:9012/api/v1/snapshots/pthome
+
+# 获取预览版（供开发/测试验证）
+curl "http://par:9012/api/v1/snapshots/pthome?preview=true"
+
+# ETag 增量更新
+curl -H "If-None-Match: abc123..." http://par:9012/api/v1/snapshots/pthome
+# → 304 Not Modified  (内容未变，零流量)
+```
+
+```json
+// Response 200 (Content-Type: application/json)
+{
+    "siteId": "pthome",
+    "checksum": "abc123def456...",
+    "generatedAt": "2026-07-07T10:30:00",
+    "script": "// Groovy 脚本完整源码...",
+    "scriptVersion": "3",
+    "scriptSource": "custom",
+    "pages": [{"pageKey": "INDEX", "url": "https://...", ...}],
+    "pagesVersion": "2",
+    "pagesSource": "custom",
+    "riskRules": [{"field": "title", "operator": "contains", ...}],
+    "riskRulesVersion": 1
+}
+```
+
+> 💡 **可用性保障**：数据库优先 → CDN 灾备 → 实时构建兜底。MediaBot 也可直接缓存 CDN URL 作为终极 fallback。
+
+#### GET /api/v1/snapshots/{siteId}/check
+
+轻量级检查是否有更新，不传输配置内容。
+
+```json
+// Response 200
+{
+    "code": 200,
+    "data": {
+        "checksum": "abc123def456...",
+        "version": 5,
+        "publishedAt": "2026-07-07T10:30:00"
+    }
+}
+```
+
+#### 兼容旧接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/configs/{siteId}/bundle` | 兼容旧路径，底层已委托给快照服务 |
+
+### 2.7 Groovy 适配脚本
 
 | 方法 | 路径 | 认证 | 说明 |
 |------|------|------|------|
@@ -381,6 +451,22 @@ Groovy 脚本定义以下方法，mediabot 按需调用：
 | status | String | `pending` / `approved` / `rejected` |
 | isLatest | Boolean | 是否最新版本 |
 
+### 站点快照 (SiteSnapshot / Bundle)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| siteId | String | 站点唯一标识 |
+| checksum | String | 完整内容 SHA-256（用于 ETag） |
+| generatedAt | DateTime | 快照生成/发布时间 |
+| script | String | Groovy 脚本完整源码 |
+| scriptVersion | String | 脚本版本号 |
+| scriptSource | String | `custom` 或 `default` |
+| pages | Array | 页面入口配置条目列表 |
+| pagesVersion | String | 页面配置版本号 |
+| pagesSource | String | `custom` 或 `default` |
+| riskRules | Array | 风险规则列表 |
+| riskRulesVersion | Integer | 风险规则版本号 |
+
 ---
 
 ## 4. 工作流程
@@ -413,12 +499,15 @@ Groovy 脚本定义以下方法，mediabot 按需调用：
 ② 所有旧凭据无需修改，签名方式不变
 ```
 
-### 4.3 配置更新
+### 4.3 配置更新（两阶段发布）
 
 ```
-① GET /api/v1/configs/{siteId} 查看当前版本
+① 开发者提交配置 → POST /api/v1/configs/{siteId}/submit
-② 准备新配置 JSON → POST /api/v1/configs/{siteId}/submit
+② 管理员审核通过 → 自动生成预览版快照（draft 状态）
-③ 等待管理员审核通过
+③ 管理员在后台编辑站点 → 点击"保存预览版"（可选，手动触发生成预览版）
+④ MediaBot 通过 ?preview=true 验证预览版效果
+⑤ 管理员确认无误 → 点击"发布正式版"（draft → published，同步上传 CDN）
+⑥ MediaBot 下次拉取正式版时自动获取最新配置
 ```
 
 ---

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 接口以获得更好的性能和可用性。