PuranCMS 系统概述

什么是 PuranCMS？

PuranCMS 是一款基于 ThinkPHP 8.0 框架开发的轻量级内容管理系统（CMS），专为中小企业和个人开发者设计。系统采用前后端分离的架构思想，后端使用 ThinkPHP 8.0 提供 API 接口，前端使用 Layui 构建管理界面，模板引擎采用 ThinkPHP 原生模板引擎。

设计理念

• 简洁高效：去除冗余功能，专注于核心内容管理
• 灵活扩展：采用模型驱动架构，支持自定义内容模型
• 易于部署：标准 LAMP/LEMP 环境即可运行
• 安全可靠：内置权限管理、SQL 防注入、XSS 防护

核心特性

• 多模型内容管理（文章、产品、页面、图片、下载、招聘、分支等）
• 自定义导航菜单管理
• 广告位管理
• 留言管理
• 后台权限管理
• 操作日志记录
• 访客统计
• 插件扩展机制
• UEditor 富文本编辑器集成

适用场景

PuranCMS 适用于以下场景：

• 企业官网建设
• 产品展示网站
• 新闻资讯网站
• 个人博客
• 小型电商网站

功能特性详解

内容管理

系统支持多种内容模型，每种模型对应不同的业务场景：

导航管理

支持自定义导航菜单，可绑定不同的内容模型和模板，实现灵活的页面跳转和内容展示。

广告管理

支持多种广告类型（图片广告、文字广告、HTML 代码），可设置广告位置、排序、状态等。

留言管理

前台用户可提交留言，后台管理员可查看、标记已读、删除留言，支持批量操作。

权限管理

基于角色的权限控制（RBAC），支持菜单权限、操作权限的细粒度控制。

数据统计

提供控制台仪表盘，展示访客统计、地区分布、流量统计、操作日志等数据。

技术栈说明

后端技术栈

核心依赖包

前端技术栈

服务器环境

• Web 服务器：Nginx 1.18+ / Apache 2.4+
• PHP 扩展：PDO、MBString、OpenSSL、JSON、Fileinfo
• 推荐配置：2 核 CPU / 4GB 内存 / 50GB SSD

环境要求与准备

服务器环境要求

• PHP：版本 >= 8.0，推荐 8.1 或 8.2
• MySQL：版本 >= 5.7，推荐 8.0
• Web 服务器：Nginx 1.18+ 或 Apache 2.4+
• Composer：版本 >= 2.0

PHP 扩展要求

确保以下 PHP 扩展已启用：

• pdo_mysql - 数据库连接
• mbstring - 多字节字符串处理
• openssl - 加密支持
• json - JSON 处理
• fileinfo - 文件类型检测
• gd - 图像处理（验证码、二维码）

目录权限要求

以下目录需要写入权限：

• runtime/ - 运行时缓存目录
• public/uploads/ - 文件上传目录
• logs/ - 日志目录（如有）

检查环境

# 检查 PHP 版本
php -v

# 检查 PHP 扩展
php -m | grep -E "pdo_mysql|mbstring|openssl|json|fileinfo|gd"

# 检查 Composer 版本
composer -V

安装步骤指南

方式一：通过安装向导安装（推荐）

1. 将项目文件部署到 Web 服务器目录
2. 配置 Web 服务器，将网站根目录指向 public/ 目录
3. 访问 http://your-domain/install 进入安装向导
4. 按照向导提示完成环境检测、数据库配置、管理员账号设置
5. 安装完成后，访问 http://your-domain/admin 登录后台

方式二：手动安装

1. 克隆或下载项目

   git clone https://github.com/your-repo/purancms.git
   cd purancms

2. 安装依赖

   composer install

3. 配置环境变量

   cp .example.env .env

   编辑 .env 文件，配置数据库连接信息
4. 导入数据库

   mysql -u root -p your_database < database/install.sql

5. 设置目录权限

   chmod -R 755 runtime/
   chmod -R 755 public/uploads/

6. 配置 Web 服务器

   参考下方 Nginx/Apache 配置示例

Nginx 配置示例

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/purancms/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ .php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Apache 配置示例

项目已包含 public/.htaccess 文件，确保 Apache 启用了 mod_rewrite 模块。

配置参数说明

环境变量配置 (.env)

[APP]
DEBUG = true

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = purancms
USERNAME = root
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8mb4
PREFIX = pr_

配置文件说明

后台系统配置

登录后台后，可在"系统设置"中配置：

• 站点名称、Logo、后台 Logo
• SEO 设置（标题、关键词、描述）
• 联系方式（电话、邮箱、地址）
• 版权信息、备案号

后端目录结构

核心目录说明

app/
├── admin/                    # 后台模块
│   ├── controller/           # 后台控制器
│   │   ├── Base.php          # 后台基础控制器
│   │   ├── Dashboard.php     # 控制台
│   │   ├── Content.php       # 内容管理
│   │   ├── System.php        # 系统设置
│   │   ├── Upload.php        # 文件上传
│   │   └── ...
│   └── view/                 # 后台视图
│       ├── layout/main.html  # 后台布局模板
│       └── ...
├── index/                    # 前台模块
│   └── controller/           # 前台控制器
├── common/                   # 公共模块
│   └── controller/Install.php # 安装向导
├── model/                    # 数据模型
│   ├── BaseModel.php         # 模型基类
│   ├── Article.php           # 文章模型
│   ├── Product.php           # 产品模型
│   └── ...
├── service/                  # 服务层
│   ├── ContentService.php    # 内容服务
│   ├── AdminService.php      # 管理员服务
│   └── ...
├── middleware/               # 中间件
│   ├── AdminCheck.php        # 后台权限验证
│   └── InstallCheck.php      # 安装状态检查
└── taglib/                   # 自定义标签库
    └── PuranTag.php          # PuranCMS 模板标签

目录职责

• controller/：处理 HTTP 请求，调用服务层，返回响应
• model/：数据库操作，数据验证，业务数据封装
• service/：复杂业务逻辑，组合多个模型操作
• middleware/：请求拦截，权限验证，日志记录
• taglib/：自定义模板标签，简化前端数据调用

前端目录结构

静态资源目录

public/static/
├── admin/                    # 后台静态资源
│   ├── css/                  # 后台样式文件
│   │   ├── admin.css         # 后台全局样式
│   │   ├── dashboard.css     # 控制台样式
│   │   ├── content.css       # 内容管理样式
│   │   └── ...
│   ├── js/                   # 后台 JavaScript 文件
│   │   ├── admin.js          # 后台全局脚本
│   │   ├── content.js        # 内容管理脚本
│   │   ├── dashboard.js      # 控制台脚本
│   │   └── ...
│   └── ueditor/              # UEditor 编辑器
├── index/                    # 前台静态资源
│   ├── css/style.css         # 前台样式
│   └── js/main.js            # 前台脚本
└── layui/                    # Layui 框架

视图模板目录

template/default/             # 默认模板主题
├── layout/main.html          # 前台布局模板
├── index/index.html          # 首页模板
├── product-list.html         # 产品列表模板
└── product-detail.html       # 产品详情模板

前端架构说明

• 后台采用 Layui 作为 UI 框架
• JavaScript 采用模块化 IIFE 模式，避免全局污染
• AJAX 请求统一使用 Layui 内置的 jQuery
• 样式采用独立文件，按功能模块划分

模板目录说明

模板目录结构

template/
└── default/                  # 默认模板主题
    ├── layout/               # 布局模板
    │   └── main.html         # 主布局（header + content + footer）
    └── index/                # 前台控制器对应模板
        ├── index.html        # 首页
        ├── product-list.html # 产品列表
        └── product-detail.html # 产品详情

模板引擎语法

ThinkPHP 模板引擎支持以下语法：

• 变量输出：{$variable}
• 条件判断：{if condition="$status eq 1"}...{/if}
• 循环遍历：{foreach $list as $item}...{/foreach}
• 模板继承：{extend name="layout/main" /}
• 区块定义：{block name="content"}...{/block}
• 原始输出：{$content|raw}（不转义 HTML）

自定义标签

PuranCMS 提供了自定义标签库 PuranTag，可在模板中直接使用：

{puran:list name="模型标识" limit="10" category_id="分类ID" order="id desc"}
    <h3>{$item.title}</h3>
    <p>{$item.description}</p>
{/puran:list}

{puran:detail name="模型标识" id="$id"}
    <h1>{$item.title}</h1>
    <div>{$item.content|raw}</div>
{/puran:detail}

{puran:model key="模型标识"}
    <h2>{$modelInfo.name}</h2>
{/puran:model}

命名空间规范

PSR-4 自动加载规范

项目遵循 PSR-4 自动加载规范，命名空间与目录结构严格对应：

命名空间映射

命名空间声明示例

<?php
namespace app\admin\controller;

use app\service\ContentManageService;
use think\facade\View;

class Content extends Base
{
    // ...
}

注意事项

• 所有 PHP 文件必须声明 <?php 开头
• 命名空间声明必须在文件顶部（<?php 之后第一行）
• 使用 use 语句引入外部类，避免使用完整命名空间
• 类名必须与文件名一致（大小写敏感）

文件命名规范

PHP 文件命名

• 控制器：大驼峰命名（PascalCase），如 Content.php、System.php
• 模型：大驼峰命名，如 Article.php、Product.php
• 服务：大驼峰命名 + Service 后缀，如 ContentService.php
• 中间件：大驼峰命名，如 AdminCheck.php

视图文件命名

• 使用小写字母 + 下划线，如 index.html、form.html
• 布局文件放在 layout/ 目录下，如 main.html

静态资源命名

• CSS 文件：小写字母 + 连字符，如 content.css、dashboard.css
• JavaScript 文件：小写字母 + 连字符，如 content.js、admin.js

数据库命名

• 表名：小写字母 + 下划线，前缀 pr_，如 pr_article
• 字段名：小写字母 + 下划线，如 create_time、status

代码开发规范

PHP 编码规范

• 遵循 PSR-12 编码规范
• 使用 4 个空格缩进
• 类名使用大驼峰命名（PascalCase）
• 方法名使用小驼峰命名（camelCase）
• 属性名使用小驼峰命名
• 常量使用全大写字母 + 下划线

控制器规范

• 控制器只负责接收请求、调用服务、返回响应
• 业务逻辑必须放在 Service 层
• 使用 $this->success() 和 $this->error() 返回统一格式

模型规范

• 所有模型继承 BaseModel
• 开启自动时间戳：protected $autoWriteTimestamp = true;
• 定义表名：protected $name = 'table_name';
• 定义关联关系方法

JavaScript 规范

• 使用 IIFE 模式封装，避免全局污染
• 变量使用 var 声明
• 使用 layui.use() 加载模块
• AJAX 请求统一使用 JSON 格式

数据库配置说明

数据库连接配置

数据库配置在 config/database.php 或 .env 文件中：

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = purancms
USERNAME = root
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8mb4
PREFIX = pr_

数据库表前缀

所有数据表使用 pr_ 前缀，方便多系统部署：

• pr_admin - 管理员表
• pr_admin_menu - 菜单表
• pr_article - 文章表
• pr_product - 产品表
• pr_nav - 导航表
• pr_message - 留言表
• pr_advertisement - 广告表
• pr_system_config - 系统配置表

字符集

使用 utf8mb4 字符集，支持 Emoji 和特殊字符。

二次开发指南

开发环境搭建

1. 安装 PHP 8.0+ 和 Composer
2. 克隆项目并安装依赖：composer install
3. 配置 .env 文件
4. 导入数据库：mysql -u root -p db_name < database/install.sql
5. 启动开发服务器：php think run

添加新模块

1. 在 app/admin/controller/ 创建控制器
2. 在 app/model/ 创建模型
3. 在 app/admin/view/ 创建视图
4. 在 route/app.php 添加路由
5. 在后台菜单管理中添加菜单项

添加新模型

1. 创建数据库表
2. 在 app/model/ 创建模型类，继承 BaseModel
3. 在后台"模型管理"中注册模型
4. 在导航管理中绑定模型

交互逻辑脑图

用户请求
  │
  ├─ 前台请求
  │   ├─ Index 控制器
  │   │   ├─ 获取导航
  │   │   ├─ 获取内容列表
  │   │   └─ 渲染模板
  │   └─ Upload 控制器
  │       └─ 处理文件上传
  │
  └─ 后台请求
      ├─ AdminCheck 中间件
      │   └─ 验证登录状态
      ├─ 控制器
      │   ├─ 接收参数
      │   ├─ 调用 Service
      │   └─ 返回 JSON/视图
      └─ Service
          ├─ 业务逻辑处理
          ├─ 调用 Model
          └─ 返回结果

v1.0.0 安全中心模块与项目基础架构

发布信息

一、项目立项背景

1.1 项目定位

PuranCMS 是一款基于 ThinkPHP 8.0+ 框架开发的企业级内容管理系统（CMS），旨在为企业提供一个功能完善、易于扩展、安全可靠的内容管理解决方案。

核心目标：

1.2 技术栈选型

1.3 系统架构设计

┌─────────────────────────────────────────────────────┐
│                   表现层 (Presentation)                │
│  ┌──────────────────┐  ┌──────────────────┐          │
│  │   后台管理视图     │  │   前台展示模板     │          │
│  │  (Layui + TP模板) │  │  (default/enterprise)        │
│  └──────────────────┘  └──────────────────┘          │
├─────────────────────────────────────────────────────┤
│                    控制层 (Controller)                  │
│  admin/ | index/ | api/ | common/                     │
├─────────────────────────────────────────────────────┤
│                  中间件层 (Middleware)                  │
│  AdminCheck │ AuthCheck │ SecurityGuard              │
├─────────────────────────────────────────────────────┤
│                    业务层 (Service)                    │
│  ContentService │ SecurityService │ MemberService ...  │
├─────────────────────────────────────────────────────┤
│                    模型层 (Model)                      │
│  Product │ News │ Page │ User │ Admin │ Model ...     │
├─────────────────────────────────────────────────────┤
│                 数据存储层 (Database)                   │
│           MySQL 5.7+ (utf8mb4)                       │
└─────────────────────────────────────────────────────┘

1.4 项目目录结构

web.puran.cc/
├── app/
│   ├── admin/controller/    # 后台控制器
│   ├── index/controller/    # 前台控制器
│   ├── api/controller/      # API 控制器
│   ├── model/               # 数据模型
│   ├── service/             # 业务服务层
│   ├── middleware/          # 中间件
│   ├── taglib/              # 自定义标签库
│   └── common/              # 公共模块
├── template/
│   └── default/             # 默认前台主题
│       ├── index/           # 首页/列表页
│       ├── user/            # 会员中心
│       └── common/          # 公共组件(header/footer)
├── public/static/           # 静态资源
├── config/                  # 配置文件
├── database/                # 数据库脚本
├── route/                   # 路由配置
└── extend/                  # 扩展类库

二、基础开发历程（v0.1.0 ~ v0.9.0）

2.1 v0.1.0 — 项目初始化（2026-04-01）

• 引入 ThinkPHP 8.1.4 框架，完成 Composer 依赖配置
• 配置单应用模式（auto_multi_app = false）
• 建立项目基础目录结构
• 初始化路由分组配置
• 创建入口文件 public/index.php

2.2 v0.5.0 — 项目骨架搭建（2026-04-10）

• 后台基类控制器 AdminBase.php —— 权限校验、通用方法封装
• 前台基类控制器 Index.php —— 前台公共逻辑
• 路由配置 app/route.php —— 前后台路由分组
• 基础模型层骨架（Admin、SystemConfig、Nav 等）
• 基础服务层骨架（AdminService、ContentService、AddonService）
• Layui 2.13.5 前端框架集成
• 后台布局模板 layout/main.html
• 登录页面 login/index.html
• 数据库安装脚本 database/install.sql 初版

2.3 v0.7.0 — RBAC 权限认证系统（2026-04-15）

权限三表模型：

安装向导（4 步骤）：

2.4 v0.8.0 — 内容管理核心（2026-04-20）

8 大内容类型：

前台控制器：

• Index.php —— 首页渲染
• Doc.php —— 文档详情
• Dynamic.php —— 动态内容页
• BranchPage.php —— 门店页面
• Member.php —— 会员中心

2.5 v0.9.0 — 站点配置与仪表盘增强（2026-04-25）

• 站点配置：后台 Logo / 前台 Logo（固定+滑动）/ 公安备案号 / 联系信息
• 仪表盘增强：ECharts 中国地图访客分布 / 访问流量统计图表 / 流量来源分析
• 新增服务：DashboardService.php
• 新增数据表：pr_visitor_log / pr_operation_log

三、v1.0.0 核心新增：安全中心模块

3.1 安全评分仪表盘

ECharts 仪表盘组件展示 0-100 分的安全评分，基于 8 项检测加权计算。

3.2 8 项安全检测

3.3 风险等级划分

3.4 安全策略配置（5 大类）

3.5 IP 黑名单管理

支持精确 IP / CIDR 格式封禁，含封禁原因 + 过期时间（永久可选）

3.6 安全防御中间件 SecurityGuard（7 层防护链）

请求 → IP黑名单拦截 → HTTPS强制 → 请求限流 → CSRF验证
     → SQL注入检测 → XSS检测 → 安全响应头 → 控制器

3.7 新增数据表（3 张）

• pr_security_config — 安全配置表
• pr_ip_blacklist — IP 黑名单表
• pr_login_log — 登录日志表（用户名/IP/归属地/状态/时间）

3.8 新增文件清单

后端文件：

• app/admin/controller/Security.php — 安全中心控制器
• app/model/SecurityConfig.php — 安全配置模型
• app/model/IpBlacklist.php — IP 黑名单模型
• app/model/LoginLog.php — 登录日志模型
• app/service/SecurityService.php — 安全服务层
• app/middleware/SecurityGuard.php — 安全防御中间件

扩展类库：

• extend/security/IpTool.php — IP 工具类
• extend/security/SqlInjectFilter.php — SQL 注入过滤器
• extend/security/XssClean.php — XSS 过滤器
• extend/security/PathValidator.php — 目录权限验证器
• extend/security/PasswordChecker.php — 密码强度检查器

前端文件：

• app/admin/view/security/index.html — 安全中心主页面
• app/admin/view/security/policy.html — 安全策略配置弹窗
• app/admin/view/security/ip_blacklist.html — IP 黑名单弹窗
• app/admin/view/security/permission.html — 目录权限检查弹窗
• app/admin/view/security/login_log.html — 登录日志弹窗
• public/static/admin/css/security.css — 样式
• public/static/admin/js/security.js — 前端逻辑

v1.1.0 图片管理增强与 IP 地理位置集成

发布信息

一、图片管理增强

• 上传弹窗：120×120 占位框 → 多图选择 → 80×80 缩略图网格预览 → 串行上传

• 图片列表：时间 Y-m-d H:i:s 格式化 / B/KB/MB/GB 大小格式化 / 复制链接按钮

• 分类操作：悬停显示编辑/删除图标按钮、"全部图片"节点

二、IP 地理位置（ip2region v3.0 集成）

// 全局函数
$location = ip2region('61.142.118.231');
// 输出：中国广东省中山市【电信】

// 类方式（返回数组：country/province/city/isp/ip/version）
$ip2region = new Ip2Region();
$info = $ip2region->getIpInfo('61.142.118.231');

三、Bug 修复

• finfo_file / SplFileInfo 报错：move() 前先获取文件信息

• 前端 renderImageItem 空引用 / deleteCategory $ 未定义 / 按钮布局修复

v1.2.0 页面命名空间重构与安装向导优化

发布信息

一、8 个页面重构（命名空间隔离）

规范：IIFE 包裹 + 命名空间对象 + 事件委托 + XSS 防护（escapeHtml）

二、安装向导重构

修复步骤间导航 404 Bug（路由 POST→GET 修正）

v1.3.0 标签库加载修复与登录验证码校验失败修复

发布信息

一、标签库加载问题修复

问题：PuranTag 无法正常加载，{puran:xxx} 标签无法解析

根因：PuranTag 缺少 $tagLib = 'puran' 属性

修复：添加属性 → TagLibService 注册 → ViewInitMiddleware 触发

二、登录验证码校验失败修复

2.1 滑块验证

onEnd 中 setTimeout 1秒自动重置导致 token 失效 → 移除自动重置

2.2 点选验证

clickCount≥4 时 500ms 自动刷新 → 移除自动刷新

2.3 坐标不一致

前端显示坐标 vs 后端原始坐标(310×155) → 新增 scaleClickCoords() 换算函数

v1.4.0 导航样式修复与文档完善

发布信息

更新概述

本版本主要修复顶部导航样式问题，并输出完整开发历程文档。

一、顶部导航样式修复

涉及文件：style.css / simple_header.css / page_detail.css

二、完整开发历程文档

docs/PuranCMS_完整开发历程文档.md — 含项目立项/技术栈/架构设计/数据库设计/开发阶段记录/功能模块/前后台模板/更新迭代日志/未来规划

v1.5.0 ~ v1.5.1 会员等级功能增强与协议修复

一、v1.5.0 会员等级功能增强

发布信息

1.1 新增功能概览

• 会员积分系统 — user 表新增 points、total_amount 字段
• 等级升级条件 — min_points / max_points / min_amount 双重条件判断
• 会员权益管理 — benefits 字段（JSON 数组），后台动态添加/删除权益项
• 等级图标与颜色 — icon（layui 图标类名）+ color（如 #FFD700）
• 自动升级机制 — UserLevelService：checkAndUpgrade / calculateLevel / addPoints / addAmount

1.2 数据库变更

pr_user_level 表新增字段：

pr_user 表新增字段：points（积分）、total_amount（累计消费金额）

二、v1.5.1 前台用户协议验证修复

发布信息

2.1 问题

前台登录/注册/找回密码页面，未勾选同意协议可绕过验证成功提交。根因：user.js 的 submit handler 与页面内联 handler 冲突，user.js 先执行且无协议检查。

2.2 修复方案

1. 在 user.js 统一添加协议勾选验证（login/register/forgot 三个表单）
2. 移除各 HTML 页面中的重复 submit handler
3. 将"记住我"自动填充逻辑迁移至 user.js

2.3 修改文件

• public/static/index/js/user.js — 统一协议验证 + 找回密码 handler + 记住我逻辑
• template/default/user/login.html — 移除重复 handler
• template/default/user/register.html — 移除重复 handler
• template/default/user/forgot_password.html — 移除重复 handler

v1.6.0 会员体系完善与管理增强

发布信息

更新概述

在 v1.5.0/v1.5.1 会员等级基础上，进一步完善会员系统的配套功能：会员设置面板、积分规则配置、标签管理、UEditor 集成、前台会员中心全套页面（16 个页面）。

一、会员设置管理面板

1.1 配置项（group: member）

配套服务：MemberService::getConfig() / isEnabled() / isRegisterEnabled()（带缓存 TTL=3600s）

二、积分规则配置

2.1 规则项（group: points_rule）

配套服务：PointsService::addPoints($userId, $points, $type, $desc)（带日志+缓存）

三、其他新增模块

3.1 标签管理系统

• 控制器：TagManage.php | 服务：TagService.php | 模型：Tag.php + TagRelation.php
• 支持 CRUD + 多对多关联 + 删除保护（有内容不可删）+ SEO 字段

3.2 UEditor 富文本编辑器集成

• 控制器：Ueditor.php | 支持 7 种 action（config/uploadimage/uploadvideo/uploadfile/listimage/catchimage 等）
• 安全特性：文件类型白名单、大小限制、远程抓取域名白名单、XSS 过滤

3.3 自定义链接管理

• 控制器：CustomLinkManage.php | 模型：CustomLink.php
• 三种类型：导航链接 / 友情链接 / 底部链接

四、前台会员中心（16 个页面）

五、新增数据表（3 张）

• pr_custom_link — 自定义链接表（title/url/type/target/icon/status）
• pr_tag — 标签表（name/slug/description/cover/SEO字段/article_count/product_count）
• pr_tag_relation — 标签关联表（tag_id + target_type + target_id 唯一索引）

v1.7.0 文档管理与动态表单系统

发布信息

更新概述

新增两大核心模块：文档管理系统（树形分类 + 富文本内容）和动态表单系统（12 种字段类型 + JSON 数据收集）。

一、文档管理系统

1.1 模块组成

1.2 文档分类（DocCategory）字段

1.3 文档内容（DocContent）字段

二、动态表单系统

2.1 模块组成

2.2 支持的字段类型（12 种）

2.3 表单数据存储

所有提交数据以 JSON 格式存储在 FormData.data 字段中，便于灵活扩展。

三、新增数据表（5 张）

• pr_doc_category — 文档分类表（树形结构）
• pr_doc_content — 文档内容表（富文本）
• pr_form — 自定义表单表
• pr_form_field — 表单字段定义表
• pr_form_data — 表单提交数据表（JSON）

v1.8.0 自定义内容模型、插件系统与主题管理

发布信息

一、自定义内容模型系统

1.1 功能概述

允许管理员在后台动态创建新的内容类型（如"课程"、"案例"、"FAQ"等），无需修改代码即可扩展平台的内容承载能力。每个模型自动生成对应的数据表。

1.2 核心能力

• 14 种字段类型：文本/多行文本/富文本/数字/日期时间/单选/多选/下拉框/图片上传/文件上传/开关/评分/关联模型/JSON
• 保留关键字保护：内置 17 个保留 key 防止与系统表冲突
• 自动建表：创建模型时根据字段定义自动生成数据库表结构
• 前台渲染支持：通过 {custom:content} 标签在前台展示

二、插件系统（Addon System）

2.1 设计理念

插件系统采用"热插拔"架构设计，开发者可通过标准化的目录结构和接口规范开发独立的功能模块，实现功能的模块化封装与灵活组合。

2.2 插件目录结构

addons/
├── anticode/                    # 示例：防伪码查询插件
│   ├── config.php               # 插件配置文件（元数据+钩子+标签）
│   ├── Plugin.php               # 插件主类（继承 BasePlugin）
│   ├── Install.php              # 安装脚本
│   ├── Uninstall.php            # 卸载脚本
│   ├── route.php                # 插件路由规则
│   ├── controller/              # 控制器层
│   │   ├── Admin.php            # 后台控制器
│   │   └── Index.php            # 前台控制器
│   ├── model/                   # 数据模型
│   │   └── Anticode.php
│   ├── service/                 # 业务服务
│   │   └── Service.php
│   ├── view/                    # 视图模板
│   │   ├── admin/               # 后台视图
│   │   │   ├── index.html       # 列表页
│   │   │   ├── edit.html        # 编辑页
│   │   │   ├── settings.html    # 设置页
│   │   │   └── nav.html         # 导航配置
│   │   ├── index/               # 前台视图
│   │   │   ├── index.html       # 列表页
│   │   │   ├── detail.html      # 详情页
│   │   │   └── widget.html      # 组件模板（可嵌入任意页面）
│   │   └── assets/              # 静态资源
│   │       ├── css/admin.css
│   │       └── js/admin.js
│   ├── logs/                    # 运行日志目录
│   └── README.md                # 说明文档
├── appointment/                 # 示例：在线预约插件
├── multilang/                   # 示例：多语言切换插件
├── timeline/                    # 示例：时间线展示插件
└── .gitignore

2.3 BasePlugin 抽象基类

所有插件必须继承 app\common\BasePlugin，提供以下核心能力：

2.4 config.php 配置文件结构

 'my_addon',
    'title' => '我的插件',
    'description' => '插件功能说明',
    'version' => '1.0.0',
    'author' => 'AuthorName',
    'icon' => 'layui-icon-app',
    'status' => 0,           // 0=未安装, 1=已安装启用, -1=已停用

    // ===== 钩子系统 =====
    'hooks' => [
        'my_addon_widget' => [
            'method' => 'renderWidget',          // Plugin 类中的方法名
            'description' => '组件（可嵌入任意页面）',
        ],
    ],

    // ===== 标签系统 =====
    'tags' => [
        'list' => ['description' => '列表标签', 'params' => ['limit'=>'显示数量']],
        'detail' => ['description' => '详情标签', 'params' => ['id'=>'内容ID']],
    ],

    // ===== 业务配置项 =====
    'config' => [
        'pagesize' => 10,
        'show_status' => 1,
        'nav_menu_show' => ['type'=>'switch', 'title'=>'前台导航显示', 'value'=>1],
    ],

    // ===== 导航菜单集成 =====
    'nav_menu' => [
        'enable' => true,
        'position' => 'top',
        'menus' => [['title'=>'我的插件', 'url'=>'/addons/my_addon/index', ...]],
    ],
];

2.5 插件生命周期管理

5 大操作流程：

2.6 钩子机制（HookService）

钩子系统是插件与系统交互的核心桥梁，采用观察者模式实现事件驱动：

请求到达 → 触发钩子 → HookService::trigger('hook_name')
     ↓
遍历所有已注册的回调函数 → 按优先级排序 → 依次执行
     ↓
收集所有返回值 → 返回给调用方

// 系统触发示例（在需要的位置）
HookService::trigger('frontend_header_js');   // 输出前端头部JS
HookService::trigger('frontend_footer_js');   // 输出前端底部JS

// 插件注册示例（在 Plugin.php 中）
$this->hooks = [
    'frontend_header_js' => ['method' => 'injectHeaderScript'],
];

HookService API：

2.7 内置插件一览

2.8 插件路由与静态资源

• 路由：每个插件可定义独立的 route.php，通过 /addons/{name}/{action} 访问
• 静态资源：后台提供 Addons::asset() 方法安全输出 CSS/JS/图片等静态文件，含 MIME 类型检测和目录穿越防护
• 图标上传：后台支持为每个插件上传专属图标（jpg/png/gif）

2.9 新增数据表

• pr_addon — 插件主表（name/title/version/status/config/hooks/tags/install_time）

2.10 插件相关新增文件清单

核心框架：

• app/common/BasePlugin.php — 插件抽象基类
• app/common/AddonTemplate.php — 插件代码生成器（22 个文件模板）
• app/service/HookService.php — 钩子服务（事件驱动引擎）
• app/service/AddonService.php — 插件生命周期管理服务
• app/model/Addon.php — 插件数据模型

后台管理：

• app/admin/controller/Addons.php — 插件管理控制器（11 个方法：index/list/install/uninstall/toggle/create/config/saveConfig/manage/checkName/uploadIcon/asset）
• app/admin/view/addons/index.html — 插件列表页
• app/admin/view/addons/create.html — 创建插件向导
• app/admin/view/addons/config.html — 插件配置弹窗

内置插件（4 个）：

• addons/anticode/ — 防伪码查询插件（完整 MVC + 服务层 + 日志）
• addons/appointment/ — 在线预约插件（分类/时段/订单/字段自定义）
• addons/multilang/ — 多语言切换插件（中英双语 + 术语映射）
• addons/timeline/ — 时间线展示插件（树形分类 + 组件嵌入）

三、主题管理系统

3.1 功能概述

主题管理系统允许管理员在后台自由切换、预览、配置不同的前台视觉主题，支持多套主题并存，一键切换生效。

3.2 已有主题

3.3 theme.json 元数据格式

每个主题根目录下的 theme.json 定义主题基本信息：

{
    "name": "default",
    "title": "默认主题",
    "version": "1.0.0",
    "author": "PuranCMS",
    "description": "PuranCMS 默认前台主题，适用于企业官网场景",
    "screenshots": ["screenshot.png", "screenshot-home.png", "screenshot-list.png", "screenshot-detail.png"],
    "config": {
        "primary_color": {"type": "color", "title": "主色调", "value": "#1890ff"},
        "header_style": {"type": "select", "title": "头部样式", "value": "fixed", "options": ["fixed", "static"]}
    },
    "required_files": []
}

3.4 主题管理功能（ThemeService）

3.5 后台管理界面（Theme 控制器）

提供 8 个管理方法：

3.6 Default 主题模板清单

公共组件 (common/)：

• header.html — 公共头部（Logo/导航/搜索/会员入口）
• footer.html — 公共底部（版权/备案/友情链接）
• simple_footer.html — 简洁底部
• pagination.html — 分页组件
• layout.html — 布局母版

首页 (index/)：

• index.html — 首页
• product_list/detail.html — 产品列表/详情
• article_list/detail.html — 新闻文章列表/详情
• page_detail.html — 单页详情
• branch_list/detail.html — 门店列表/详情
• download_list/detail.html — 下载中心列表/详情
• recruitment_list/detail.html — 招聘列表/详情
• image_list/detail.html — 图集列表/详情
• message.html — 留言板
• page_detail_contact.html — 联系我们
• page_detail_doc.html — 开发文档
• page_detail_anticode.html — 防伪查询（插件页）
• page_detail_appointment.html — 在线预约（插件页）

会员中心 (user/)：

• center/login/register/forgot_password/profile/password/level/points_rule/messages/notifications/... — 完整会员体系页面

3.7 Enterprise 主题模板清单

• common/layout.html — 企业版布局母版
• index/index/article_list/detail/product_list/detail/page_detail/contact — 精简版页面
• user/auth_layout/center/login/register/layout — 企业版会员页面

3.8 主题相关新增文件清单

• app/service/ThemeService.php — 主题管理服务（15 个方法）
• app/admin/controller/Theme.php — 主题管理控制器（8 个方法）
• app/admin/view/theme/index.html — 主题列表页
• app/admin/view/theme/config.html — 主题配置页
• app/admin/view/theme/preview.html — 主题预览页
• template/default/theme.json — 默认主题元数据
• template/enterprise/theme.json — 企业版主题元数据
• template/default/screenshot*.png — 默认主题截图（4 张）

v1.9.0 SEO 管理、缓存管理与 HTML 静态化

发布信息

更新概述

本版本聚焦于 SEO 优化能力、缓存管理 和 HTML 静态化生成 三大基础设施功能。

一、SEO 管理系统

1.1 SEO 配置项（system_config, group=seo）

1.2 Sitemap 自动生成

SitemapService::generateSitemap();    // 生成 Sitemap XML
SitemapService::getSitemapUrl();      // 获取访问 URL
SitemapService::addUrl($url, $lastmod, $changefreq, $priority); // 添加条目

自动收录：首页、栏目页、详情页、单页、文档页面

1.3 结构化数据（LD-JSON）

{"@context": "https://schema.org", "@type": "WebSite", "name": "PuranCMS", "url": "https://example.com"}

二、缓存管理中心

2.1 可管理的缓存类型

2.2 API 接口

POST /admin/cache_manage/clear?type=template|log|html|cache|all
GET  /admin/cache_manage/index   → 各类型磁盘占用大小

三、HTML 静态化缓存

3.1 支持的生成类型

3.2 核心方法

HtmlCacheService::generateHome();
HtmlCacheService::generateNavPage($navId);
HtmlCacheService::generateContentPage($type, $id);
HtmlCacheService::generateAll();
HtmlCacheService::getStatistics();  // 统计：总文件数/总大小/各类型数量

3.3 静态文件存储规则

runtime/html/
├── index.html              # 首页
├── article/                # 文章
├── product/                # 产品
├── page/                   # 单页
└── doc/                    # 文档

3.4 Nginx 配置建议

location ~ ^/(article|product|page)/ {
    try_files /runtime/html/$uri/index.html /runtime/html/$uri.html /index.php?$query_string;
}

四、新增文件清单

• app/admin/controller/SeoManage.php — SEO 管理
• app/admin/controller/CacheManage.php — 缓存管理
• app/admin/controller/HtmlCache.php — 静态化管理
• app/service/SeoService.php — SEO 服务
• app/service/SitemapService.php — Sitemap 生成
• app/service/HtmlCacheService.php — 静态化核心服务
• 对应视图、CSS、JS 文件

v2.0.0 平台级能力全面升级

发布信息

更新概述

v2.0.0 是 PuranCMS 发展历程中最重要的里程碑版本。本版本标志着系统从"内容管理系统（CMS）"正式跨越为"综合性应用平台"，引入了 RESTful API 接口体系、通知消息系统、图片管理完善化，并整合了此前 v1.6.0 ~ v1.9.0 的全部平台能力。

版本号语义 — 从 v1.x 跳升至 v2.0.0 的理由：

1. API 体系的引入 — 新增完整的 RESTful API 模块，支持外部系统集成
2. 通知系统的建立 — 站内消息/系统通知的统一管理能力
3. 架构层面的扩展 — 新增 api 独立模块、中间件体系扩展
4. 功能数量翻倍 — 从约 15 个功能模块增长到 30+ 个功能模块

一、RESTful API 接口体系（核心新增）

1.1 目录结构

app/api/
├── controller/
│   ├── BaseController.php        # API 基础控制器
│   ├── v1/                       # v1 版本接口
│   │   ├── Content.php           # 内容接口 v1
│   │   └── User.php              # 用户接口 v1
│   ├── v2/                       # v2 版本接口
│   │   ├── Content.php           # 内容接口 v2
│   │   └── User.php              # 用户接口 v2
│   ├── BranchController.php      # 门店 API
│   ├── ContentController.php     # 内容 API（通用）
│   └── MemberController.php      # 会员 API
├── middleware/
│   ├── ApiAuth.php               # API 身份认证中间件
│   └── ApiRateLimit.php          # API 频率限制中间件
└── route/
    └── app.php                   # API 路由配置

1.2 基础控制器（BaseController）

1.3 API 中间件

ApiAuth — 身份认证中间件：从 Header "Authorization" 或参数 "token" 获取 Token → Cache 验证 → 注入 userId / 返回 401

ApiRateLimit — 频率限制中间件：以 IP 为 key 计数 → 默认 60次/60秒/IP → 超限返回 429

1.4 版本策略

1.5 已实现接口清单

内容接口：GET list/detail/search（v1 + v2）

用户接口：POST register/login, GET info/points, PUT profile（v1 + v2）

门店接口：GET list/detail/nearby

会员接口：GET level/points/log/notification/list, PUT notification/read

1.6 认证流程

注册：POST /api/v2/user/register { nickname, email, password }
登录：POST /api/v2/user/login { email, password } → 返回 token + user
认证：GET /api/v2/user/info  Header: Authorization: Bearer xxx

二、通知消息系统

2.1 通知类型

2.2 核心方法

NotificationService::send($userId, $type, $title, $content, $extra);       // 单人发送
NotificationService::sendBatch($userIds, $type, $title, $content);         // 批量发送
NotificationService::broadcast($type, $title, $content);                   // 全员广播
NotificationService::markAsRead($notificationId, $userId);                 // 标记已读
NotificationService::markAllRead($userId);                                 // 全部已读
NotificationService::getUserNotifications($userId, $page, $limit, $type);  // 列表
NotificationService::getUnreadCount($userId);                              // 未读数

2.3 数据表结构（pr_notification）

三、图片管理完善化

3.1 新增服务类

四、新增文件清单

API 模块（12 文件）

• app/api/controller/BaseController.php — API 基础控制器
• app/api/controller/v1/Content.php, User.php — v1 接口
• app/api/controller/v2/Content.php, User.php — v2 接口
• app/api/controller/BranchController.php — 门店 API
• app/api/controller/ContentController.php — 通用内容 API
• app/api/controller/MemberController.php — 会员 API
• app/api/middleware/ApiAuth.php — 认证中间件
• app/api/middleware/ApiRateLimit.php — 限流中间件
• app/api/route/app.php — API 路由

通知系统（3 文件）

• app/admin/controller/Notification.php — 后台管理
• app/service/NotificationService.php — 发送服务
• app/model/Notification.php — 数据模型

图片增强（3+ 文件）

• app/service/ThumbnailService.php, WatermarkService.php, FileStorageService.php
• app/admin/controller/ImageCategory.php

服务层补充（5 文件）

• AddonLoader.php, HookService.php, ContentManageService.php, MessageService.php, Ip2RegionAdapter.php

五、完整功能矩阵（v2.0.0）

总计：30+ 功能模块，60+ 控制器/服务/模型文件

v2.1.0 安全中心全面升级

更新概述

v2.1.0 聚焦安全中心的全面升级与体验优化。本次更新完善了安全告警体系、通知系统隔离、操作日志追踪，并对安全中心 UI 进行了全面优化，使安全中心成为真正实用、易用的安全管理平台。

新增功能

1. 安全告警独立模块

功能概述

将安全告警从通用通知系统中独立出来，专属安全中心管理。安全告警（XSS 拦截、SQL 注入、暴力破解等）不再混入普通通知列表，而是集中在安全中心的安全告警模块中统一管理。

模块组成

新增接口

顶部导航角标

在后台顶部导航新增盾牌图标，实时显示未读安全告警数量：

• 有未读告警时显示红色数字角标（超过 99 显示 99+）

• 无未读告警时自动隐藏

• 点击跳转到安全中心页面

• 每次页面切换自动刷新角标数量

2. 通知系统用户类型隔离

问题背景

之前安全告警通过 notification 表发送，但 user_id 字段同时被管理员和前台用户共用，导致安全告警可能被前台用户看到。

解决方案

新增 user_type 字段区分通知接收者类型：

代码变更

3. 留言回复通知精准推送

留言回复通知逻辑正确，无需修改：每个用户只收到自己留言的回复通知，互不干扰。

4. 安全中心 UI 优化

安全告警弹窗

• 采用 iframe 弹窗模式（type:2），与 IP 白名单/黑名单页面风格一致

• 弹窗尺寸优化为 60% × 80%，适配不同屏幕

• 工具栏布局：左侧按钮组 + 右侧搜索框

• 空状态显示表情图标 + "暂无数据"文字

模块卡片渐变色

为安全中心 7 个模块卡片补充渐变色：

修复问题

1. 安全告警通知推送给前台用户：新增 user_type 字段隔离，安全告警只发送给管理员。

2. 后台通知列表为空：后台通知管理显示所有通知（管理员视角），只有前台用户中心才过滤 user_type='user'。

3. 删除通知后列表不刷新：统一为 res.code === 0 判断成功。

4. 安全告警弹窗一直加载中：在 route/app.php 补充 5 条安全告警路由。

5. 安全告警弹窗样式不一致：在 security.css 新增 #pr-page-security-alerts 专属样式。

6. 安全告警弹窗 jQuery 未定义：为 5 个方法全部补充 $ 声明。

文件变更清单

新增文件

修改文件

数据库变更

ALTER TABLE `pr_notification`
ADD COLUMN `user_type` varchar(20) NOT NULL DEFAULT 'user'
COMMENT '用户类型：user-前台用户, admin-后台管理员'
AFTER `user_id`;

ALTER TABLE `pr_notification` ADD INDEX `idx_user_type` (`user_type`);

-- 更新 type 字段注释
ALTER TABLE `pr_notification`
MODIFY COLUMN `type` varchar(20) NOT NULL DEFAULT 'system'
COMMENT '通知类型：system-系统通知, order-订单通知, activity-活动通知, message-留言回复, security-安全告警';

安全告警触发场景

升级指南

1. 数据库升级：执行 notify_user_type.sql 迁移脚本

2. 清除缓存：后台访问 缓存管理 → 全部清理

3. 验证安全告警：访问安全中心，点击安全告警卡片，确认弹窗正常显示