🏛️ 工程架构

SunAdmin 采用"Laravel 13 后端 + 多前端源码 + 编译产物托管"的结构。后端负责模块、接口、认证、数据和业务编排；前端源码放在 frontend/，生产构建后由 Laravel 的 public/admin/、public/h5/ 目录托管。

🔩 目录结构

text

SunAdmin
├─ app/                         Laravel 应用公共层
│  ├─ Core/                     项目级基础能力
│  ├─ Http/                     Laravel 公共 HTTP 能力
│  ├─ Models/                   跨模块公共模型
│  ├─ Providers/                Laravel 应用启动注册器
│  └─ Support/                  模块注册、缓存、安装、URL 等支持类
├─ bootstrap/                   Laravel 启动文件与框架缓存
├─ config/                      Laravel 与业务配置
├─ database/                    全局迁移、工厂、Seeder
├─ docs/                        项目原始文档与说明资料
├─ extend/                      扩展类库、第三方扩展或项目增强代码
├─ frontend/
│  ├─ admin/                    Vue3 后台管理端源码
│  └─ uniapp/                   跨端移动端，uni-app Vue3
├─ modules/                     业务模块
│  ├─ System/                   系统核心业务模块
│  │  ├─ module.json            模块基础信息，提供标题、版本、路由标识等配置
│  │  ├─ Ai/                    Laravel AI Agent 工具适配，按 Tools 等能力归类
│  │  ├─ Application/           应用层，承载 Actions、Services、Jobs
│  │  │  ├─ Actions/            接口业务动作，一个 Action 通常对应一次接口操作
│  │  │  │  ├─ Admin/           后台管理端接口业务动作
│  │  │  │  └─ Api/             用户端接口业务动作
│  │  │  ├─ Jobs/               队列任务、异步任务，AI 相关任务放在 Ai 子目录
│  │  │  └─ Services/           可复用业务服务，按 Auth、Config、File、Pay 等领域归类
│  │  │     ├─ Ai/              AI、知识库、MCP 运行服务
│  │  │     ├─ Auth/            认证与权限
│  │  │     ├─ Config/          系统配置
│  │  │     ├─ Decorate/        页面装修
│  │  │     ├─ File/            文件与存储
│  │  │     ├─ Message/         消息与短信
│  │  │     ├─ Pay/             支付基础能力、支付单、退款单与业务分发
│  │  │     ├─ Search/          搜索能力
│  │  │     └─ Wechat/          微信生态能力
│  │  ├─ Dao/                   数据访问层，封装模型查询、列表过滤、保存删除等数据操作
│  │  ├─ Database/              System 模块迁移、Seeder、初始化数据
│  │  ├─ Domain/                领域层，承载模型、枚举、类型转换等业务实体能力
│  │  │  ├─ Casts/              Eloquent 属性类型转换
│  │  │  ├─ Enums/              业务枚举
│  │  │  └─ Models/             Eloquent 模型，按 Ai、Auth、Pay、User 等领域归类
│  │  ├─ Http/                  HTTP 入口层，承载控制器与请求校验
│  │  │  ├─ Controllers/        控制器，按 Admin / Api 入口区分
│  │  │  │  ├─ Admin/           后台管理端控制器
│  │  │  │  └─ Api/             用户端控制器
│  │  │  └─ Requests/           FormRequest，请求参数校验与入参规范化
│  │  │     ├─ Admin/           后台管理端请求校验
│  │  │     └─ Api/             用户端请求校验
│  │  ├─ Mcp/                   Laravel MCP Server 工具，按 Tools 等能力归类
│  │  └─ Providers/             模块启动注册器，接入路由、配置、事件等
├─ public/
│  ├─ admin/                    Admin 生产构建产物
│  ├─ assets/                   Laravel / Vite 公共静态资源
│  ├─ h5/                       uni-app H5 生产构建产物
│  ├─ modules/                  业务模块运行包发布目录
│  ├─ resource/                 项目公共资源，例如 Logo、默认图片等
│  └─ storage/                  公开附件映射，指向 storage/app/public
├─ resources/                   Blade、前端资源入口、传统静态资源
│  ├─ css/                      Laravel 默认样式资源
│  ├─ js/                       Laravel 默认脚本资源
│  └─ views/                    Blade 视图
├─ routes/                      Web、AI、Console 路由入口
│  ├─ ai.php                    AI / MCP 相关路由
│  ├─ console.php               Artisan 命令路由
│  └─ web.php                   Web 页面与前端托管入口
├─ storage/                     Laravel 运行时目录
│  ├─ app/                      应用文件存储，public 磁盘位于 app/public
│  ├─ framework/                缓存、视图、会话等框架运行文件
│  ├─ logs/                     应用日志
│  └─ tmp/                      临时文件
└─ vendor/                      Composer 依赖目录

🧱 System 模块目录说明

modules/System 是本项目系统核心业务模块，承担后台管理、用户端基础能力、支付、上传、AI、权限与配置等功能。新增系统级业务时，应优先放入该模块的对应分层目录，避免把业务代码散落到 Laravel 根目录。

目录	说明	常见内容
`Ai/Tools`	Laravel AI Agent 工具适配	给管理端 AI 助手注入的工具适配类
`Application/Actions/Admin`	后台管理端接口业务动作	列表、详情、创建、更新、删除、状态切换、导入导出
`Application/Actions/Api`	用户端接口业务动作	登录注册、用户资料、文章、装修页面、上传调用
`Application/Jobs`	队列与异步任务	AI 知识库处理、耗时任务、后台异步执行逻辑
`Application/Services/Ai`	AI 业务服务	模型配置、对话、知识库、MCP 调用编排等
`Application/Services/Auth`	认证授权服务	登录、Token、权限判断、角色菜单关系
`Application/Services/Config`	配置服务	系统配置读取、保存、分组、缓存刷新
`Application/Services/Decorate`	装修服务	页面装修、组件数据、移动端页面渲染数据
`Application/Services/File`	文件服务	附件上传、存储驱动、文件分组、文件访问地址
`Application/Services/Message`	消息服务	系统通知、消息模板、站内消息
`Application/Services/Pay`	支付服务	支付基础能力、支付单、退款单、支付驱动契约和业务分发
`Application/Services/Search`	搜索服务	搜索条件组织、索引或业务查询封装
`Application/Services/Wechat`	微信服务	微信配置、小程序、公众号相关能力
`Dao/*`	数据访问层	按业务领域封装查询条件、分页、写入、删除、统计
`Database/Seeders`	模块初始化数据	菜单、权限、配置、字典、默认数据
`Domain/Casts`	模型字段转换	JSON、金额、数组、枚举等属性转换
`Domain/Enums`	业务枚举	状态、类型、渠道、来源、开关值
`Domain/Models/*`	领域模型	对应数据库表的 Eloquent 模型、关联、scope、get/set 访问器
`Http/Controllers/Admin`	后台接口控制器	`/adminapi/system/*` 相关入口
`Http/Controllers/Api`	用户端接口控制器	`/api/system/*` 相关入口
`Http/Requests/Admin`	后台接口请求校验	管理端新增、编辑、查询、状态变更参数
`Http/Requests/Api`	用户端接口请求校验	移动端、H5、小程序接口参数
`Mcp/Tools`	Laravel MCP Server 工具	MCP 客户端和后台 MCP 调试接口可调用的工具
`Providers`	模块启动注册器	模块启动时把路由、配置、事件、依赖注入等能力接入 Laravel，不承载具体业务流程

System 业务子域

System 模块内部按功能域继续拆分目录。阅读代码时可以先看控制器入口，再顺着接口业务动作 Action、Service、Dao、Model 向下追踪业务链路。

分层目录	子目录	说明
`Ai`	`Tools`	Laravel AI Agent 工具适配类，按约定目录自动发现
`Application/Actions/Admin`	`Auth`、`Core`、`Decorate`、`File`、`Integration`、`Language`、`Message`、`Org`、`Search`、`Setting`、`User`	后台管理端接口业务动作，覆盖权限、组织、配置、装修、消息、语言、文件、用户等后台业务
`Application/Actions/Api`	`Ai`、`Auth`、`Core`、`File`、`Message`、`Search`、`User`	用户端接口业务动作，覆盖登录认证、用户资料、AI、上传、消息、搜索等能力
`Application/Services/Ai`	`Mcp`	AI 服务下的 MCP 调用编排、工具发现服务、官方 MCP Server 接入
`Application/Services/File`	`Drivers`	文件存储驱动层，承接本地、云存储等不同存储实现
`Application/Services/Message`	`Sms`	消息服务下的短信能力封装
`Application/Services/Pay`	`Contracts`、`Handlers`	支付驱动契约与支付处理器，便于扩展不同支付渠道
`Application/Services/Search`	`Providers`	搜索服务提供者，封装不同搜索来源或搜索实现
`Dao`	`Ai`、`Article`、`Auth`、`Decorate`、`File`、`Language`、`Message`、`Org`、`Pay`、`Setting`、`User`	各业务域的数据访问对象，负责查询封装、筛选条件、分页与统计
`Domain/Models`	`Ai`、`Article`、`Auth`、`Decorate`、`File`、`Language`、`Message`、`Org`、`Pay`、`Setting`、`User`	各业务域模型目录，放置 Eloquent 模型、关联、访问器、修改器和 scope
`Http/Controllers/Admin`	`Article`、`Auth`、`Decorate`、`Integration`、`Language`、`Message`、`Org`、`Setting`、`User`	后台接口控制器，按后台菜单与业务模块归类
`Http/Controllers/Api`	`User`	用户端接口控制器，承接用户相关 API 入口
`Http/Requests/Admin`	`Article`、`Auth`、`Core`、`Decorate`、`File`、`Integration`、`Language`、`Message`、`Org`、`Setting`、`User`	后台接口请求校验，按控制器与业务模块拆分
`Http/Requests/Api`	`Ai`、`Auth`、`File`、`Message`、`User`、`Wechat`	用户端接口请求校验
`Mcp`	`Tools`	Laravel MCP Server 工具类，按约定目录自动发现

📦 public/storage 目录说明

public/storage 是公开附件访问入口，本项目中它是一个 Junction，目标指向 storage/app/public。浏览器访问公开上传文件时，实际文件保存在 storage/app/public，再通过 public/storage 暴露访问路径。

路径	说明
`storage/app/public`	公开磁盘真实存储目录，上传文件最终落到这里
`public/storage`	Web 可访问映射目录，生产环境需确保链接或映射有效
`public/storage/uploads`	上传附件目录，通常存放图片、文件、富文本附件等

部署时需要确认 Web 服务允许访问 public/storage 下的静态文件。如果生产环境未生成映射，应执行 Laravel 的 php artisan storage:link，或按服务器策略手动建立等价软链接 / 目录映射。

🌐 模块注册流程

后端模块由 app/Support/ModuleRegistry.php 自动扫描：

模块目录：modules/*
模块配置：modules/{Module}/module.json
模块启动注册器：Modules\{Module}\Providers\{Module}ServiceProvider
Admin 控制器：modules/{Module}/Http/Controllers/Admin
Api 控制器：modules/{Module}/Http/Controllers/Api

路由前缀优先由 module.json 中的 slug 规范化生成，例如 System 模块会生成后台接口前缀 /adminapi/system 和用户端接口前缀 /api/system；UserCenter 模块可生成 /adminapi/user-center 和 /api/user-center。普通模块必须在 system_modules 中存在安装记录且 status=1，才会加载模块启动注册器和路由扫描；System 是核心模块，强制启用且不可卸载。

app/Providers/ModuleServiceProvider.php 会把每个模块的启动注册器注册进 Laravel 容器。config/route-attributes.php 读取 ModuleRegistry::routeAttributeDirectories()，再交给 Spatie Route Attributes 扫描注解路由。

🧩 三端职责边界

层	边界
后端	数据表、模型、Dao、Action、Service、Controller、FormRequest、统一响应
Admin	后台菜单、动态路由、权限按钮、管理表单、运营工具、系统配置
uni-app	用户端页面、装修渲染、登录态、H5/小程序/App 运行时兼容

🛜 接口前缀

类型	前缀	主要调用方
后台管理接口	`/adminapi/{routePrefix}`	`frontend/admin`
用户端接口	`/api/{routePrefix}`	`frontend/uniapp`
安装向导	`/install`	浏览器
Admin SPA	`/admin`	浏览器
uni-app H5	`/h5`	浏览器

⭐ 核心能力

权限、管理员、角色、菜单、组织部门、岗位。
用户、地址。
文章、协议、页面装修、媒体上传。
字典、系统配置、缓存维护、操作日志、系统日志、语言包。
微信配置、支付接入、存储配置。
AI 配置、知识库、MCP 工具与管理端 AI 助手。

🏛️ 工程架构 ​

🔩 目录结构 ​

🧱 System 模块目录说明 ​

System 业务子域 ​

📦 public/storage 目录说明 ​

🌐 模块注册流程 ​

🧩 三端职责边界 ​

🛜 接口前缀 ​

⭐ 核心能力 ​