插件开发手册

插件用于扩展核心能力，例如登录方式、支付通道、短信通道、对象存储、SEO 工具、站点备份、迁移助手和活动玩法。插件必须可以安装、启用、禁用和卸载。

适合做插件的能力

• 第三方服务接入，例如短信、支付、OAuth、云存储。
• 独立后台菜单和配置页。
• 新字段类型、新模板标签、新会员菜单。
• 需要独立数据表、事件监听、计划任务或公开回调的能力。
• 可选增强能力，禁用后不影响核心 CMS 基础运行。

不适合做插件：

• 内容、栏目、字段、模板、会员、权限等核心主流程。
• 一方业务主域，例如官方订单、支付、文档。
• 需要长期写入核心控制器才能工作的能力。

目录结构

plugins/{code}/
├─ plugin.json
├─ src/
│  ├─ {Name}ServiceProvider.php
│  └─ Http/Controllers/
├─ routes/
│  ├─ web.php
│  ├─ admin.php
│  └─ api.php
├─ database/migrations/
├─ resources/views/
├─ resources/assets/
└─ resources/lang/zh_CN/

插件资源发布到：

public/assets/plugins/{code}/

插件主题覆盖放到：

themes/{theme}/plugins/{code}/

plugin.json

plugin.json 应声明：

• 插件代码、名称、版本。
• ServiceProvider。
• 兼容 TanzCMS 版本。
• 需要的数据表、权限、菜单。
• 模板标签声明。
• 公开回调声明。
• 高风险能力说明。

插件代码一旦发布，不应随意变更，否则会影响资源路径、配置键、表名和市场升级。

生命周期

插件至少要考虑：

阶段	要求
安装	校验版本、依赖、迁移和资源发布
启用	注册菜单、路由、标签、事件和任务
禁用	停止路由、标签、任务和菜单入口
升级	执行迁移、刷新资源和兼容检查
卸载	提示数据保留或删除策略，记录日志

插件卸载删除数据属于高风险操作，应有二次确认和审计日志。

后台页面

插件后台页面应复用 TanzCMS 后台通用组件：

• 列表、搜索、分页、批量操作优先复用通用 CRUD。
• 弹窗、确认框、消息提示使用后台统一皮肤。
• CSS/JS 通过插件资源发布机制加载。
• 页面和接口都必须校验权限。

插件后台不应依赖 Layui 内部 DOM 或内部 class，后续后台渲染器升级时只应修改核心适配层。

前台页面和模板

插件前台页面可以使用插件自己的路由和模板，也可以提供模板标签让主题调用。

主题中引用插件页面：

<a href="{plugin_url code=flash_sale path='campaigns'}">活动列表</a>

引用插件资源：

<link rel="stylesheet" href="{plugin_asset code=flash_sale path='flash-sale.css' version=mtime}">

模板标签

插件可以实现 TemplateTagHandlerContract 并在 ServiceProvider 中注册：

app(TemplateTagRegistry::class)->register(app(FriendLinksTag::class));

插件还应在 plugin.json 中声明 template_tags，让标签生成器能展示示例和参数。

公开回调

插件公开回调统一走：

/api/callback/{plugin}/{action}/{payload?}

回调必须校验签名、处理重复通知、记录日志，并返回第三方平台要求的确认内容。

安全边界

• 不把密钥写入前端页面或公开模板。
• 不绕过系统上传服务保存文件。
• 不直接修改 .env。
• 不在核心中硬编码插件控制器或插件标签。
• 不让插件禁用后留下必须依赖的核心运行分支。