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 驱动表单、域控制器、导入导出
• 用户与增长 — 统一登录注册、OAuth 登录、签到奖励、邀请奖励、等级/徽章/认证/举报结构
• 内容与交互 — 首页模块化、归档/搜索/404、单篇资源页、评论审核与通知
• 响应式设计

---

文件结构

AKSRT-theme/
├── functions.php                      # 入口：常量 + Composer autoload + bootstrap + 单例 init
├── style.css                          # WordPress 主题声明头
├── composer.json                      # 第三方依赖 + 主题 PSR-4（AKSRT\ → src/）
│
├── *.php                              # WP 核心模板保留根目录
│
├── src/                               # 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 / 内容审核
│   ├── 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-sign.php              #     唯一登录注册页面
│   │   ├── page-profile.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/ 自动加载；vendor/ 不进 Git。部署或更新主题后必须在主题根目录生成 autoload，否则会出现 Class "AKSRT\Core\DomainModel" not found 等致命错误。

前置：Composer（必做）

在主题目录（含 composer.json 的那一层）执行：

# 首次或依赖变更后（安装第三方库 + 生成主题 PSR-4）
composer install --no-dev --optimize-autoloader

# 仅 composer.json autoload 映射变更时（无需重下包）
composer dump-autoload -o

确认：

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 进入主题目录后：

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、创作分成、推广返佣、收款接口
• 备份&导入：导入导出、健康检查、迁移状态、备份与更新

4. 推广、邀请与佣金（用户中心 → 收益）

• 推广链接：用户中心「收益」页展示带 ?ref= 的推广链接、二维码（可下载 PNG）与推广海报（按「推广返佣」设置中的海报文案生成）。归因模式（首触/末触）在「支付&付费 → 推广返佣 → 推广归因模式」配置。
• 一次性邀请码：后台「用户 → 邀请码管理」三视图运营页——列表（状态筛选/搜索/批量删除/排序/分页/点击复制）、添加（系统自动生成：数量/标识/四类奖励[经验值、积分、余额、VIP]/高级选项自定义位数；或 Zibll 兼容文本导入：一行一码 邀请码 奖励 标识，奖励参数串 points=20&balance=30&vip=1&vip_time=5&level_integral=100，分隔符可自定义）、导出（状态筛选 + 文本文档[可回流导入]/Excel表格 双格式）。注册门控模式在「用户&互动 → 登录注册 → 邀请码注册」。消费为原子操作，并发注册不会超发；开启注册验证时奖励延迟到邮箱验证后发放。
• 佣金：订单支付成功后按推广者等级分档比例记录到佣金账本，经「结算观察期」后自动结算入钱包，支持提现与退款联动回滚。「推广码禁用后停止返佣」开关默认关闭。

5. 部署注意事项

• 佣金结算时效：结算依赖小时级 wp-cron，并有收益页访问触发的懒结算兜底。高流量站点建议禁用 WP_CRON_LOCK 场景下的默认 WP-Cron，改用系统 crontab 定时请求 wp-cron.php，保证结算与过期任务准时执行。
• 反代 / CDN 与 IP 风控：主题默认按 Cloudflare → 通用代理头顺序识别真实 IP。若需收紧伪造风险，添加 add_filter('aksrt_trusted_proxies', fn() => ['10.0.0.0/8', '173.245.48.0/20'])（填入你的代理/CDN 网段）；名单非空时仅当 REMOTE_ADDR 命中名单才采纳转发头，否则直接使用 REMOTE_ADDR（推广奖励的 IP 日上限、验证码等均依赖该函数）。

---

开发说明

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-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	微博	微信开放平台	微信公众号
✅	✅	✅	✅	✅	✅	✅

回调地址格式

直连 OAuth：

https://你的域名.com/oauth/callback/

代理服务端按平台配置：

https://代理服务端域名.com/oauth/proxy/{provider}/callback/

彩虹聚合登录：

https://你的域名.com/oauth/clogin/callback/

---

技术栈

• 后端: 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)