【QKCMS 插件/工具开发规范】
注意 官方提供的插件文件名称不要随意修改

1. 文件命名与存放
扩展名：.php
存放目录：admin/Plugin/
文件名：ID_插件名.php（如 1_mp3box.php），禁止中文名称
ID：取现有最大ID+1，不可随意命名

2. 插件信息格式
使用PHP文档注释定义插件信息：

/
 * @id 1                    # 唯一数字ID
 * @name 插件名称            # 简洁明了，建议≤10字符
 * @version 1.0.0           # 语义化版本号
 * @description            # 清晰说明功能，建议≤28字符
 * @price 0                 # 免费填0
 * @type                   # 类型：工具或插件
* @frontend_callable true  # 是否可前台调用，默认false
 * @website http://www.qiken.com # 插件作者网站
 * @width 500               # 插件宽度 如300px
 * @height 400              # 插件高度  如30px
 * @thumbnail               # 插件图标，插件截图专用
 * @tpl                     # 自动插入前端模板（填写相对路径，如 templates/footer.html；默认插入到模板文件最后一行；不填写则安装时不自动插入）
 * @mp4 #云端插件视频教程字段
 */

2.1 插件系统类型机制
本插件系统分为两种类型：插件和工具。

- **默认行为**：插件可在前台和后台调用，工具仅能在后台操作。
- **白名单机制**：为满足复杂场景需求，系统提供白名单机制，允许特定工具在前台调用。

### 实现方法
在工具的PHPDoc注释中添加 `@frontend_callable true` 标识，即可将工具设置为可前台调用，例如：

```php
/**
 * @id 35
 * @name 网站运行时间
 * @type 工具
 * @frontend_callable true
 */
```

### 调用逻辑
工具/插件应包含以下调用逻辑，以区分前台和后台调用：

```php
// 检查调用来源
if (isset($_POST['plugin']) || isset($_GET['plugin'])) {
    // 后台调用：显示配置界面
    // 配置界面HTML代码
} else {
    // 前台调用：仅显示功能内容
    echo your_function($params);
}
```

3. 插件参数格式
【重要】必须使用以下格式包裹配置块：
1. 输入框参数 ：直接使用普通格式 如：参数名 = 默认值
2. 下拉框参数 ：使用 |select| 格式   如：参参数名 = 默认值|select|选项1,选项2,选项3

// 插件配置参数
$plugin_config = <<<EOT
[config_params]
参数名1 = 参数值1
参数名2 = 参数值2
参数名3 = false    # 插件开关：false或true
[/config_params]

[Plugin Instructions]
插件说明专用标记 插件的使用说明教程都可以写这个标记内 会以多行方式显示
[/Plugin Instructions]
EOT;


【注意事项】
必须使用HEREDOC语法包裹，否则会导致PHP语法错误
支持JSON数组等复杂配置
禁止直接写[config_params]标签


4. 前端交互函数

// 提示框
callParentToast('消息内容', { type: 'success/error/info/warning' });

// 确认框
callParentConfirm('确认消息').then(function(result) {
    if (result) { /* 确认操作 */ } else { /* 取消操作 */ }
});

5. 插件调用方式
在模板文件中使用：
{qk_Plugin:ID}
将 ID 替换为实际插件的数字ID。

6.1 自动插入模板（可选）
当插件需要在前台模板中自动注入调用标签时，可在插件PHPDoc中填写 `@tpl` 字段。

- 字段值：模板文件相对路径（例如：templates/footer.html）。
- 行为：安装完成后，系统可自动把 `{qk_Plugin:IDxx}` 插入到指定模板文件中。
- 说明：如需更精确到某个页面/某个位置，建议手动插入或后续扩展更细粒度的插入规则。

6. 开发注意事项
CSS样式：禁止使用 body、* 等全局标签样式
HTML输出：建议使用HEREDOC语法
AJAX处理：确保只在AJAX请求时执行，设置正确响应头
安全：禁止使用 eval()、exec() 等危险函数
兼容性：使用标准PHP函数，确保PHP 7.0+兼容

7. 常见问题
插件无法加载：检查语法错误，查看服务器日志
插件信息不显示：检查PHP文档注释格式
参数无法保存：检查[config_params]格式
AJAX失败：确保设置了正确的响应头

通过遵循以上规范，可开发出兼容、安全、稳定的QKCMS插件。
