版本：Next

epoch-app-core - 应用核心模块

1. 模块概述

epoch-app-core 是 epoch-boot 的应用核心模块，提供了应用开发所需的基础功能支持，包括用户认证、权限管理、日志管理等。该模块是其他业务模块的基础，所有业务模块都依赖于该模块。

2. 模块结构

epoch-app-core/
├── auth/              # 认证授权
├── config/            # 配置管理
├── entity/            # 实体类
├── enums/             # 枚举类
├── exception/         # 异常处理
├── mapper/            # Mapper 接口
├── service/           # 服务层
├── utils/             # 工具类
└── vo/                # 视图对象

3. 核心功能

3.1 认证与授权 (auth)

提供用户认证与授权功能，基于 Sa-Token 实现，支持 JWT、Cookie 等认证方式。

主要功能：

用户登录与登出
角色认证
权限验证
JWT 令牌生成与验证
会话管理
记住我功能

使用示例：

// 用户登录
@PostMapping("/login")
public ResponseResult login(@RequestBody LoginRequest request) {
    // 验证用户名和密码
    User user = userService.validateUser(request.getUsername(), request.getPassword());
    
    // 生成令牌
    String token = authService.login(user);
    
    // 返回令牌
    return ResponseResult.success("登录成功", token);
}

// 权限验证
@PreAuth("hasPermission('system:user:list')")
@GetMapping("/user/list")
public ResponseResult listUser() {
    // 获取用户列表
    List<User> userList = userService.list();
    return ResponseResult.success(userList);
}

3.2 用户管理

提供用户信息管理功能，包括用户的增删改查、密码修改等。

主要功能：

用户信息查询
用户信息添加
用户信息修改
用户信息删除
密码修改
用户状态管理

使用示例：

// 获取当前用户信息
@GetMapping("/user/current")
public ResponseResult getCurrentUser() {
    Long userId = UserUtils.getCurrentUserId();
    User user = userService.getById(userId);
    return ResponseResult.success(user);
}

// 修改用户信息
@PutMapping("/user")
public ResponseResult updateUser(@RequestBody UserRequest request) {
    userService.updateUser(request);
    return ResponseResult.success("用户信息修改成功");
}

3.3 角色管理

提供角色信息管理功能，包括角色的增删改查、权限分配等。

主要功能：

角色信息查询
角色信息添加
角色信息修改
角色信息删除
角色权限分配

使用示例：

// 获取角色列表
@GetMapping("/role/list")
public ResponseResult listRole() {
    List<Role> roleList = roleService.list();
    return ResponseResult.success(roleList);
}

// 分配角色权限
@PostMapping("/role/assignPermission")
public ResponseResult assignPermission(@RequestBody RolePermissionRequest request) {
    roleService.assignPermission(request.getRoleId(), request.getPermissionIds());
    return ResponseResult.success("权限分配成功");
}

3.4 权限管理

提供权限信息管理功能，包括权限的增删改查、权限验证等。

主要功能：

权限信息查询
权限信息添加
权限信息修改
权限信息删除
权限验证

使用示例：

// 检查用户是否有权限
if (permissionService.hasPermission(userId, "system:user:add")) {
    // 执行添加用户操作
}

3.5 日志管理

提供系统日志管理功能，包括操作日志、登录日志、异常日志等。

主要功能：

操作日志记录
登录日志记录
异常日志记录
日志查询
日志导出

使用示例：

// 记录操作日志
@OperationLog("添加用户")
@PostMapping("/user")
public ResponseResult addUser(@RequestBody UserRequest request) {
    userService.addUser(request);
    return ResponseResult.success("用户添加成功");
}

3.6 系统配置管理

提供系统配置管理功能，支持动态配置系统参数。

主要功能：

系统配置查询
系统配置修改
配置缓存管理

使用示例：

// 获取系统配置
String configValue = systemConfigService.getConfigValue("system.title");

// 修改系统配置
SystemConfigRequest request = new SystemConfigRequest();
request.setKey("system.title");
request.setValue("Epoch 管理系统");
systemConfigService.updateConfig(request);

3.7 数据权限控制

提供数据权限控制功能，支持基于角色的数据访问控制。

主要功能：

数据权限规则定义
数据权限验证
数据过滤

使用示例：

// 查询用户列表，自动应用数据权限过滤
List<User> userList = userService.listWithDataPermission();

4. 设计理念

4.1 基于权限的访问控制

采用 RBAC (Role-Based Access Control) 模型，实现基于角色的权限管理，支持细粒度的权限控制。

4.2 可扩展性

提供扩展点和配置选项，支持自定义认证方式、权限规则等。

4.3 安全可靠

基于成熟的安全框架 Sa-Token 实现，确保认证和授权的安全性。

4.4 易用性

提供简洁的 API 和自动配置，减少使用成本，提高开发效率。

5. 使用指南

5.1 引入依赖

<dependency>
    <groupId>com.epoch</groupId>
    <artifactId>epoch-app-core</artifactId>
    <version>${epoch.version}</version>
</dependency>

5.2 配置说明

在 application.yml 中配置相关参数：

# Sa-Token 配置
sa-token:
  token-name: Authorization
  timeout: 3600
  activity-timeout: 3600
  is-concurrent: true
  is-share: false
  token-style: jwt
  jwt-secret-key: epoch-secret-key

# 系统配置
epoch:
  app:
    title: Epoch 管理系统
    version: 3.4.0
    description: Epoch 企业级应用开发平台

5.3 启动应用

在 Spring Boot 应用的启动类上添加 @EnableEpochAppCore 注解：

@SpringBootApplication
@EnableEpochAppCore
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

6. 扩展机制

6.1 自定义认证方式

可以通过实现 AuthService 接口自定义认证方式：

@Component
public class CustomAuthService implements AuthService {
    @Override
    public String login(User user) {
        // 自定义登录逻辑
        return "custom-token";
    }
    
    @Override
    public void logout() {
        // 自定义登出逻辑
    }
}

6.2 自定义权限规则

可以通过实现 PermissionService 接口自定义权限规则：

@Component
public class CustomPermissionService implements PermissionService {
    @Override
    public boolean hasPermission(Long userId, String permission) {
        // 自定义权限验证逻辑
        return true;
    }
}

7. 版本变更

7.1 主要变更

3.4.0：
- 升级 Sa-Token 到 1.44.0
- 优化认证流程，提高安全性
- 新增数据权限控制功能
- 完善日志管理功能
3.3.0：
- 重构认证模块，支持 JWT 认证
- 优化权限管理功能，支持更细粒度的权限控制
- 新增系统配置管理功能
3.2.0：
- 初始版本，提供用户认证、权限管理、日志管理等基础功能

8. 常见问题

8.1 如何自定义登录逻辑？

可以通过实现 AuthService 接口自定义登录逻辑：

@Component
public class CustomAuthService implements AuthService {
    @Override
    public String login(User user) {
        // 自定义登录逻辑
        return "custom-token";
    }
}

8.2 如何实现数据权限控制？

可以通过实现 DataPermissionService 接口自定义数据权限规则：

@Component
public class CustomDataPermissionService implements DataPermissionService {
    @Override
    public String getDataPermissionSql(Long userId, String tableAlias) {
        // 自定义数据权限 SQL
        return " and " + tableAlias + ".create_user_id = " + userId;
    }
}

8.3 如何配置 JWT 密钥？

在 application.yml 中配置：

sa-token:
  jwt-secret-key: your-secret-key

8.4 如何修改令牌过期时间？

在 application.yml 中配置：

sa-token:
  timeout: 7200 # 令牌过期时间，单位：秒

8.5 如何记录操作日志？

使用 @OperationLog 注解：

@OperationLog("添加用户")
@PostMapping("/user")
public ResponseResult addUser(@RequestBody UserRequest request) {
    userService.addUser(request);
    return ResponseResult.success("用户添加成功");
}

9. 安全建议

使用 HTTPS 协议：确保所有 API 请求都通过 HTTPS 协议传输，防止数据泄露
定期更换密钥：定期更换 JWT 密钥，提高系统安全性
设置合理的令牌过期时间：根据业务需求设置合理的令牌过期时间，平衡安全性和用户体验
使用强密码策略：实施强密码策略，要求用户使用包含大小写字母、数字和特殊字符的密码
限制登录尝试次数：限制同一账号的登录尝试次数，防止暴力破解
定期清理无效会话：定期清理无效的用户会话，释放系统资源

10. 性能优化

缓存优化：将用户信息、角色信息、权限信息等频繁访问的数据缓存到 Redis 中，减少数据库查询
SQL 优化：优化数据库查询语句，使用索引提高查询效率
批量操作：对于批量数据操作，使用批量插入、更新等方式，减少数据库交互次数
异步处理：对于非实时性要求高的操作，如日志记录，使用异步处理方式，提高响应速度

11. 监控与维护

登录监控：监控用户登录情况，及时发现异常登录行为
权限监控：监控权限使用情况，及时发现异常权限访问
性能监控：监控系统性能，包括响应时间、并发数等，及时发现性能瓶颈
日志分析：定期分析系统日志，及时发现系统问题和安全隐患

1. 模块概述​

2. 模块结构​

3. 核心功能​

3.1 认证与授权 (auth)​

3.2 用户管理​

3.3 角色管理​

3.4 权限管理​

3.5 日志管理​

3.6 系统配置管理​

3.7 数据权限控制​

4. 设计理念​

4.1 基于权限的访问控制​

4.2 可扩展性​

4.3 安全可靠​

4.4 易用性​

5. 使用指南​

5.1 引入依赖​

5.2 配置说明​

5.3 启动应用​

6. 扩展机制​

6.1 自定义认证方式​

6.2 自定义权限规则​

7. 版本变更​

7.1 主要变更​

8. 常见问题​

8.1 如何自定义登录逻辑？​

8.2 如何实现数据权限控制？​

8.3 如何配置 JWT 密钥？​

8.4 如何修改令牌过期时间？​

8.5 如何记录操作日志？​

9. 安全建议​

10. 性能优化​

11. 监控与维护​

1. 模块概述

2. 模块结构

3. 核心功能

3.1 认证与授权 (auth)

3.2 用户管理

3.3 角色管理

3.4 权限管理

3.5 日志管理

3.6 系统配置管理

3.7 数据权限控制

4. 设计理念

4.1 基于权限的访问控制

4.2 可扩展性

4.3 安全可靠

4.4 易用性

5. 使用指南

5.1 引入依赖

5.2 配置说明

5.3 启动应用

6. 扩展机制

6.1 自定义认证方式

6.2 自定义权限规则

7. 版本变更

7.1 主要变更

8. 常见问题

8.1 如何自定义登录逻辑？

8.2 如何实现数据权限控制？

8.3 如何配置 JWT 密钥？

8.4 如何修改令牌过期时间？

8.5 如何记录操作日志？

9. 安全建议

10. 性能优化

11. 监控与维护