开发指南

扩展点手册

扩展点（Hook）是 Tenraft 的一等公民：内核与应用在关键流程发布事件，插件订阅介入——二开不改源码，升级不冲突。本章讲机制与事件目录。

三种事件类型

类型	执行方式	用途
filter（同步过滤）	监听器按优先级链式执行，可修改载荷并返回，也可标记取消	支付方式列表过滤、下单前风控、通知内容改写、AI 输入审核
sync（同步阻塞）	内联执行，监听器抛异常可中止业务流程	升级前自检（不兼容直接拦下升级）
action（异步）	入 Redis 队列由消费进程执行；至少一次投递	发通知、统计、审计旁路

应用与插件在包内 server/hooks.php 返回「事件名 → 监听器列表」映射，安装时登记、卸载时自动回收：

server/hooks.php（商城应用实例）

<?php

return [

// 事件名 => [[监听器类, 优先级], ...]

'pay.paid' => [

[\apps\shop\hook\OrderPaidPrintListener::class, 100],

];

命名规范：域.对象.动作，全小写点分；载荷为类型化的载荷对象（filter 型返回修改后的载荷）。
开发环境用 php webman hook:list 查看全部事件与已注册监听器。
事件目录带稳定性标记：stable 事件主版本内保持兼容；experimental 事件的载荷形状可能调整，生产插件优先订阅 stable 事件。

事件	类型	说明
`tenant.created` / `tenant.disabled` / `tenant.removed`	action	租户生命周期
`site.created`（stable）/ `site.enabled` / `site.disabled` / `site.expired` / `site.deleted`	action	站点生命周期
`app.installed` / `app.upgraded` / `app.uninstalled` / `app.enabled` / `app.disabled`（stable）	action	应用部署级生命周期
`app.site.bound` / `app.site.unbound`（stable）	action	站点绑定 / 解绑应用
`addon.installed` / `addon.upgraded` / `addon.uninstalled` / `addon.enabled` / `addon.disabled` / `addon.site.enabled` / `addon.site.disabled`（stable）	action	插件生命周期与站点开关
`upgrade.before` / `upgrade.after`	sync	升级前后；before 抛异常可中止升级

事件	类型	说明
`member.registered` / `member.login`	action	注册与登录（含渠道信息）
`member.account.changed`	action	资产变动后：账户类型、方向、金额、来源

事件	类型	说明
`notice.send.before`	filter	可改写模板变量或拦截发送
`notice.sent`	action	发送完成（含结果）
`diy.page.published`	action	装修发布（home / member / custom 三种页面）
`form.submitted`	action	万能表单收到提交
`ai.input.filter`	filter	AI 输入审核，标记取消即拒发
`ai.message.completed`	action	AI 生成完成
`wxopen.authorized` / `wxopen.unauthorized` / `wxopen.released`	action	第三方平台授权变更与发布完成
`admin.login` / `admin.operation.after`	action	管理端审计旁路