XPCMS 开发文档
涵盖后台开发、XPUI框架、XPAPI接口、前端开发四大模块
一、系统总览
1.1 技术栈
XPCMS（小彭CMS）是基于 ThinkPHP8 开发的多应用内容管理系统，采用以下核心技术栈：
| 层级 | 技术 | 说明 |
|---|---|---|
| 后端框架 | ThinkPHP 8 | PSR-4 自动加载，多应用模式 |
| 数据库 | MySQL | 表前缀固定 xp_ |
| 前端样式 | Tailwind CSS | 优先使用，减少自定义 CSS |
| UI 框架 | XPUI 自研 | 唯一 UI 框架，禁止引入任何第三方 UI |
| 接口规范 | RESTful JSON | 统一返回 {code, msg, data} |
| 模板引擎 | ThinkPHP 模板 | 原生标签 + 自定义扩展 |
1.2 双端架构
项目采用双目录结构，各自维护独立主题系统，通过 ThemeService 动态加载当前激活主题：
| 目录 | 定位 | 功能范围 |
|---|---|---|
| tp/ | 控制端完整版 | 后台管控 + 社区/会员/推送 + 官网 + 文档，53个控制器 |
| tp-pure/ | 客户纯净版 | 仅保留基础建站+资源接收，43个控制器，移除社区/会员/推送模块 |
注意：Service层（17个）、中间件（4个）、配置文件、静态资源在双端完全一致。仅控制器、模型、验证器按功能裁剪。
1.3 应用体系
| 应用 | 入口 | 用途 |
|---|---|---|
| admin | /admin | 后台管理（iframe框架，RBAC权限体系） |
| index | / | 前台官网（主题渲染，公开访问） |
| xpapi | /api | RESTful API 接口（JWT鉴权，66条路由） |
| install | /install | 安装向导（首次部署） |
1.4 项目目录结构
{项目}/app/
├── admin/ ← 后台应用（控制器+验证器+中间件）
│ ├── controller/ # 53个控制器（tp完整版）
│ ├── middleware/ # AuthCheck / LicenseCheck / PermissionCheck / ConfigCache
│ ├── validate/ # 26个验证器
│ ├── trait/CurdTrait # 通用CRUD复用
│ └── route/app.php
├── index/ ← 前台应用
│ ├── controller/ # 15个控制器（含FrontendConfig Trait）
│ └── middleware/ # ConfigCache / MemberAuth
├── xpapi/ ← API应用
│ ├── controller/ # 13个控制器（双端一致）
│ ├── middleware/JwtAuth
│ └── route/app.php # 66条RESTful路由
├── common/ ← 公共代码（双端共享）
│ ├── model/ # 46个Model
│ └── service/ # 17个Service（双端完全一致）
├── middleware/InstallCheck ← 全局安装检测
└── middleware.php ← 全局中间件注册
二、快速导航
后端开发
CurdTrait、BaseController、模型、验证器、中间件、Service服务层、新模块开发流程
前端开发
命名规范、代码分离、主题开发、FrontendConfig、模板语法、视图模板规范
XPUI 框架
33个文件清单、全部CSS组件class表、XpCore/Toast/Modal/Form/Table/Upload完整API
API 接口
JWT认证流程、66条完整路由表、控制器开发模板、数据安全规范
三、开发规范速查
3.1 PHP 文件头部规范
每个PHP文件必须包含标准版权注释（自动填充当天日期）：
<?php
/**
* 模块描述：[模块功能描述]
* 作者：彭浩
* 邮箱：2443257717@qq.com
* 开发时间：2026-08-02
* 版权：由彭浩独家所有，未经授权禁止转载或商业使用
*/
declare(strict_types=1); // ← 首行必须声明强类型
namespace app\xxx\controller;3.2 命名规范
| 类型 | 规则 | 示例 |
|---|---|---|
| 类名 | 大驼峰 | ArticleCategory |
| 方法名 | 小驼峰 | getList() |
| 数据表名 | 小写蛇形 + xp_ 前缀 | xp_article_category |
| 字段名 | 小写蛇形 | create_time |
| 变量名 | 小驼峰 | $userName |
| 前端 class/id | xp-前缀 + 短横线 + 全小写 | xp-header、xp-form |
| 路由 | 小写蛇形语义化 | /article/list |
| 数据库操作 | 仅用 think\facade\Db | \think\facade\Db::table() |
3.3 API 统一格式
| 请求方式 | 操作 | 成功码 | 示例 |
|---|---|---|---|
| GET | 查询 | 200 | 分页列表 / 单条详情 / 统计汇总 |
| POST | 新增 | 200 | 新增记录 / 登录 / 刷新Token |
| PUT | 修改 | 200 | 更新记录 / 批量更新配置 |
| DELETE | 删除 | 200 | 单条删除 / 批量删除 |
统一返回格式：{code: 200, msg: "操作成功", data: {}}
参数接收：统一使用 Request 依赖注入，禁止 $_GET / $_POST / $_REQUEST。
四、快速入门
4.1 新模块开发6步流程
1 创建Model
→
2 创建SQL表
→
3 创建Validate
→
4 创建Controller
→
5 创建视图模板
→
6 注册路由+权限
控制器只需 use CurdTrait + 配置3个属性，即可获得完整CRUD能力（列表/详情/新增/编辑/删除/切换状态）。
4.2 常用 Service 速查
| Service | 常用方法 |
|---|---|
| ConfigService | get('key')、getSiteConfig()、getUploadConfig()、batchUpdate($data)、clearCache() |
| CacheService | get('key')、set('key', $val, $ttl)、remember('key', fn(), $ttl)、lock('key', $ttl)、warmUp() |
| UploadService | uploadImage($file)（含缩略图）、uploadFile($file) |
| ThemeService | getCurrentViewPath('frontend')、setCurrentTheme('name')、getCurrentTheme() |
| JwtService | encode($payload)、decode($token)（HS256 + hash_equals时序安全） |
4.3 常用 XpCore JS API 速查
| 方法 | 说明 |
|---|---|
| XpCore.request(url, {method, body}) | 统一AJAX（body传对象，自动JSON.stringify+设Content-Type） |
| XpCore.isSuccess(res) | 判断 res.code === 200 |
| XpCore.escapeHtml(str) | HTML 转义防 XSS |
| XpCore.formatDate(ts, 'YYYY-MM-DD HH:mm') | 格式化日期 |
| XpCore.on(el, event, selector, handler) | 事件委托绑定 |
| XpToast.success(msg) | 绿色成功提示（右上角滑入，3s自动消失） |
| XpModal.confirm({title, content}).then(fn) | 确认弹窗（返回Promise） |
| XpForm.submit('#form', {url, success, redirect}) | AJAX表单提交（自动loading状态） |
| XpList.init({container, url, onRender}) | 列表管理器（分页+搜索集成） |
| XpTable.initCheckbox({tableSelector}) | 表格全选联动 |
| XpUpload.create({container, url, maxSize}) | 文件上传（点击+拖拽，进度条，缩略图预览） |