better-staridc-MNBT
1---
2title: 插件对接 API
3description: MNBT PHP 业务插件系统对接（AJAX、页面、注册函数、钩子、支付插件、自动鉴权）
4---
5
6# 插件对接 API
7
8## 5.1 插件 AJAX 调用规则
9
10**管理端：** `POST /admin/ajax.php`，`gn` 必须以 `p_` 开头（建议 `p_{slug}_xxx`）
11**用户端：** `POST /user/ajax.php`，`gn` 必须以 `p_` 开头（建议 `p_{slug}_xxx`）
12
13> 框架在分发核心 `gn` 前会优先调用 `mnbt_plugin_dispatch_ajax($scope, $egn)` 命中插件回调。
14
15**示例（domain_shop 插件）：**
16
17```http
18POST /admin/ajax.php
19gn=p_domain_addym&url=example.com&bt=1&jg=10&ymjs=介绍&kg=true&channel=pan&provider_id=0
20```
21
22```http
23POST /user/ajax.php
24gn=p_dns_record_list&type=A
25```
26
27## 5.2 插件页面 URL 规则
28
29| 端 | URL 模板 |
30|----|----------|
31| 管理端 | `/admin/plugin.php?p={slug}&page={page}` |
32| 用户端 | `/user/plugin.php?p={slug}&page={page}` |
33
34**示例：**
35
36- `/admin/plugin.php?p=domain_shop&page=products`
37- `/user/plugin.php?p=domain_shop&page=bind`
38
39## 5.3 插件注册函数
40
41> 全部定义在 `MPHX/plugin.php`，详见 `app_plugins/PLUGIN_DEV.md`
42
43### 基础注册
44
45| 函数 | 用途 |
46|------|------|
47| `mnbt_plugin_register($slug, $info)` | 注册插件基础信息 |
48| `mnbt_add_action($hook, $callback, $priority=10)` | 注册动作钩子 |
49| `mnbt_do_action($hook, ...$args)` | 触发动作 |
50| `mnbt_add_filter($hook, $callback, $priority=10)` | 注册过滤器 |
51| `mnbt_apply_filters($hook, $value, ...$args)` | 应用过滤器 |
52
53### 能力注册
54
55| 函数 | 用途 |
56|------|------|
57| `mnbt_register_ajax($scope, $gn, $callback, $auth=null)` | 注册 AJAX 接口（`scope`: `admin`/`user`） |
58| `mnbt_register_page($scope, $page, $file, $title)` | 注册插件页面 |
59| `mnbt_register_menu($scope, $menu)` | 注册菜单（支持 `children` 子菜单） |
60| `mnbt_register_widget($scope, $area, $callback)` | 注册小部件（仪表盘） |
61| `mnbt_register_settings_tab($scope, $tab)` | 注册设置页 Tab |
62| `mnbt_register_home($callback, $priority=10)` | 接管站点首页 `/` |
63| `mnbt_register_route($method, $path, $callback, $priority=10, $auth=null)` | 注册通用路由 |
64| `mnbt_register_page_override($scope, $view, $callback)` | 接管主题页面渲染 |
65| `mnbt_register_partial_override($scope, $view, $callback)` | 接管主题 partial |
66
67### 通用路由示例
68
69```php
70// 命名参数 {id}、尾斜杠可选
71mnbt_register_route('GET', '/api/items/{id}', function ($params, $ctx) {
72 return ['id' => $params['id']];
73}, 10, 'user');
74```
75
76### 配置存取
77
78| 函数 | 用途 |
79|------|------|
80| `mnbt_plugin_option_get($slug, $key, $default=null)` | 获取插件配置 |
81| `mnbt_plugin_option_set($slug, $key, $value)` | 设置插件配置 |
82| `mnbt_plugin_require_admin()` | 强制要求管理员（手动调用） |
83| `mnbt_plugin_require_user()` | 强制要求用户（手动调用） |
84
85### HTTP 工具
86
87| 函数 | 用途 |
88|------|------|
89| `mnbt_http_get($url, $headers=[])` | GET 请求（默认禁内网） |
90| `mnbt_http_post($url, $data, $headers=[])` | POST 请求（默认禁内网） |
91
92## 5.4 钩子（Hooks）一览
93
94| 钩子名 | 触发位置 | 参数 |
95|--------|----------|------|
96| `boot` | 系统启动完成 | 无 |
97| `host.created` | 主机开通后 | `$user`、`$zjid`、`$bh` |
98| `host.paused` | 主机暂停 | `$user`、`$zjid` |
99| `host.unpaused` | 主机解除暂停 | `$user`、`$zjid` |
100| `host.renewed` | 主机续费 | `$user`、`$zjid`、`$new_date` |
101| `host.deleted` | 主机删除 | `$user`、`$zjid` |
102| `order.paid` | 订单支付成功 | `$order` |
103| `cron` | 计划任务触发 | 无 |
104| `menu.admin` | 管理端菜单构建 | `&$menu` |
105| `menu.user` | 用户端菜单构建 | `&$menu` |
106| `dashboard.admin.widgets` | 管理端仪表盘小部件 | `&$widgets` |
107| `dashboard.user.widgets` | 用户端仪表盘小部件 | `&$widgets` |
108| `settings.admin.tabs` | 管理端设置页 Tab | `&$tabs` |
109
110**示例：监听主机开通钩子自动建 DNS 记录**
111
112```php
113mnbt_add_action('host.created', function ($user, $zjid, $bh) {
114 // 自动为新主机创建 A 记录
115 domain_shop_auto_create_dns($user, $bh);
116}, 10);
117```
118
119## 5.5 支付插件 API
120
121| 函数 | 用途 |
122|------|------|
123| `mnbt_register_payment($slug, $info)` | 注册支付插件 |
124| `mnbt_get_payment_plugins()` | 获取所有已注册支付插件 |
125| `mnbt_get_enabled_payment_methods()` | 获取已启用的支付方式 |
126| `mnbt_save_payment_methods($methods)` | 保存支付方式配置 |
127| `mnbt_pay_type($slug, $method)` | 构造支付方式 type 字符串 |
128| `mnbt_pay_parse_type($type)` | 解析支付方式 type |
129| `mnbt_pay_dispatch_gateway($order, $type)` | 分发到支付插件 build 回调 |
130| `mnbt_pay_settle_order($order, $gateway_slug, $extra=[])` | **支付结算核心**（更新订单状态 + 触发 `order.paid` 钩子） |
131| `mnbt_pay_log($content, $level='info')` | 支付日志记录 |
132
133**支付回调路由约定：**
134
135| URL | 类型 | 说明 |
136|-----|------|------|
137| `/pay/{slug}/notify` | 异步通知 | 支付网关服务器回调 |
138| `/pay/{slug}/return` | 同步返回 | 用户支付完成跳转 |
139
140**支付插件注册示例（epay）：**
141
142```php
143mnbt_register_payment('epay', [
144 'name' => '易支付',
145 'methods' => ['alipay' => '支付宝', 'wxpay' => '微信', 'qqpay' => 'QQ'],
146 'build' => function ($order, $method) { /* 跳转支付 */ },
147 'notify' => function () { /* 验签 + mnbt_pay_settle_order */ },
148 'return' => function () { /* 同步跳转 */ },
149]);
150```
151
152**支付流程时序：**
153
154```
155用户下单 → mnbt_pay_dispatch_gateway → epay.build() → 跳转易支付
156 ↓
157用户支付完成 → /pay/epay/notify → epay.notify() → mnbt_pay_settle_order()
158 ↓
159mnbt_pay_settle_order() → 更新 MN_dd → 触发 order.paid 钩子 → 插件自动开通业务
160```
161
162## 5.6 自动鉴权机制
163
164V1.81+ 插件系统支持通过 `auth` 参数声明权限要求，框架自动验证。
165
166### `auth` 取值
167
168| 值 | 含义 | 失败响应 |
169|----|------|----------|
170| `null` / `''` / `'none'` | 无验证（默认） | — |
171| `'admin'` | 需要管理员登录 | `{"code":"请登陆后台"}` |
172| `'user'` | 需要用户登录 | `{"code":"请登陆"}` |
173| 回调函数 | 自定义验证，返回 `true`/`false` | 自动跳转登录或返回 `{"code":"请登陆"}` |
174
175### 路由自动鉴权
176
177```php
178mnbt_register_route('POST', '/api/admin/config', function ($params, $ctx) {
179 // 框架已自动验证管理员身份
180}, 10, 'admin');
181```
182
183### AJAX 自动鉴权
184
185```php
186mnbt_register_ajax('admin', 'my_plugin_save', function () {
187 // 框架已自动验证管理员
188}, 'admin');
189
190mnbt_register_ajax('user', 'my_plugin_get_data', function () {
191 // 框架已自动验证用户
192}, 'user');
193```
194
195### 核心函数
196
197| 函数 | 用途 |
198|------|------|
199| `mnbt_plugin_auth_check($auth)` | 验证鉴权（返回 bool） |
200| `mnbt_plugin_auth_fail($auth)` | 鉴权失败处理（自动 exit） |
201
202---
203
204**相关文档：**
205
206- [API 通用约定](./overview.md)
207- [后台管理接口](./admin.md) —— `plugin_*` 管理接口
208- [用户控制面板接口](./user.md) —— 插件 AJAX 分发
209- [核心工具函数](./functions.md)