feat: 前台动态路由与积木页面、网页路径/发布/模式、PAGE_BUILDER 文档

Made-with: Cursor

docs/PAGE_BUILDER.md

@@ -0,0 +1,52 @@
+# 前台积木页面（动态路由）
+
+## 概念
+
+- 在 **网页管理** 中创建页面，设置 **前台路径**（`route_path` 或默认 `/{slug}`）、**发布**、**内容模式**。
+- **HTML**：`content` 为 HTML 字符串，前台用 `v-html` 渲染（仅信任后台内容）。
+- **积木（builder）**：`content` 为 JSON，结构如下，前台按模块渲染并支持入场动画。
+
+## 动态路由
+
+- 前台启动时请求 `GET /api/web/routes`，按已发布页面注册 Vue Router。
+- `slug` 为 `index` 的页面不参与动态路由（仍由首页 `Home.vue` + 首页数据驱动）。
+- 单页数据：`GET /api/web/page?path=/your-path`（`site_id` 可选，默认官网站点）。
+
+## 积木 JSON 结构
+
+```json
+{
+  "version": 1,
+  "blocks": [
+    {
+      "id": "唯一可选",
+      "type": "heading",
+      "props": { "text": "标题", "level": 2 },
+      "animation": { "enter": "fadeIn", "delay_ms": 0, "duration_ms": 600 }
+    }
+  ]
+}
+```
+
+### 模块类型 `type`
+
+| type | props 说明 |
+|------|------------|
+| `heading` | `text`, `level` (1–6) |
+| `text` | `text` 纯文本；或 `html: true` 时用 `html` / `text` 作为 HTML |
+| `link_list` | `items: [{ label, url, target? }]` |
+| `button` | `text`, `url`, `variant`: `primary` \| `ghost`, `target?` |
+| `html` | `html` 原始 HTML 片段 |
+| `spacer` | `height` 像素 |
+| `divider` | 无 |
+| `section` | `padding`, `maxWidth`, `background`；`children` 为子 `blocks` 数组 |
+
+### 动画 `animation.enter`
+
+- `none` | `fadeIn` | `slideUp` | `slideLeft` | `zoomIn`
+- `delay_ms`、`duration_ms` 控制延迟与时长（毫秒）
+
+## 扩展新模块
+
+1. 在 `web/src/components/blocks/BlockRenderer.vue` 增加 `type` 分支与样式。
+2. 后台仍通过 JSON 配置 `props`，无需改库表结构。