kate522
34b7aa7a91
Stale vendor/ after the PSR-4 cutover omits AKSRT\ from autoload_psr4, so helpers fatal on DomainModel constants. Fail loud with composer install/dump-autoload guidance and document the deploy step in README + ADR.
249 lines
10 KiB
Markdown
249 lines
10 KiB
Markdown
# AKSRT WordPress Theme
|
||
|
||
> **版本**: 3.4.0-dev | **架构**: 原生 PHP + WordPress (非 headless)
|
||
> **要求**: WordPress >= 6.4 | PHP >= 8.1
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
AKSRT 是一款现代化的 WordPress 主题，采用**原生 WordPress 主题架构**开发（PHP + HTML + CSS + JavaScript），不依赖 REST API 进行前端渲染。
|
||
|
||
### 核心特性
|
||
|
||
- **自定义管理面板 (SPA)** — Vue3 + Vite + Naive UI 的 12 个一级业务域后台
|
||
- **统一设置契约** — Schema 驱动表单、域控制器、导入导出、按域重置、迁移状态与健康检查
|
||
- **支付/下载主线** — 下载/付费内容中心、充值/VIP/分成/返佣/网关结构、10 分钟下载 token
|
||
- **用户与增长** — OAuth 登录、邮箱验证门禁、签到奖励、邀请奖励、等级/徽章/认证/举报结构
|
||
- **内容与交互** — 首页模块化、归档/搜索/404、单篇资源页、评论审核与通知中心
|
||
- **运维工具** — 配置导出导入、dry-run 校验、邮件回滚、数据库与环境诊断
|
||
- **自定义页面模板**：About / Friends / Login / Profile / Register
|
||
- **响应式设计**
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
AKSRT-theme/
|
||
├── functions.php # 入口：常量 + Composer autoload + bootstrap + 单例 init
|
||
├── style.css # WordPress 主题声明头
|
||
├── composer.json # 第三方依赖 + 主题 PSR-4（AKSRT\ → src/AKSRT/）
|
||
│
|
||
├── *.php # WP 核心模板保留根目录
|
||
│
|
||
├── src/AKSRT/ # Composer PSR-4 类型根（namespace AKSRT\）
|
||
│ ├── Admin/ # SPA 编排 + 域控制器 + Schema + Native ops
|
||
│ ├── Auth/ # 登录 / OAuth / 审核 / 邮箱
|
||
│ ├── Content/ # 下载 token / 付费内容 / VIP / 可见性
|
||
│ ├── Core/ # 主题壳层（Setup / Scripts / Templates / SEO / DB…）
|
||
│ ├── Credits/ # 积分 / 钱包 / 签到 / 邀请
|
||
│ ├── Extensions/ # MeiliSearch / 推送 / IP / 内容审核
|
||
│ ├── Forum/ # 论坛服务 + 收银台
|
||
│ ├── Frontend/ # 前端渲染辅助
|
||
│ ├── Messages/ # 站内信 / 私信 / 公告 / 举报
|
||
│ ├── Payment/ # 订单 / 网关 / 售后 / 物流 / 分成
|
||
│ │ └── Gateways/ # 支付宝 / 微信 / PayPal / Stripe
|
||
│ ├── Settings/ # 设置门面 + 运行时 delegates
|
||
│ ├── Shop/ # 商城服务 + meta box
|
||
│ ├── Sms/ # 短信编排 + 云厂商 adapter
|
||
│ ├── Ai/ # AI / SEO prompt
|
||
│ ├── User/ # 用户中心 / 主页 / 徽章 / 等级 / 关注
|
||
│ └── Widgets/ # 小工具类（一类一文件）
|
||
│
|
||
├── inc/ # 过程式引导与辅助
|
||
│ ├── bootstrap.php # helpers + modules + core-hooks（类由 Composer 加载）
|
||
│ ├── core-hooks.php # 核心功能钩子
|
||
│ ├── modules/ # 非类过程式模块（captcha / user-parts / widgets 注册…）
|
||
│ └── helpers/ # 辅助函数
|
||
│
|
||
├── templates/ # 模板目录（与 inc/ 隔离）
|
||
│ ├── pages/ # 自定义页面模板
|
||
│ │ ├── page-about.php # 关于页面
|
||
│ │ ├── page-friends.php # 友链墙
|
||
│ │ ├── page-login.php # 登录页面
|
||
│ │ ├── page-profile.php # 用户中心
|
||
│ │ └── page-register.php # 注册页面
|
||
│ │
|
||
│ └── parts/ # 可复用模板片段
|
||
│ ├── content-post-card.php # 文章卡片组件
|
||
│ ├── post-card.php # 文章卡片（旧版兼容）
|
||
│ └── comments.php # 评论列表组件
|
||
│
|
||
└── assets/ # 静态资源（前后端隔离）
|
||
├── css/
|
||
│ ├── frontend/ # 前端样式
|
||
│ │ ├── main.css # 主样式表
|
||
│ │ └── variables.css # CSS 变量（颜色/间距/字体）
|
||
│ ├── admin/ # 后台专用样式
|
||
│ │ └── admin-panel.css # SPA 容器面板样式
|
||
│ └── shared/ # 前后端共用
|
||
│ └── captcha.css # 人机验证样式
|
||
│
|
||
├── js/
|
||
│ └── main.js # 前端交互脚本
|
||
│
|
||
├── img/
|
||
│ └── icons/ # 本地 SVG 图标（17个）
|
||
│
|
||
└── admin/ # Vue3 SPA 后台构建产物
|
||
└── build/ # Vite 构建输出（ESM）
|
||
```
|
||
|
||
---
|
||
|
||
## 安装方式
|
||
|
||
主题类型（`AKSRT\…`）通过 Composer PSR-4 从 `src/AKSRT/` 自动加载；`vendor/` 不进 Git。**部署或更新主题后必须在主题根目录生成 autoload**，否则会出现 `Class "AKSRT\Core\DomainModel" not found` 等致命错误。
|
||
|
||
### 前置：Composer（必做）
|
||
|
||
在主题目录（含 `composer.json` 的那一层）执行：
|
||
|
||
```bash
|
||
# 首次或依赖变更后（安装第三方库 + 生成主题 PSR-4）
|
||
composer install --no-dev --optimize-autoloader
|
||
|
||
# 仅 composer.json autoload 映射变更时（无需重下包）
|
||
composer dump-autoload -o
|
||
```
|
||
|
||
确认：
|
||
|
||
```bash
|
||
php -r "require 'vendor/autoload.php'; echo class_exists('AKSRT\\\\Core\\\\DomainModel') ? \"ok\\n\" : \"missing\\n\";"
|
||
```
|
||
|
||
应输出 `ok`。若 PHP 开启了 OPcache，重载 php-fpm / 重启 PHP 后再访问站点。
|
||
|
||
### 方式一：直接上传（推荐）
|
||
|
||
1. 将整个 `AKSRT-theme` 文件夹上传到 `wp-content/themes/`
|
||
2. 在服务器主题目录执行上一节的 `composer install`（若打包时已带上完整 `vendor/` 且已 `dump-autoload`，可跳过）
|
||
3. WordPress 后台 → **外观** → **主题** → 找到 **AKSRT** → **激活**
|
||
|
||
### 方式二：ZIP 打包上传
|
||
|
||
压缩为 `.zip` 后通过 WordPress 后台上传；上传后同样需要在服务器主题目录生成/校验 Composer autoload（见上）。
|
||
|
||
### 生产急救（已白屏 / DomainModel not found）
|
||
|
||
SSH 进入主题目录后：
|
||
|
||
```bash
|
||
cd /path/to/wp-content/themes/AKsrt-theme # 以实际路径为准
|
||
composer install --no-dev --optimize-autoloader
|
||
# 或仅刷新映射：composer dump-autoload -o
|
||
# 可选：reload php-fpm / 清 OPcache
|
||
```
|
||
|
||
---
|
||
|
||
## 使用指南
|
||
|
||
### 1. 创建基础页面
|
||
|
||
激活主题后创建以下页面并选择对应模板：
|
||
|
||
| 页面名称 | 选择模板 | 路径建议 |
|
||
|---------|---------|---------|
|
||
| 关于我 | **About** | `/about` |
|
||
| 友情链接 | **Friends** | `/friends` |
|
||
| 个人中心 | **Profile** | `/profile` |
|
||
|
||
登录/注册页面会自动检测，无需手动创建。
|
||
|
||
### 2. 后台配置路径
|
||
|
||
WordPress 后台左侧 **Admin Bar** → ⚡ **AKSRT 主题设置**
|
||
|
||
或直接访问：`/wp-admin/admin.php?page=aksrt-settings`
|
||
|
||
### 3. 当前后台域
|
||
|
||
- `全局&功能`：品牌、布局、搜索、自定义代码、邮件
|
||
- `页面&显示`：首页、分类、标签、用户主页、404/搜索结果
|
||
- `文章&列表`：列表、缩略图、单篇、筛选、评论
|
||
- `功能&权限`：审核、验证码、评论/附件/下载权限
|
||
- `用户&互动`：登录注册、OAuth、通知、签到、认证、等级、徽章、举报、积分
|
||
- `支付&付费`：下载/付费内容中心、余额充值、VIP、创作分成、推广返佣、收款接口
|
||
- `备份&导入`：导入导出、健康检查、迁移状态、邮件回滚
|
||
|
||
---
|
||
|
||
## 开发说明
|
||
|
||
### Settings Facade 分层
|
||
|
||
- `AKSRT_Settings` 仍是主题设置的**唯一静态 facade**，外部调用方式保持 `AKSRT_Settings::*`
|
||
- 具体运行时 getter 已按领域拆分到 `inc/classes/settings/`，例如：
|
||
- `class-aksrt-settings-theme-search.php`
|
||
- `class-aksrt-settings-post-display.php`
|
||
- `class-aksrt-settings-home-cms.php`
|
||
- `class-aksrt-settings-user-runtime.php`
|
||
- `class-aksrt-settings-integration.php`
|
||
- `class-aksrt-settings-display-runtime.php`
|
||
- `class-aksrt-settings-extension-runtime.php`
|
||
- `class-aksrt-settings-credits-runtime.php`
|
||
- `class-aksrt-settings-category-runtime.php`
|
||
- `class-aksrt-settings-forum-shop.php`
|
||
- `class-aksrt-settings-capabilities.php`
|
||
- `inc/bootstrap.php` 会先加载 `settings/class-aksrt-settings.php`，再按领域加载这些 delegate 类
|
||
- 新增设置运行时逻辑时，优先放入对应 settings 子类；仅把聚合输出、统一入口和跨域装配保留在 `AKSRT_Settings`
|
||
|
||
### 添加新辅助函数
|
||
|
||
将函数文件放入 `inc/helpers/`，在 `bootstrap.php` 阶段1 加载。
|
||
|
||
### 添加新页面模板
|
||
|
||
将 `page-{name}.php` 放入 `templates/pages/`，并在 `class-aksrt-templates.php` 中注册。
|
||
|
||
### CSS 组织规范
|
||
|
||
| 目录 | 用途 | 加载场景 |
|
||
|------|------|---------|
|
||
| `css/frontend/` | 前端公共样式 | 所有前台页面 |
|
||
| `css/admin/` | 后台管理样式 | 仅 AKSRT 设置页面 |
|
||
| `css/shared/` | 共用组件样式 | 前后端按需加载（如验证码） |
|
||
|
||
---
|
||
|
||
## OAuth 第三方登录配置
|
||
|
||
### 支持的平台
|
||
|
||
GitHub | Gitee | QQ | Google
|
||
:---:|:---:|:---:|:---:
|
||
✅ | ✅ | ✅ | ✅
|
||
|
||
### 回调地址格式
|
||
|
||
```
|
||
https://你的域名.com/?aksrt_oauth_callback={provider}
|
||
```
|
||
|
||
`{provider}`: `github` / `gitee` / `qq` / `google`
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- **后端**: PHP 8.1+ / WordPress 6.4+
|
||
- **前端**: HTML5 / CSS3 (CSS Variables) / Vanilla JavaScript
|
||
- **图标**: 本地 SVG 图标 + 按需加载
|
||
- **字体**: Manrope + Source Serif 4 (Google Fonts)
|
||
- **后台**: Vue3 + Vite + NaiveUI (SPA)
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
---
|
||
|
||
## 作者
|
||
|
||
Kate (Lexo0522)
|