bsm-infra/full

Fork 0

Files

yanweidong 5cc5fd92ed refactor: reorganize modules and add Linux build tooling

2026-08-09 12:41:08 +08:00

17 KiB

Raw Blame History

mgt - 系统管理

一个基于 Go 语言开发的企业级 Mgt（Role-Based Access Control）权限管理系统，提供完整的用户、角色、权限、应用和部门管理功能。

📋 目录

功能特性
技术栈
项目结构
快速开始
配置说明
API 文档
测试
开发说明
贡献指南

✨ 功能特性

核心功能

👥 用户管理 - 完整的用户CRUD操作，支持用户角色和权限分配
🎭 角色管理 - 灵活的角色定义，支持角色权限批量设置
🔐 权限管理 - 多层级权限体系，支持菜单和按钮权限
📱 应用管理 - 多应用支持，应用级别的权限隔离
🏢 部门管理 - 组织架构管理，支持树形结构

安全特性

🔒 密码加密 - 使用 bcrypt 加密存储，支持 MD5 向后兼容
🎫 JWT认证 - 基于 JWT 的 Token 认证机制
✅ 参数验证 - 统一的参数验证框架，支持自定义验证规则
📝 统一日志 - 结构化的日志记录，支持多级别日志
🛡️ 错误处理 - 统一的错误处理和响应格式

技术特性

🚀 高性能 - 基于 Gin 框架，支持高并发
💾 多数据库支持 - 支持 PostgreSQL 和 MySQL
🔄 数据库连接池 - 优化的连接池配置
📦 事务支持 - 完整的事务管理，保证数据一致性
🔍 灵活查询 - 支持复杂的关联查询和数据过滤

🛠 技术栈

核心框架

Go 1.26.5 - 编程语言
Gin - Web 框架
GORM - ORM 框架
PostgreSQL/MySQL - 数据库
Redis - 缓存和会话存储

主要依赖

git.apinb.com/bsm-sdk/core - 内部 SDK
github.com/gin-gonic/gin - HTTP Web 框架
gorm.io/gorm - ORM 框架
golang.org/x/crypto - 加密库（bcrypt）
go-playground/validator - 参数验证

开发工具

VS Code REST Client - API 测试
Go Testing - 单元测试框架

📁 项目结构

mgt/
├── cmd/                    # 应用程序入口
│   └── main/              # 主程序
│       └── main.go
├── internal/              # 内部代码（不对外暴露）
│   ├── config/           # 配置管理
│   ├── define/           # 数据结构定义
│   ├── errcode/          # 错误码定义
│   ├── impl/             # 实现层（数据库、Redis等）
│   ├── logic/            # 业务逻辑层
│   │   ├── user/         # 用户模块
│   │   ├── role/         # 角色模块
│   │   ├── permission/   # 权限模块
│   │   ├── application/  # 应用模块
│   │   ├── department/   # 部门模块
│   │   └── pub/          # 公共接口（登录等）
│   ├── models/           # 数据模型
│   ├── routers/          # 路由注册
│   └── utils/            # 工具函数
│       ├── validator.go  # 参数验证
│       ├── handler.go    # 错误处理
│       └── logger.go     # 日志记录
├── etc/                   # 配置文件
│   ├── mgt_dev.yaml    # 开发环境配置
│   ├── mgt_test.yaml   # 测试环境配置
│   └── mgt_prod.yaml   # 生产环境配置
├── test/                  # API 测试文件
│   ├── *.http            # REST Client 测试文件
│   └── ...
├── scripts/               # 脚本工具
│   ├── init_ops_monitor_app.go  # 初始化运维监控平台应用脚本
│   ├── cleanup_invalid_links.go # 清理无效关联数据脚本
│   ├── parse_menu_excel.py      # Excel菜单解析脚本（Python）
│   └── ...
├── other/                 # 其他资源文件
│   ├── menu_structure.json      # 菜单结构JSON文件
│   └── ...
├── pkg/                   # 可复用包
├── go.mod                 # Go 模块定义
├── go.sum                 # 依赖校验
├── README.md              # 项目说明
└── TEST_EXECUTION_GUIDE.md # 测试执行指南

🚀 快速开始

环境要求

Go 1.26.5 - 安装指南
PostgreSQL 12+ 或 MySQL 8.0+
Redis 6.0+

安装步骤

1. 克隆项目

git clone <repository-url>
cd mgt

2. 安装依赖

go mod download

3. 配置数据库

编辑 etc/mgt_dev.yaml，配置数据库连接信息：

Databases:
  Driver: postgres  # 或 mysql
  Source:
    - host=localhost user=postgres password=your_password dbname=mgt port=5432 sslmode=disable

Cache: redis://:your_password@localhost:6379/0

4. 初始化数据库

系统会在首次启动时自动创建数据表。如果需要初始化管理员用户，设置：

InitRootUser: true

默认管理员账号：

账号: root
密码: 123456

⚠️ 安全提示: 生产环境请务必修改默认密码！

4.1 初始化运维监控平台应用（可选）

如果需要初始化运维监控平台应用及其菜单权限，可以运行：

go run scripts/init_ops_monitor_app.go

此脚本会：

创建"运维监控平台"应用
根据 other/menu_structure.json 创建所有菜单权限
自动关联超级管理员角色和 root 用户

详细说明请参考脚本工具章节。

5. 编译项目

go build -o mgt.exe bsm/full/module/base/mgt/cmd/main

6. 启动服务

# Windows
.\mgt.exe

# Linux/Mac
./mgt

或使用启动脚本：

# Windows PowerShell
.\START_TEST.ps1

7. 验证服务

访问健康检查接口：

curl http://rest.apinb.com/mgt/ping

⚙️ 配置说明

配置文件位置

配置文件位于 etc/ 目录，支持多环境：

mgt_dev.yaml - 开发环境
mgt_test.yaml - 测试环境
mgt_prod.yaml - 生产环境

配置项说明

Service: mgt              # 服务名称
Port: 10001                 # 服务端口

Databases:                  # 数据库配置
  Driver: postgres          # 数据库驱动 (postgres/mysql)
  Source:                   # 数据库连接字符串
    - host=localhost user=postgres password=xxx dbname=mgt port=5432

Cache: redis://:password@localhost:6379/0  # Redis 连接

InitRootUser: false         # 是否初始化管理员用户（默认false）
SecretKey: xxx              # JWT 密钥
OnMicroService: false       # 是否启用微服务模式

环境变量

可以通过环境变量 ENV 指定配置环境：

export ENV=dev      # 使用 mgt_dev.yaml
export ENV=test     # 使用 mgt_test.yaml
export ENV=prod     # 使用 mgt_prod.yaml

📚 API 文档

API 基础路径

所有 API 的基础路径格式为：http://host:port/mgt/v1/

认证说明

大部分接口需要 JWT Token 认证，在请求头中添加：

Authorization: Bearer <your_token>

API 模块

公共接口（无需认证）

方法	路径	说明
GET	`/mgt/v1/ping`	健康检查
POST	`/mgt/v1/login`	用户登录
POST	`/mgt/v1/refresh`	刷新Token
POST	`/mgt/v1/reset`	重置密码

用户管理

方法	路径	说明
POST	`/mgt/v1/user/create`	创建用户
POST	`/mgt/v1/user/del`	删除用户
POST	`/mgt/v1/user/detail`	用户详情
POST	`/mgt/v1/user/modify`	修改用户
POST	`/mgt/v1/user/fetch`	用户列表
POST	`/mgt/v1/user/set_role`	设置用户角色
POST	`/mgt/v1/user/set_pmn`	设置用户权限
POST	`/mgt/v1/user/role`	获取用户角色
POST	`/mgt/v1/user/pmn`	获取用户权限

角色管理

方法	路径	说明
POST	`/mgt/v1/role/create`	创建角色
POST	`/mgt/v1/role/del`	删除角色
POST	`/mgt/v1/role/detail`	角色详情
POST	`/mgt/v1/role/modify`	修改角色
POST	`/mgt/v1/role/fetch`	角色列表
POST	`/mgt/v1/role/set_pmn`	设置角色权限
POST	`/mgt/v1/role/pmn`	获取角色权限

权限管理

方法	路径	说明
POST	`/mgt/v1/pmn/create`	创建权限
POST	`/mgt/v1/pmn/del`	删除权限
POST	`/mgt/v1/pmn/detail`	权限详情
POST	`/mgt/v1/pmn/modify`	修改权限
POST	`/mgt/v1/pmn/fetch`	权限列表
POST	`/mgt/v1/pmn/sort`	权限排序

应用管理

方法	路径	说明
POST	`/mgt/v1/app/create`	创建应用
POST	`/mgt/v1/app/del`	删除应用
POST	`/mgt/v1/app/detail`	应用详情
POST	`/mgt/v1/app/modify`	修改应用
POST	`/mgt/v1/app/fetch`	应用列表

部门管理

方法	路径	说明
POST	`/mgt/v1/dpt/create`	创建部门
POST	`/mgt/v1/dpt/del`	删除部门
POST	`/mgt/v1/dpt/detail`	部门详情
POST	`/mgt/v1/dpt/modify`	修改部门
POST	`/mgt/v1/dpt/fetch`	部门列表
POST	`/mgt/v1/dpt/fetch_tree`	部门树

API 测试

项目提供了完整的 API 测试文件，位于 test/ 目录，包含 54 个 .http 测试文件。

推荐使用 VS Code REST Client 插件：

安装插件：REST Client (humao.rest-client)
打开 test/*.http 文件
点击 "Send Request" 执行测试

更多测试说明请参考：测试执行指南

🧪 测试

单元测试

运行参数验证工具函数的单元测试：

go test -v bsm/full/module/base/mgt/internal/utils

测试结果： ✅ 19个测试用例全部通过

API 测试

使用 test/ 目录下的 HTTP 测试文件进行 API 测试，详细步骤请参考测试执行指南。

测试覆盖

✅ 参数验证测试（手机号、邮箱、密码长度等）
✅ 错误处理测试
✅ 日志格式测试
✅ 数据库事务测试

👨‍💻 开发说明

代码规范

遵循 Go 官方代码规范
使用统一的错误处理机制
使用统一的日志记录格式
所有接口参数需要验证

新增接口流程

在 internal/define/req.go 中定义请求结构体
在 internal/logic/ 对应模块中实现业务逻辑
在 internal/routers/register.go 中注册路由
在 test/ 目录中创建测试文件

工具函数使用

参数验证

import "bsm/full/module/base/mgt/internal/utils"

// 验证结构体
if err := libs.ValidateStruct(&request); err != nil {
    infra.Response.Error(c, errcode.ErrInvalidArgument)
    return
}

错误处理

// JSON解析错误
if err := c.ShouldBindJSON(&request); err != nil {
    infra.Response.Error(c, errcode.ErrJsonUnmarshal)
    return
}

// 数据库错误
if err := models.DBService.Create(&user).Error; err != nil {
    utils.HandleDBError(c, err, "创建用户")
    return
}

日志记录

// 信息日志
printer.Info("用户创建成功: ID=%d, account=%s", user.ID, user.Account)

// 错误日志
printer.Error("创建用户失败: %v", err)

// 警告日志
printer.Info("用户已存在: account=%s", account)

数据库模型

所有模型位于 internal/models/ 目录，使用 GORM 标签定义：

type MgtUser struct {
    coreTypes.Std_IICUDS          // 标准字段（ID、创建时间等）
    Account  string           `gorm:"column:account;uniqueIndex"`
    Name     string           `gorm:"column:name"`
    Password string           `gorm:"column:password"`
    // ...
}

脚本工具

项目提供了多个实用脚本，位于 scripts/ 目录：

初始化运维监控平台应用

init_ops_monitor_app.go - 根据 menu_structure.json 自动创建运维监控平台应用及其菜单权限。

功能：

创建"运维监控平台"应用（workspace: ops-monitor）
根据 JSON 文件自动创建一级和二级菜单权限（17个一级菜单 + 48个二级菜单）
自动生成权限标识码（Code）、英文标题（TitleEn）、图标等
自动关联超级管理员角色和 root 用户
自动建立所有关联关系（用户-应用、用户-角色、角色-应用、角色-权限、用户-权限）

前置条件：

确保数据库中已存在超级管理员角色（名称：超级管理员）
确保数据库中已存在 root 用户（账号：root）
确保 other/menu_structure.json 文件存在且格式正确

JSON 文件格式：

{
  "menus": [
    {
      "level1": "首页",
      "level1_path": "/",
      "children": []
    },
    {
      "level1": "可视化大屏管理",
      "level1_path": "/visual",
      "children": [
        {
          "level2": "我的组件",
          "path": "/visual/component"
        }
      ]
    }
  ],
  "total_level1": 17,
  "total_level2": 48
}

使用方法：

# 确保 menu_structure.json 文件存在于 other/ 目录
go run scripts/init_ops_monitor_app.go

输出示例：

✅ 应用创建成功: 运维监控平台 (ID: 15, Workspace: ops-monitor)
✅ 获取超级管理员角色成功: 超级管理员 (ID: 1)
✅ 获取root用户成功: root (ID: 1)
✅ 创建一级菜单: 首页 (Code: ops:首页)
✅ 创建二级菜单: 可视化大屏管理 - 我的组件 (Code: ops:可视化大屏管理:我的组件)
...
✅ 菜单创建完成，共创建/获取 65 个权限（一级菜单: 17, 二级菜单: 48）
✅ 关联root用户和应用成功
✅ 关联root用户和超级管理员角色成功
✅ 关联超级管理员角色和应用成功
✅ 关联超级管理员角色和权限成功，共 65 个权限
✅ 关联root用户和权限成功，共 65 个权限
✅ 运维监控平台应用初始化完成！

注意事项：

脚本使用事务执行，确保数据一致性，失败时自动回滚
如果应用或菜单已存在（通过 code 和 app_id 判断），会跳过创建并使用现有记录
脚本会自动重置 PostgreSQL 序列号，避免主键冲突
脚本是幂等的，可以安全地多次运行
权限标识码（Code）格式：一级菜单为 ops:菜单名，二级菜单为 ops:一级菜单名:二级菜单名

清理无效关联数据

cleanup_invalid_links.go - 清理数据库中无效的关联记录。

功能：

清理 mgt_link_user_role 中引用了不存在用户或角色的记录
清理 mgt_link_user_dpt 中引用了不存在用户或部门的记录
清理 mgt_link_user_app 中引用了不存在用户或应用的记录
清理 mgt_link_user_pmn 中引用了不存在用户、应用或权限的记录
清理 mgt_link_role_app 中引用了不存在角色或应用的记录
清理 mgt_link_role_pmn 中引用了不存在角色、应用或权限的记录

使用方法：

go run scripts/cleanup_invalid_links.go

输出示例：

开始清理无效的关联数据...
  ✅ 清理 mgt_link_user_role: 删除 5 条无效记录
  ✅ 清理 mgt_link_user_dpt: 删除 2 条无效记录
  ✅ 清理 mgt_link_user_app: 删除 1 条无效记录
  ✅ 清理 mgt_link_user_pmn: 删除 3 条无效记录
  ✅ 清理 mgt_link_role_app: 删除 0 条无效记录
  ✅ 清理 mgt_link_role_pmn: 删除 0 条无效记录

✅ 清理完成！共删除 11 条无效记录
✅ 所有无效关联数据已清理完成！

注意事项：

脚本使用事务执行，确保数据一致性
只清理软删除的记录（deleted_at IS NULL）
建议定期运行此脚本，保持数据库数据一致性

📝 更新日志

优化改进

🔧 数据库连接池优化
🔧 事务处理优化
🔧 代码质量提升
🔧 接口迁移完成（38个接口）

详细更新记录请参考：

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

提交规范

代码必须通过 linter 检查
新增功能需要添加测试
更新相关文档

📄 许可证

本项目采用 MIT 许可证。详情请查看 LICENSE 文件。

👥 联系方式

如有问题或建议，请通过以下方式联系：

提交 Issue
发送 Pull Request

⭐ 如果这个项目对你有帮助，欢迎 Star！

17 KiB Raw Blame History Unescape Escape

mgt - 系统管理

📋 目录

✨ 功能特性

核心功能

安全特性

技术特性

🛠 技术栈

核心框架

主要依赖

开发工具

📁 项目结构

🚀 快速开始

环境要求

安装步骤

1. 克隆项目

2. 安装依赖

3. 配置数据库

4. 初始化数据库

4.1 初始化运维监控平台应用（可选）

5. 编译项目

6. 启动服务

7. 验证服务

⚙️ 配置说明

配置文件位置

配置项说明

环境变量

📚 API 文档

API 基础路径

认证说明

API 模块

公共接口（无需认证）

用户管理

角色管理

权限管理

应用管理

部门管理

API 测试

🧪 测试

单元测试

API 测试

测试覆盖

👨‍💻 开发说明

代码规范

新增接口流程

工具函数使用

参数验证

错误处理

日志记录

数据库模型

脚本工具

初始化运维监控平台应用

清理无效关联数据

📝 更新日志

最新特性

优化改进

🤝 贡献指南

提交规范

📄 许可证

👥 联系方式

17 KiB

Raw Blame History