# ebox

**Repository Path**: yunnuo520/ebox

## Basic Information

- **Project Name**: ebox
- **Description**: 基于Springboot3的多模块快速开发框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-29
- **Last Updated**: 2025-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EBox Framework

EBox Framework 是一个基于 Spring Boot 3.5.4 和 Java 21 的通用多模块快速开发框架，专为 UniApp 小程序项目设计。框架采用模块化设计，解耦各业务模块，提供完整的开发解决方案。

## 🚀 技术栈

### 后端技术
- **基础框架**: Spring Boot 3.5.4
- **开发语言**: Java 21
- **数据库**: MySQL 8.0+
- **连接池**: Druid 1.2.23
- **ORM框架**: MyBatis-Flex 1.11.1
- **Redis**: Redisson 3.35.0
- **权限认证**: Sa-Token 1.39.0
- **API文档**: Knife4j 4.5.0
- **工具库**: Hutool 5.8.32
- **JSON处理**: FastJSON2 2.0.53

### 前端支持
- **管理端**: Vue.js
- **用户端**: UniApp 小程序
- **API文档**: 支持 Swagger/OpenAPI 3.0

## 📁 项目结构

```
ebox-framework/
├── ebox-common/          # 通用模块
│   ├── core/            # 核心类库 (R<T>、BaseEntity、BaseController)
│   ├── config/          # 配置类 (Sa-Token、全局异常处理)
│   ├── enums/           # 枚举类 (ResultCode状态码)
│   ├── exception/       # 异常处理
│   ├── service/         # 通用服务接口
│   └── utils/           # 工具类
├── ebox-system/         # 系统核心模块
│   ├── domain/          # 实体类 (SysUser、SysDept、SysRole)
│   ├── service/         # 业务层
│   ├── mapper/          # 数据层
│   └── controller/      # 控制层
├── ebox-client/         # 用户端模块 🆕
│   ├── domain/          # 用户端实体 (ClientUser)
│   ├── service/         # 用户端服务 (ClientLoginService - 支持微信登录)
│   └── controller/      # 用户端控制器 (ClientUserController)
├── ebox-generator/      # 代码生成模块 🆕
│   ├── config/          # 代码生成器配置
│   ├── controller/      # 代码生成控制器
│   ├── service/         # 代码生成服务
│   └── dto/            # 数据传输对象
├── ebox-starter/        # 启动模块
│   ├── config/          # 配置文件
│   └── resources/       # 资源文件 (多环境配置)
├── sql/                 # 数据库脚本
│   └── ebox.sql        # 完整的数据库初始化脚本
└── pom.xml             # 父级依赖管理
```

## ✨ 核心特性

### 1. 🔧 通用响应结果类 (R<T>) - 重新设计
- **状态码枚举**: 使用 `ResultCode` 枚举，支持易扩展的状态码管理
- **分类完整**: 包含成功、客户端错误、服务器错误、业务错误、用户相关、权限相关、管理端、用户端等全面的错误码分类
- **统一响应**: 所有API返回统一的JSON格式

### 2. 🌍 多环境配置支持
- **application.yml**: 主配置文件
- **application-dev.yml**: 开发环境配置
- **application-prod.yml**: 生产环境配置
- 支持环境变量，便于Docker部署

### 3. 👥 双端用户体系分离
- **管理端 (ebox-system)**:
  - 独立的 `SysUser` 实体和表结构
  - 管理员登录、权限验证
  - 完整的管理员用户CRUD操作
  - 部门树、角色授权等功能

- **用户端 (ebox-client)**:
  - 独立的 `ClientUser` 实体和表结构
  - 支持微信小程序登录
  - 用户注册、手机号/邮箱绑定
  - 积分系统、余额管理、签到功能
  - 用户等级、VIP体系

### 4. 🔐 Sa-Token权限认证
- **双端隔离**: 管理端和用户端使用不同的Token体系
- **路由拦截**: 自动拦截需要登录的接口
- **权限校验**: 细粒度的权限控制

### 5. 🗄️ MyBatis-Flex ORM
- **高性能**: 相比MyBatis Plus更轻量、更快速
- **代码生成**: 支持实体类和Mapper自动生成
- **灵活查询**: 支持复杂的条件查询构建

### 6. 📊 数据库连接优化
- **Druid连接池**: 高性能数据库连接池
- **SQL监控**: 内置SQL执行监控和统计
- **连接池监控**: 实时监控连接池状态

### 7. 🛠️ MyBatis-Flex 代码生成器 🆕
- **智能生成**: 基于数据库表结构自动生成 Entity、Mapper、Service、Controller
- **灵活配置**: 支持自定义包名、输出目录、生成策略等
- **API 支持**: 提供 REST API 接口，支持在线代码生成
- **表信息查询**: 可查询数据库表结构和字段信息
- **模板定制**: 支持 Swagger 注解、Lombok 注解等

## 🛠️ 快速开始

### 环境要求
- JDK 21+
- Maven 3.6+
- MySQL 8.0+
- Redis 5.0+

### 1. 克隆项目
```bash
git clone <repository-url>
cd ebox-framework
```

### 2. 数据库初始化
```sql
-- 创建数据库
CREATE DATABASE ebox DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 导入初始化脚本
source sql/ebox.sql
```

### 3. 配置文件
复制并修改配置文件：
```bash
# 开发环境
cp ebox-starter/src/main/resources/application-dev.yml.example ebox-starter/src/main/resources/application-dev.yml

# 生产环境  
cp ebox-starter/src/main/resources/application-prod.yml.example ebox-starter/src/main/resources/application-prod.yml
```

### 4. 编译运行
```bash
# 编译项目
mvn clean install

# 启动项目
cd ebox-starter
mvn spring-boot:run
```

### 5. 访问应用
- **健康检查**: http://localhost:8123/health
- **API文档**: http://localhost:8123/doc.html
- **管理端接口**: http://localhost:8123/admin/user/list
- **用户端接口**: http://localhost:8123/client/user/info
- **Druid监控**: http://localhost:8123/druid/

## 📋 API接口说明

### 管理端接口 (/admin/*)
- `POST /admin/user/login` - 管理员登录
- `POST /admin/user/logout` - 退出登录
- `GET /admin/user/info` - 获取当前管理员信息
- `GET /admin/user/list` - 管理员列表
- `POST /admin/user` - 新增管理员
- `PUT /admin/user` - 修改管理员
- `DELETE /admin/user/{userIds}` - 删除管理员

### 用户端接口 (/client/*)
- `POST /client/user/login` - 用户登录
- `POST /client/user/wechat-login` - 微信登录
- `POST /client/user/register` - 用户注册
- `POST /client/user/logout` - 退出登录
- `GET /client/user/info` - 获取当前用户信息
- `PUT /client/user/profile` - 更新用户资料
- `POST /client/user/checkin` - 每日签到
- `GET /client/user/points/records` - 积分记录

### 代码生成接口 (/admin/generator/*) 🆕
- `GET /admin/generator/tables` - 获取数据库表列表
- `GET /admin/generator/table/{tableName}` - 获取表详细信息
- `POST /admin/generator/generate` - 生成代码
- `POST /admin/generator/preview` - 预览生成配置

## 🛠️ 代码生成器使用指南

### 1. 代码生成器配置

可在 `application.yml` 中配置代码生成器的默认参数：

```yaml
ebox:
  generator:
    # 是否启用代码生成器
    enabled: true
    
    # 作者名称
    author: "允诺"
    
    # 基础包名
    package-name: "vip.ebox"
    
    # 生成文件的输出目录
    output-dir: "./src/main/java"
    
    # 是否覆盖已存在的文件
    file-override: false
    
    # 是否生成 Service 层
    enable-service: true
    
    # 是否生成 Controller 层
    enable-controller: true
    
    # 是否启用 Swagger 注解
    enable-swagger: true
    
    # 是否启用 Lombok 注解
    enable-lombok: true
    
    # 表前缀，生成时会移除前缀
    table-prefix:
      - "sys_"
      - "t_"
```

### 2. 使用 API 生成代码

#### 获取数据库表列表
```bash
GET /admin/generator/tables?tableName=sys_
```

#### 生成代码
```bash
POST /admin/generator/generate
Content-Type: application/json

{
  "tableNames": ["sys_user", "sys_role"],
  "packageName": "vip.ebox.system",
  "author": "允诺",
  "enableService": true,
  "enableController": true,
  "enableSwagger": true,
  "enableLombok": true,
  "tablePrefix": ["sys_"]
}
```

### 3. 生成的代码结构

生成的代码将按照以下结构组织：

```
src/main/java/vip/ebox/system/
├── domain/           # 实体类
│   ├── SysUser.java
│   └── SysRole.java
├── mapper/           # MyBatis Mapper 接口
│   ├── SysUserMapper.java
│   └── SysRoleMapper.java
├── service/          # Service 接口
│   ├── SysUserService.java
│   └── SysRoleService.java
├── service/impl/     # Service 实现类
│   ├── SysUserServiceImpl.java
│   └── SysRoleServiceImpl.java
└── controller/       # REST 控制器
    ├── SysUserController.java
    └── SysRoleController.java
```

### 4. 生成代码特性

- **实体类**: 自动生成 `@Data`、`@Builder` 等 Lombok 注解
- **Swagger 注解**: 自动添加 `@Schema` 注解用于 API 文档生成
- **MyBatis-Flex**: 使用 MyBatis-Flex 的注解和特性
- **统一响应**: Controller 自动使用框架的统一响应格式 `R<T>`
- **基础 CRUD**: 自动生成增删改查的基础方法

## 🔧 配置说明

### 数据库配置 (application-dev.yml)

**重要提示**：请根据您的实际数据库环境修改以下配置

#### 动态数据源配置（推荐）

```yaml
spring:
  datasource:
    dynamic:
      # 设置默认的数据源或者数据源组，默认值即为 master
      primary: master
      # 严格模式,默认false. 启动后会检查数据源连接状况
      strict: false
      datasource:
        master:
          type: com.alibaba.druid.pool.DruidDataSource
          driver-class-name: com.mysql.cj.jdbc.Driver
          # 本地数据库配置（默认）
          url: jdbc:mysql://localhost:3306/ebox?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8
          username: root
          password: 123456
          druid:
            initial-size: 1
            min-idle: 1
            max-active: 20
            # 其他连接池配置...
```

#### 简单数据源配置（备选方案）

如果动态数据源配置有问题，可以使用简单配置：

```yaml
spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/ebox?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8
    username: root
    password: 123456
    druid:
      initial-size: 1
      min-idle: 1
      max-active: 20
```

**如果您使用远程数据库**，请修改URL、用户名和密码。

### 数据库连接问题排查

如果遇到 `SQLException: Unknown error 1045` 错误，请检查：

1. **数据库服务是否启动**
2. **用户名密码是否正确**
3. **数据库 `ebox` 是否已创建**
4. **用户是否有访问权限**
5. **如果使用动态数据源，检查配置格式是否正确**

**创建数据库的SQL命令**：
```sql
CREATE DATABASE ebox DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

**常见问题解决方案**：
- 如果动态数据源启动失败，可以临时注释掉 `ebox-common/pom.xml` 中的 `dynamic-datasource-spring-boot3-starter` 依赖
- 检查 MySQL 服务是否运行：`brew services list | grep mysql` (macOS) 或 `systemctl status mysql` (Linux)
- 验证数据库连接：`mysql -u root -p -h localhost -P 3306`

### Redis配置
```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: your_password
      database: 0
```

### Sa-Token权限配置
框架已预配置Sa-Token，支持：
- 管理端和用户端Token隔离
- 自动路由拦截
- JWT Token支持

## 📝 数据库设计

### 用户表结构
- **sys_user**: 系统用户表 (保留兼容性)
- **admin_user**: 管理员用户表 (独立)
- **client_user**: 客户用户表 (独立，支持微信登录)

### 系统表结构
- **sys_dept**: 部门表
- **sys_role**: 角色表

## 🎯 开发指南

### 1. 新增模块
```bash
# 在父POM中添加新模块
<modules>
    <module>ebox-your-module</module>
</modules>

# 在dependencyManagement中声明
<dependency>
    <groupId>vip.ebox</groupId>
    <artifactId>ebox-your-module</artifactId>
    <version>${project.version}</version>
</dependency>
```

### 2. 使用统一响应
```java
// 成功响应
return R.ok(data, "操作成功");

// 失败响应  
return R.fail(ResultCode.USER_NOT_EXIST);

// 自定义响应
return R.fail(4001, "自定义错误信息");
```

### 3. 权限控制
```java
// 在Controller中使用Sa-Token
@SaCheckLogin  // 需要登录
@SaCheckRole("admin")  // 需要admin角色
@SaCheckPermission("user:add")  // 需要特定权限
```

## 🔄 版本历史

### v1.0.0 (当前版本)
- ✅ 基础框架搭建 (Spring Boot 3.5.4 + Java 21)
- ✅ 移除PageHelper，集成MyBatis-Flex
- ✅ 重新设计统一响应结果类 (R<T>) 和状态码 (ResultCode)
- ✅ 实现多环境配置支持 (dev/prod)
- ✅ 管理端和用户端双用户体系分离
- ✅ Sa-Token权限认证集成
- ✅ 微信登录支持
- ✅ 完整的数据库初始化脚本

## 🤝 贡献指南

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

## 📄 许可证

该项目使用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 👨‍💻 作者

**允诺** - [ebox.vip](https://ebox.vip)

---

如有问题或建议，请提交 Issue 或联系作者。