插件开发

一、插件架构

看店通采用事件驱动的插件架构，核心系统在关键流程节点触发钩子事件，插件通过监听这些事件实现功能扩展。这种设计把扩展点隔离在插件内，核心升级时不必改插件代码。

• 插件目录：plugins/ 目录下每个子目录为一个插件，目录名即插件标识
• 插件配置：manifest.json 定义插件名称、版本、作者、依赖、钩子等元信息
• 生命周期：安装、启用、禁用、卸载，每个阶段有对应回调
• 钩子机制：订单创建、支付成功、用户注册等数十个钩子点

二、常用钩子

钩子名	触发时机	可否修改参数
order.create.before	订单落库前	可以，常用于追加备注、改写收货信息
order.create.after	订单落库后	否，只读通知
order.pay.after	支付成功回调处理完成后	否，只读通知
order.refund.after	退款完成后	否，只读通知
user.register.after	用户注册成功后	否，常用于发放新人券
user.login.after	登录成功后	否，常用于同步 CRM 标签
product.update.after	商品信息变更后	否，常用于推送至 ERP

钩子分两类：before 类允许修改传入参数并可以中断流程（抛出业务异常即中断），after 类只做通知，返回值不影响主流程。两类钩子都是同步执行的，因此绝不能在里面做耗时操作——调用外部 HTTP 接口、发送短信、生成报表这类逻辑请投递到队列异步处理。一个在 order.pay.after 里同步调 ERP 的插件，足以在大促时把整个支付回调链路拖垮。

三、开发流程

1. 在 plugins/ 下创建插件目录，目录名即插件标识，使用小写字母与下划线。
2. 编写 manifest.json，声明名称、版本、作者、依赖的核心版本范围与要监听的钩子。
3. 实现插件主类，继承基类并实现对应的钩子方法与生命周期回调。
4. 在后台「插件管理」中启用，用测试数据跑通完整业务链路。
5. 补充卸载逻辑：清理自建表、删除配置、注销定时任务，不要留垃圾数据。
6. 打包发布，生成可安装的插件包并附上版本说明。

四、插件目录结构

标准插件目录包含 Plugin.php（主类）、manifest.json（元信息与钩子声明）、config.json（可配置项定义）、views/（后台视图）、assets/（静态资源）、migrations/（数据库变更脚本）。

插件可以建自己的数据库表，但表名必须加插件标识前缀，例如 plugin_erpsync_task。不要直接修改核心表结构，核心升级时你的改动会被覆盖；确实需要扩展字段时请用独立的扩展表加外键关联。所有表变更都写进 migrations/ 并支持回滚，这样启用与卸载才能做到干净。

五、开发注意事项

命名上要避免与核心类冲突，插件的类统一放在以插件标识命名的命名空间下。数据库操作使用框架提供的 ORM 并显式管理事务，尤其是涉及库存扣减与金额变动时，要把相关操作包在同一个事务里，避免出现「扣了库存没生成订单」这类中间态。

异常处理是插件最容易出问题的地方。原则是：after 类钩子中的异常必须被插件自己捕获并记日志，不能让它冒泡中断主流程——用户不该因为某个统计插件报错而支付失败；before 类钩子中则应该主动抛出带明确文案的业务异常，让用户知道为什么下不了单。涉及金额的逻辑一律记操作日志，包含操作前后的值与触发来源，出问题时这是唯一能还原现场的东西。

发布前请至少做三项测试：与核心功能的兼容性（关掉插件后系统仍正常）、与其他常用插件的共存（多个插件监听同一钩子时的执行顺序）、以及卸载后的清理是否彻底。

六、插件市场

看店通提供插件市场，开发者可将插件上架供其他商户使用并获得收益分成。上架需通过审核，审核重点是三项：功能与描述是否一致、是否存在安全风险（越权读取商户数据、外传用户信息、内置后门）、以及卸载后是否留有残留。

热门插件类型包括 ERP 与 WMS 对接、CRM 与企业微信集成、营销玩法扩展、数据分析与报表、发票与电子面单。上架时请提供清晰的配置说明与常见问题，这部分内容的质量直接影响商户的安装留存率——很多插件不是功能不好，而是商户配不明白就卸载了。

七、延伸阅读

如果你的需求只是与外部系统交换数据，不一定要写插件，直接用API 接口文档中的开放接口配合事件回调 Webhook通常更简单、升级也更省心；前端定制见小程序定制。