full/module/base/mgt/README.md

# mgt - 系统管理

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

[![Go Version](https://img.shields.io/badge/Go-1.25.1-blue.svg)](https://golang.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 📋 目录

- [功能特性](#-功能特性)
- [技术栈](#-技术栈)
- [项目结构](#-项目结构)
- [快速开始](#-快速开始)
- [配置说明](#-配置说明)
- [API 文档](#-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** - [安装指南](https://golang.org/doc/install)
- **PostgreSQL 12+** 或 **MySQL 8.0+**
- **Redis 6.0+**

### 安装步骤

#### 1. 克隆项目

```bash
git clone <repository-url>
cd mgt
```

#### 2. 安装依赖

```bash
go mod download
```

#### 3. 配置数据库

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

```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. 初始化数据库

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

```yaml
InitRootUser: true
```

默认管理员账号：
- **账号**: `root`
- **密码**: `123456`

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

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

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

```bash
go run scripts/init_ops_monitor_app.go
```

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

详细说明请参考 [脚本工具](#脚本工具) 章节。

#### 5. 编译项目

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

#### 6. 启动服务

```bash
# Windows
.\mgt.exe

# Linux/Mac
./mgt
```

或使用启动脚本：

```powershell
# Windows PowerShell
.\START_TEST.ps1
```

#### 7. 验证服务

访问健康检查接口：

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

---

## ⚙️ 配置说明

### 配置文件位置

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

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

### 配置项说明

```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` 指定配置环境：

```bash
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 插件：**

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

更多测试说明请参考：[测试执行指南](TEST_EXECUTION_GUIDE.md)

---

## 🧪 测试

### 单元测试

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

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

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

### API 测试

使用 `test/` 目录下的 HTTP 测试文件进行 API 测试，详细步骤请参考 [测试执行指南](TEST_EXECUTION_GUIDE.md)。

### 测试覆盖

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

---

## 👨‍💻 开发说明

### 代码规范

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

### 新增接口流程

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

### 工具函数使用

#### 参数验证

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

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

#### 错误处理

```go
// 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
}
```

#### 日志记录

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

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

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

### 数据库模型

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

```go
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 文件格式：**

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

**使用方法：**

```bash
# 确保 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` 中引用了不存在角色、应用或权限的记录

**使用方法：**

```bash
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）
- 建议定期运行此脚本，保持数据库数据一致性

---

## 📝 更新日志

### 最新特性

- ✅ 统一的参数验证框架
- ✅ 统一的错误处理机制
- ✅ 结构化的日志记录
- ✅ 完整的测试覆盖
- ✅ 支持 bcrypt 密码加密（向后兼容 MD5）
- ✅ 运维监控平台应用初始化脚本

### 优化改进

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

详细更新记录请参考：
- [P0修复总结](P0_FIXES_SUMMARY.md)
- [P1修复总结](P1_FIXES_SUMMARY.md)
- [P2修复总结](P2_FIXES_SUMMARY.md)
- [优化建议](OPTIMIZATION_SUGGESTIONS.md)

---

## 🤝 贡献指南

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

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

### 提交规范

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

---

## 📄 许可证

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

---


## 👥 联系方式

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

- 提交 Issue
- 发送 Pull Request

---

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