mirror of
https://github.com/RaisFast/raisfast.git
synced 2026-09-24 00:02:28 +00:00
487 lines
17 KiB
Markdown
487 lines
17 KiB
Markdown
# 模板系统设计
|
||
|
||
> 借鉴 WordPress 的模板层级 + Gutenberg 块编辑器，适配无头 CMS 架构。
|
||
> 后端存储模板配置和 Block 结构化数据，前端负责渲染。
|
||
|
||
## 1. 核心概念
|
||
|
||
| 概念 | 说明 | 类比 WordPress |
|
||
|------|------|---------------|
|
||
| **Block** | 最小内容单元（段落、标题、图片、代码等），以 JSON 存储 | Gutenberg Block |
|
||
| **Block 字段** | Content Type 的 `content` 字段类型为 `blocks`，存储 Block 数组 | `post_content`（富文本） |
|
||
| **Layout** | 页面骨架，定义有哪些区域（regions） | `header.php` + `footer.php` + `sidebar.php` |
|
||
| **Page Template** | 将 Layout 绑定到特定 Content Type 或单篇文章 | `single-post.php` / `page.php` |
|
||
| **Region** | Layout 中的一个插槽，可配置 Block 列表 | `get_sidebar()` / 动态 Widget 区域 |
|
||
| **模板层级** | 前端根据路由自动匹配最具体的模板 | WordPress Template Hierarchy |
|
||
|
||
## 2. 架构总览
|
||
|
||
```
|
||
┌─ 后端 Rust ──────────────────────────────────────────────┐
|
||
│ │
|
||
│ content_types/post.toml │
|
||
│ fields.content.type = "blocks" ← 块编辑器字段类型 │
|
||
│ │
|
||
│ layouts 表 │
|
||
│ id | name | regions │
|
||
│ L1 | default | ["header","nav","content","sidebar", │
|
||
│ | | "footer"] │
|
||
│ L2 | full | ["header","content","footer"] │
|
||
│ │
|
||
│ page_templates 表 │
|
||
│ id | name | layout | content_type │
|
||
│ T1 | Post Detail | L1 | post │
|
||
│ T2 | Post Full | L2 | post │
|
||
│ T3 | Page Landing | L2 | page │
|
||
│ │
|
||
│ template_regions 表 (每个区域放哪些 block) │
|
||
│ template=T1, region="sidebar" │
|
||
│ → [{"type":"recent_posts","limit":5}] │
|
||
│ │
|
||
└───────────────────────────────────────────────────────────┘
|
||
|
||
┌─ 前端 Next.js ────────────────────────────────────────────┐
|
||
│ │
|
||
│ TemplateProvider │
|
||
│ ├─ 查询当前路由 → 匹配 page_template │
|
||
│ ├─ 加载 layout → 渲染 regions │
|
||
│ └─ 每个 region → 渲染配置的 blocks │
|
||
│ │
|
||
│ BlockRegistry (前端) │
|
||
│ "paragraph" → <ParagraphBlock /> │
|
||
│ "heading" → <HeadingBlock /> │
|
||
│ "image" → <ImageBlock /> │
|
||
│ "code" → <CodeBlock /> │
|
||
│ "gallery" → <GalleryBlock /> │
|
||
│ "recent_posts" → <RecentPostsBlock /> │
|
||
│ "newsletter" → <NewsletterBlock /> │
|
||
│ ...插件可注册新 block... │
|
||
│ │
|
||
│ LayoutRegistry (前端) │
|
||
│ "default" → Header + Nav + Content + Sidebar + Footer │
|
||
│ "full" → Header + Content + Footer │
|
||
│ "landing" → 全自定义 │
|
||
│ │
|
||
└───────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 3. Block 编辑器
|
||
|
||
### 3.1 Block 数据结构
|
||
|
||
内容不再是纯 Markdown 文本，而是结构化的 Block 数组。
|
||
|
||
`content` 字段存储格式：
|
||
|
||
```jsonc
|
||
[
|
||
{ "type": "heading", "attrs": { "level": 2 }, "content": "为什么选择我们" },
|
||
{ "type": "paragraph", "content": "我们提供最优质的服务..." },
|
||
{
|
||
"type": "image",
|
||
"attrs": { "src": "/uploads/team.jpg", "alt": "团队照片", "width": 800 }
|
||
},
|
||
{
|
||
"type": "columns",
|
||
"attrs": { "count": 3 },
|
||
"children": [
|
||
[{ "type": "card", "attrs": { "title": "快速", "icon": "zap" } }],
|
||
[{ "type": "card", "attrs": { "title": "安全", "icon": "shield" } }],
|
||
[{ "type": "card", "attrs": { "title": "可靠", "icon": "check" } }]
|
||
]
|
||
},
|
||
{ "type": "code", "attrs": { "language": "rust" }, "content": "fn main() {}" },
|
||
{ "type": "newsletter" } // 自定义 block（插件注册）
|
||
]
|
||
```
|
||
|
||
### 3.2 Block 类型定义
|
||
|
||
每个 Block 统一结构：
|
||
|
||
```typescript
|
||
interface Block {
|
||
type: string; // block 类型标识
|
||
content?: string; // 文本内容（paragraph / heading / code）
|
||
attrs?: Record<string, unknown>; // 属性（src / level / language 等）
|
||
children?: Block[][]; // 嵌套子 block（columns 等）
|
||
}
|
||
```
|
||
|
||
### 3.3 内置 Block 类型
|
||
|
||
| Block 类型 | attrs | 说明 |
|
||
|-----------|-------|------|
|
||
| `paragraph` | — | 段落文本，支持内联标记（粗体、链接等） |
|
||
| `heading` | `level: 1-6` | 标题 |
|
||
| `image` | `src, alt, width, caption?` | 图片 |
|
||
| `image_gallery` | `images: [{src, alt}]` | 图片画廊 |
|
||
| `code` | `language` | 代码块 |
|
||
| `quote` | `author?, source?` | 引用 |
|
||
| `list` | `ordered: bool` | 有序/无序列表 |
|
||
| `columns` | `count: 2-4` | 多栏布局，children 是二维数组 |
|
||
| `divider` | — | 分隔线 |
|
||
| `embed` | `url, provider, width, height` | 第三方嵌入（YouTube、Tweet 等） |
|
||
| `table` | `rows, headers: bool` | 表格 |
|
||
| `callout` | `variant: info/warning/danger/tip` | 提示框 |
|
||
| `card` | `title, icon?, image?` | 卡片（常用于 columns 内） |
|
||
| `raw_html` | — | 原始 HTML（仅管理员可用） |
|
||
|
||
### 3.4 前端 Block 渲染
|
||
|
||
```tsx
|
||
// components/BlockRenderer.tsx
|
||
|
||
interface BlockProps {
|
||
type: string;
|
||
content?: string;
|
||
attrs?: Record<string, unknown>;
|
||
children?: Block[][];
|
||
}
|
||
|
||
const blockRegistry: Record<string, React.ComponentType<BlockProps>> = {
|
||
heading: HeadingBlock,
|
||
paragraph: ParagraphBlock,
|
||
image: ImageBlock,
|
||
columns: ColumnsBlock,
|
||
code: CodeBlock,
|
||
gallery: GalleryBlock,
|
||
newsletter: NewsletterBlock,
|
||
// 插件运行时动态注册更多...
|
||
};
|
||
|
||
export function BlockRenderer({ blocks }: { blocks: Block[] }) {
|
||
return (
|
||
<>
|
||
{blocks.map((block, i) => {
|
||
const Component = blockRegistry[block.type];
|
||
if (!Component) return <UnknownBlock key={i} type={block.type} />;
|
||
return <Component key={i} {...block} />;
|
||
})}
|
||
</>
|
||
);
|
||
}
|
||
```
|
||
|
||
插件可注册自定义 Block：
|
||
|
||
```tsx
|
||
// 插件注册 block
|
||
BlockRegistry.register("newsletter", NewsletterBlock);
|
||
BlockRegistry.register("pricing_table", PricingTableBlock);
|
||
```
|
||
|
||
### 3.5 后端兼容
|
||
|
||
现有 `content` 字段是 Markdown 文本。迁移策略：
|
||
|
||
1. 新增字段类型 `blocks`，新 Content Type 使用
|
||
2. 现有 `richtext` 字段保持 Markdown 存储不变
|
||
3. 前端 `BlockRenderer` 遇到 `string` 类型 content 自动走 Markdown 渲染
|
||
4. Admin 编辑器：`richtext` 用 Markdown 编辑器，`blocks` 用 Block 编辑器
|
||
|
||
## 4. Layout 与 Page Template
|
||
|
||
### 4.1 模板匹配规则（Template Resolution）
|
||
|
||
模仿 WordPress 模板层级，前端根据路由自动匹配模板：
|
||
|
||
```
|
||
请求 /posts/hello-world
|
||
1. 查找 page_template: content_type=post, slug="hello-world" → 没找到
|
||
2. 查找 page_template: content_type=post, slug=null → 找到 "Post Full"
|
||
3. 加载 layout → Header + Content + Footer
|
||
4. Content 区域渲染 post.content 的 blocks
|
||
|
||
请求 /pages/about
|
||
1. 查找 page_template: content_type=page, slug="about" → 找到 "Page Landing"
|
||
2. 加载对应 layout
|
||
3. 渲染 region 配置的 blocks + 文章 content
|
||
|
||
请求 / (首页)
|
||
1. 查找 page_template: content_type=null, slug=null → 找到 "Homepage"
|
||
2. 加载 landing layout
|
||
3. 所有 region 均由 template region_config 定义
|
||
```
|
||
|
||
匹配优先级（从高到低）：
|
||
|
||
| 优先级 | 匹配条件 | 示例 |
|
||
|--------|---------|------|
|
||
| 1 | `content_type` + `slug` 精确匹配 | `post` + `hello-world` |
|
||
| 2 | `content_type` + `slug=null` 默认模板 | `post` + null |
|
||
| 3 | 全局默认 | null + null |
|
||
|
||
### 4.2 前端 TemplateProvider
|
||
|
||
```tsx
|
||
// components/TemplateProvider.tsx
|
||
|
||
async function resolveTemplate(
|
||
contentType: string | null,
|
||
slug: string | null,
|
||
): Promise<PageTemplate | null> {
|
||
const templates = await api.get<Template[]>("/templates");
|
||
|
||
// 优先级 1: content_type + slug 精确匹配
|
||
let matched = templates.find(
|
||
(t) => t.content_type === contentType && t.slug === slug,
|
||
);
|
||
|
||
// 优先级 2: content_type 默认模板
|
||
if (!matched) {
|
||
matched = templates.find(
|
||
(t) => t.content_type === contentType && !t.slug,
|
||
);
|
||
}
|
||
|
||
// 优先级 3: 全局默认
|
||
if (!matched) {
|
||
matched = templates.find((t) => !t.content_type && !t.slug);
|
||
}
|
||
|
||
return matched ?? null;
|
||
}
|
||
|
||
export function TemplateProvider({
|
||
template,
|
||
data,
|
||
children,
|
||
}: {
|
||
template: PageTemplate;
|
||
data?: Record<string, unknown>;
|
||
children?: React.ReactNode;
|
||
}) {
|
||
const layout = layouts[template.layout_id];
|
||
|
||
return (
|
||
<layout.Component>
|
||
{layout.regions.map((region) => (
|
||
<Region key={region} name={region}>
|
||
{region === "content" && children}
|
||
{template.region_config[region]?.map((block, i) => (
|
||
<BlockRenderer key={i} blocks={[block]} />
|
||
))}
|
||
</Region>
|
||
))}
|
||
</layout.Component>
|
||
);
|
||
}
|
||
```
|
||
|
||
## 5. 数据库设计
|
||
|
||
### 5.1 layouts 表
|
||
|
||
```sql
|
||
CREATE TABLE layouts (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL UNIQUE,
|
||
regions TEXT NOT NULL, -- JSON: ["header","nav","content","sidebar","footer"]
|
||
preview TEXT, -- 预览图 URL（可选）
|
||
is_system BOOLEAN NOT NULL DEFAULT 0,
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT NOT NULL
|
||
);
|
||
```
|
||
|
||
### 5.2 page_templates 表
|
||
|
||
```sql
|
||
CREATE TABLE page_templates (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL,
|
||
layout_id TEXT NOT NULL REFERENCES layouts(id) ON DELETE CASCADE,
|
||
content_type TEXT, -- null = 全局/首页
|
||
slug TEXT, -- null = 该 content_type 的默认模板
|
||
region_config TEXT NOT NULL DEFAULT '{}', -- JSON: region → block 配置数组
|
||
is_system BOOLEAN NOT NULL DEFAULT 0,
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT NOT NULL,
|
||
UNIQUE(content_type, slug)
|
||
);
|
||
```
|
||
|
||
### 5.3 预置数据
|
||
|
||
```sql
|
||
INSERT INTO layouts (id, name, regions, is_system, created_at, updated_at) VALUES
|
||
('layout-default', 'Default', '["header","nav","content","sidebar","footer"]', 1, datetime('now'), datetime('now')),
|
||
('layout-full', 'Full Width', '["header","content","footer"]', 1, datetime('now'), datetime('now')),
|
||
('layout-landing', 'Landing', '["content"]', 1, datetime('now'), datetime('now'));
|
||
|
||
INSERT INTO page_templates (id, name, layout_id, content_type, slug, region_config, is_system, created_at, updated_at) VALUES
|
||
('tpl-post', 'Post Detail', 'layout-default', 'post', NULL,
|
||
'{"sidebar":[{"type":"recent_posts","attrs":{"limit":5}},{"type":"tags"}]}',
|
||
1, datetime('now'), datetime('now')),
|
||
('tpl-page', 'Page', 'layout-full', 'page', NULL, '{}',
|
||
1, datetime('now'), datetime('now')),
|
||
('tpl-home', 'Homepage', 'layout-landing', NULL, NULL,
|
||
'{"content":[{"type":"hero"},{"type":"featured_posts","attrs":{"limit":3}},{"type":"newsletter"}]}',
|
||
1, datetime('now'), datetime('now'));
|
||
```
|
||
|
||
## 6. API 设计
|
||
|
||
### 6.1 Layout CRUD
|
||
|
||
| Method | Path | 说明 |
|
||
|--------|------|------|
|
||
| GET | `/api/v1/admin/layouts` | 列出所有布局 |
|
||
| GET | `/api/v1/admin/layouts/:id` | 获取单个布局 |
|
||
| POST | `/api/v1/admin/layouts` | 创建布局 |
|
||
| PUT | `/api/v1/admin/layouts/:id` | 更新布局 |
|
||
| DELETE | `/api/v1/admin/layouts/:id` | 删除布局（非 system） |
|
||
|
||
### 6.2 Page Template CRUD
|
||
|
||
| Method | Path | 说明 |
|
||
|--------|------|------|
|
||
| GET | `/api/v1/admin/templates` | 列出所有模板 |
|
||
| GET | `/api/v1/admin/templates/:id` | 获取单个模板 |
|
||
| POST | `/api/v1/admin/templates` | 创建模板 |
|
||
| PUT | `/api/v1/admin/templates/:id` | 更新模板（改布局、配 region） |
|
||
| DELETE | `/api/v1/admin/templates/:id` | 删除模板（非 system） |
|
||
|
||
### 6.3 模板解析（前端用）
|
||
|
||
| Method | Path | 说明 |
|
||
|--------|------|------|
|
||
| GET | `/api/v1/templates/resolve?content_type=post&slug=hello` | 解析匹配的模板 |
|
||
| GET | `/api/v1/templates/resolve` | 首页模板 |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"template": {
|
||
"id": "tpl-post",
|
||
"name": "Post Detail",
|
||
"layout": {
|
||
"id": "layout-default",
|
||
"name": "Default",
|
||
"regions": ["header", "nav", "content", "sidebar", "footer"]
|
||
},
|
||
"region_config": {
|
||
"sidebar": [
|
||
{ "type": "recent_posts", "attrs": { "limit": 5 } },
|
||
{ "type": "tags" }
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 7. Content Type Schema 扩展
|
||
|
||
`blocks` 字段类型加到 Content Type 定义中：
|
||
|
||
```toml
|
||
# content_types/post.toml
|
||
|
||
[fields.content]
|
||
type = "blocks" # 新字段类型
|
||
label = "正文"
|
||
required = true
|
||
|
||
[fields.excerpt]
|
||
type = "text"
|
||
max_length = 500
|
||
label = "摘要"
|
||
```
|
||
|
||
`blocks` 字段在数据库中存储为 `TEXT`（JSON 数组），与 `json` 字段类型存储方式相同，
|
||
区别在于前端使用 Block 编辑器而非 JSON 文本框。
|
||
|
||
## 8. 前端 Admin 页面
|
||
|
||
### 8.1 Block 编辑器组件
|
||
|
||
核心编辑组件，用于 `blocks` 类型字段的输入：
|
||
|
||
```
|
||
components/admin/block-editor/
|
||
├── BlockEditor.tsx # 编辑器主体
|
||
├── BlockToolbar.tsx # 顶部工具栏（插入 block / 拖拽排序）
|
||
├── blocks/ # 每个 block 类型的编辑态组件
|
||
│ ├── ParagraphEdit.tsx
|
||
│ ├── HeadingEdit.tsx
|
||
│ ├── ImageEdit.tsx
|
||
│ ├── CodeEdit.tsx
|
||
│ ├── ColumnsEdit.tsx
|
||
│ └── ...
|
||
└── BlockSelector.tsx # "+" 按钮弹出的 block 选择面板
|
||
```
|
||
|
||
### 8.2 模板管理页面
|
||
|
||
```
|
||
web/src/app/admin/templates/
|
||
├── page.tsx # 模板列表 + Layout 列表
|
||
├── [id]/page.tsx # 模板编辑：选 Layout + 配置每个 Region 的 blocks
|
||
└── layouts/
|
||
└── page.tsx # Layout 管理（增删 regions）
|
||
```
|
||
|
||
### 8.3 Admin 侧边栏
|
||
|
||
layout.tsx 的 menuItems 增加：
|
||
|
||
```ts
|
||
{ label: "Templates", href: "/admin/templates", icon: LayoutTemplate },
|
||
```
|
||
|
||
## 9. 与现有系统集成
|
||
|
||
### 9.1 Content Type 字段类型扩展
|
||
|
||
`FieldType` 枚举新增 `Blocks`：
|
||
|
||
```rust
|
||
// src/content_type/schema.rs
|
||
pub enum FieldType {
|
||
Text,
|
||
RichText,
|
||
// ... 现有类型
|
||
Blocks, // 新增
|
||
}
|
||
```
|
||
|
||
`blocks` 字段在数据库中存储为 `TEXT`（JSON 数组），与 `json` 字段类型的 migration 逻辑相同。
|
||
|
||
### 9.2 与插件系统结合
|
||
|
||
插件可通过 manifest 注册自定义 Block：
|
||
|
||
```toml
|
||
# plugins/newsletter/plugin.toml
|
||
|
||
[[blocks]]
|
||
type = "newsletter"
|
||
label = "Newsletter Signup"
|
||
icon = "mail"
|
||
component = "blocks/NewsletterBlock" # 前端组件路径
|
||
```
|
||
|
||
插件加载时，前端通过 API 获取插件注册的 block 列表，动态加入 `BlockRegistry`。
|
||
|
||
### 9.3 与多租户结合
|
||
|
||
每个租户可有独立的 page_templates 配置（`tenant_id` 列过滤），
|
||
不同租户可使用不同的布局和 region block 配置。
|
||
|
||
## 10. 实施步骤
|
||
|
||
| 步骤 | 内容 | 优先级 |
|
||
|------|------|--------|
|
||
| 1 | 数据库 migration（layouts + page_templates 表 + 预置数据） | P0 |
|
||
| 2 | 后端 CRUD API（layout + template） | P0 |
|
||
| 3 | 后端模板解析 API（`/templates/resolve`） | P0 |
|
||
| 4 | Content Type 新增 `blocks` 字段类型 | P0 |
|
||
| 5 | 前端 BlockRegistry + BlockRenderer（只渲染，不编辑） | P0 |
|
||
| 6 | 前端 TemplateProvider + 模板匹配 | P0 |
|
||
| 7 | 前端 Admin 模板管理页面 | P1 |
|
||
| 8 | 前端 Block 编辑器（可视化编辑 block） | P1 |
|
||
| 9 | 插件注册自定义 Block 机制 | P2 |
|
||
| 10 | 拖拽排序 block | P2 |
|