# web_self_assembly

**Repository Path**: fofo_1/web_self_assembly

## Basic Information

- **Project Name**: web_self_assembly
- **Description**: 拖拽构建网页
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Local Puck Builder

一个基于 **Next.js + Puck + Tailwind CSS** 的本地可视化建站原型。项目目标是让前端用户通过拖拽成品区块搭建简易网站，并把站点、页面、草稿、发布内容和表单提交都保存在本地 JSON 文件中，方便先做产品验证和二次开发。

## 技术栈

| 类型 | 技术 |
| --- | --- |
| 应用框架 | Next.js 16 App Router |
| 前端框架 | React 19 |
| 页面编辑器 | @puckeditor/core |
| 样式 | Tailwind CSS 4 |
| 图标 | lucide-react |
| 语言 | TypeScript |
| 本地存储 | data/local-db.json |

## 环境要求

建议使用以下环境：

```bash
node >= 20.9.0
npm >= 10
```

当前开发环境验证版本：

```bash
node v20.19.4
npm 10.8.2
```

如果使用 nvm-windows：

```bash
nvm install 20.19.4
nvm use 20.19.4
```

## 快速启动

安装依赖：

```bash
npm install
```

启动开发服务：

```bash
npm run dev
```

访问入口：

```txt
http://localhost:3000
```

常用页面：

| 页面 | 地址 |
| --- | --- |
| 项目首页 | http://localhost:3000 |
| 拖拽编辑器 | http://localhost:3000/editor/page-home |
| 网站预览 | http://localhost:3000/site/demo-site |
| 表单提交 API | http://localhost:3000/api/submissions |

## 常用命令

```bash
npm run dev      # 启动本地开发服务
npm run build    # 生产构建和类型检查
npm run start    # 启动生产构建后的服务
npm run lint     # ESLint 检查
```

## 项目架构

```txt
src/
  app/
    page.tsx
    globals.css
    layout.tsx
    api/
      pages/[pageId]/route.ts
      session/route.ts
      submissions/route.ts
    editor/[pageId]/
      page.tsx
      editor-client.tsx
    site/[siteSlug]/[[...pageSlug]]/
      page.tsx

  components/
    blocks.tsx
    public-render.tsx

  lib/
    db.ts
    default-data.ts
    puck-config.tsx
    types.ts
    utils.ts

data/
  local-db.json
```

## 核心模块说明

### 1. 首页入口

文件：

```txt
src/app/page.tsx
```

首页展示当前本地站点、页面数量、表单提交数量，并提供进入编辑器和预览网站的入口。

### 2. Puck 编辑器

文件：

```txt
src/app/editor/[pageId]/page.tsx
src/app/editor/[pageId]/editor-client.tsx
```

编辑器页面会读取指定页面的 `draft` 数据，并交给 Puck 渲染。用户在编辑器中拖拽组件或修改右侧属性后，会自动保存草稿。

点击编辑器右上角的“发布”按钮后，会把当前草稿同步到 `published` 字段，网站预览页读取的就是发布版本。

### 3. 前台网站渲染

文件：

```txt
src/app/site/[siteSlug]/[[...pageSlug]]/page.tsx
src/components/public-render.tsx
```

前台页面根据 URL 中的 `siteSlug` 和 `pageSlug` 查找本地页面数据，然后使用 Puck 的 `Render` 组件渲染发布后的 JSON。

默认演示页面：

```txt
/site/demo-site
```

### 4. 可拖拽组件库

文件：

```txt
src/components/blocks.tsx
src/lib/puck-config.tsx
```

当前内置区块：

| 组件 | 说明 |
| --- | --- |
| Navbar | 顶部导航 |
| Hero | 首屏大图与行动按钮 |
| FeatureGrid | 功能介绍网格 |
| Stats | 数据展示 |
| Pricing | 价格卡片 |
| FAQ | 常见问题 |
| TextSection | 文本内容区块 |
| ImageText | 图文介绍区块 |
| CTASection | 行动召唤区块 |
| LogoCloud | 合作品牌 |
| Testimonials | 用户评价 |
| ServiceList | 服务列表 |
| TeamSection | 团队介绍 |
| Timeline | 发展历程 |
| ImageGallery | 图片画廊 |
| VideoBlock | 视频区块 |
| ProductGrid | 产品列表 |
| ArticleList | 文章列表 |
| Contact | 联系表单 |
| Footer | 页脚 |

Puck 的组件字段、默认值、分类和渲染组件都在 `src/lib/puck-config.tsx` 中配置。

新增一个可拖拽组件的一般流程：

1. 在 `src/lib/types.ts` 中补充组件 Props 类型。
2. 在 `src/components/blocks.tsx` 中实现 React 组件。
3. 在 `src/lib/puck-config.tsx` 中注册组件字段、默认值和渲染函数。
4. 如需初始页面展示，在 `src/lib/default-data.ts` 中加入示例 JSON。

### 5. 本地数据层

文件：

```txt
src/lib/db.ts
src/lib/default-data.ts
data/local-db.json
```

项目不依赖真实数据库。第一次运行时，如果 `data/local-db.json` 不存在，`db.ts` 会根据 `default-data.ts` 自动创建一份本地数据。

本地数据结构：

```txt
users
sites
pages
submissions
```

页面数据中最重要的是：

```txt
draft       # 编辑器草稿
published   # 前台网站使用的已发布版本
```

这样用户编辑草稿时，不会立刻影响已发布页面。

### 6. API 路由

| API | 方法 | 说明 |
| --- | --- | --- |
| `/api/pages/[pageId]` | GET | 获取页面数据 |
| `/api/pages/[pageId]` | PUT | 保存草稿 |
| `/api/pages/[pageId]` | POST | 发布页面 |
| `/api/submissions` | GET | 查看表单提交 |
| `/api/submissions` | POST | 保存表单提交 |
| `/api/session` | POST | 本地登录模拟 |
| `/api/session` | DELETE | 清除本地登录 Cookie |

当前登录只是本地 Cookie 模拟，没有接入真实账号密码系统。后续可以替换成 Auth.js、JWT 或自有用户系统。

## 数据流

页面编辑和发布流程：

```txt
打开 /editor/page-home
  ↓
读取 pages[].draft
  ↓
Puck 编辑器渲染页面
  ↓
拖拽组件或修改属性
  ↓
PUT /api/pages/page-home 保存 draft
  ↓
点击发布
  ↓
POST /api/pages/page-home 同步 draft 到 published
  ↓
/site/demo-site 读取 published 并渲染
```

联系表单提交流程：

```txt
用户在预览页提交 Contact 表单
  ↓
POST /api/submissions
  ↓
写入 data/local-db.json 的 submissions
```

## 本地数据重置

如果想恢复初始演示数据，可以删除：

```txt
data/local-db.json
```

然后重新访问页面或重启开发服务，项目会自动根据 `src/lib/default-data.ts` 生成新的本地数据文件。

## 后续扩展建议

可以按这个顺序继续扩展：

1. 接入真实用户登录：Auth.js、JWT 或后端 Session。
2. 把 `data/local-db.json` 替换为 PostgreSQL/MySQL。
3. 使用 Prisma 或 Drizzle 管理数据模型。
4. 增加图片上传：本地上传、S3、R2、OSS 或 MinIO。
5. 增加多页面管理：新建页面、复制页面、删除页面。
6. 增加模板市场：保存页面为模板，一键套用。
7. 增加主题系统：颜色、字体、圆角、按钮风格统一配置。
8. 增加站点发布能力：静态导出、绑定域名、SEO 配置。

## 注意事项

- 当前项目用于本地测试和原型验证，不包含生产级权限控制。
- `data/local-db.json` 是本地数据文件，团队协作时要决定是否纳入 Git。
- Puck 编辑器样式只在编辑器客户端中加载，避免影响前台页面。
- 前台渲染通过客户端包装组件 `PublicRender` 执行，适配 Next.js 16 的 Server/Client 边界。