xnx_custom_groups 自定义用户组示例

Xiuno BBS X 示例插件，演示如何通过插件创建自定义 gid 的用户组并注册插件权限项，作为开发者编写同类插件的参考实现。

功能特性

通过 install.php 创建 3 个自定义 gid 的用户组（gid=3、200、201）
通过 hook/admin_group_start.php 注册 2 个示例插件权限项
3 种语言资源（简中、繁中、英文）
卸载时安全清理：检测组内仍有用户时跳过删除，避免用户被孤立
幂等安装：重复安装时只更新基础字段，不覆盖管理员后期调整的权限

创建的用户组

| gid | 名称 | 用途 | 图标颜色 | 关键权限 | | ---- | ----------- | ------------ | --------- | --------------------------------- | | 3 | 副版主组 | 系统组空缺位 | #fd7e14 | 可置顶/编辑/移动，不可删帖/封禁 | | 200 | VIP 会员组 | 扩展区间 | #ffc107 | 基本发帖权限 | | 201 | 荣誉会员组 | 扩展区间 | #198754 | 基本发帖权限 |

> gid=3 占用系统组 install.sql 中预留的空缺位（命中 gid 1-5 管理权限区间）；gid=200/201 避开 101-105 的等级用户组。

注册的权限项

通过 PermissionService::register() 注册 2 个权限键：

| 权限键 | 显示名称（简中） | 分组 | | ----------------------------------- | ---------------- | ------ | | xnx_custom_groups_demo_access | 示例功能访问权 | plugin | | xnx_custom_groups_vip_feature | VIP 专属功能 | plugin |

注册后自动出现在后台 → 用户组编辑 → 插件权限分组中，所有用户组（包括本插件创建的 3 个组）都会显示对应的勾选框。

安装与卸载

在后台 → 插件管理中安装/卸载，无需手动操作。

安装

调用 group_create() 创建 3 个用户组
group_create() 内部自动调用 forum_access_padding($gid, TRUE)，使新组自动出现在所有版块的权限矩阵中
调用 group_list_cache_delete() 清缓存
写入 kv: xnx_custom_groups_installed 安装标记

卸载

遍历 3 个 gid，逐个安全检查
若组内仍有用户（db_count('user', ['gid' => $gid]) > 0），写入日志并跳过删除
空组调用 group_delete() 删除，内部自动清理 bbs_forum_access 关联
清理 kv: xnx_custom_groups_installed

自动继承的系统功能（无需额外代码）

本插件创建的用户组会自动出现在以下位置：

版块编辑页权限矩阵：group_create() 调用 forum_access_padding() 自动填充 bbs_forum_access 表
用户组列表与编辑页：$grouplist 读取 bbs_group 表所有组
其他插件的权限设置：group_update.htm 遍历 PermissionService::getAllRegisteredKeys()，所有已注册的插件权限项都会显示在本插件创建的组的编辑页中

使用示例

权限检查（PHP）

if (!PermissionService::check('xnx_custom_groups_vip_feature', $uid)) {
    message(-1, '权限不足');
}
// 管理员组（gid=1,2）自动返回 true，无需特殊处理

将用户加入自定义组（PHP）

user_update($uid, array('gid' => 200));  // 设为 VIP 会员组

技术实现要点

gid 选择：避开 0/1/2/4/5/6/7（系统组）、101-105（等级组），使用预留空缺 3 和扩展区间 200/201
幂等安装：已存在的组只 group_update 基础字段，不覆盖管理员后期调整的权限
运行时权限注册：PermissionService::register() 是静态注册（重启即丢失），通过 hook/admin_group_start.php 在每次进入后台用户组管理页时重新注册
卸载安全：检测组内用户数，非空时跳过删除并写日志
多语言 hook：3 个 lang_*_bbs.php hook 注册语言键，自动合并到全局 $lang 数组

文件结构

xnx_custom_groups/
├── conf.json                       # 插件配置
├── icon.png                        # 插件图标
├── install.php                     # 安装脚本（创建用户组）
├── uninstall.php                   # 卸载脚本（安全删除用户组）
└── hook/
    ├── admin_group_start.php       # 注册插件权限项
    ├── lang_zh_cn_bbs.php          # 简体中文语言包
    ├── lang_zh_tw_bbs.php          # 繁体中文语言包
    └── lang_en_us_bbs.php          # 英文语言包

版本信息

插件版本：1.0.0
兼容核心版本：Xiuno BBS X 1.1
作者：twelve

自定义用户组示例