04b 插件对接 API（完整）

本文是插件与可得财务对接的 HTTP / 驱动 / 魔方兼容 全量说明。
开发流程见 04 · 04a；钩子见 11；支付/实名/通知细节见 06–08。
源码冲突时以 kede-finance/ 为准。

0. 先看这一页（逻辑总览）

                    ┌─────────────────────────────┐
                    │  插件磁盘 public/plugins/…   │
                    └──────────────┬──────────────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
  本地管理 API              类型驱动对接                 自定义业务 API
  /admin/addon/*            gateway / sms /            route.php
  /admin/marketplace/*      mail / certification       + app 控制器
         │                         │                         │
         ▼                         ▼                         ▼
  安装·启停·配置·菜单页      系统选驱动后调接口          前台/后台 REST
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
             可得标准回调                    魔方兼容路由
             /api/notify/*                  /gateway/* · /console/module/*

你要做的事	读哪一节
后台装插件、改配置、开侧栏页	§2 本地管理 · §3 市场 · §4 宿主 UI
写支付 / 短信 / 邮件 / 实名驱动	§6–§8
给插件加自己的 REST	§5 自定义路由 · §5.2 范例
兼容魔方网关/模块 URL	§9
只挂业务钩子、无 HTTP	§10 · 11-hooks

1. 总则

1.1 URL 形态

ThinkPHP 多应用约定路由（url_route_must = false）：

/{app}/{Controller}/{action}

前缀	用途
`/admin/...`	后台（需管理员 Bearer）
`/home/...`	前台 / 会员
`/api/...`	公开回调、状态查询等
`/gateway/...`	魔方支付兼容（全局路由）
`/console/module/...` · `/admin/module/...`	魔方 server 模块兼容

另有少量全局路由：/ping、/setup/...、/license/...（见 12-api）。

1.2 统一 JSON

ApiResponse：

json

{
  "status": 200,
  "msg": "ok",
  "data": { }
}

`status`	含义
`200`	成功
`400`	参数/业务错误（常见 `msg`）
`401`	未登录 / Token 无效
`403`	无权限
`404`	资源不存在（插件未启用、无页面等）
`429`	限流（部分回调）
`502`	安装/下游失败等

例外：支付异步回调、魔方 /gateway/... 成功应答经常是 纯文本/HTML（如 success），不是 JSON。

1.3 鉴权与权限

接口族	鉴权
`/admin/addon/` · `/admin/marketplace/` · `/admin/gateway/` · `/admin/notify/`	Header `Authorization: Bearer {admin_token}`
`/home/invoice/` · `/home/auth/realname` · 插件会员接口	会员 Bearer（中间件要求处）
`/home/content/siteConfig` · `/api/notify/` · `/gateway/`	公开（回调自行验签）

后台权限模块键：plugin（控制器 Addon / Marketplace / 示例 FeedbackSurvey 均映射到此）。

1.4 插件类型与驱动键

PluginService::TYPES：

addon · gateway · server · reserver · oauth · sms · mail · certification · captcha

业务里引用已安装插件驱动时，键一般为：

plugin:{目录名}

例：plugin:payjs、plugin:tencent_face。短信/邮件列表里也可能直接显示驱动 name()（魔方短信桥接常用目录名）。

2. 本地插件管理 API

控制器：app/admin/controller/Addon.php
权限：plugin

2.1 一览

方法	路径	作用
GET	`/admin/addon/index`	扫描列表
POST	`/admin/addon/install`	安装并启用
POST	`/admin/addon/uninstall`	卸载（删库登记，文件保留）
POST	`/admin/addon/enable`	启用
POST	`/admin/addon/disable`	停用
GET	`/admin/addon/config`	读配置 + 字段定义
POST	`/admin/addon/saveConfig`	写配置
GET	`/admin/addon/menus`	侧栏注入菜单
GET	`/admin/addon/page`	宿主页 HTML

2.2 列表 `GET /admin/addon/index`

参数	说明
`type`	`addon`（默认）或其它 TYPES；`all` = 全部类型

data：

json

{
  "types": ["all", "addon", "gateway", "..."],
  "list": [
    {
      "type": "addon",
      "name": "hello_world",
      "title": "Hello 示例插件",
      "description": "...",
      "author": "...",
      "version": "1.0.0",
      "zjmf": false,
      "installed": true,
      "status": 1,
      "has_config": true,
      "has_hooks": true,
      "load_error": "",
      "server_heavy": false
    }
  ]
}

2.3 安装 / 卸载 / 启停

公共参数：type（必填语义）、name（目录名，仅 [a-zA-Z0-9_-]）。

接口	成功 `msg`	失败
`POST .../install`	已安装并启用	`502` + 原因（`install()` 失败等）
`POST .../uninstall`	已卸载	`502`
`POST .../enable`	已启用	`400` 等
`POST .../disable`	已停用	`400` 等

Body 可用 form / JSON；与 query 等价，以 ThinkPHP param 为准。

2.4 配置

读 GET /admin/addon/config?type=&name=

data = 配置键值并附带：

字段	含义
`_values`	纯配置字典（推荐前端读这个）
`_fields`	`configFields()` / Magfang 字段定义，供表单渲染

写 POST /admin/addon/saveConfig

参数	说明
`type`, `name`	插件定位
`config`	必须是 array；勿传 `_values`/`_fields`（服务端会剔除）

成功：msg = 已保存。

配置来源：config.php 默认值 ∪ kd_addons.config 覆盖；运行时用 Plugin::getConfig()。

3. 插件市场 API

控制器：app/admin/controller/Marketplace.php
权限：plugin

方法	路径	参数	说明
GET	`/admin/marketplace/index`	`type?` `keyword?` `page` `per_page`(≤50)	目录列表
GET	`/admin/marketplace/detail`	`type` `name`	详情 + 本地状态
POST	`/admin/marketplace/fetch`	`type` `name`	仅下载到磁盘
POST	`/admin/marketplace/install`	`type` `name`	下载 + `install()`
POST	`/admin/marketplace/upgrade`	`type` `name`	覆盖升级
POST	`/admin/marketplace/sync`	—	重扫本地，`data.local_count`

index data 要点：list · total · page · per_page · types · categories · server · source。

detail 额外字段：on_disk · installed · enabled · local_version。

远程市场（开发环境，.env MARKETPLACE_SERVER）：

GET {MARKETPLACE_SERVER}/api/marketplace/catalog?slug=kede-finance
GET {MARKETPLACE_SERVER}/api/marketplace/download?type=&name=&slug=kede-finance

生产推荐 压缩包 → 本地插件安装，见 05-marketplace。

4. 宿主 UI：菜单与页面

4.1 菜单 `GET /admin/addon/menus`

data.list[]：

字段	说明
`key`	建议 `plugin:{addon}` 或 `plugin:{addon}/{view}`
`title`	侧栏标题
`addon`	目录名
`type`	通常 `addon`
`icon`	图标名（前端映射）
`sort`	排序
`permission`	多为 `plugin`

来源：

各启用插件的 admin_menu.php
钩子 AdminMenu / admin_menu

4.2 页面 `GET /admin/addon/page`

参数	说明
`name` 或 `addon`	目录名；兼容 `addon/view`
`view`	子页；对应 `admin/page_{view}.php`，空则 `admin/page.php`

data：{ title, html, addon, type, view }

前端宿主：PluginHost.vue（路由 plugin-page/:addon）。

插件侧声明示例（admin_menu.php）：

php

return [[
    'key'        => 'plugin:sidebar_demo',
    'title'      => '测试模块',
    'addon'      => 'sidebar_demo',
    'icon'       => 'experiment',
    'sort'       => 85,
    'permission' => 'plugin',
]];

5. 自定义路由与控制器

5.1 `route.php` 何时加载

PluginService::boot()（AppInit → PluginBoot）：

条件	行为
`kd_addons.status=1` 且完整性校验通过	`include hooks.php` + `include route.php`
类型 `server` / `reserver`	有目录即尝试加载 hooks/route（不强制 DB 登记）

在 route.php 内可用 think\facade\Route。注意：多应用下 pathinfo 往往不含 home/admin 前缀，只写 feedback_survey/schema 这类片段时要清楚当前应用上下文。

5.2 推荐模式：应用控制器（稳定）

把控制器放到：

app/home/controller/{Name}.php   → /home/{name}/{action}
app/admin/controller/{Name}.php  → /admin/{name}/{action}

插件目录可保留 stubs/ 说明如何同步；业务实现可委托插件内 HttpApi 类。

务必：在 AdminPermissionService（或既有映射）为后台控制器挂上 plugin 权限，避免 403。

5.3 范例：feedback_survey

侧	方法	路径	说明
前台	GET	`/home/feedback_survey/schema`	问卷结构
前台	POST	`/home/feedback_survey/submit`	提交，`answers` 数组
后台	GET	`/admin/feedback_survey/bundle`	管理包数据
后台	POST	`/admin/feedback_survey/saveSurvey`	保存问卷
后台	POST	`/admin/feedback_survey/saveQuestion`	保存题目
后台	POST	`/admin/feedback_survey/deleteQuestion`	删题
后台	POST	`/admin/feedback_survey/reorder`	排序
后台	GET	`/admin/feedback_survey/leaderboard`	排行，`limit?`
后台	GET	`/admin/feedback_survey/answers`	答卷列表，`page`/`page_size`

实现：app/{home|admin}/controller/FeedbackSurvey.php + public/plugins/addon/feedback_survey/{HttpApi,route.php}。
插件未启用时返回 JSON 404。

6. Gateway 支付对接

6.1 契约

目录：public/plugins/gateway/{name}/
基类：GatewayPlugin + GatewayInterface
驱动键：plugin:{name}
后台网关表：/admin/gateway/*（创建时选 driver）

必实现：name() · title() · configFields() · pay() · notify() · notifySuccessResponse()。

6.2 系统拼好的回调 URL

PaymentService::callbackUrls（逻辑名）：

键	URL
`notify`	`{system_url}/api/notify/callback?gateway={网关name}`
`return`	`{system_url}/api/notify/sync?gateway={网关name}&invoice={账单号}`
`zjmf_notify`	`{system_url}/gateway/{plugin}/index/notifyHandle`

其中 gateway 查询参数是 支付网关实例 name（kd_payment_gateways.name），不是插件目录名。

6.3 前台消费

方法	路径	说明
GET	`/home/invoice/methods`	可用支付方式（含 plugin 网关）
POST	`/home/invoice/pay`	`id`/`gateway`/`pay_type?` → `{ type, payload, extra }`（`redirect`\|`qrcode`\|`html`）
GET	`/home/invoice/status` 等	账单状态（以控制器为准）

6.4 标准回调（可得）

方法	路径	响应
GET\|POST	`/api/notify/callback?gateway=`	多为 HTML/文本（驱动成功应答）
GET\|POST	`/api/notify/sync?gateway=&invoice=`	跳转前台支付结果页
GET	`/api/notify/status?invoice=`	JSON 状态

6.5 魔方网关控制器

见 §9.1。魔方控制器验签后可调全局函数 order_pay_handle($param) 入账。

7. SMS / Mail 通知对接

7.1 契约

类型	目录	接口
sms	`public/plugins/sms/{name}/`	`SmsPlugin` + `SmsDriverInterface::send`
mail	`public/plugins/mail/{name}/`	`MailPlugin` + `MailDriverInterface::send`

也可放 extend/notify/sms|mail/（非插件市场形态）。

魔方短信：保留 sendCnSms 等时由 ZjmfSmsDriverBridge 桥接；驱动名常用目录名。

7.2 后台选择与测试

方法	路径	说明
GET	`/admin/notify/index`	`{ mail:{drivers,config}, sms:{drivers,config} }`
POST	`/admin/notify/save`	`{ type: "mail"\|"sms", data: { driver, … } }`
POST	`/admin/notify/testMail`	`{ to }`
POST	`/admin/notify/testSms`	`{ phone }`

配置也可走 /admin/setting/group · saveGroup（group=mail|sms）。

业务侧发送：NotifyService::sendMail / sendSms（服务层，非独立公开 REST）。插件装好并启用后，会出现在 drivers 列表供选择。

8. Certification 实名对接

8.1 契约

目录：public/plugins/certification/{name}/
基类：CertificationPlugin + RealnameProviderInterface
驱动键：plugin:{name}（内置芝麻为 zhima）

方法：initVerify · queryStatus · configFields 等（见 07）。

插件密钥走 Addon 配置（/admin/addon/config）；全局开关/选用驱动走实名设置。

8.2 后台设置

方法	路径	说明
GET	`/admin/setting/realname`	当前实名配置
POST	`/admin/setting/saveRealname`	`provider` · `required` · `min_age` + 内置密钥字段

8.3 前台与回调（正确路径）

方法	路径	说明
POST	`/home/auth/realname`	body: `real_name` · `id_card` · `return_url?`
GET	`/home/auth/realnameQuery`	`biz_no`
GET\|POST	`/api/notify/realname`	第三方回调；参数含 `BizToken`/`biz_token`/`biz_no` · `uid` · `return?` → 跳转前台
GET	`/home/content/siteConfig`	`data.realname` 公开设置

旧文档中的 /home/realname/submit|query 不存在，请以本节为准。

9. 魔方 / ZJMF 兼容路由

定义于 route/app.php。

9.1 支付 `/gateway/...`

GET|POST /gateway/{_plugin}
GET|POST /gateway/{_plugin}/{_controller}/{_action}

默认 controller=index，action=notifyHandle
分发到：gateway\{plugin}\controller\{Ctrl}Controller
实现：app/common/controller/GatewayDispatch.php
失败时可能回落到 PaymentService::handleNotify
成功应答多为 HTML success / fail

9.2 模块 `/console/module/...` · `/admin/module/...`

GET|POST /console/module/{module}/{controller}/{method}
GET|POST /admin/module/{module}/{controller}/{method}

读取 public/plugins/server/{module}/controller/{admin|home}/...
实现：ModuleDispatch（注意：路径命名对齐魔方习惯，admin/home 与方法名对应关系以源码为准）

server/reserver 插件的 route.php / hooks 在 boot 时更宽松（见 §5.1）。

9.3 PHP 入账助手

魔方支付控制器内验签成功后：

php

order_pay_handle($param); // app/common.php → InvoiceService::markPaidByNum

10. 钩子运行时（无独立 HTTP API）

插件不通过 REST 注册钩子，只在 hooks.php：

php

add_hook('after_user_register', function ($param) { /* ... */ }, 50);

助手	说明
`add_hook` / `run_hook` / `hook`	`app/common.php`
`HookService::trigger`	业务触发；CamelCase ↔ snake_case
表 `kd_hooks`	可选 DB 钩子

常用事件与魔方别名：11-hooks。

11. 前台「消费插件能力」速查

能力	接口
站点/主题/实名公开配置	`GET /home/content/siteConfig`
选支付方式并支付	`GET /home/invoice/methods` · `POST /home/invoice/pay`
发起/查询实名	`POST /home/auth/realname` · `GET /home/auth/realnameQuery`
支付结果轮询	`GET /api/notify/status?invoice=`
插件自有页面 API	见 §5（如 feedback_survey）

12. 对接检查清单

12.1 通用 addon

文件在 public/plugins/addon/{name}/，命名空间正确
POST /admin/addon/install → index 中 installed=true,status=1
有配置：config 可读、saveConfig 可写
有钩子：触发业务后副作用出现
有菜单：menus 含项，page 返回 html

12.2 类型驱动

类型	检查
gateway	后台创建网关 `driver=plugin:x` → 前台 pay → notify 入账
sms/mail	`/admin/notify/index` 可见 → save 选用 → test 成功
certification	saveRealname 选 `plugin:x` → 前台 realname 全流程

12.3 自定义 API

控制器或 route.php 已加载
未启用插件时返回明确 404
后台接口需 admin JWT + plugin 权限

13. 源码锚点

主题	路径
本地插件 API	`app/admin/controller/Addon.php`
市场	`app/admin/controller/Marketplace.php`
菜单/页	`app/common/service/PluginMenuService.php`
生命周期	`app/common/service/PluginService.php`
Boot	`app/listener/PluginBoot.php`
支付	`app/common/service/PaymentService.php` · `app/api/controller/Notify.php`
通知设置	`app/admin/controller/Notify.php` · `NotifyService.php`
实名	`app/home/controller/Auth.php` · `RealnameService.php`
魔方分发	`GatewayDispatch.php` · `ModuleDispatch.php` · `route/app.php`
自定义范例	`public/plugins/addon/feedback_survey/`

14. 相关文档

文档	内容
04 插件系统	类型、生命周期、最小示例
04a 教程	手把手 addon
05 市场	zip / 市场安装与打包
06 支付	网关开发细节
07 实名	Provider 接口细节
08 通知	短信邮件细节
11 钩子	事件表
12 API 总览	全站路由约定
00 Agent 手册	AI 开发入口

下一章：05-marketplace

04b 插件对接 API（完整） ​

0. 先看这一页（逻辑总览） ​

1. 总则 ​

1.1 URL 形态 ​

1.2 统一 JSON ​

1.3 鉴权与权限 ​

1.4 插件类型与驱动键 ​

2. 本地插件管理 API ​

2.1 一览 ​

2.2 列表 GET /admin/addon/index ​

2.3 安装 / 卸载 / 启停 ​

2.4 配置 ​

3. 插件市场 API ​

4. 宿主 UI：菜单与页面 ​

4.1 菜单 GET /admin/addon/menus ​

4.2 页面 GET /admin/addon/page ​

5. 自定义路由与控制器 ​

5.1 route.php 何时加载 ​

5.2 推荐模式：应用控制器（稳定） ​

5.3 范例：feedback_survey ​

6. Gateway 支付对接 ​

6.1 契约 ​

6.2 系统拼好的回调 URL ​

6.3 前台消费 ​

6.4 标准回调（可得） ​

6.5 魔方网关控制器 ​

7. SMS / Mail 通知对接 ​

7.1 契约 ​

7.2 后台选择与测试 ​

8. Certification 实名对接 ​

8.1 契约 ​

8.2 后台设置 ​

8.3 前台与回调（正确路径） ​

9. 魔方 / ZJMF 兼容路由 ​

9.1 支付 /gateway/... ​

9.2 模块 /console/module/... · /admin/module/... ​

9.3 PHP 入账助手 ​

10. 钩子运行时（无独立 HTTP API） ​

11. 前台「消费插件能力」速查 ​

12. 对接检查清单 ​

12.1 通用 addon ​

12.2 类型驱动 ​

12.3 自定义 API ​

13. 源码锚点 ​

14. 相关文档 ​