From 9681dd3d487cb46cea61fd16c7e05708a61a6552 Mon Sep 17 00:00:00 2001 From: unknown Date: Fri, 3 Jul 2026 16:17:32 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96=20AKSRT=20=E4=B8=BB?= =?UTF-8?q?=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..cb660ffe --- /dev/null +++ b/README.md @@ -0,0 +1,220 @@ +# 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 # 入口文件（精简版：常量+bootstrap加载+实例初始化） +├── style.css # WordPress 主题声明头 +│ +├── *.php # WP 核心模板保留根目录 +│ ├── index.php # 首页（文章列表 Loop） +│ ├── single.php # 文章详情页 +│ ├── page.php # 默认页面模板 +│ ├── front-page.php # 首页静态页面 +│ ├── archive.php # 归档页 +│ ├── author.php # 作者存档 +│ ├── search.php # 搜索结果 +│ ├── 404.php # 错误页 +│ ├── header.php / footer.php # 页头/页脚 +│ ├── sidebar.php # 侧边栏 +│ └── comments.php # 评论模板 +│ +├── inc/ # 核心代码目录 +│ ├── bootstrap.php # 自动加载器（统一 require 所有模块） +│ ├── core-hooks.php # 核心功能钩子（Gravatar/SMTP/评论/CPT等） +│ │ +│ ├── classes/ # ← 所有类文件集中在此 +│ │ ├── class-aksrt-setup.php # 主题初始化（侧边栏/CPT/菜单支持） +│ │ ├── class-aksrt-scripts.php # 前端/后台资源加载（CSS/JS/内联变量） +│ │ ├── class-aksrt-admin.php # SPA 后台面板（REST API/Vue3容器） +│ │ ├── class-aksrt-settings.php # 设置门面（统一静态入口 + 聚合输出） +│ │ ├── class-aksrt-oauth.php # OAuth 第三方登录 +│ │ ├── class-aksrt-user.php # 用户系统（路由/AJAX资料保存） +│ │ ├── class-aksrt-widgets.php # 小工具 +│ │ ├── class-aksrt-captcha.php # 人机验证集成 +│ │ ├── class-aksrt-moderation.php # 评论审核 +│ │ └── class-aksrt-templates.php # 页面模板注册与加载 +│ │ +│ └── helpers/ # ← 辅助函数文件 +│ ├── aksrt-icons.php # SVG 图标系统（读取/缓存/映射） +│ ├── aksrt-template-tags.php # 模板标签（Banners/友链/Logo/SEO Head） +│ └── aksrt-frontend-tags.php # 前端标签（阅读时长/面包屑/评论回调） +│ +├── 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） +``` + +--- + +## 安装方式 + +### 方式一：直接上传（推荐） + +1. 将整个 `AKSRT-theme` 文件夹上传到 `wp-content/themes/` +2. WordPress 后台 → **外观** → **主题** → 找到 **AKSRT** → **激活** + +### 方式二：ZIP 打包上传 + +压缩为 `.zip` 后通过 WordPress 后台上传。 + +--- + +## 使用指南 + +### 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` 会先加载 `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)