# mole-user

**Repository Path**: mole-platform/mole-user

## Basic Information

- **Project Name**: mole-user
- **Description**: 基于mole-platform的用户中心
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Mole, 用户中心

## README

# Mole User(用户中心)

Mole User 是基于 Mole 组件库构建的 **企业级用户中心模块**，提供用户管理、角色权限、多场景登录等核心能力，旨在为业务系统提供安全、易扩展、易集成的身份与权限管理解决方案。

## 核心功能

### 🔐 认证授权
- 支持用户名密码登录
- 支持验证码登录
- 支持第三方登录（预留扩展接口）
- OAuth2 认证中心
- **支持 TOTP 多因子认证**（Google Authenticator、Microsoft Authenticator 等）

### 👥 用户管理
- 完整的用户 CRUD 操作
- 用户信息维护（基本信息、联系方式等）
- 用户状态管理（启用/禁用、锁定/解锁）

### 🎯 权限管理
- 角色创建与分配
- 资源权限控制
- 菜单权限配置
- 数据权限支持

### 📦 系统能力
- Redis 缓存优化
- Nacos 服务注册与配置
- MySQL 持久化存储
- Flyway 数据库版本管理
- Swagger API 文档自动生成

## 技术栈

| 技术栈               | 版本          | 用途                     |
|--------------------|-------------|------------------------|
| Spring Boot        | 2.3.12.RELEASE | 框架基础                  |
| Spring Security    | 5.3.10.RELEASE | 安全框架                  |
| Spring Cloud       | Hoxton.SR12   | 微服务框架                 |
| Spring Cloud Alibaba | 2.2.7.RELEASE | 服务注册与配置（Nacos）       |
| MyBatis Plus       | 3.4.3.1     | ORM 框架                 |
| Redis              | 5.0+        | 缓存服务                  |
| MySQL              | 5.7+        | 数据库                   |
| Flyway             | 5.2.4       | 数据库版本管理               |
| Swagger            | 2.9.2       | API 文档                  |
| Google Authenticator | 1.5.0     | TOTP 多因子认证库          |

## 快速开始

### 1. 环境要求
- JDK 8+
- Maven 3.3.9+
- MySQL 5.7+
- Redis 5.0+
- Nacos 1.4.1+（可选，用于服务注册与配置）

### 2. 配置修改
2.创建通用配置application-dev.yaml  Group 1.0.1
注意：application-dev.yaml文件名中的 dev 根据profile名称一致。

Nacos的 Group 信息 与 maven 中 version 字段一致。

```yaml
# Spring 相关
spring:
  http-client:
    pool:
      readTimeout: 20000
      retryTimes: 0
  cloud:
    inetutils:
      preferredNetworks:
        - 172. #这里可以是IP的全拼也可以是一部分.主要是用IP去匹配的
  redis:
    host: X.X.X.X
    port: 6379
    password: XXXXXX
    database: 0
    timeout: 10000
```

3.创建mole-user配置 mole-user.yaml Group 1.0.1
```yaml
server:
  port: 8600

security:
  oauth2:
    client:
      resourceId: ${spring.application.name}

spring:
  datasource:
    dynamic:
      #设置默认的数据源或者数据源组,默认值即为master
      primary: master
      #严格匹配数据源,默认false. true未匹配到指定数据源时抛异常,false使用默认数据源
      strict: false
      datasource:
        master:
          username: root
          password: Qrbrqj99
          url: jdbc:mysql://X.X.X.X:3306/mole-user?serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=utf-8&useSSL=false
          driver-class-name: com.mysql.cj.jdbc.Driver

# mybatis-plus输出日志配置
mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl

# 预制密钥
secret:
  preSecretKey: 01cc84fa3a7d7b413488011a3a934c98

# 消息配置
msg:
  smsCodeValidationEnabled: false

# 小程序配置
wechat:
  #微信小程序APP ID
  appId: XXXXXX
  #微信小程序APP SECRET
  appSecret: XXXXXX
  # 微信Token接口
  tokenUrl: https://api.weixin.qq.com/cgi-bin/stable_token
  # 根据code获取手机号接口
  codePhoneUrl: https://api.weixin.qq.com/wxa/business/getuserphonenumber?access_token=
  # 获取OpenId接口
  openIdUrl: https://api.weixin.qq.com/sns/jscode2session

ignore:
  urls:
    - /doc.html
    - /**/swagger-resources/**
    - /webjars/**
    - /v2/api-docs
```

项目启动时会加载通用配置application-dev.yaml 和 mole-user.yaml

### 3. 启动项目
```bash
# 方式一：直接运行
mvn spring-boot:run

# 方式二：打包运行
mvn clean package
java -jar target/mole-user-1.0.1.jar
```

### 4. 访问验证
- 服务访问地址：http://localhost:8600
- Swagger API 文档：http://localhost:8600/swagger-ui.html

## 项目结构

```
src/main/java/com/platform/mole/
├── MoleUserApplication.java      # 项目入口类，Spring Boot 应用启动器
├── auth/                         # 认证授权核心模块
│   ├── controller/              # 认证接口层，提供登录、验证码、令牌、MFA 相关 REST API
│   ├── exception/               # 认证异常体系，定义认证失败、令牌无效等业务异常
│   ├── model/                   # 认证数据模型，包括登录请求、令牌响应、第三方登录回调等
│   └── service/                 # 认证业务逻辑层，实现 OAuth2 认证、JWT 签发、用户身份验证、TOTP MFA 等核心功能
├── config/                       # 系统配置模块
│   ├── security/                # Spring Security 安全配置，包括 OAuth2 授权服务器、资源服务器、权限拦截器等
│   └── swagger/                 # Swagger API 文档配置，自动生成并展示接口信息
├── constants/                   # 系统常量定义，统一管理所有业务常量和错误码
└── user/                        # 用户与权限管理模块
    ├── controller/              # 用户权限接口层，提供用户 CRUD、角色分配、权限配置等 REST API
    ├── mapper/                  # 数据持久层，基于 MyBatis Plus 实现数据库访问
    ├── model/                   # 用户数据模型，包括用户实体、角色实体、权限实体等（已扩展支持 TOTP MFA 字段）
    └── service/                 # 用户业务逻辑层，实现用户管理、角色权限分配、数据权限控制等核心功能
```

## TOTP 多因子认证 API 文档

### 接口前缀
所有 MFA 接口的前缀为：`/auth/mfa`

### 1. 生成 TOTP 密钥和二维码
- **接口地址**: `POST /totp/generate`
- **请求方式**: POST
- **请求参数**: 无（需携带登录令牌）
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "操作成功",
    "data": {
      "secret": "JBSWY3DPEHPK3PXP",
      "qrCodeUrl": "otpauth://totp/Mole+Platform:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Mole+Platform",
      "otpAuthUrl": "otpauth://totp/Mole+Platform:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Mole+Platform"
    }
  }
  ```

### 2. 验证并启用 TOTP
- **接口地址**: `POST /totp/enable`
- **请求方式**: POST
- **请求参数**:
  ```json
  {
    "code": 123456  // 用户从 Authenticator 应用中获取的 TOTP 码
  }
  ```
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "TOTP认证器已启用",
    "data": true
  }
  ```

### 3. 禁用 TOTP
- **接口地址**: `POST /totp/disable`
- **请求方式**: POST
- **请求参数**: 无（需携带登录令牌）
- **响应示例**:
  ```json
  {
    "code": 200,
    "message": "TOTP认证器已禁用",
    "data": true
  }
  ```

### 4. MFA 登录
- **接口地址**: `/oauth/token`
- **请求方式**: POST
- **请求参数**:
  ```
  grant_type=mfa&username=admin&password=123456&totp_code=123456
  ```
- **响应示例**:
  ```json
  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "scope": "read write"
  }
  ```

## 配置说明

### 核心配置（bootstrap.yml）通用配置 根据profile自动填充
```yaml
spring:
  application:
    name: @artifactId@
  cloud:
    inetutils:
      preferredNetworks:
        - @preferredNetworks@
    nacos:
      discovery:
        server-addr: @nacos.host@:@nacos.port@
        namespace: @nacos.namespace@
        cluster-name: DEFAULT
        metadata:
          version: @version@
      config:
        server-addr: ${spring.cloud.nacos.discovery.server-addr}
        file-extension: yaml
        namespace: ${spring.cloud.nacos.discovery.namespace}
        group: @version@
        shared-configs:
          - data-id: application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}
            group: @version@
  profiles:
    active: @profiles.active@
```

## 开发规范

### 代码风格
- 遵循 Spring 官方代码规范
- 使用 Lombok 简化代码
- 方法参数超过 3 个时使用 DTO 封装

### 数据库规范
- 所有表名使用下划线命名
- 主键使用自增 ID
- 时间字段使用 `datetime` 类型
- 字段注释清晰

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/xxxx`)
3. 提交代码 (`git commit -m 'feature: 新增xxxx功能'`)
4. 推送到分支 (`git push origin feature/xxxx`)
5. 提交 Pull Request

## 许可证

[MIT License](LICENSE)