# PufferGo Core - AI 独立站引擎底座

> 由前阿里、腾讯、京东等一线大厂精英团队倾力打造，AI 驱动的独立站引擎。专为中国企业出海服务，快速构建高转化、国际标准的品牌站点。

[![WordPress](https://img.shields.io/badge/WordPress-6.7%2B-blue.svg)](https://wordpress.org/)
[![PHP](https://img.shields.io/badge/PHP-7.4%2B-purple.svg)](https://www.php.net/)
[![License](https://img.shields.io/badge/License-GPL--2.0%2B-green.svg)](LICENSE)

---

## 📋 目录

- [核心功能](#核心功能)
- [技术架构](#技术架构)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [开发指南](#开发指南)
- [项目结构](#项目结构)
- [构建与部署](#构建与部署)
- [常见问题](#常见问题)
- [许可证](#许可证)

---

## 🚀 核心功能

PufferGo Core 提供 5 个核心管理应用，为 WordPress 站点提供完整的 AI 建站能力：

### 1. 📊 Dashboard（主控制面板）

- 账户状态与套餐信息展示
- 积分余额查询
- 快速入口导航
- 使用统计概览

### 2. 🤖 AI 页面构建器（AI Page Builder）

- **智能页面生成**：根据需求描述自动生成页面结构
- **区块推荐**：AI 分析并推荐合适的页面区块组合
- **Pattern 生成**：将 HTML 代码转换为可复用的 Pattern 区块
- **实时预览**：在编辑器中实时查看生成的页面结构
- **侧边栏集成**：无缝集成到 Gutenberg 编辑器侧边栏

### 3. 🏗️ AI 整站构建器（AI Site Builder）

- **五步建站流程**：
  1. **数据收集**：结构化收集企业信息、产品数据、业务需求
  2. **网站架构**：AI 生成完整的网站架构和页面规划
  3. **区块规划**：为每个页面规划合适的区块结构
  4. **Pattern 匹配**：从设计资源库智能匹配 Pattern 区块
  5. **页面创建**：批量创建页面并插入匹配的区块
- **批量操作**：支持批量创建、发布、更新页面
- **进度追踪**：实时显示建站进度和状态

### 4. 🎨 设计资源库（Design Library）

- **Pattern 管理**：完整的 Pattern 区块生命周期管理
- **三栏标注工作流**：
  - **左栏**：实时预览 Pattern 渲染效果
  - **中栏**：人工分类标注（类别、适用页面、风格、布局等）
  - **右栏**：AI 字段分析（自动识别可编辑字段）
- **导入功能**：支持从代码粘贴、文件上传、URL 导入
- **AI 分析**：自动分析 HTML 结构，识别可配置字段
- **字段管理**：支持文本、图片、链接等多种字段类型
- **状态管理**：草稿、已发布、已归档等状态流转

### 5. ⚙️ 设置页面（Settings）

- **API 密钥配置**：PufferGo AI 服务 API 密钥管理
- **统计代码配置**：
  - Google Analytics 4 集成
  - 百度统计集成
- **邮件配置**：联系表单邮件通知设置
- **系统信息**：版本号、环境信息等

---

## 🏗️ 技术架构

### 前端技术栈

- **React 18+**：现代化 UI 框架
- **WordPress Gutenberg**：基于 WordPress 官方区块编辑器
- **TailwindCSS 3.4+**：原子化 CSS 框架
- **Sass**：CSS 预处理器
- **@wordpress/scripts**：WordPress 官方构建工具链

### 后端技术栈

- **PHP 7.4+**：WordPress 插件开发
- **WordPress REST API**：前后端数据交互
- **Custom Post Types**：Pattern 区块存储（`pg_block`）
- **Custom Meta Fields**：Pattern 元数据管理

### 开发工具

- **@wordpress/block-editor**：区块编辑器 API
- **@wordpress/components**：WordPress UI 组件库
- **react-dnd**：拖拽功能支持
- **autoprefixer**：CSS 兼容性处理

---

## 📦 环境要求

### 必需环境

- **WordPress**: 6.7 或更高版本
- **PHP**: 7.4 或更高版本
- **Node.js**: 18 或更高版本（推荐 v20.19.4）
- **npm**: 9 或更高版本（推荐 10.8.2）

### 推荐环境

- **MySQL**: 5.7+ 或 MariaDB 10.3+
- **内存**: 至少 256MB PHP 内存限制
- **服务器**: Apache 或 Nginx

---

## 🚀 快速开始

### 1. 安装依赖

```bash
# 克隆项目（如果从 Git 仓库）
git clone <repository-url>
cd puffergo

# 安装 Node.js 依赖
npm install
```

### 2. 开发模式

#### WordPress 开发（需要本地 WordPress 环境）

```bash
# 启动开发服务器（支持热重载）
npm run start
```

在 WordPress 后台激活插件后，即可在编辑器中看到实时更新的区块。

#### Storybook 开发（独立组件开发）

```bash
# 启动 Storybook（端口 6006）
npm run storybook
```

### 3. 生产构建

```bash
# 构建生产版本
npm run build
```

构建产物位于 `build/` 目录。

### 4. 部署

```bash
# 构建并打包插件（生成 ZIP 文件）
npm run deploy
# 或使用脚本
./deploy.sh
```

生成的 ZIP 包可直接在 WordPress 后台安装。

---

## 💻 开发指南

### 项目结构

```
puffergo/
├── src/                          # 源码目录
│   ├── admin/                    # 管理后台应用
│   │   ├── dashboard/            # Dashboard 应用
│   │   ├── ai-page-builder/      # AI 页面构建器
│   │   ├── ai-site-builder/      # AI 整站构建器
│   │   ├── design-library/       # 设计资源库
│   │   ├── settings/             # 设置页面
│   │   └── tailwind.css          # Tailwind 入口文件
│   ├── blocks/                   # Gutenberg 区块
│   │   ├── dashboard-app/        # Dashboard 区块
│   │   ├── ai-admin-app/         # AI 页面构建器区块
│   │   ├── ai-site-builder-app/  # AI 整站构建器区块
│   │   ├── design-library-app/   # 设计资源库区块
│   │   └── settings-app/         # 设置页面区块
│   └── shared/                   # 共享资源
│       ├── components/           # 共享组件
│       ├── constants/            # 常量定义
│       ├── styles/               # 共享样式
│       └── utils/                # 工具函数
├── php/                          # PHP 后端代码
│   ├── dashboard.php             # Dashboard 页面
│   ├── ai-page-builder.php       # AI 页面构建器
│   ├── ai-site-builder.php       # AI 整站构建器
│   ├── design-library.php        # 设计资源库
│   ├── settings.php              # 设置页面
│   ├── pattern-generator.php     # Pattern 生成器
│   ├── class-puffergo-api-client.php  # API 客户端
│   └── class-contact-form-handler.php # 联系表单处理器
├── build/                        # 构建输出目录
├── languages/                    # 语言包
│   ├── puffergo-zh_CN.po        # 中文翻译
│   └── puffergo-en_US.po        # 英文翻译
├── puffergo.php                  # 插件主文件
├── package.json                  # Node.js 配置
├── tailwind.config.js            # Tailwind 配置
└── deploy.sh                     # 部署脚本
```

### 常用命令

#### 开发命令

```bash
# 启动开发服务器（WordPress 环境）
npm run start

# 启动 Storybook（独立开发）
npm run storybook

# 构建生产版本
npm run build
```

#### 代码质量

```bash
# 格式化代码（JS/CSS）
npm run format

# 检查 JavaScript 代码
npm run lint:js

# 检查 CSS 代码
npm run lint:css
```

#### 依赖管理

```bash
# 更新 @wordpress 相关依赖
npm run packages-update
```

#### 部署命令

```bash
# 构建并打包插件（生成 ZIP）
npm run deploy
```

### 开发流程

#### 1. 新增管理应用

1. 在 `src/admin/` 下创建应用目录
2. 创建 `App.jsx`、`index.js`、`style.scss` 等文件
3. 在 `src/blocks/` 下创建对应的区块注册文件
4. 在 `php/` 下创建对应的 PHP 后端文件
5. 在 `puffergo.php` 中注册应用

#### 2. 新增共享组件

1. 在 `src/shared/components/` 下创建组件
2. 导出组件供其他应用使用
3. 如需样式，在 `src/shared/styles/` 下添加

#### 3. 修改 API 端点

1. 在对应的 PHP 文件中注册 REST API 路由
2. 在前端使用 `apiFetch` 或 `fetch` 调用 API
3. 确保权限检查（`check_permission`）

### 代码规范

- **JavaScript/JSX**：遵循 WordPress JavaScript 编码规范
- **PHP**：遵循 WordPress PHP 编码规范
- **CSS/SCSS**：使用 TailwindCSS 工具类，必要时使用 SCSS
- **命名**：使用有意义的变量和函数名，遵循 WordPress 命名约定

---

## 🔧 构建与部署

### 构建流程

1. **开发构建**：`npm run start` - 生成开发版本，支持热重载
2. **生产构建**：`npm run build` - 生成优化后的生产版本
3. **部署打包**：`npm run deploy` - 构建并打包为 ZIP 文件

### 部署脚本说明

`deploy.sh` 脚本执行以下操作：

1. ✅ 清理之前的构建
2. ✅ 运行 `npm run build`
3. ✅ 创建插件目录结构
4. ✅ 复制必要文件（PHP、构建产物、语言包等）
5. ✅ 优化 PHP 代码（去除注释、格式化）
6. ✅ 验证插件结构
7. ✅ 创建 ZIP 包
8. ✅ 验证 ZIP 包完整性

### 部署产物

部署完成后，会在项目根目录生成：

```
puffergo-v1.0.0.zip  # 可直接安装的插件包
```

### 安装方式

#### 方式一：WordPress 后台安装

1. 进入 WordPress 后台 → 插件 → 安装插件
2. 点击「上传插件」
3. 选择生成的 ZIP 文件
4. 点击「现在安装」→「启用插件」

#### 方式二：手动安装

1. 解压 ZIP 文件
2. 将 `puffergo` 文件夹上传到 `/wp-content/plugins/`
3. 在 WordPress 后台激活插件

---

## ❓ 常见问题

### Q: 如何配置 AI 服务？

A: 进入 WordPress 后台 → **PufferGo** → **设置**，填写 API 密钥。

**API 地址配置**：
- **开发环境**：在 `wp-config.php` 中添加：
  ```php
  define('PUFFERGO_AI_PAGE_BUILDER_BASE_URL', 'http://localhost:3000');
  define('PUFFERGO_BASE_URL', 'http://localhost:4000');
  ```
- **生产环境**：无需额外配置，默认使用 `https://api.puffergo.com` 和 `https://puffergo.com`。
- **自定义环境**：可在 `wp-config.php` 中自定义上述常量来覆盖默认值。

### Q: Pattern 区块存储在哪里？

A: Pattern 区块使用 WordPress 的 `pg_block` Custom Post Type 存储，可通过 REST API (`/wp-json/wp/v2/pg_blocks`) 访问。

### Q: 如何添加新的字段类型？

A: 在 `php/design-library.php` 中的字段类型定义处添加新类型，并在前端 `src/admin/design-library/components/` 中添加对应的渲染组件。

### Q: 开发时如何调试？

A: 
- 前端：使用浏览器开发者工具，查看 React DevTools
- 后端：启用 WordPress 调试模式（`WP_DEBUG`），查看 PHP 错误日志
- API：使用浏览器 Network 面板查看 REST API 请求

### Q: 如何自定义样式？

A: 
- 使用 TailwindCSS 工具类（推荐）
- 在组件的 `style.scss` 中编写自定义样式
- 修改 `tailwind.config.js` 扩展主题配置

### Q: 支持多语言吗？

A: 是的，插件内置中英文支持。语言文件位于 `languages/` 目录，可通过 WordPress 标准翻译流程添加其他语言。

---

## 📄 许可证

本项目采用 **GPL-2.0-or-later** 许可证。

详见 [LICENSE](LICENSE) 文件。

---

## 👥 贡献者

- **开发团队**：深圳小河豚出海科技有限公司
- **联系方式**：support@puffergo.com
- **官网**：https://PufferGo.com
- **文档**：https://puffergo.com

---

## 📚 相关文档

- [QUICK-START.md](QUICK-START.md) - Design Library 快速开始指南
- [readme.txt](readme.txt) - WordPress 插件目录标准说明文件

---

## 🎯 版本历史

### v1.0.0（当前版本）

- ✨ 重构为 AI 独立站引擎底座
- ✨ 新增 AI 整站构建器
- ✨ 新增设计资源库（Pattern 标注工作室）
- ✨ 优化 AI 页面构建器
- ✨ 统一管理后台 UI（TailwindCSS）
- 🔧 优化构建流程和部署脚本
- 📝 完善文档和代码注释

---

**Made with ❤️ by PufferGo Team**