开发指南
插件开发规范
插件是功能增强单元：支付通道、短信通道、商城秒杀都以插件形态存在。本章定义插件分类、包规范、依赖解析与注册物清单。
两类插件
| 类型 | 生效范围 | 示例 |
|---|---|---|
| 框架级插件 | 部署级启用后全部站点默认可用，站点可独立关闭 | 支付通道、短信通道、打印驱动、存储驱动、AI 驱动 |
| 应用级插件 | info.json 声明 parent_app；仅在已绑定父应用的站点生效；安装时校验父应用已装且启用 | 商城-秒杀扩展、预约-排队叫号 |
插件按部署买断，没有名额概念。包格式 .tzaddon 与应用包同构，后端命名空间 addon\{key}\，业务表前缀 {{prefix}}addon_{key}_，生命周期入口为 server/Addon.php：
install() / upgrade($from, $to) / uninstall(bool $keepData)
onSiteEnable(int $siteId) // 站点开启本插件
onSiteDisable(int $siteId) // 站点关闭本插件
{
"key": "shop_seckill_plus",
"type": "addon",
"name": "商城秒杀增强",
"version": "1.0.0",
"parent_app": "shop", // 应用级插件必填
"dependencies": { "sms_aliyun": ">=1.0" }, // 插件间 semver 依赖
"min_framework": ">=0.2.0"
}
- 安装时做依赖解析：父应用存在性、
dependencies约束满足、拓扑排序决定安装顺序。 - 卸载做反向依赖检查——有插件依赖它则禁止。
- 站点级开关：框架级插件在站点后台有独立开关；关闭后其贡献（搜索域、组件等）对该站点自动隐去。
注册物清单
插件对系统的一切挂载都走声明式注册：安装挂载、卸载回收、升级差量同步，零残留由注册台账兜底保证。全部注册物类型：
| 注册物 | 声明文件 | 说明 |
|---|---|---|
| 支付通道 | pay/ways.json | {key, name, class, config_fields}；卸载前校验无在途交易 |
| 通知通道 | notice/channels.json | 内置 sms / weapp_subscribe 两个桩允许被插件覆盖（站内信不可覆盖） |
| 功能开关 | features.json | 键必须以 {插件key}. 前缀，禁止抢占内核或他人键 |
| 菜单 / 权限点 | menu.json | 升级保持菜单 ID 稳定，角色授权不丢失 |
| 事件监听 | server/hooks.php | 见扩展点手册 |
| 定时任务 | server/schedules.php | 统一进定时任务调度与后台可视化 |
| 装修组件 | diy/components.json | schema 同时驱动编辑器、校验与渲染 |
| AI 驱动 | 对应声明文件 | 对话 / 生图 / 向量嵌入三类驱动 |
| 打印驱动 | print/drivers.json | 云打印机品牌驱动 |
| 搜索域 / 导出源 / 海报场景 / 待办 | 各自 JSON | 与应用同一套横向接入机制 |
| 管理端页面 | admin/routes.json | 免编译 ESM，见 Admin SDK |
范本：阿里云短信插件
内置的阿里云 / 腾讯云短信插件是通道类插件的标准范本，结构一目了然：
├── info.json # type: addon, key: sms_aliyun
├── notice/channels.json # 注册通道：覆盖内置 sms 桩
├── server/
│ ├── Addon.php # 卸载不保数据时清理站点密文配置
│ ├── channel/AliyunSmsChannel.php # 通道实现（发送/模板/回执）
│ ├── controller/ConfigController.php
│ └── route.php
└── admin/ # 站点配置页（ESM + routes.json）
C 端功能策略
- 1优先级 1 —— 装修组件：以「注册 DIY 组件 + 配置驱动」实现 C 端功能，渲染器内置，免出包即生效。
- 2优先级 2 —— 原生页面：页面并入父应用的 C 端工作区目录，需重新构建小程序并走发布流程后生效——安装完成页会明确提示。
打包与签名与应用一致：ext:pack 产出 .tzaddon（Ed25519 逐文件签名），生产环境验签不过不装。