From 3cb5241878cecea3c7aeb4a0f89dc5749f327d51 Mon Sep 17 00:00:00 2001 From: Leo Date: Wed, 8 Oct 2025 02:04:57 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=B7=BB=E5=8A=A0Maven=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E5=92=8C=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加Maven父POM，定义所有依赖版本 - 配置6个子模块结构 - 添加开发规范文档CLAUDE.md - 配置IDEA项目设置 --- .gitignore | 49 +++ .idea/.gitignore | 8 + .idea/ApifoxUploaderProjectSetting.xml | 15 + .idea/dataSources.xml | 17 + .idea/encodings.xml | 79 +++++ .idea/git_toolbox_blame.xml | 6 + .idea/inspectionProfiles/Project_Default.xml | 72 +++++ .idea/misc.xml | 16 + .idea/vcs.xml | 6 + CLAUDE.md | 320 +++++++++++++++++++ pom.xml | 294 +++++++++++++++++ 11 files changed, 882 insertions(+) create mode 100644 .gitignore create mode 100644 .idea/.gitignore create mode 100644 .idea/ApifoxUploaderProjectSetting.xml create mode 100644 .idea/dataSources.xml create mode 100644 .idea/encodings.xml create mode 100644 .idea/git_toolbox_blame.xml create mode 100644 .idea/inspectionProfiles/Project_Default.xml create mode 100644 .idea/misc.xml create mode 100644 .idea/vcs.xml create mode 100644 CLAUDE.md create mode 100644 pom.xml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e0e4af8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +target/ +!.mvn/wrapper/maven-wrapper.jar +!**/src/main/**/target/ +!**/src/test/**/target/ + +### IntelliJ IDEA ### +.idea/modules.xml +.idea/jarRepositories.xml +.idea/compiler.xml +.idea/libraries/ +*.iws +*.iml +*.ipr + +### Eclipse ### +.apt_generated +.classpath +.factorypath +.project +.settings +.springBeans +.sts4-cache + +### NetBeans ### +/nbproject/private/ +/nbbuild/ +/dist/ +/nbdist/ +/.nb-gradle/ +build/ +!**/src/main/**/build/ +!**/src/test/**/build/ + +### VS Code ### +.vscode/ + +### Mac OS ### +.DS_Store + +### Logs ### +logs/ +/logs/ +spy.log + +### Upload Files ### +picture/ + +### Local Configuration Files ### +**/application-local.yml diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 0000000..13566b8 --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,8 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Editor-based HTTP Client requests +/httpRequests/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml diff --git a/.idea/ApifoxUploaderProjectSetting.xml b/.idea/ApifoxUploaderProjectSetting.xml new file mode 100644 index 0000000..30ac844 --- /dev/null +++ b/.idea/ApifoxUploaderProjectSetting.xml @@ -0,0 +1,15 @@ + + + + + + \ No newline at end of file diff --git a/.idea/dataSources.xml b/.idea/dataSources.xml new file mode 100644 index 0000000..c3314f1 --- /dev/null +++ b/.idea/dataSources.xml @@ -0,0 +1,17 @@ + + + + + mysql.8 + true + com.mysql.cj.jdbc.Driver + jdbc:mysql://localhost:3306/coder-common-thin + + + + + + $ProjectFileDir$ + + + \ No newline at end of file diff --git a/.idea/encodings.xml b/.idea/encodings.xml new file mode 100644 index 0000000..0e41fa6 --- /dev/null +++ b/.idea/encodings.xml @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/git_toolbox_blame.xml b/.idea/git_toolbox_blame.xml new file mode 100644 index 0000000..7dc1249 --- /dev/null +++ b/.idea/git_toolbox_blame.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml new file mode 100644 index 0000000..0b4782f --- /dev/null +++ b/.idea/inspectionProfiles/Project_Default.xml @@ -0,0 +1,72 @@ + + + + \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 0000000..a2da2e7 --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,16 @@ + + + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 0000000..94a25f7 --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c814987 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,320 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +### 第一部分：核心编程原则 (Guiding Principles) +这是我们合作的顶层思想，指导所有具体的行为。 +可读性优先 (Readability First)：始终牢记“代码是写给人看的，只是恰好机器可以执行”。清晰度高于一切。 +DRY (Don't Repeat Yourself)：绝不复制代码片段。通过抽象（如函数、类、模块）来封装和复用通用逻辑。 +高内聚，低耦合 (High Cohesion, Low Coupling)：功能高度相关的代码应该放在一起（高内聚），而模块之间应尽量减少依赖（低耦合），以增强模块独立性和可维护性。 + +### 第二部分：具体执行指令 (Actionable Instructions) +这是 Claude 在日常工作中需要严格遵守的具体操作指南。 +沟通与语言规范 +默认语言：请默认使用简体中文进行所有交流、解释和思考过程的陈述。 +代码与术语：所有代码实体（变量名、函数名、类名等）及技术术语（如库名、框架名、设计模式等）必须保持英文原文。 +注释规范：代码注释应使用中文。 +行尾注释禁令 (End-of-Line Comment Prohibition)：严格禁止在代码行末尾添加注释（如 `code; // 注释`）。所有单行注释必须在代码行前面单独占一行，格式为： +```java +// 设置文件访问路径 +String fileUploadPath = (String) fileMap.get("fileUploadPath"); +``` +这确保代码的简洁性和可读性，避免行尾注释造成的视觉干扰。 + +方法注释规范 (Method Comment Standard)：所有新增的Java文件中的方法都必须添加方法注释，格式为： +```java +/** + * @description [功能描述] + * @author Leocoder + */ +``` +此规范适用于： +- 所有public方法 +- 所有private方法 +- 所有protected方法 +- 接口方法 +- 抽象方法 +- 静态方法 + +示例： +```java +/** + * @description [上传文件到阿里云OSS] + * @author Leocoder + */ +public Map uploadFile(MultipartFile file, String fileName, String folderPath) { + // 方法实现 +} +``` +批判性反馈与破框思维 (Critical Feedback & Out-of-the-Box Thinking)： +审慎分析：必须以审视和批判的眼光分析我的输入，主动识别潜在的问题、逻辑谬误或认知偏差。 +坦率直言：需要明确、直接地指出我思考中的盲点，并提供显著超越我当前思考框架的建议，以挑战我的预设。 +严厉质询 (Tough Questioning)：当我提出的想法或方案明显不合理、过于理想化或偏离正轨时，必须使用更直接、甚至尖锐的言辞进行反驳和质询，帮我打破思维定式，回归理性。 +开发与调试策略 (Development & Debugging Strategy) +坚韧不拔的解决问题 (Tenacious Problem-Solving)：当面对编译错误、逻辑不通或多次尝试失败时，绝不允许通过简化或伪造实现来“绕过”问题。 +逐个击破 (Incremental Debugging)：必须坚持对错误和问题进行逐一分析、定位和修复。 + +### 探索有效替代方案 (Explore Viable Alternatives)：如果当前路径确实无法走通，应切换到另一个逻辑完整、功能健全的替代方案来解决问题，而不是退回到一个简化的、虚假的版本。 +禁止伪造实现 (No Fake Implementations)：严禁使用占位符逻辑（如空的循环）、虚假数据或不完整的函数来伪装功能已经实现。所有交付的代码都必须是意图明确且具备真实逻辑的。 +战略性搁置 (Strategic Postponement)：只有当一个问题被证实非常困难，且其当前优先级不高时，才允许被暂时搁置。搁置时，必须以 TODO 形式在代码中或任务列表中明确标记，并清晰说明遇到的问题。在核心任务完成后，必须回过头来重新审视并解决这些被搁置的问题。 +规范化测试文件管理 (Standardized Test File Management)：严禁为新功能在根目录或不相关位置创建孤立的测试文件。在添加测试时，必须首先检查项目中已有的测试套件（通常位于 tests/ 目录下），并将新的测试用例整合到与被测模块最相关的现有测试文件中。只有当确实没有合适的宿主文件时，才允许在 tests/ 目录下创建符合项目命名规范的新测试文件。 +项目与代码维护 (Project & Code Maintenance) +统一文档维护 (Unified Documentation Maintenance)：严禁为每个独立任务（如重构、功能实现）创建新的总结文档（例如 CODE_REFACTORING_SUMMARY.md）。在任务完成后，必须优先检查项目中已有的相关文档（如 README.md、既有的设计文档等），并将新的总结、变更或补充内容直接整合到现有文档中，维护其完整性和时效性。 +及时清理 (Timely Cleanup)：在完成开发任务时，如果发现任何已无用（过时）的代码、文件或注释，应主动提出清理建议。 + +## 常用命令 + +### 构建和运行 +```bash +# 编译整个项目 +mvn clean compile + +# 打包项目 +mvn clean package + +# 运行应用程序 +cd heritage-web +mvn spring-boot:run + +# 或者运行打包后的jar +java -jar heritage-web/target/heritage-web-1.0.0.jar +``` + +### 测试 +```bash +# 运行所有测试 +mvn test + +# 运行单个模块测试 +mvn test -pl heritage-web +``` + +### 数据库 +```bash +# 数据库初始化SQL位于 +# sql/heritage.sql +``` + +## 项目架构概览 + +这是一个基于Spring Boot 3.5.0的多模块企业级开发框架，采用插件化架构设计。 + +### 模块结构 +- **heritage-web**: Web启动模块，应用程序入口点 +- **heritage-common**: 公共工具模块，包含大量工具类、配置类和拦截器 +- **heritage-model**: 数据模型模块，包含POJO、BO、VO和数据验证 +- **heritage-mybatisplus**: 数据访问层模块，MyBatis Plus配置和Mapper +- **heritage-modules**: 业务模块容器 +- **heritage-plugins**: 插件模块，包含各种功能插件 + +### 插件化架构 +项目采用@Enable注解实现功能模块的可插拔配置： +- `@EnableCoderSaToken`: Sa-Token认证插件 +- `@EnableCoderEasyExcel`: Excel处理插件 +- `@EnableCoderLimit`: 限流插件 +- `@EnableCoderRepeatSubmit`: 防重提交插件 +- `@EnableCoderDesensitize`: 数据脱敏插件 + +### 技术栈 +- **核心框架**: Spring Boot 3.5.0 + Java 17 +- **数据库**: MySQL 9.3.0 + MyBatis Plus 3.5.12 +- **缓存**: Redis（Spring Data Redis） +- **安全认证**: Sa-Token 1.43.0 +- **工具库**: Hutool 5.8.38, Fastjson2 2.0.57, Guava 33.4.8 +- **业务功能**: EasyExcel 4.0.3, Easy-Captcha 1.6.2 + +### 数据层设计 +- **主键策略**: 雪花算法（ASSIGN_ID） +- **逻辑删除**: 0-已删除, 1-未删除 +- **多数据源**: 支持master/slave数据源动态切换 +- **SQL监控**: 集成P6spy进行SQL性能监控 + +### 配置文件 +- **主配置**: `application.yml` +- **环境配置**: `application-dev.yml` +- **数据库配置**: 支持MySQL主从配置 +- **Redis配置**: 使用Jackson2序列化，支持连接池 + +## 开发指南 + +### 添加新功能插件 +1. 在`heritage-plugins`下创建新模块 +2. 创建@Enable注解用于启用插件 +3. 实现必要的配置类和工具类 +4. 在主启动类上使用@Enable注解启用 + +### 数据访问层开发 +1. 实体类放在`heritage-model/domain/pojo` +2. Mapper接口放在`heritage-mybatisplus/mapper` +3. XML映射文件放在`resources/mapper` +4. 使用`@DS("dataSourceName")`注解切换数据源 + +### 业务层开发规范 +1. **依赖注入规范**: 所有ServiceImpl实现类必须使用`@RequiredArgsConstructor`构造器注入模式，禁止使用`@Autowired`字段注入 + - 在类上添加`@RequiredArgsConstructor`注解 + - 将需要注入的依赖声明为`private final`字段 + - Spring会自动通过构造器注入依赖 + +2. **Service分层规范**: Service层必须按功能模块分目录组织，不允许使用单一的impl目录 + - 每个功能模块创建独立目录（如：courseselection、courseoffering、coursecart） + - 在各功能目录下放置对应的Service接口和ServiceImpl实现类 + - 包路径示例：`org.leocoder.course.education.service.courseselection.SysCourseSelectionService` + +3. **Controller路径规范**: 所有Controller必须使用统一的`/coder`前缀作为API根路径 + - 所有Controller的`@RequestMapping`必须以`/coder`开头 + - 路径格式：`/coder/模块名/功能名` + - 示例路径：`/coder/education/selection`、`/coder/education/offering`、`/coder/education/cart` + - 参考示例：`@RequestMapping("/coder/education/selection")` + +4. **Controller权限验证规范**: 所有Controller的接口方法必须配置权限验证 + - **强制要求**: 每个Controller方法都必须添加`@SaCheckPermission`注解 + - **导入依赖**: 在Controller类中导入`import cn.dev33.satoken.annotation.SaCheckPermission;` + - **权限命名规范**: 使用格式`模块名:功能名:操作名` + - 教育模块示例：`@SaCheckPermission("education:selection:list")` + - 系统模块示例：`@SaCheckPermission("system:user:list")` + - **操作名对应关系**: + - `list` - 查询列表 + - `page` - 分页查询 + - `detail` - 查询详情 + - `add` - 新增 + - `edit` - 修改 + - `delete` - 删除 + - `status` - 状态变更 + - `import` - 导入 + - `export` - 导出 + - **示例代码**: + ```java + @RestController + @RequestMapping("/coder/education/selection") + public class SysCourseSelectionController { + + @SaCheckPermission("education:selection:list") + @GetMapping("/list") + public List list(@Validated CourseSelectionBo bo) { + // 业务逻辑 + } + + @SaCheckPermission("education:selection:add") + @PostMapping("/add") + public String add(@Validated CourseSelectionBo bo) { + // 业务逻辑 + } + } + ``` + - **禁止行为**: + - 严禁创建没有权限验证的Controller方法 + - 严禁在Sa-Token配置中添加业务接口的排除路径 + - 严禁通过其他方式绕过权限验证 + +5. **Controller接口文档规范**: 所有Controller必须配置Swagger注解以生成规范的中文接口文档 + - **强制要求**: 每个Controller类和方法都必须添加完整的Swagger注解 + - **类级别注解**: 必须添加`@Tag(name = "中文模块名", description = "详细描述")` + - **方法级别注解**: 必须添加`@Operation(summary = "中文接口名", description = "详细功能描述")` + - **必要导入**: 在Controller类中导入： + ```java + import io.swagger.v3.oas.annotations.Operation; + import io.swagger.v3.oas.annotations.tags.Tag; + ``` + - **依赖配置**: 使用Swagger注解的模块必须在pom.xml中添加SpringDoc依赖： + ```xml + + + org.springdoc + springdoc-openapi-starter-webmvc-ui + + ``` + - **标准示例**: + ```java + @Tag(name = "定时任务管理", description = "系统定时任务的增删改查和执行控制") + @RestController + @RequestMapping("/coder") + public class SysJobController { + + @Operation(summary = "分页查询定时任务", description = "根据查询条件分页获取系统定时任务列表") + @SaCheckPermission("monitor:job:list") + @GetMapping("/sysJob/listPage") + public IPage listPage(SysJobVo vo) { + // 业务逻辑 + } + } + ``` + - **接口文档效果**: 正确配置后，接口文档将显示中文模块名和接口名，而不是英文类名和方法名 + - **禁止行为**: + - 严禁创建没有Swagger注解的Controller + - 严禁使用英文summary和description + - 严禁在缺少SpringDoc依赖的模块中使用Swagger注解 + +### 工具类使用 +项目提供了丰富的工具类，位于`heritage-common/utils`： +- **缓存工具**: `RedisUtil`, `LocalCacheUtil` +- **日期工具**: `DateUtil`, `CalendarUtil` +- **文件工具**: `FileUtil`, `UploadUtil`, `ZipUtil` +- **字符串工具**: `StringUtil`, `ConvertUtil` +- **IP工具**: `IpUtil`, `IpAddressUtil` +- **JSON工具**: `JsonUtil` +- **加密工具**: `MD5Util`, `CoderPasswordUtil` + +### 配置说明 +- **端口**: 默认18099，可通过`port`环境变量覆盖 +- **文件路径**: 在`application-dev.yml`中配置`coder.filePath` +- **数据库连接**: 在`application-dev.yml`中配置数据源信息 +- **Redis配置**: 在`application-dev.yml`中配置Redis连接信息 + +### 日志配置 +- **日志文件**: `logback-spring.xml` +- **日志级别**: 可通过环境变量调整 +- **操作日志**: 自动记录，支持异步处理和定时清理 + +## 注意事项 + +- 项目基于Java 17，确保开发环境版本匹配 +- 使用中文注释，保持代码风格一致 +- 新增功能遵循插件化设计模式 +- 数据库操作优先使用MyBatis Plus提供的方法 +- 安全认证统一使用Sa-Token，避免重复造轮子 +- 工具类使用前先检查是否已有现成实现 + +## 重要规范文档 + +- 所有Controller必须配置权限验证（强制要求） +- 使用统一的路径前缀和权限命名规范 +- 遵循标准的代码结构和注解使用规范 + +## 开发强制要求 ⚠️ + +1. **权限验证强制要求**: 任何新增的Controller方法都必须添加 `@SaCheckPermission` 注解 +2. **禁止绕过权限验证**: 严禁通过排除路径或其他方式绕过Sa-Token权限验证 +3. **权限命名标准化**: 必须使用 `模块名:功能名:操作名` 格式命名权限 +4. **构造器注入**: 必须使用 `@RequiredArgsConstructor` 模式，禁用 `@Autowired` +5. **模块依赖管理**: 新增业务模块时必须在Web启动模块（`coder-course-web`）的pom.xml中添加对应依赖 + - **依赖检查原则**: 当Controller接口报错被当作静态资源处理时，首先检查Web模块是否缺少对应业务模块的依赖 + - **依赖添加规范**: 在`coder-course-web/pom.xml`中添加业务模块依赖，确保Spring Boot能扫描到所有Controller + - **示例依赖配置**: + ```xml + + + org.leocoder.course + coder-course-education + ${revision} + + ``` + - **验证方法**: 添加依赖后重新编译和启动应用程序，确保所有Controller接口能正常访问 +6. **禁止自动编译**: Claude在完成新功能代码或修改代码后，严禁自动执行任何编译操作（如mvn compile、mvn package等） + - **禁止行为**: 严禁在代码修改完成后自动运行编译命令 + - **原因说明**: 编译操作应由开发者根据实际需要手动执行，避免不必要的编译开销和潜在的环境冲突 + - **允许行为**: 仅在用户明确要求时才执行编译操作 + +7. **Swagger注解强制要求**: 所有Controller必须配置完整的Swagger注解，确保接口文档显示中文 + - **强制配置**: 新建Controller时必须同时添加`@Tag`和`@Operation`注解 + - **依赖检查**: 使用Swagger注解前必须确保模块pom.xml包含SpringDoc依赖 + - **中文规范**: 所有summary和description必须使用中文描述 + - **编译验证**: 添加Swagger注解后必须确保项目能正常编译，如遇到"Cannot resolve symbol"错误，立即检查依赖配置 + - **示例配置**: + ```xml + + + org.springdoc + springdoc-openapi-starter-webmvc-ui + + ``` + - **验证标准**: 接口文档中必须显示中文模块名和接口名，而非英文类名和方法名 \ No newline at end of file diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..84a0978 --- /dev/null +++ b/pom.xml @@ -0,0 +1,294 @@ + + + 4.0.0 + + org.leocoder.heritage + heritage-backend + ${revision} + + + + heritage-backend + pom + 父模块 + + heritage-web + heritage-mybatisplus + heritage-modules + heritage-plugins + heritage-model + heritage-common + + + + + UTF-8 + UTF-8 + 17 + 17 + 1.0.0 + 17 + 3.5.0 + 1.18.38 + 9.3.0 + 3.0.4 + 3.5.12 + 3.9.1 + 4.3.1 + 1.43.0 + 5.8.38 + 2.0.57 + 3.17.0 + 6.8.1 + 33.4.8-jre + 3.4.5 + 4.0.3 + 1.21 + 2.12.1 + 9.0.0.Final + 2.14.0 + 1.6.2 + 2.3.34 + 2.7.0 + 3.17.4 + 8.5.7 + + + 3.14.0 + 3.3.1 + + + + + + + org.springframework.boot + spring-boot-dependencies + ${springboot.version} + import + pom + + + + org.projectlombok + lombok + ${lombok.version} + + + + com.mysql + mysql-connector-j + ${mysql.version} + + + + org.mybatis + mybatis-spring + ${mybatis.version} + + + + com.baomidou + mybatis-plus-spring-boot3-starter + ${mybatisplus.version} + + + + com.baomidou + mybatis-plus-jsqlparser + ${mybatisplus.version} + + + + p6spy + p6spy + ${p6spy.version} + + + + com.baomidou + dynamic-datasource-spring-boot3-starter + ${dynamic.version} + + + + cn.hutool + hutool-all + ${hutool.version} + + + + com.alibaba.fastjson2 + fastjson2 + ${fastjson2.version} + + + + + org.apache.commons + commons-lang3 + ${lang3.version} + + + + org.hibernate.validator + hibernate-validator + ${validator.version} + + + + joda-time + joda-time + ${jodaTime.version} + + + + eu.bitwalker + UserAgentUtils + ${UserAgentUtils.version} + + + + + com.github.oshi + oshi-core + ${oshi.version} + + + + + com.google.guava + guava + ${guava.version} + + + + net.dreamlu + mica-ip2region + ${ip2region.version} + + + + com.alibaba + easyexcel + ${easyexcel.version} + + + + cn.dev33 + sa-token-spring-boot3-starter + ${satoken.version} + + + + cn.dev33 + sa-token-redis-jackson + ${satoken.version} + + + + + org.apache.commons + commons-pool2 + ${pool2.version} + + + + cn.dev33 + sa-token-spring-aop + ${satoken.version} + + + + com.github.whvcse + easy-captcha + ${captcha.version} + + + + org.freemarker + freemarker + ${freemarker.version} + + + + org.springdoc + springdoc-openapi-starter-webmvc-ui + ${springdoc.version} + + + + com.aliyun.oss + aliyun-sdk-oss + ${aliyun.oss.version} + + + + io.minio + minio + ${minio.version} + + + + + + + + + + + org.springframework.boot + spring-boot-maven-plugin + ${springboot.version} + + + + org.projectlombok + lombok + + + + + + org.apache.maven.plugins + maven-compiler-plugin + ${maven-compiler-plugin.verison} + + true + ${java.version} + ${java.version} + + + org.projectlombok + lombok + ${lombok.version} + + + + + + org.apache.maven.plugins + maven-resources-plugin + ${maven-resources-plugin.version} + + + + + + src/main/java + + **/*.xml + + + + src/main/resources + + **/* + + + + + + \ No newline at end of file