feat: add sync checkpoint restore for last successful sync

Capture rolling online DB snapshots after push/drain/reconcile and expose SyncPage 数据恢复 plus checkpoint/restore APIs; mark Z12h and restore done in coop docs.

Co-authored-by: Cursor <cursoragent@cursor.com>

联调后修改意见-宇恒松离线.md

@@ -1,7 +1,7 @@
 # 联调后修改意见 · 宇恒松离线（形态 B）
 
-> 初稿：2026-08-01 · 修订至 **2026-08-06**（Z12h 已落实）  
-> 焦点：**§0.2**（按负责方：宇恒改宇恒、智建改智建）；配合见 **§0.3**  
+> 初稿：2026-08-01 · 修订至 **2026-08-06**（Z12h + 数据恢复已落实）  
+> 焦点：**§0.2**（按负责方）；**改代码前须先写入本意见**（见 §0.0）  
 > 来源：宇恒 `yuhengyihao_client` ↔ 智建（生产 `aisite.yuxindazhineng.com`）  
 > 依据：`松离线-dbsync方案-最终版.md`、`宇恒-松离线数据同步使用文档.md`
 
@@ -16,9 +16,17 @@
 | **Z1–Z9 / Z11–Z13** | **已落实** | 绑定/凭票/模块导入等；见 §5 |
 | **Z10 + Z10d** | **代码齐；生产 pull** | 空表 ensure；已存在表 **ADD COLUMN**（§5.7） |
 | **Z12 默认同步** | **已落实（含 Z12h）** | 启用即通道；误删 → Ensure+重挂（§5.9） |
+| **数据恢复** | **智建已落实** | SyncPage「数据恢复」：同步成功后打线上快照，可恢复上次/上一代（§5.13） |
 | **Z14 + Z14c** | **代码齐；生产 pull** | fingerprint；智能体挂载 `online_db_id`（§5.11） |
 | **Z14d 双向补齐** | **宇恒已接** | 误删任一侧 → 心跳/选同步按主键并集 pull↔push（§5.11） |
-| **仍关注** | 用法 | 通道断了靠智建自愈；表数据靠宇恒双向指纹；不是「再点启动」 |
+| **Z15 建站配置/绑定优先** | **宇恒已改完；智建无需** | 新机缺 `config.json` 自动生成；无权限先绑定再鉴权（§5.12） |
+| **仍关注** | 用法 | 通道断了靠智建自愈；表数据靠宇恒双向指纹 / 数据恢复；不是「再点启动」 |
+
+### 0.0 修改流程（冻结）
+
+1. **先写本意见**（§0.2 分 A/B″，§5 写清诉求/分工/验收）→ 双方对齐。  
+2. **再改代码**：宇恒只改 `yuhengyihao_client`；智建只改 `ai建站`；**互不代改**。  
+3. 接口/产品有变 → 回写 §1 契约与验收；禁止口头改完再补意见。
 
 ### 0.1 绑定产品冻结（Z13 · 试运行）
 
@@ -43,6 +51,7 @@
 | **Z13b–e** | 绑定码 / 同号确认 / policy / 凭票 / 选「同步」即 Binding+drain |
 | **Z14a** | 表级指纹慢心跳（原：不一致 → ensure + full-push） |
 | **Z14d** | **双向并集补齐（2026-08-06）**：不一致 → 先 `pull` 灌本机（不进 outbox）再 ensure+full-push；选「同步」同样先 pull 再 push；**默认不做 prune**（`YXD_SYNC_PRUNE_EXTRAS=1` 才清线上多余）。覆盖：线上误删 / 本地误删 / 缺表 |
+| **Z15** | **建站技能 config 自生成 + 无权限先绑定（2026-08-06 · 宇恒已改完）**：`ai-site-agent-api` 缺 `config.json` 自动写默认模板；绑定优先；门闸含「绑定账号或手机号」。改动：`config_loader.py` / `host_bootstrap.py` / `forms.py` / `forms_ui.py` / `forms_ui.json` / `reference.md`。**智建无需改** |
 
 #### A′. 宇恒 · 配合注意（非阻塞新开发）
 
@@ -63,6 +72,7 @@
 | **Z14c** ACL | 智能体 JWT 放行挂载 `online_db_id`（`agentOwnsOnlineDB`） |
 | Podman DNS / 脚本可执行位 | compose aliases；`restart.sh` 100755 |
 | **Z12h / Z12h-1 / Z12h-2** | `HealTenantSyncBind`：Ensure 默认通道 + 重挂 Agent/Binding；默认同步**可删**，删后立即 Ensure+heal；列表/换票/`agents/me`/ensure Binding 触发；见 §5.9 |
+| **数据恢复（§5.13）** | 成功同步后线上库快照（latest+previous）；SyncPage「数据恢复」；`GET …/checkpoint` + `POST …/restore` |
 
 > 产品一句：**账号已绑定 ⇒ 落点信息固定；通道没了平台自动补，终端无需手填 channel_id。**
 
@@ -70,13 +80,23 @@
 
 | 优先级 | 编号 | 项 | 说明 |
 |--------|------|----|------|
-| — | — | **无阻塞开发项** | Z12h 已合入；后续仅生产 pull 与运维配号 |
+| — | — | **无阻塞开发项** | Z12h、数据恢复已合入；后续仅生产 pull 与运维配号 |
+
+#### B‴. 智建 · 本次明确不改（Z15）
+
+| 项 | 说明 |
+|----|------|
+| 新机缺 `config.json` | **宇恒技能本地文件**问题；平台不负责生成终端 config |
+| 「模块操作 / 等待授权」表单 | 宇恒 `sendFrom` + `yxd_skill_ty_host`；智建已有 bind/register/token API，**契约够用** |
+| pending 待管理员启用 | 仍靠控制台赋「生成发布」；**不**为此新开接口 |
+
+> 结论：**Z15 智建无需开发**；仅当后续要把「绑定失败错误码 / pending 文案」标准化进 API 时再开智建项并先改本意见。
 
 #### B′. 智建 · 仍待办（仅运维）
 
 | 优先级 | 项 | 说明 |
 |--------|----|------|
-| **P0** | **生产 pull 本批** | Z10d + `schema/fingerprint` + Z14c + **Z12h**；`bash ./restart.sh --pull` |
+| **P0** | **生产 pull 本批** | Z10d + fingerprint + Z14c + **Z12h** + **数据恢复**；`bash ./restart.sh --pull` |
 | **P0** | 成员手机 | 「宇信达」绑 **`13531041944`**；勿超管号 |
 | **P0** | 通道表白名单 | **勿**「填入测试默认」；形态 B 可空 |
 | **P1** | 凭票 Secret | `YuhengTicket.Secret` ≡ `YXD_YUHENG_TICKET_SECRET` |
@@ -101,8 +121,9 @@
   3. 启用智能体 → 默认同步通道应「运行中」
   4.（可选）生成绑定码
 
-【智建 · Z12h 已落实】
-  误删默认同步 / Binding 挂死 → 打开 SyncPage / 换票 / agents/me 自动 Ensure+重挂
+【智建 · Z12h / 数据恢复 已落实】
+  误删默认同步 / Binding 挂死 → SyncPage / 换票 / agents/me 自动 Ensure+重挂
+  误删线上数据 → SyncPage「数据恢复」按上次同步快照恢复线上（本机靠下次 pull）
 
 【宇恒终端】
   5. 未绑定 → policy → lookup/confirm 或 redeem 或 ticket-exchange
@@ -113,8 +134,8 @@
 【智建验收】
   9. 「查看线上表」刷新 → 应有业务表（含曾 0 行空表）
   10. 仍空 = 终端尚未 push/ensure/pull，不是再点一次「启动」就能灌表
-  11. 故意删默认同步通道后：换票或打开 SyncPage / agents/me → 通道自动回来，Binding 不再红字
-```
+  11. 删默认同步后：换票或打开 SyncPage / agents/me → 通道自动回来
+  12. 同步成功后误删线上行 →「数据恢复」可选最近一次/上一代快照恢复
 
 | 角色 | 负责 | 不负责 |
 |------|------|--------|
@@ -551,14 +572,14 @@ POST .../schema
 | **Z12e** | **P1** | **唯一默认通道** | 每公司至多 1 条 `is_system_default`；复用已有默认 | **智建已落实** + 宇恒「仅 1 条则写入 env」 |
 | **Z12f** | **P1** | **开通 UX** | 启用智能体即可；DSN 用公司级默认 | **智建已落实** |
 | **Z12g** | **P1** | **默认同步通道默认启动** | 创建 `Enabled=true`；重启对 `IsSystemDefault` 自动 Start；控制台保存后自动启动 | **智建已落实**（`cb76824`） |
-| **Z12h** | **P0** | **通道误删自愈** | `HealTenantSyncBind`：Ensure 默认通道 + 重挂挂死 Agent/Binding（保留 `online_db_id`）；触发：`ensureAgentSyncBind` / `agents/me` / 换票 / 通道·Binding 列表 / 删非默认通道后 | **智建已落实** |
+| **Z12h** | **P0** | **通道误删自愈** | `HealTenantSyncBind`：Ensure 默认通道 + 重挂挂死 Agent/Binding；触发：列表/换票/`agents/me`/ensure Binding/删通道后 | **智建已落实** |
 | **Z12h-1** | **P1** | **禁删或删后重建默认同步** | `is_system_default` **可删**；删后立即 Ensure+heal 重建并重挂 | **智建已落实** |
 | **Z12h-2** | **P1** | **orphan Binding heal** | 列表 / Ensure Binding 时通道缺失 → 静默改挂默认通道 | **智建已落实** |
 
 **缺口说明（2026-08-06 · 已关闭）**
 
 - 原：SyncPage「通道已删除」、`ensureAgentSyncBind` 见非空 `channel_id` 即跳过。  
-- 现：列表/换票等路径先 heal；默认通道可删并立即重建。生产须 **pull** 后验收第 4 条。
+- 现：列表/换票等路径先 heal；默认同步可删并立即重建。生产须 **pull** 后验收。
 
 **宇恒已做（2026-08-05）**
 
@@ -571,7 +592,7 @@ POST .../schema
 1. 新公司：只「启用智能体」，**不**点新建通道，换票已带 `channel_id`，宇恒可 drain。  
 2. 账号 A 的本机库 push 不会出现在账号 B 的线上库；共享库仅在显式共享时可见。  
 3. 用户全程无需 F12、无需手填 `YXD_SYNC_CHANNEL_ID`。  
-4. **（Z12h）** 删除默认同步通道 → 立即重建并重挂；Binding/Agent 挂死 ID 时打开 SyncPage / 换票 / `agents/me` 亦会自愈，「通道已删除」红字消失；宇恒无需手填新 ID。
+4. **（Z12h）** 删除默认同步通道 → 立即重建并重挂；Binding 挂死 ID 时打开 SyncPage / 换票亦自愈。
 
 ### 5.10 【双方代码已接 Z13】绑定流程简化：绑定码 / 手机号（2026-08-05）
 
@@ -684,7 +705,7 @@ POST /api/v1/agent/sync/channels/{id}/pull
 | 方 | 做什么 |
 |----|--------|
 | 宇恒 | 本机指纹；404 回退 `row_count`；**Z14d** 双向 pull↔push；选同步默认不 prune |
-| 智建 | 生产 pull：fingerprint + Z10d + Z14c + **Z12h**；保持 pull/bootstrap 契约 |
+| 智建 | 生产 pull：fingerprint + Z10d + Z14c + **Z12h** + **数据恢复**；保持 pull/bootstrap 契约 |
 
 **联调踩坑（宇信达 · 已回写）**
 
@@ -702,14 +723,70 @@ POST /api/v1/agent/sync/channels/{id}/pull
 5. **（Z14d）** 线上删某表行 → 心跳后本机行仍在且线上恢复；本机删某表行（未 prune）→ 心跳后本机从线上拉回。  
 6. **（Z12h）** 见 §5.9 验收第 4 条。
 
+### 5.12 【Z15 · 2026-08-06】建站技能 config 自生成 + 无权限先绑定
+
+**状态**：**宇恒已改完（2026-08-06）**；**智建不改 / 无需开发**。  
+落地文件（宇恒仓 `.yxd/skills/user/ai-site-agent-api/`）：`scripts/config_loader.py`（`ensure_config`）、`scripts/host_bootstrap.py`（绑定优先）、`scripts/forms.py`、`scripts/forms_ui.py`、`forms_ui.json`、`reference.md`。
+
+**现象（另一台电脑）**
+
+- 克隆后无 `config.json`（gitignore 密钥文件）→ `默认登记失败: [Errno 2] No such file or directory: '.../config.json'`  
+- 随后卡在鉴权/换票，而不是先走绑定码/手机号
+
+**诉求**
+
+1. 缺 `config.json` → 自动写默认模板（可再填绑定码/手机号等），**禁止**裸抛 Errno 2  
+2. 启动顺序：**绑定优先** → 再鉴权/换票；未绑定或无权限时门闸选项含「绑定账号或手机号」  
+3. 聊天表单仍走宇恒 `sendFrom` / `yxd_skill_ty_host`（与税务 TY 插件无关，但是同一套交互壳）
+
+**分工**
+
+| 方 | 做什么 |
+|----|--------|
+| 宇恒 | `ai-site-agent-api`：`config_loader.ensure_config`、`host_bootstrap` 绑定优先、`forms`/`forms_ui` 门闸选项 |
+| 智建 | **不改**；bind / register / ticket 已够用（见 §0.2 B‴） |
+
+**宇恒落地（已改完）**
+
+1. `ensure_config()`：缺 `config.json` 写默认模板，不再 Errno 2  
+2. `host_bootstrap`：绑定码/手机号优先于鉴权换票  
+3. `pending_auth` 等门闸选项含「绑定账号或手机号」  
+
+**验收**
+
+1. 新机无 config → 首次跑技能生成模板文件，无 Errno 2  
+2. 未绑定 → 弹绑定相关表单，而非只提示换票失败  
+3. 已绑定有权限 → 原鉴权/模块操作路径不变  
+
+### 5.13 【智建已落实 · 2026-08-06】数据恢复（恢复上次同步）
+
+**状态**：**智建已落实**（须生产 `bash ./restart.sh --pull`）。
+
+**诉求**：10:00 同步成功 → 11:00 误删 → 可恢复到最后一次成功同步（含自动 push/drain）时的线上库状态。
+
+| 项 | 说明 |
+|----|------|
+| 快照 | 成功同步后对通道 **Remote 线上库** 打滚动快照（`latest` + `previous`，约 30s 防抖） |
+| 触发 | agent push/batch（有 applied）、通道 drain 有变更、控制台「同步修复」成功 |
+| UI | SyncPage 通道操作「**数据恢复**」；可选最近一次 / 上一代 |
+| API | `GET /api/v1/admin/sync/channels/{id}/checkpoint`；`POST …/restore`（`confirm=true`，`which=latest\|previous`） |
+| 恢复范围 | **仅线上库**；本机靠宇恒下次同步/指纹 pull 从线上补回 |
+| 注意 | 误删后若又自动同步成功，最新快照可能已含删除态 → 选「上一代」或尽快恢复 |
+
+**验收**
+
+1. 同步成功约 30s 后，checkpoint 有 `latest`。  
+2. 删线上若干行 →「数据恢复」选最近一次 → 「查看线上表」行数/内容回到快照。  
+3. 无快照时按钮提示「尚无成功同步快照」，不静默失败。  
+
 ---
 
 ## 6. 联系与附件
 
-- **待改清单（优先看）**：§0.2（**A′ 宇恒配合 · B′ 智建运维**；开发项已清空）；配合见 **§0.3**  
+- **待改清单（优先看）**：§0.2（**A′ 宇恒配合 · B′ 智建运维**；开发项已清空）；**改代码前先写本意见**（§0.0）；配合见 **§0.3**  
 - 方案：`松离线-dbsync方案-最终版.md`（含 2026-08-01 联调建议落地记录）  
 - 宇恒使用说明：`宇恒-松离线数据同步使用文档.md`（含 Z10 schema/ensure、Z13 绑定）  
-- 开通说明：`docs/数据同步-开通说明.md`  
+- 开通说明：`docs/数据同步-开通说明.md`（含 **数据恢复**）  
 - 绑定策略探测：`GET /api/v1/auth/bind/policy`（`trial_mode` / `require_for_bind`）  
-- 本意见如与冻结方案冲突，**以冻结方案为准**；§5.1–5.11 为产品增量与复测记录，不推翻 H1–H6 默认无感约束。  
+- 本意见如与冻结方案冲突，**以冻结方案为准**；§5.1–5.13 为产品增量与复测记录，不推翻 H1–H6 默认无感约束。  
 - **分工**：宇恒只改宇恒仓；智建只改智建仓；互不代改。