📦 模块配置

每个业务模块都放在 modules/{Module} 目录下，并通过 module.json 描述模块包信息。模块是否安装、启用和进入运行时，以数据库中的 system_modules 记录为准。本页聚焦 module.json 字段和模块安装状态；安装、卸载、运行包等操作命令见 模块安装与运维；publish-manifest.json 资源清单见 模块资源发布。

🎯 本页目标

读完本章节后，应能掌握：

• module.json 应该放在哪里、包含哪些字段。
• 模块包信息和安装状态由谁负责。
• core、business、feature、payment 四类模块的定位与差异。
• 模块菜单与初始数据应该放在哪里、注意点是什么。

📍 文件位置

以 Booking 模块为例：

modules/Booking/module.json

模块资源清单默认放在：

modules/Booking/Resources/publish-manifest.json

🧾 配置示例

{
  "title": "示例模块",
  "slug": "example",
  "description": "提供某个业务域的后台、接口和用户端页面能力。",
  "version": "1.0.0",
  "min_sunadmin_version": "1.0.0",
  "type": "business",
  "dependencies": [
    "System",
    { "name": "Wallet", "version": ">=1.0.0 <2.0.0" }
  ],
  "resources": "Resources/publish-manifest.json"
}

🧱 字段说明

字段	是否必填	说明
title	建议填写	后台或模块市场展示名称
slug	建议填写	模块稳定机器标识，参与默认路由前缀推导，例如 example
description	可选	模块功能简介
version	建议填写	模块版本号，遵循 SemVer，用于升级判断
min_sunadmin_version	可选	该模块所需的最低 SunAdmin 框架版本；安装/启用时会校验，不满足直接报错
max_sunadmin_version	可选	该模块支持的最高 SunAdmin 框架版本；用于声明不兼容未来 MAJOR
type	可选	模块类型标识，只允许使用 core、business、feature、payment
dependencies	可选	依赖模块列表，支持字符串或对象（带 version 约束）两种形式
resources	可选	资源发布清单路径，默认 Resources/publish-manifest.json

模块类型固定取值：

类型	说明
core	框架基础模块，只用于系统基础能力
business	业务模块，提供一套完整业务流程
feature	功能模块，提供可被多个业务复用的横向能力
payment	支付通道模块

应用中心按固定取值展示模块类型。模块开发时使用以上 4 个取值；其他取值不会被识别为合法模块类型。

🧮 版本约束语法

min_sunadmin_version 与 dependencies[].version 都遵循同一套约束语法（由 App\Support\Version::satisfies() 解析）：

表达式	含义
1.2.0	精确匹配 1.2.0
>=1.0.0	大于等于 1.0.0
<2.0.0	小于 2.0.0
>=1.0.0 <2.0.0	同 major 内（≥1.0.0 且 <2.0.0）
!=1.5.0	排除某个 buggy 版本

约束失败时框架会抛出明确错误（"模块 X 需要 SunAdmin >= Y，当前为 Z"），不允许继续安装。

➕ 依赖声明形式

"dependencies": [
  "System",                                                  // 字符串：仅校验已安装
  { "name": "Wallet", "version": ">=1.0.0 <2.0.0" }          // 对象：额外校验版本
]

System 是框架核心，框架始终视为"已安装"，写入 dependencies 仅为可读性。

🚦 安装状态

真实安装状态存放在 system_modules 表。modules 目录中存在模块文件时，后台应用中心会展示该模块；是否安装取决于 system_modules 中是否存在对应记录。

字段	说明
name	模块目录名，例如 {Module}
title	模块显示名称
version	当前安装版本
type	模块类型
status	1 表示启用，0 表示停用
installed_at	安装时间
enabled_at	启用时间
disabled_at	停用时间

常见状态：

状态	判断方式	说明
未安装	modules/{Module} 存在，system_modules 无记录	可以在应用中心执行安装
已启用	system_modules 有记录且 status=1	会加载模块启动注册器和路由
已停用	system_modules 有记录且 status=0	保留安装记录，不加载运行时代码
文件缺失	system_modules 有记录，但 modules/{Module} 不存在	需要恢复模块文件，或清理残留记录

除 System 基础模块强制启用外，普通模块必须满足：

system_modules.name = 模块名
system_modules.status = 1

模块启动注册器和注解路由才会被加载。

支付通道模块

支付通道也按模块安装。框架的 System 模块只提供支付单、退款单、回调日志和分发能力；微信支付、支付宝支付、通联支付等通道应分别作为 type=payment 的模块提供。

支付模块通常包含：

• Providers/{Module}ServiceProvider.php：注册支付驱动。
• Application/Services/Pay/*Driver.php：实现 PaymentDriverInterface，提供支付、退款、查单和后台配置字段。
• Http/Controllers/Api：提供渠道回调入口。
• Database/Seeders：写入通道配置项和默认驱动初始值。

后台统一通过“应用接入 / 支付接入”选择默认支付驱动，并按已安装支付模块配置参数。业务模块接入支付时如无特殊情况通常不需要写指定支付驱动名；如果默认驱动对应的支付模块未安装，框架会返回明确的驱动缺失提示。详见 支付基础能力 与 支付业务对接。

功能模块

功能模块用于承载可被多个业务复用的横向能力。业务模块需要使用这类能力时，应依赖 System 中定义的接口或基础服务，而不是直接依赖某个具体模块的 Controller、Dao 或 Model。

以优惠券为例：

• System 提供 CouponServiceInterface 和默认空实现。
• Coupon 模块启用后，在自己的模块启动注册器中绑定真实优惠券服务。
• 业务模块通过 CouponServiceInterface 查询可用优惠券、预览优惠金额或确认使用优惠券。
• 未安装或未启用 Coupon 时，查询可用优惠券返回空列表；业务传入具体 coupon_id 执行核销时会得到明确的模块未启用提示。

这种写法可以保证业务模块在没有安装优惠券模块的环境中仍然可以正常安装和运行。

🌱 菜单与初始数据

模块自己的后台菜单、权限、默认配置建议放到模块自己的 Seeder 或安装器中，不要继续写进 System 模块的初始化数据。

菜单写入时不要固定 id。推荐通过查找已存在菜单后更新，或通过 insertGetId() 使用当前数据库自增 ID，再把真实菜单 ID 授权给超级管理员。

这样模块可以在已有项目中独立安装，不会和 System 模块菜单 ID、其他业务模块菜单 ID 发生冲突。

⚠️ 注意事项

• module.json 只描述模块包，真实安装状态由 system_modules.status 判断。
• 除 System 外，模块只有在 system_modules 存在记录且 status=1 时才会进入运行时。
• status=0 表示模块已安装但停用；卸载模块会删除 system_modules 记录。
• System 模块强制启用，不依赖安装命令。
• 前端页面不要直接长期写死在主工程；可选业务模块应放入 Resources，安装时发布。
• uni-app 核心system模块页面源码在 src/pages/system。
• uni-app 模块源码统一安装在 src/modules/{module}，页面放在 src/modules/{module}/pages。
• uni-app 页面默认需要登录，只有在 pages.json 声明 "guest": true 的页面允许游客访问。
• 卸载模块默认保留数据，只有勾选 删除业务表和数据 或 卸载命令加上 --drop-data 才回滚模块迁移。
• 业务数据敏感模块不要在生产环境随意执行 删除业务表和数据 或 卸载命令加上 --drop-data。