开发文档

一、技术架构

• 形态：这不是独立站点，而是智简魔方 V10（idcsmart）业务系统的功能插件，装在魔方主程序里，帮你在魔方后台把「宝塔面板」变成可售卖的商品（自动开通/管理客户宝塔面板）；
• 框架：跟随魔方主程序（ThinkPHP 系），插件目录 idcsmart_common/，命名空间与类名统一带 IdcsmartCommon 前缀；PHP 7.4~8.1；
• 对接通道：idcsmart_common/module/skymnbt/ 是与宝塔/ skymnbt 服务端通信的模块（API 对接、开通、停复机、续费、升降级）；
• 多语言：idcsmart_common/lang/{zh-cn,en-us,zh-hk}.php。

二、目录结构

idcsmart_common/
├── IdcsmartCommon.php        # 插件主类（注册菜单、路由、钩子）
├── hooks.php                 # 钩子注册（魔方事件 → 插件方法）
├── controller/
│   ├── admin/                # 后台控制器（商品配置、服务器、订单操作）
│   └── home/                 # 前台/客户区控制器（购买、管理面板）
├── model/                    # 数据模型（IdcsmartCommon*Model.php）
├── logic/                    # 业务逻辑（开通 ProvisionLogic / 工具 ToolLogic / 级联 CascadeLogic）
├── validate/                 # 参数校验
├── module/skymnbt/           # 对接模块（服务端 API 调用）
├── data/                     # 安装数据（abc.zip 等）
├── template/
│   ├── admin/                # 后台模板
│   ├── cart/                 # 购物车/下单页模板
│   └── clientarea/           # 客户中心模板
└── lang/                     # 多语言

三、数据表

• 插件不建独立库，直接用魔方主库，表名统一带 module_idcsmart_common_ 前缀，共 14 张：
• module_idcsmart_common_product（商品）、module_idcsmart_common_pricing（价格周期）、module_idcsmart_common_custom_cycle / _custom_cycle_pricing（自定义周期与价格）；
• module_idcsmart_common_server / _server_group / _server_host_link（服务器、服务器分组、服务器与主机关联）；
• module_idcsmart_common_product_configoption / _configoption_sub（可配置项）、module_idcsmart_common_host_configoption（主机上的配置项取值）；
• module_idcsmart_common_product_custom_field / _custom_field_value（自定义字段与取值）、module_idcsmart_common_cascade_group / _cascade_item（级联项，如机房/地区级联）；
• 安装/升级随魔方插件机制执行（插件目录里的数据与迁移）。

四、关键机制

4.1 钩子（hooks.php）

魔方在「下单 / 支付成功 / 开通 / 删除」等节点触发钩子，插件里对应方法完成开通与同步。做二开时先看 hooks.php 登记了哪些钩子，再顺着 logic/ProvisionLogic.php 看开通流程。

4.2 对接模块（module/skymnbt）

所有对宝塔服务端的请求都收口在这个模块里（API 地址、密钥、请求签名、返回值解析）。换对接通道/升级接口，只动这里，不要散落到控制器。

4.3 商品配置

可配置项（机型/带宽/周期等）由 idcsmart_common_product_configoption* 系列表驱动，后台模板在 template/admin/，前台购买页在 template/cart/。

五、二次开发指引

• 加一个后台设置页：在 controller/admin/ 加控制器方法 + template/admin/ 加模板，并在主类里注册菜单；
• 加字段：优先加 idcsmart_common_ 自己的表；改主库表要在升级脚本里写可重复执行的 SQL；
• 改开通流程：logic/ProvisionLogic.php（开通/续费/升降级），调试时配合魔方「任务队列」日志；
• 注意：插件后台控制器目录 idcsmart_common/controller/admin/ 带授权验证（未授权时后台插件页会提示授权），别删除验证相关代码；
• 官方主程序更新覆盖：魔方升级后本插件目录通常不受影响，但若你改过魔方本体用于对接的文件，升级会被覆盖，升级前先备份改动。

六、授权说明

插件包带授权验证（绑定域名 + 安装时激活）。同一份包在魔方后台「插件管理」安装启用后，未授权时后台相关页面会锁；授权码在插件设置或 xj_panel.php（如随包提供）里核对。