主题设置结构地图

为什么需要结构地图

inc/options/admin-options.php 超过一万行，商城和论坛还在独立 admin 文件里继续追加 section。只靠搜索字段标题，很容易把字段放错业务域。

子比主题设置页的结构规律是：

zibll_options
├─ 一级 section：业务域，只负责左侧菜单分组
└─ 子 section：具体设置页，真正包含 fields

新增或排查字段时先确定业务域，再确定子 section，最后查字段 id。

一级业务域

zib_csf_admin_options() 先注册这些一级 section：

这几个 id 也是子 section 的 parent 可选值。字段归类时不要按“文件方便”放置，而要按它实际影响的用户流程归类。

全局与功能

basic 是全站基础能力，字段大多会被前台高频读取。

这类字段前台读取一般用 _pz()。涉及 HTML 或脚本的字段要明确权限和输出过滤。

页面与显示

page 负责页面级结构，不直接处理文章内容本身。

页面显示类字段通常会影响模板选择、CSS class 或查询参数。保存后不一定需要特殊同步，但读取前要给默认值，避免未保存设置时页面空白。

文章与列表

post 负责内容列表和文章页行为。

文章页同时还会读取 post meta，例如独立 SEO、封面、付费内容、筛选项。全局设置用 _pz()，单篇字段用 zib_get_post_meta() 或对应业务函数。

用户与互动

user 是用户体系主入口，字段会牵动登录、资料、安全、通知和成长体系。

用户字段不要只改 meta。绑定邮箱、改密码、认证、封禁、积分、消息都应该走对应业务函数和 Ajax 流程，保证验证码、权限、日志和通知都一致。

支付与付费

pay 字段属于高风险业务域，不能当普通展示设置处理。

支付字段保存后要关注订单、回调、余额、积分、会员和缓存。涉及密钥的字段不要输出到前台，也不要进入低权限导出流程。

商城与论坛模块

商城和论坛的后台 section 不完全写在 admin-options.php：

这两个模块字段通常还有配套 post meta、taxonomy meta 和业务表单。全局开关在 zibll_options，单个商品、版块、帖子或分类的配置要看对应 Meta 文档。

扩展与增强

over 集中放站点增强能力：

这类字段常和第三方服务、缓存、请求频率有关。新增字段时要给清楚默认值，避免未配置时误请求外部服务。

定位字段的实际方法

查一个后台设置字段时建议按这个路径走：

1. 在文档结构地图确定业务域。
2. 在源码中搜索子 section 标题。
3. 找字段 id。
4. 全站搜索 _pz('字段id' 或 _pz("字段id"。
5. 如果搜索不到，继续搜字段 id 的纯文本，确认是否通过数组、模块或 JS 使用。
6. 判断保存后是否需要同步缓存、rewrite、用户数据、支付数据或任务队列。

示例：

想查“邮箱验证码登录”
→ user / 注册登录
→ 搜索字段标题或验证码相关 id
→ 查看登录 Ajax 与 action/sign_register.php
→ 确认 SMTP、验证码发送、验证校验和登录流程

这种方式比从整份 admin-options.php 里盲搜更稳定，也更贴近子比主题的真实组织方式。