yujun/goalfylearning-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b01cee2fa73013d15bef874c7cc3103edfa6a459
goalfylearning-admin/discuss
History

README.md

GoalfyMax Admin 架构探索文档

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

文档导航

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

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

内容包括:

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

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

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

内容包括:

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

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

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

内容包括:

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

快速导航

我想...

了解项目的整体架构

开始阅读: 详细架构指南 - 第 1-2 节

理解菜单系统如何实现的

开始阅读: 详细架构指南 - 第 2 节

学习现有配置模块的实现

开始阅读: 详细架构指南 - 第 3 节

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

开始阅读: 快速开发指南

看懂 Handler 层如何工作的

开始阅读: 详细架构指南 - 第 4 节 或 架构可视化图 - 三层架构

了解路由是如何配置的

开始阅读: 详细架构指南 - 第 5 节

理解数据库迁移的过程

开始阅读: 详细架构指南 - 第 6 节

查看配置文件的结构

开始阅读: 详细架构指南 - 第 7 节

看实现新功能的完整步骤

开始阅读: 详细架构指南 - 第 8 节

通过图表理解三层架构

开始阅读: 架构可视化图 - 项目分层架构

看请求处理的完整流程

开始阅读: 架构可视化图 - 请求处理流程

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

开始查看: 详细架构指南 - 第 10 节

关键文件列表

模型层

  • /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 脚本。

添加新功能的基本步骤

  1. 创建模型 - internal/models/new_feature.go
  2. 创建存储层 - internal/storage/new_feature_storage.go
  3. 创建服务层 - internal/services/new_feature_service.go
  4. 创建处理器 - internal/api/handlers/new_feature_handler.go
  5. 注册路由 - 在 routes.go 中添加路由
  6. 创建服务实例 - 在 main.go 中创建服务
  7. 数据库迁移 - 在 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 可视化架构图表

后续步骤

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

需要帮助?

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

相关链接

  • 项目根目录: /Users/youziba/goalfyagent/goalfymax-admin/
  • Models: /Users/youziba/goalfyagent/goalfymax-admin/internal/models/
  • Storage: /Users/youziba/goalfyagent/goalfymax-admin/internal/storage/
  • Services: /Users/youziba/goalfyagent/goalfymax-admin/internal/services/
  • Handlers: /Users/youziba/goalfyagent/goalfymax-admin/internal/api/handlers/
  • Routes: /Users/youziba/goalfyagent/goalfymax-admin/internal/api/routes/

文档生成日期: 2024-10-28
文档版本: 1.0
作者: Claude Code