feat(pages): pull latest by project and keep a single edge release

Agents now treat pages_project_id as the stable anchor and fetch the
control-plane active package via project latest APIs, so activating a
deployment updates edges without republishing main config. Local roots use
projects/{id}/current, only the newest release is retained after a successful
switch, hash/package races retry, and per-project failures no longer block
siblings.

docs/design/pages-design.md

@@ -89,11 +89,16 @@ graph TD
 }
 ```
 
-### 3. 与主配置版本的双轨关系
-* **主配置版本**（`config_versions`）与 **Pages 部署** 是两套独立的版本体系。
-* 快照里记录的 `pages_deployment` 仅反映**发布当时**的激活部署，用于审计与当时渲染结果存档。
-* **运行时**：下发给 Agent 的配置会把各 Pages 路由**重绑定到该项目当前激活部署**（最新包）。主配置回滚/重新激活旧版本时，**不要求**仍能拉到旧 Pages 包，只保证指向当前最新激活部署。
-* 因此 Pages 历史裁剪可以安全删除非激活部署，无需为「主配置回滚到旧 Pages 包」预留存储。
+### 3. 与主配置版本的双轨关系（项目锚点 + latest 拉取）
+* **主配置版本**与 **Pages 部署** 是两套独立的版本体系。
+* 主配置中 Pages 路由的稳定锚点是 **`pages_project_id`（项目 ID）**，不是某次部署 ID。
+* OpenResty `root` 使用项目级路径：`__OPENFLARE_PAGES_DIR__/projects/{project_id}/current`，激活切换时路径不变，无需为换包而重发主配置。
+* Agent 按项目请求「最新激活包」（类似 `github/release/latest`）：
+  * `GET /api/v1/agent/pages/projects/:project_id/latest/hash`
+  * `GET /api/v1/agent/pages/projects/:project_id/latest/package`
+  * 控制面根据该项目**当前激活部署**返回哈希与压缩包；Agent 不关心具体 deployment_id。
+* 因此：在项目内切换激活部署后，**不必发布主配置**；Agent 在周期性对账时轮询 latest hash，发现变化即下载并切换 `current`。
+* 快照中的 `pages_deployment` 字段仍可记录发布时元数据（入口文件、SPA/API 代理等），但不作为 Agent 拉包的版本锁定。
 
 ---
 
@@ -119,19 +124,19 @@ graph TD
 
 Agent 运行在各边缘代理节点上，在应用配置版本前，必须先将 Pages 静态资源“原子”地拉取到节点本地。
 
-### 1. 校验式增量拉取
-1. Agent 解析激活配置中的 `SourceConfigJSON`，检索出所有 `UpstreamType == "pages"` 的路由引用的部署 `DeploymentID` 和 `Checksum`。
-2. 检查本地部署目录是否存在正确的版本标记文件 `.openflare-pages.json`，且 `Checksum` 匹配。
-3. 若不匹配，通过专属接口 `GET /api/agent/pages/deployments/:id/package` 下载对应的部署包。下载请求头必须携带节点独有的 `X-Agent-Token` 用于 Server 鉴权。
+### 1. 按项目拉取 latest
+1. Agent 从激活主配置中解析 `UpstreamType == "pages"` 的路由，收集稳定锚点 **`pages_project_id`**。
+2. 对每个项目调用 `GET /api/v1/agent/pages/projects/:project_id/latest/hash` 获取控制面当前激活包哈希（类似 latest 指针）。
+3. 若本地 `projects/{project_id}/releases/{hash}` 尚未就绪，再下载 `.../latest/package`。下载后 **再次请求 hash** 与包内容 SHA-256 对齐，避免激活切换造成的竞态；不一致则有限次重试。
+4. 请求头携带节点 `X-Agent-Token`。
 
-### 2. 安全解压缩与原子切换
-为了保证配置应用过程的“无缝”且能在出错时立即回滚：
-1. Agent 将下载的部署包数据写入临时目录，并重新计算 SHA-256 Checksum。如果与配置指明的 checksum 不符，立即报错并阻断发布流程。
-2. 解压部署包至临时目录 `releases/{checksum}.tmp`。解压支持 zip / tar.* / 7z。**Agent 默认信任控制面**：不再重复校验文件数/体积等业务限额（控制面上传时已完成）；仅做本机落盘安全处理（路径逃逸、软链接拒绝）与下载 checksum 完整性校验。
-3. 解压成功后，写入标记文件 `.openflare-pages.json`。
-4. 清理 `releases/{checksum}` 目录，将整个临时目录重命名为 `releases/{checksum}`。
-5. **原子切换**：建立拷贝当前部署的物理副本到目标位置 `deployments/{deployment_id}/current`。切换前先备份上一版本的 `current`，一旦重载配置失败，Agent 能够快速恢复 `current` 目录并回滚 OpenResty。
-6. **定时清理**：每次配置成功应用后，Agent 自动比对本地部署目录，将所有不活跃的（即未被当前激活版本引用的）历史部署包和文件夹进行物理删除，释放磁盘空间。
+### 2. 安全解压缩、原子切换与只保留最新
+1. 下载字节计算 SHA-256，须与「下载后再次查询」的 latest hash 一致。
+2. 解压至 `projects/{project_id}/releases/{hash}.tmp`（支持 zip / tar.* / 7z）。Agent 信任控制面业务校验，仅做路径逃逸/软链防护。
+3. 写入 `.openflare-pages.json` 后 rename 为 `releases/{hash}`。
+4. **原子切换** `projects/{project_id}/current` 指向新 release（优先 symlink，失败则拷贝）。
+5. **仅当新包已就绪且 current 切换成功后**，删除该项目下其它 `releases/*`（含 `.tmp`），**不保留历史部署包**。边缘节点每个项目永远只保留一份最新内容。
+6. 多项目对账时 **隔离失败**：单个项目失败记日志并继续其它项目，最后汇总返回错误。
 
 ---
 
@@ -141,13 +146,13 @@ Agent 运行在各边缘代理节点上，在应用配置版本前，必须先
 
 ### 1. 静态服务指令渲染
 * **`root` 与 `index`**：
-  Server 根据配置将 `root` 指向 Agent 的 Pages 动态目录占位符 `__OPENFLARE_PAGES_DIR__/deployments/{deployment_id}/current`，并在此基础上追加项目的 `RootDir`。`index` 指向设置的入口文件。
+  Server 将 `root` 指向项目级占位路径 `__OPENFLARE_PAGES_DIR__/projects/{project_id}/current`（可再追加 `RootDir`）。激活切换只换目录内容，路径不变，无需为换包重发主配置。
   ```nginx
   server {
       listen 80;
       server_name myapp.example.com;
       
-      root "/var/lib/openflare/pages/deployments/12/current";
+      root "/var/lib/openflare/pages/projects/3/current";
       index "index.html";
       ...
   }