yujun/goalfylearning-admin

Fork 0

Files

yuj 88e048f4d1 feat():learning后台管理项目初始化

2025-12-04 16:23:46 +08:00

8.7 KiB

Raw Blame History

GoalfyMax Admin 架构探索文档

欢迎使用本架构探索指南。这个文档集合帮助开发者快速理解和实现新的功能模块。

文档导航

1. 详细架构指南 (1182 行)

适合: 需要深入理解项目架构的开发者

内容包括:

项目整体架构和目录结构
菜单系统实现 (Page 模型)
用户等级配置模块完整实现示例
Handler/Controller 层实现模式
路由配置详解
数据库迁移方式
配置管理
添加新"通用配置"功能的完整 7 步骤
最佳实践总结
快速查找表

2. 快速开发指南 (336 行)

适合: 想快速添加新功能模块的开发者

内容包括:

5 分钟快速步骤 (7 个步骤)
文件复制清单
API 端点快速查询
常见错误排查
测试方法 (curl 示例)
关键对比表
模板代码片段
内存关键点

3. 架构可视化图 (473 行)

适合: 喜欢通过图表理解架构的开发者

内容包括:

项目分层架构图
请求处理流程图
文件依赖关系图
三层架构详解 (代码示例)
数据模型关系图
请求-响应周期示例
关键文件交互图
菜单权限系统图
配置流程图

快速导航

我想...

关键文件列表

模型层

/Users/youziba/goalfyagent/goalfymax-admin/internal/models/user_level_config.go - 用户等级配置模型
/Users/youziba/goalfyagent/goalfymax-admin/internal/models/request.go - 所有请求模型
/Users/youziba/goalfyagent/goalfymax-admin/internal/models/rbac.go - 页面和权限模型
/Users/youziba/goalfyagent/goalfymax-admin/internal/models/common.go - 基础模型

存储层

/Users/youziba/goalfyagent/goalfymax-admin/internal/storage/user_level_config_storage.go - 用户等级配置存储
/Users/youziba/goalfyagent/goalfymax-admin/internal/storage/page_storage.go - 页面存储
/Users/youziba/goalfyagent/goalfymax-admin/internal/storage/database.go - 数据库初始化和迁移

服务层

/Users/youziba/goalfyagent/goalfymax-admin/internal/services/user_level_config_service.go - 用户等级配置服务
/Users/youziba/goalfyagent/goalfymax-admin/internal/services/page_service.go - 页面服务

Handler 层

/Users/youziba/goalfyagent/goalfymax-admin/internal/api/handlers/user_level_config_handler.go - 用户等级配置处理器
/Users/youziba/goalfyagent/goalfymax-admin/internal/api/handlers/page_handler.go - 页面处理器

路由和配置

/Users/youziba/goalfyagent/goalfymax-admin/internal/api/routes/routes.go - 路由配置 (203-213 行有用户等级配置的路由)
/Users/youziba/goalfyagent/goalfymax-admin/internal/api/routes/routes.go (174-181 行有页面管理的路由)
/Users/youziba/goalfyagent/goalfymax-admin/cmd/server/main.go - 应用入口点
/Users/youziba/goalfyagent/goalfymax-admin/internal/config/config.go - 配置管理
/Users/youziba/goalfyagent/goalfymax-admin/etc/config.yaml - YAML 配置文件

核心概念

三层架构

项目采用三层架构模式:

HTTP 请求
   ↓
[Handler 层] - 处理 HTTP 请求和响应
   ↓
[Service 层] - 实现业务逻辑和验证
   ↓
[Storage 层] - 操作数据库
   ↓
[数据库]

菜单系统

项目中的"菜单"通过 Page 模型实现，其中：

admin_pages 表存储菜单项
admin_role_page_permissions 表关联角色和菜单权限

配置模块

用户等级配置是一个典范的配置模块，包含：

模型定义 (Model)
数据访问 (Storage)
业务逻辑 (Service)
HTTP 处理 (Handler)
路由配置 (Routes)

数据库迁移

项目使用 GORM 的 AutoMigrate 自动迁移，无需手写 SQL 脚本。

添加新功能的基本步骤

创建模型 - internal/models/new_feature.go
创建存储层 - internal/storage/new_feature_storage.go
创建服务层 - internal/services/new_feature_service.go
创建处理器 - internal/api/handlers/new_feature_handler.go
注册路由 - 在 routes.go 中添加路由
创建服务实例 - 在 main.go 中创建服务
数据库迁移 - 在 database.go 的 AutoMigrate 中添加模型

预计耗时: 5-10 分钟

最佳实践速查

主题	快速查看
错误处理	详细架构 - 4.3
字段验证	详细架构 - 4.2
数据库操作	详细架构 - 3.2b
业务逻辑	详细架构 - 3.2c
日志记录	详细架构 - 9.6
代码组织	详细架构 - 9.1

常见问题

Q: 如何添加新的配置模块?

A: 参考快速开发指南中的 7 个步骤，预计 5-10 分钟。

Q: 页面权限是如何工作的?

A: 查看详细架构 - 2.5 节和架构可视化 - 菜单权限系统。

Q: 数据库表是如何自动创建的?

A: GORM 根据模型定义自动创建表。详见详细架构 - 6.2 节。

Q: 如何测试新的 API?

A: 使用 curl 命令。参考快速开发指南 - 测试新模块。

Q: 项目中使用了哪些技术栈?

A: Gin (Web), GORM (ORM), MySQL (数据库), Zap (日志), Viper (配置)。详见详细架构 - 1.2。

文件大小和内容

文件	大小	行数	内容
architecture_guide.md	34 KB	1182	详细的架构和实现指南
QUICK_START.md	8.6 KB	336	快速开发清单和示例
ARCHITECTURE_DIAGRAM.md	18 KB	473	可视化架构图表

后续步骤

阅读文档: 根据需要选择上面的文档
参考示例: 查看 user_level_config 模块的实现
实施新功能: 按照快速开发指南的步骤
测试验证: 使用 curl 或其他工具测试 API
提交代码: 遵循项目的 Git 工作流

需要帮助?

如果您对任何内容有疑问，请参考对应的文档部分。所有文件都是自包含的，包含完整的代码示例和解释。

8.7 KiB Raw Blame History

GoalfyMax Admin 架构探索文档

文档导航

1. 详细架构指南 (1182 行)

2. 快速开发指南 (336 行)

3. 架构可视化图 (473 行)

快速导航

我想...

了解项目的整体架构

理解菜单系统如何实现的

学习现有配置模块的实现

快速添加一个新的配置模块

看懂 Handler 层如何工作的

了解路由是如何配置的

理解数据库迁移的过程

查看配置文件的结构

看实现新功能的完整步骤

通过图表理解三层架构

看请求处理的完整流程

找到项目中某个文件的位置

关键文件列表

模型层

存储层

服务层

Handler 层

路由和配置

核心概念

三层架构

菜单系统

配置模块

数据库迁移

添加新功能的基本步骤

最佳实践速查

常见问题

Q: 如何添加新的配置模块?

Q: 页面权限是如何工作的?

Q: 数据库表是如何自动创建的?

Q: 如何测试新的 API?

Q: 项目中使用了哪些技术栈?

文件大小和内容

后续步骤

需要帮助?

相关链接

8.7 KiB

Raw Blame History