🔌 UM 插件开发规范 v1.2

为什么需要插件

服装行业举例：

• UM 官方：服装模块（退货拦截、AI 上新、私域管家）
• 第三方插件：
  • 杭州丝绸商家：silk-cert-plugin（丝绸认证）
  • 广州牛仔商家：colorfast-plugin（色牢度检测）
  • 童装商家：kids-age-plugin（年龄段合规）
  • 汉服商家：original-protect-plugin（原创保护）

插件分类（6 大类）

插件开发：5 大原则

1. 单一职责：一个插件只解决一个问题
2. 标准 API：只能通过 UM 公开的 Hook/API 接入，不允许改主系统
3. 沙箱运行：插件代码在沙箱中执行，崩溃不影响主系统
4. 声明式：插件需声明权限、依赖、数据范围，用户可见可管
5. 版本化：所有插件必须支持版本管理，可升级可回滚

插件目录结构

um-plugins/
├── silk-cert-plugin/                    # 插件根目录
│   ├── plugin.json                      # 插件清单（必填）
│   ├── README.md                        # 文档
│   ├── LICENSE                          # 许可证
│   ├── src/                             # 源代码
│   │   ├── Plugin.php                   # 插件主类
│   │   ├── Hooks/                       # Hook 监听
│   │   ├── Api/                         # 暴露的 API
│   │   └── Admin/                       # 后台页面
│   ├── assets/                          # 前端资源
│   │   ├── icon.png                     # 插件图标
│   │   ├── screenshot-1.png             # 截图
│   │   └── admin.js
│   ├── views/                           # 后台模板
│   ├── migrations/                      # 数据库变更
│   ├── tests/                           # 测试用例
│   └── CHANGELOG.md                     # 变更日志

plugin.json 规范

{
    "name": "silk-cert-plugin",
    "title": "杭州丝绸认证",
    "version": "1.0.0",
    "description": "为丝绸商家提供权威认证标识和质检报告",
    "author": {
        "name": "杭州丝绸协会",
        "email": "support@hz-silk.cn",
        "url": "https://hz-silk.cn"
    },
    "license": "Commercial",
    "um": {
        "min_version": "1.2.0",
        "max_version": "2.x"
    },
    "category": "tool",
    "industries": ["clothing"],
    "permissions": [
        "user.read",
        "user.write",
        "order.read",
        "config.write"
    ],
    "hooks": [
        "user.login.after",
        "order.create.after",
        "admin.menu.render"
    ],
    "apis": [
        {
            "method": "GET",
            "path": "/api/silk-cert/check",
            "handler": "Api\\CheckController@check"
        }
    ],
    "admin_pages": [
        {
            "title": "丝绸认证",
            "path": "silk-cert/index",
            "icon": "🌸"
        }
    ],
    "pricing": {
        "model": "subscription",
        "price": 99,
        "currency": "CNY",
        "period": "month"
    }
}

插件主类（Plugin.php）

<?php
namespace Plugin\SilkCert;

use UM\Plugin\BasePlugin;

class Plugin extends BasePlugin
{
    /**
     * 插件安装
     */
    public function install(): bool
    {
        // 创建插件专用表
        $this->migration->run('create_cert_records_table');
        return true;
    }

    /**
     * 插件激活
     */
    public function activate(): bool
    {
        // 注册 Hook 监听
        $this->hooks->on('order.create.after', [$this, 'onOrderCreate']);
        return true;
    }

    /**
     * 插件停用
     */
    public function deactivate(): bool
    {
        $this->hooks->off('order.create.after', [$this, 'onOrderCreate']);
        return true;
    }

    /**
     * Hook 处理：订单创建后自动申请认证
     */
    public function onOrderCreate($order)
    {
        if ($this->isSilkProduct($order['sku'])) {
            $this->api->call('silk/cert/request', [
                'order_id' => $order['id'],
                'sku'      => $order['sku']
            ]);
        }
    }
}

UM 核心 Hook 清单（开放 30+）

完整 Hook 清单见 下方附录。

插件 API 调用

// 在插件代码中调用 UM 核心 API
$user = $this->api->user->get($userId);
$order = $this->api->order->create($data);
$this->api->ai->generate('text', [
    'prompt' => '写一段丝绸产品描述',
    'context' => ['brand' => '杭州丝绸']
]);
$this->api->notify->send($userId, '微信', $templateId, $data);

插件市场（UM Plugin Market）商业模式核心

市场机制

收入分润示例

某插件定价 ¥99/月
   商家购买：1000 商家 × ¥99 = ¥99000/月 GMV
   开发者收入：¥99000 × 70% = ¥69300/月
   UM 平台收入：¥99000 × 30% = ¥29700/月

1 个爆款插件，开发者月入 7w，年入 80w+
UM 平台月入 3w，规模化后（1w 插件）月入数百万

插件分级与认证

插件安全与权限

3 道防线

1. 声明式权限：插件必须声明所需权限，用户安装时确认
2. 沙箱执行：插件在受限 PHP 命名空间运行
3. 审计日志：所有插件操作记录到 um_plugin_audit 表

权限分级

插件开发快速上手

1. 安装开发脚手架

composer global require um/um-plugin-cli
um-plugin create my-plugin --template=basic
cd my-plugin

2. 编辑 plugin.json

{
    "name": "my-plugin",
    "title": "我的第一个插件",
    "version": "0.1.0",
    "category": "tool"
}

3. 实现主类

namespace Plugin\MyPlugin;
use UM\Plugin\BasePlugin;

class Plugin extends BasePlugin
{
    public function activate()
    {
        $this->hooks->on('user.login.after', function($user) {
            $this->logger->info("User logged in: " . $user['id']);
        });
    }
}

4. 本地测试

um-plugin test
um-plugin install --local

5. 打包发布

um-plugin pack
um-plugin publish --market

附录：完整 Hook 清单

用户域（6 个）

user.register.before      // 注册前，可拦截
user.register.after       // 注册后
user.login.before         // 登录前，可拦截
user.login.after          // 登录后
user.logout               // 登出
user.update.before        // 资料更新前
user.update.after         // 资料更新后
user.password.change      // 密码修改
user.delete               // 用户删除
user.tag.add              // 标签增加
user.tag.remove           // 标签移除
user.merge                // UMID 合并

订单域（8 个）

order.create.before       // 下单前
order.create.after        // 下单后
order.pay.before          // 支付前
order.pay.after           // 支付后
order.ship                // 发货
order.confirm             // 确认收货
order.refund.before       // 退款前
order.refund.after        // 退款后
order.cancel              // 取消订单
order.complete            // 订单完成

营销域（10 个）

marketing.coupon.issue
marketing.coupon.use
marketing.campaign.start
marketing.campaign.end
marketing.seckill.before
marketing.seckill.during
marketing.group.before
marketing.group.success
marketing.reward.give
marketing.points.change

AI 域（8 个）

ai.text.generate.before
ai.text.generate.after
ai.image.generate.before
ai.image.generate.after
ai.chat.message.in
ai.chat.message.out
ai.agent.run.before
ai.agent.run.after

系统域（10+ 个）

admin.menu.render
admin.page.render
api.request.before
api.request.after
api.response.before
api.response.after
cron.daily
cron.hourly
plugin.install
plugin.activate
plugin.deactivate
plugin.upgrade
plugin.uninstall

总计 50+ 开放 Hook，覆盖 UM 全业务流程。

插件生态飞轮

为什么"积木 + 插件"是终极壁垒

关键决策（已确认）