开发说明

本页面详细介绍MISEB系统的二次开发方式和技术架构。

系统架构

┌─────────────────────────────────────────────────────────┐
│                      前端应用层                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │ 平台端  │  │ 商户端  │  │  H5端   │  │ 小程序  │   │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘   │
└───────┼────────────┼────────────┼────────────┼─────────┘
        │            │            │            │
        └────────────┴─────┬──────┴────────────┘
                           │
┌──────────────────────────┴──────────────────────────────┐
│                      API网关层                           │
│  ┌─────────────────────────────────────────────────┐   │
│  │              Nginx / API Gateway                 │   │
│  └─────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        │                                      │
┌───────┴───────┐                    ┌────────┴────────┐
│   MISEB Core  │                    │   Magic-API     │
│   (闭源核心)   │ ──── 事件推送 ───→ │  (二次开发层)    │
│               │                    │                 │
└───────────────┘                    └─────────────────┘
        │                                      │
        └──────────────────┬───────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────┐
│                      数据存储层                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │  MySQL  │  │  Redis  │  │  MinIO  │  │   ES    │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
└─────────────────────────────────────────────────────────┘

开发方式对比

特性	Magic-API	事件推送
开发难度	低	中
实时性	同步	异步
适用场景	新增接口、数据查询	业务流程扩展
技术要求	JavaScript/Groovy	任意语言
部署方式	系统内置	独立服务

Magic-API开发

工作原理

客户端请求 → Magic-API → 脚本执行 → 数据库/缓存 → 返回结果

能力范围

可以做：

• 新增自定义API接口
• 查询和操作数据库
• 调用Redis缓存
• HTTP请求第三方接口
• 数据格式转换
• 业务逻辑编排

不能做：

• 修改核心业务逻辑
• 修改现有接口行为
• 直接访问系统内部类

接口示例

// 获取商户销售排行
var sql = """
    SELECT m.name, SUM(o.pay_price) as total_sales
    FROM eb_merchant m
    LEFT JOIN eb_store_order o ON m.id = o.mer_id
    WHERE o.paid = 1 AND o.status >= 0
    GROUP BY m.id
    ORDER BY total_sales DESC
    LIMIT 10
""";

return db.select(sql);

事件推送开发

工作原理

系统业务操作 → 生成事件 → 推送到回调地址 → 外部系统处理

事件流程

1. 事件产生：系统在关键业务节点产生事件
2. 事件序列化：将事件数据序列化为JSON
3. 签名生成：使用密钥对数据签名
4. HTTP推送：POST请求推送到配置的地址
5. 重试机制：失败后自动重试

推送数据格式

{
  "event_type": "order.paid",
  "event_id": "evt_20240101120000_xxxxx",
  "timestamp": 1704067200,
  "data": {
    "order_no": "202401010001",
    "pay_price": 9900,
    "pay_type": "wechat"
  },
  "signature": "xxxxx"
}

回调响应

{
  "code": 0,
  "message": "success"
}

事件 + Magic-API

将事件推送的回调地址设置为Magic-API开发的接口，实现完整的二次开发：

示例：订单同步到ERP

1. 创建Magic-API接口

// 接口地址: /api/custom/erp/order/sync
// 方法: POST

// 验证签名
var sign = header.sign;
var timestamp = header.timestamp;
// ... 签名验证逻辑

// 获取订单数据
var orderData = body.data;

// 同步到ERP系统
var erpResult = http.post('https://erp.company.com/api/order/create', {
    headers: { 'Authorization': 'Bearer xxx' },
    body: orderData
});

return { code: 0, message: 'success' };

2. 配置事件推送

将订单创建事件的回调地址设置为：

https://your-domain.com/api/custom/erp/order/sync

安全建议

签名验证

所有事件推送都应验证签名：

import md5 from 'md5';

var sign = header.sign;
var timestamp = header.timestamp;
var secret = 'your_secret_key';

var expectedSign = md5(body + timestamp + secret);

if (sign !== expectedSign) {
    return { code: 401, message: '签名验证失败' };
}

幂等处理

事件可能重复推送，需要做幂等处理：

var eventId = body.event_id;

// 检查是否已处理
var exists = db.selectInt('SELECT COUNT(*) FROM event_log WHERE event_id = ?', eventId);

if (exists > 0) {
    return { code: 0, message: '已处理' };
}

// 处理业务逻辑...

// 记录事件
db.insert('INSERT INTO event_log (event_id, created_at) VALUES (?, NOW())', eventId);

下一步

• Magic-API简介 - 了解Magic-API
• 事件推送概述 - 了解事件推送