开发文档

一、主题概览

• 形态：这是一套 WordPress 主题（资源分享/下载站方向），不是独立程序 —— 装上 WordPress 后在「外观 → 主题」启用即可；推荐 WordPress 6.x+（随包演示站为 WP 7.1 中文版），PHP 7.4~8.2（推荐 8.1）；
• 自带设置框架：pandastudio_framework/ 是主题选项框架（选项定义在 option.json，文章类型/字段在 posttype_and_meta.json），后台「外观 → 主题设置」里的所有开关都来自它；
• 自带区块/小工具：pandastudio_plugins/（下载区块、折叠、相册、弹窗、音频等 Gutenberg 区块与小工具）；
• 会员与付费：page_member.php 是会员中心模板，配合会员/VIP 能力（演示站带 VIP 会员数据）。

二、目录结构

主题目录（wp-content/themes/yunshu/）
├── functions.php         # 主题入口（加载框架、注册资源、功能开关）
├── custom_function.php   # 自定义函数
├── sandbox_functions.php # 沙箱/演示相关函数
├── style.css             # 主题样式（WP 主题头信息）
├── screenshot.png        # 主题截图
├── header.php / footer.php / sidebar.php
├── index.php / archive.php / archives.php / single.php / page.php
├── category.php / tag.php / author.php / 404.php
├── page_member.php       # 会员中心页面模板
├── page_blank.php        # 空白页模板
├── favlinks.php / guidang.php / comments.php   # 友情链接/归档/评论
├── pandastudio_framework/   # 主题选项框架（option.json / config_framework.php）
├── pandastudio_plugins/     # 区块与小工具
├── assets/ faces/           # 静态资源与头像
└── production.php / WordpressRunningInfoStat.php  # 运行信息统计

三、数据

• 主题不建自己的表，全部用 WordPress 标准表：wp_posts（文章/资源）、wp_postmeta（主题字段与文章元数据）、wp_options（主题选项，键名前缀为框架的 option 前缀）、wp_users / wp_usermeta（会员与 VIP 标记）、wp_terms / wp_term_taxonomy（分类/标签）；
• 资源下载类字段（下载地址、提取码、价格、VIP 可见等）以 postmeta 形式挂在文章上（字段定义见 posttype_and_meta.json）。

四、关键机制

4.1 主题选项（pandastudio_framework）

加一个开关：在 option.json 里加一项 → 后台「主题设置」自动出现 → 模板里用框架的取值函数读取（如 _opt('键名')）。别把设置直接写死在模板里。

4.2 夜间/配色

主题带夜间模式（选项 night_mode / auto_switch_night_mode / night_mode_start / night_mode_end）：默认可按时间段自动切；把 auto_switch_night_mode 置空即固定白天配色（右下角「色彩模式」按钮仍保留）。

4.3 会员中心

page_member.php 放在页面模板里使用，配合 wp_users / wp_usermeta 的 VIP 字段；会员能力是主题功能，不是插件。

五、二次开发指引

• 改版式：改模板文件（index.php / single.php / archive.php 等）与 style.css；子主题方式更稳（建 child theme，把改动放子主题，升级主题不丢）；
• 加字段：在 pandastudio_framework/posttype_and_meta.json 加定义，模板用框架函数取值；
• 加区块：照 pandastudio_plugins/block_* 结构新增一个区块；
• 注意：主题文件在买家包里是加密壳（运行时由授权加载器解密），改主题请用商家提供的明文源码包，不要直接改服务器上的密文文件；wp-config.php 里不要随手开 DISALLOW_FILE_MODS 之外的限制，避免影响正常更新。

六、授权说明

主题带授权验证（绑定域名）：主题目录内的加密文件在运行时校验授权，未授权时后台主题设置页/前台会受限。授权码写在站点根目录 xj_auth.php（或主题包内提示的位置），换域名需重新绑定；主题包内提供 xj_panel.php（维护页）时可在站点根访问「验证授权 / 在线更新」。