vr-shopxo-plugin/docs/09_SHOPXO_HOOKS_REFERENCE.md

384 lines
16 KiB
Markdown
Raw Permalink Normal View History

# ShopXO 钩子完整清单v6.8.0
> 从源码提取:`app/service/*.php`, `app/index/controller/*.php`, `app/admin/controller/*.php`
> 提取时间2026-04-15
> 提取方式:`grep "hook_name = \|'plugins_" /var/www/html/app/**/*.php`
---
## 一、订单支付 — 票务插件最关键
来源:`app/service/OrderService.php`
| 钩子名称 | 触发时机 | 参数关键字段 | 票务用途 |
|---------|---------|-----------|---------|
| `plugins_service_order_pay_launch_begin` | 发起支付前 | `business_ids`, `business_data`, `payment`, `params` | 支付前预处理 |
| `plugins_service_order_pay_launch_handle` | 支付方式处理 | 同上 | 扩展支付方式 |
| `plugins_service_order_pay_notify_handle` | 支付回调通知 | `business_ids`, `business_data` | **★ 支付成功,最佳入场点** |
| `plugins_service_order_pay_handle_begin` | 支付成功后开始 | `business_data`, `payment` | 支付成功业务处理开始 |
| `plugins_service_order_pay_success_handle_end` | 支付成功处理结束 | `business_data` | **★ 支付完全成功,生成票务记录** |
| `plugins_service_order_total_begin` | 订单总价计算前 | `goods`, `params` | 修改商品价格/附加费用 |
| `plugins_service_order_status_change_history_success_handle` | 订单状态变更历史 | `order_id`, `old_status`, `new_status` | 监听状态变化 |
| `plugins_service_order_delete_success` | 订单删除成功 | `order_id` | 清理关联票务数据 |
---
## 二、商品详情页(前端)— 票务 UI 注入点
来源:`app/index/controller/Goods.php`
| 钩子名称 | 位置描述 | 最佳注入 |
|---------|---------|---------|
| `plugins_view_goods_detail_base_top` | 商品基础信息区顶部 | |
| `plugins_view_goods_detail_base_sku_top` | SKU/规格选择区顶部 | **★ 票务选座最佳注入点** |
| `plugins_view_goods_detail_base_inventory_top` | 库存显示区顶部 | |
| `plugins_view_goods_detail_base_inventory_bottom` | 库存显示区底部 | |
| `plugins_view_goods_detail_base_buy_nav_min_inside_begin` | 购买按钮区内部前 | |
| `plugins_view_goods_detail_base_buy_nav_min_inside` | 购买按钮区内部后 | |
| `plugins_view_goods_detail_base_bottom` | 商品基础信息区底部 | |
| `plugins_view_goods_detail_panel_original_price_top` | 原价上方 | |
| `plugins_view_goods_detail_panel_price_top` | 现价上方 | |
| `plugins_view_goods_detail_panel_price_bottom` | 现价下方 | |
| `plugins_view_goods_detail_panel_bottom` | 购买面板底部 | |
| `plugins_view_goods_detail_photo_within` | 相册内部 | |
| `plugins_view_goods_detail_photo_bottom` | 相册底部 | |
| `plugins_view_goods_detail_buy_nav_top` | 购买导航顶部 | |
| `plugins_view_goods_detail_right_content_top` | 右侧内容顶部 | |
| `plugins_view_goods_detail_right_content_bottom` | 右侧内容底部 | |
| `plugins_view_goods_detail_right_content_inside_top` | 右侧内容内部顶部 | |
| `plugins_view_goods_detail_right_content_inside_bottom` | 右侧内容内部底部 | |
| `plugins_view_goods_detail_tabs_top` | 标签页顶部 | |
| `plugins_view_goods_detail_tabs_content` | 标签页内容 | |
| `plugins_view_goods_detail_tabs_comments_top` | 评论区顶部 | |
| `plugins_view_goods_detail_tabs_comments_bottom` | 评论区底部 | |
| `plugins_view_goods_detail_tabs_guess_like_top` | 猜你喜欢顶部 | |
| `plugins_view_goods_detail_tabs_guess_like_bottom` | 猜你喜欢底部 | |
| `plugins_view_goods_detail_tabs_bottom` | 标签页底部 | |
| `plugins_view_goods_detail_content_top` | 商品详情内容顶部 | |
| `plugins_view_goods_detail_content_bottom` | 商品详情内容底部 | |
| `plugins_view_goods_detail_left_top` | 左侧区域顶部 | |
| `plugins_view_goods_detail_title` | 商品标题区 | |
---
## 三、购物车/结算页(前端)
来源:`app/index/controller/Buy.php`
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_view_buy_top` | 结算页顶部 |
| `plugins_view_buy_inside_top` | 结算内容区顶部 |
| `plugins_view_buy_address_bottom` | 收货地址下方 |
| `plugins_view_buy_payment_bottom` | 支付方式下方 |
| `plugins_view_buy_group_goods_bottom` | 商品分组下方 |
| `plugins_view_buy_user_note_bottom` | 用户备注下方 |
| `plugins_view_buy_base_confirm_top` | 确认信息顶部 |
| `plugins_view_buy_form_inside` | 表单内部 |
| `plugins_view_buy_inside_bottom` | 结算内容区底部 |
| `plugins_view_buy_bottom` | 结算页底部 |
---
## 四、用户中心(前端)
来源:`app/index/controller/User.php`
| 钩子名称 | 位置描述 | 票务用途 |
|---------|---------|---------|
| `plugins_view_user_center_top` | 用户中心顶部 | |
| `plugins_view_user_base_bottom` | 用户基础信息底部 | |
| `plugins_view_user_various_top` | 聚合内容顶部 | |
| `plugins_view_user_various_bottom` | 聚合内容底部 | |
| `plugins_view_user_various_inside_top` | 聚合内容内部顶部 | **★ 票夹最佳注入点** |
| `plugins_view_user_various_inside_bottom` | 聚合内容内部底部 | |
---
## 五、全局页面(前端)
来源:`app/index/controller/Common.php`
### CSS/JS 加载钩子
| 钩子名称 | 用途 |
|---------|------|
| `plugins_css` | 全局 CSS |
| `plugins_js` | 全局 JS |
### 全局视图钩子
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_common_header` | 全局头部 |
| `plugins_common_header_css` | 头部 CSS |
| `plugins_common_header_javascript` | 头部 JS |
| `plugins_common_page_bottom` | 全局页面底部 |
| `plugins_view_common_top` | 全局页面顶部 |
| `plugins_view_common_bottom` | 全局页面底部 |
| `plugins_view_common_top_header` | 头部内顶部 |
| `plugins_view_common_bottom_footer` | 底部内 |
### 头部导航钩子
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_view_header_navigation_top_left_begin` | 导航左上起始 |
| `plugins_view_header_navigation_top_left_end` | 导航左上结束 |
| `plugins_view_header_navigation_top_right_begin` | 导航右上起始 |
| `plugins_view_header_navigation_top_right_end` | 导航右上结束 |
| `plugins_view_common_header_nav_left` | 导航左侧 |
| `plugins_view_common_header_nav_search_inside` | 搜索框内部 |
| `plugins_view_common_header_nav_content_inside_top` | 导航内容顶部 |
| `plugins_view_common_header_nav_content_inside_bottom` | 导航内容底部 |
| `plugins_view_common_header_nav_right` | 导航右侧 |
| `plugins_view_common_logo_right` | Logo 右侧 |
| `plugins_view_common_search_right` | 搜索框右侧 |
| `plugins_view_common_search_inside_left` | 搜索框内部左侧 |
| `plugins_view_common_search_inside_right` | 搜索框内部右侧 |
### 登录/注册页钩子
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_view_user_login_content_inside_top` | 登录内容内部顶部 |
| `plugins_view_user_login_content_inside_bottom` | 登录内容内部底部 |
| `plugins_view_user_login_info_top` | 登录信息区域顶部 |
| `plugins_view_user_login_inside_bottom` | 登录区域内部底部 |
| `plugins_view_user_login_inside_reg_bottom` | 注册登录区域底部 |
| `plugins_view_user_login_content_bottom` | 登录内容底部 |
| `plugins_view_user_reg_info` | 注册信息区域 |
| `plugins_view_user_reg_info_top` | 注册信息顶部 |
| `plugins_view_user_reg_info_inside_bottom` | 注册信息内部底部 |
| `plugins_view_user_reg_info_inside_login_bottom` | 注册内登录底部 |
| `plugins_view_user_reg_info_bottom` | 注册信息底部 |
### 底部钩子
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_view_common_footer_top` | 页脚顶部 |
---
## 六、首页楼层(前端)
来源:`app/index/controller/Index.php`
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_view_home_floor_top` | 首页楼层顶部 |
| `plugins_view_home_floor_bottom` | 首页楼层底部 |
| `plugins_view_home_banner_mixed_bottom` | 混合 Banner 底部 |
---
## 七、搜索页(前端)
来源:`app/index/controller/Search.php`
| 钩子名称 | 位置描述 |
|---------|---------|
| `plugins_view_search_top` | 搜索页顶部 |
| `plugins_view_search_bottom` | 搜索页底部 |
| `plugins_view_search_inside_top` | 搜索结果区顶部 |
| `plugins_view_search_inside_bottom` | 搜索结果区底部 |
| `plugins_view_search_data_top` | 商品列表顶部 |
| `plugins_view_search_data_bottom` | 商品列表底部 |
| `plugins_view_search_map_top` | 地图区域顶部 |
| `plugins_view_search_nav_top` | 筛选导航顶部 |
| `plugins_view_search_nav_inside_begin` | 筛选导航内部起始 |
| `plugins_view_search_nav_inside_end` | 筛选导航内部结束 |
| `plugins_view_search_map_inside_begin` | 地图内部起始 |
| `plugins_view_search_map_inside_base_bottom` | 地图基础内容底部 |
| `plugins_view_search_map_inside_end` | 地图内部结束 |
---
## 八、服务层钩子(业务逻辑)
来源:`app/service/GoodsService.php`
| 钩子名称 | 触发时机 | 票务用途 |
|---------|---------|---------|
| `plugins_service_goods_data` | 商品数据读取 | |
| `plugins_service_goods_spec_data` | 商品规格数据 | **★ 票务座位规格注入** |
| `plugins_service_goods_parameters_data` | 商品参数数据 | |
| `plugins_service_goods_content_app_data` | 商品详情 APP 数据 | |
| `plugins_service_home_floor_data_begin` | 首页楼层数据前 | |
| `plugins_service_category_goods_total_begin` | 分类商品总数前 | |
| `plugins_service_category_goods_list_begin` | 分类商品列表前 | |
| `plugins_service_goods_list_begin` | 商品列表前 | |
| `plugins_service_goods_total_begin` | 商品总数前 | |
| `plugins_service_goods_list_handle_begin` | 商品列表处理开始 | |
| `plugins_service_goods_handle_begin` | 商品处理开始 | |
| `plugins_service_goods_handle_end` | 商品处理结束 | |
| `plugins_service_goods_list_handle_end` | 商品列表处理结束 | |
| `plugins_service_goods_save_handle` | 商品保存处理 | |
| `plugins_service_goods_save_thing_begin` | 商品保存项目开始 | |
| `plugins_service_goods_save_thing_end` | 商品保存项目结束 | |
| `plugins_service_goods_save_end` | 商品保存结束 | |
| `plugins_service_goods_base_update` | 商品基础更新 | |
| `plugins_service_goods_delete` | 商品删除 | |
| `plugins_service_goods_field_status_update` | 商品字段状态更新 | |
| `plugins_service_goods_spec_base` | 商品规格基础 | |
| `plugins_service_goods_spec_type` | 商品规格类型 | |
| `plugins_service_goods_spec_extends_handle` | 商品规格扩展处理 | |
| `plugins_service_goods_buy_left_nav_handle` | 购买左侧导航处理 | |
| `plugins_service_goods_buy_nav_button_handle` | 购买导航按钮处理 | |
| `plugins_service_goods_detail_middle_tabs_nav_handle` | 详情页标签导航处理 | |
| `plugins_service_goods_search_list_begin` | 商品搜索列表开始 | |
| `plugins_service_goods_base_forbid_operate_data` | 商品禁止操作数据 | |
| `plugins_service_goods_params_operate_data` | 商品参数操作数据 | |
| `plugins_service_goods_spec_operate_data` | 商品规格操作数据 | |
---
## 九、服务层钩子(订单)
来源:`app/service/OrderService.php`
| 钩子名称 | 触发时机 |
|---------|---------|
| `plugins_service_order_pay_launch_begin` | 发起支付前 |
| `plugins_service_order_pay_launch_handle` | 支付方式处理 |
| `plugins_service_order_pay_notify_handle` | 支付通知处理 |
| `plugins_service_order_pay_handle_begin` | 支付成功开始处理 |
| `plugins_service_order_pay_success_handle_end` | 支付成功处理结束 |
| `plugins_service_order_total_begin` | 订单总价计算前 |
| `plugins_service_order_status_group_total_begin` | 订单状态分组统计前 |
| `plugins_service_order_list_begin` | 订单列表前 |
| `plugins_service_order_list_handle_begin` | 订单列表处理开始 |
| `plugins_service_order_handle_begin` | 订单处理开始 |
| `plugins_service_order_handle_end` | 订单处理结束 |
| `plugins_service_order_list_handle_end` | 订单列表处理结束 |
| `plugins_service_order_detail_data` | 订单详情数据 |
| `plugins_service_order_extraction_data` | 订单提取数据(取货码) |
| `plugins_service_order_trace_source_data` | 订单溯源数据 |
| `plugins_service_order_service_data` | 订单服务数据 |
| `plugins_service_order_express_data` | 订单快递数据 |
| `plugins_service_order_address_data` | 订单地址数据 |
| `plugins_service_order_status_change_history_success_handle` | 订单状态变更历史 |
| `plugins_service_order_delete_success` | 订单删除成功 |
---
## 十、服务层钩子(其他)
来源:`app/service/AppHomeNavService.php`, `app/service/DiyService.php`
| 钩子名称 | 来源 | 触发时机 |
|---------|------|---------|
| `plugins_service_app_home_navigation_{client_type}` | AppHomeNavService | 首页导航client_type=pc/h5/weixin_mp等 |
| `plugins_module_diy_view_data_handle` | DiyModule | DIY 视图数据处理 |
| `plugins_module_diy_save_data_handle` | DiyModule | DIY 保存数据处理 |
| `plugins_layout_service_url_value_begin` | LayoutModule | 布局服务 URL 值前 |
| `plugins_layout_service_url_value_handle` | LayoutModule | 布局服务 URL 值处理 |
| `plugins_layout_service_search_goods_begin` | LayoutModule | 布局搜索商品前 |
| `plugins_layout_service_goods_data_begin` | LayoutModule | 布局商品数据前 |
| `plugins_layout_service_pages_list` | LayoutModule | 布局页面列表 |
---
## 十一、后台管理钩子
来源:`app/admin/controller/Common.php`
### 全局 CSS/JS 钩子
| 钩子名称 | 用途 |
|---------|------|
| `plugins_admin_css` | 后台全局 CSS |
| `plugins_admin_js` | 后台全局 JS |
| `plugins_admin_common_header` | 后台头部 |
| `plugins_admin_common_header_css` | 后台头部 CSS |
| `plugins_admin_common_header_javascript` | 后台头部 JS |
| `plugins_admin_common_page_bottom` | 后台页面底部 |
| `plugins_admin_view_common_top` | 后台页面顶部 |
| `plugins_admin_view_common_bottom` | 后台页面底部 |
### 后台表单钩子
| 钩子名称 | 来源控制器 |
|---------|---------|
| `plugins_view_admin_goods_save` | Goods.php — 商品保存 |
| `plugins_view_admin_user_save` | User.php — 用户保存 |
| `plugins_view_admin_admin_save` | Admin.php — 管理员保存 |
| `plugins_view_admin_login_info` | Admin.php — 登录页 |
| `plugins_view_admin_role_save` | Role.php — 角色保存 |
---
## 十二、VR 票务插件 — 推荐钩子使用方案
### 方案 A支付成功立即生成票最可靠
**使用钩子**: `plugins_service_order_pay_notify_handle``plugins_service_order_pay_success_handle_end`
```php
// Event.php
public function PayNotifyHandle($params = [])
{
// $params['business_data'] 包含订单数据
// $params['business_ids'] 包含订单ID列表
$order_id = $params['business_ids'][0] ?? 0;
$order = Db::name('order')->find($order_id);
if ($order['pay_status'] == 1) {
// 1. 原子扣 vr_sessions 库存
// 2. 生成 vr_ticketsAES QR
// 3. 写入 vr_attendees
}
}
```
### 方案 B商品详情页注入票务选座 UI
**使用钩子**: `plugins_view_goods_detail_base_sku_top`
```php
// view/Goods.php
public static function PluginsViewGoodsDetailBaseSkuTop($params)
{
$goods = $params['goods'];
if (empty($goods['item_type']) || $goods['item_type'] != 'ticket') {
return '';
}
return '<div id="ticket-seat-map" data-goods-id="'.$goods['id'].'"></div>';
}
```
### 方案 C用户中心票夹
**使用钩子**: `plugins_view_user_various_inside_top`
```php
// view/User.php
public static function PluginsViewUserVariousInsideTop($params)
{
return '<div id="ticket-wallet"></div>';
}
```
---
## 十三、钩子注册方式config.json
```json
{
"base": {
"name": "VR票务",
"plugins": "vr_ticket"
},
"hook": {
"plugins_service_order_pay_success_handle_end": [
"\\app\\plugins\\vr_ticket\\Event::PaySuccess"
],
"plugins_view_goods_detail_base_sku_top": [
"\\app\\plugins\\vr_ticket\\view\\Goods::PluginsViewGoodsDetailBaseSkuTop"
],
"plugins_view_user_various_inside_top": [
"\\app\\plugins\\vr_ticket\\view\\User::PluginsViewUserVariousInsideTop"
]
},
"backend_hook": {
"plugins_view_admin_goods_save": [
"\\app\\plugins\\vr_ticket\\hook\\AdminGoodsSave"
]
}
}
```