diff --git a/.gitignore b/.gitignore index 987273c..410b9ca 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,16 @@ Thumbs.db *.war *.ear /target + +# Application logs and runtime files # +application.log +*.pid +nohup.out + +# Caddy and deployment files # +Caddyfile +*.sh +*_SETUP.md +PORT_FORWARD.md +QUICKSTART.md +SERVICE_CONFIG.md diff --git a/.sdkmanrc b/.sdkmanrc new file mode 100644 index 0000000..31fb053 --- /dev/null +++ b/.sdkmanrc @@ -0,0 +1,6 @@ +# Enable auto-env through the sdkman_auto_env config +# To use .sdkmanrc auto-switching, run: sdk config +# Set sdkman_auto_env=true in ~/.sdkman/etc/config + +java=17.0.17-tem +maven=3.9.11 diff --git a/.vscode/DEBUG_GUIDE.md b/.vscode/DEBUG_GUIDE.md new file mode 100644 index 0000000..78f23de --- /dev/null +++ b/.vscode/DEBUG_GUIDE.md @@ -0,0 +1,302 @@ +# VS Code 调试指南 + +## 前置要求 + +确保已安装以下 VS Code 扩展： + +1. **Extension Pack for Java** (Microsoft) + - 包含：Language Support for Java, Debugger for Java, Maven for Java 等 +2. **Spring Boot Extension Pack** (VMware) + - 包含：Spring Boot Tools, Spring Initializr 等 + +安装方式： +- 按 `Ctrl+Shift+X` 打开扩展面板 +- 搜索 "Extension Pack for Java" 并安装 +- 搜索 "Spring Boot Extension Pack" 并安装 + +## 一、Debug 运行（推荐） + +### 方法 1：使用侧边栏（最简单） + +1. **打开运行和调试面板**： + - 快捷键：`Ctrl+Shift+D` (Windows/Linux) 或 `Cmd+Shift+D` (Mac) + - 或点击左侧活动栏的「运行和调试」图标 + +2. **选择配置**： + - 在顶部下拉框选择：`Debug Spring Boot App (Dev)` + +3. **开始调试**： + - 点击绿色的「启动调试」按钮（三角形） + - 或按 `F5` + +4. **设置断点**： + - 在代码行号左侧点击，出现红点即为断点 + - 例如在 Controller 方法中打断点 + +5. **调试操作**： + - `F5` - 继续执行 + - `F10` - 单步跳过 + - `F11` - 单步进入 + - `Shift+F11` - 单步跳出 + - `Shift+F5` - 停止调试 + +### 方法 2：右键快速启动 + +1. **打开主类**： + - 打开 `src/main/java/org/springblade/Application.java` + +2. **右键运行**： + - 在编辑器中右键 + - 选择 `Run Java` 或 `Debug Java` + +### 方法 3：使用命令面板 + +1. 按 `Ctrl+Shift+P` (或 `Cmd+Shift+P`) +2. 输入 `Java: Run` +3. 选择 `Debug Spring Boot App (Dev)` + +## 二、普通运行（无调试） + +### 使用终端运行 + +```bash +# 在 VS Code 集成终端中（Ctrl+`） +cd /remote_dev/martial/martial-master + +# 加载 Java 环境 +source ~/.sdkman/bin/sdkman-init.sh + +# 运行应用 +mvn spring-boot:run +``` + +### 使用 Maven 侧边栏 + +1. 点击左侧 Maven 图标（M） +2. 展开 `blade-api` → `Plugins` → `spring-boot` +3. 右键 `spring-boot:run` → `Run Maven Goal` + +## 三、构建任务 + +按 `Ctrl+Shift+B` 可以快速访问构建任务： + +- **Maven: Clean** - 清理 target 目录 +- **Maven: Compile** - 编译项目 +- **Maven: Package (Skip Tests)** - 打包（默认任务） +- **Maven: Install BladeX Framework** - 编译 BladeX 框架依赖 +- **Spring Boot: Run Dev** - 后台运行开发环境 +- **Kill Java Process on Port 8123** - 停止占用 8123 端口的进程 + +## 四、端口转发设置 + +### 自动转发（推荐） + +VS Code Remote SSH 会自动检测端口 8123，只需： + +1. 应用启动后，底部会出现提示 +2. 点击「在浏览器中打开」即可 + +### 手动添加端口 + +1. **打开端口面板**： + - 按 `Ctrl+Shift+P` + - 输入 `Forward a Port` + - 输入 `8123` + +2. **或使用端口视图**： + - 点击底部状态栏的「端口」标签 + - 点击「+」添加端口 + - 输入 `8123` + +3. **访问应用**： + - 浏览器访问：`http://localhost:8123/doc.html` + - Knife4j API 文档自动打开 + +### 批量转发（开发常用端口） + +在端口面板添加： +- `8123` - Spring Boot 应用 +- `33066` - MySQL +- `63379` - Redis + +## 五、调试配置说明 + +已配置的调试选项： + +### 1. Debug Spring Boot App (Dev) +- **用途**：开发环境调试 +- **配置文件**：application-dev.yml +- **快捷键**：F5 启动 + +### 2. Debug Spring Boot App (Test) +- **用途**：测试环境调试 +- **配置文件**：application-test.yml + +### 3. Debug Current Java File +- **用途**：调试单个 Java 文件（有 main 方法） +- **使用**：打开文件后按 F5 + +### 4. Attach to Remote JVM +- **用途**：连接到远程 JVM 进程 +- **端口**：5005 +- **使用场景**：当应用已在运行时附加调试器 + +## 六、常见问题 + +### 问题 1：找不到主类 + +**解决方案**： +```bash +# 清理并重新编译 +mvn clean compile + +# 或在 VS Code 中 +Ctrl+Shift+P -> Java: Clean Java Language Server Workspace +``` + +### 问题 2：端口 8123 已被占用 + +**解决方案**： +```bash +# 查找占用端口的进程 +lsof -i:8123 + +# 或使用配置的任务 +Ctrl+Shift+P -> Tasks: Run Task -> Kill Java Process on Port 8123 +``` + +### 问题 3：Maven 依赖未找到 + +**解决方案**： +```bash +# 先编译 BladeX 框架 +cd /remote_dev/martial/martial-tool +mvn clean install -DskipTests + +# 或使用任务 +Ctrl+Shift+P -> Tasks: Run Task -> Maven: Install BladeX Framework +``` + +### 问题 4：断点不生效 + +**原因**：代码未重新编译 + +**解决方案**： +- 停止调试 (Shift+F5) +- 重新编译 (Ctrl+Shift+B) +- 再次启动调试 (F5) + +### 问题 5：MySQL/Redis 连接失败 + +**检查服务**： +```bash +# MySQL +docker ps --filter "name=dev-mysql" + +# Redis +docker ps --filter "name=dev-redis" + +# 如未运行，启动它们 +docker start dev-mysql dev-redis +``` + +## 七、调试技巧 + +### 1. 条件断点 +- 在断点上右键 → `Edit Breakpoint` +- 输入条件，例如：`userId == 1` + +### 2. 日志断点 +- 右键断点 → `Edit Breakpoint` +- 勾选 `Log Message` +- 输入消息，例如：`User ID: {userId}` + +### 3. 异常断点 +- 调试面板 → `BREAKPOINTS` → 点击 `+` +- 选择 `Java Exception Breakpoints` +- 输入异常类名，如：`NullPointerException` + +### 4. 查看变量 +- 鼠标悬停在变量上查看值 +- 或在左侧 `VARIABLES` 面板查看所有变量 +- 右键变量 → `Copy Value` 复制值 + +### 5. 表达式求值 +- 调试时，点击 `DEBUG CONSOLE` +- 输入表达式并执行，例如： + ```java + user.getName() + list.size() + ``` + +### 6. 热重载（Spring Boot DevTools） +- 修改代码后自动重启应用 +- 已在 `pom.xml` 中配置（如果需要） + +## 八、快捷键速查表 + +| 操作 | Windows/Linux | Mac | +|------|---------------|-----| +| 开始调试 | F5 | F5 | +| 停止调试 | Shift+F5 | Shift+F5 | +| 单步跳过 | F10 | F10 | +| 单步进入 | F11 | F11 | +| 单步跳出 | Shift+F11 | Shift+F11 | +| 继续执行 | F5 | F5 | +| 切换断点 | F9 | F9 | +| 打开调试面板 | Ctrl+Shift+D | Cmd+Shift+D | +| 打开终端 | Ctrl+` | Ctrl+` | +| 命令面板 | Ctrl+Shift+P | Cmd+Shift+P | +| 构建任务 | Ctrl+Shift+B | Cmd+Shift+B | + +## 九、开发工作流 + +### 典型开发流程： + +1. **启动服务**： + ```bash + # 确保 MySQL 和 Redis 运行 + docker ps + ``` + +2. **开始调试**： + - 按 `F5` 启动应用 + - 等待应用启动（看底部终端日志） + +3. **转发端口**： + - VS Code 自动转发 8123 + - 或手动添加 + +4. **访问应用**： + - 浏览器：`http://localhost:8123/doc.html` + +5. **设置断点**： + - 在 Controller 或 Service 方法中打断点 + +6. **测试 API**： + - 在 Knife4j 界面发起请求 + - VS Code 会在断点处暂停 + +7. **修改代码**： + - 停止调试 (Shift+F5) + - 修改代码 + - 重新启动调试 (F5) + +8. **查看日志**： + - 集成终端显示应用日志 + - 或查看 `application.log` 文件 + +## 十、推荐扩展 + +除了必需的扩展，还推荐： + +- **REST Client** - 直接在 VS Code 测试 API +- **Database Client** - 连接 MySQL 查看数据 +- **GitLens** - Git 增强工具 +- **Error Lens** - 内联显示错误 +- **Better Comments** - 增强注释高亮 +- **Material Icon Theme** - 美化文件图标 + +--- + +**快速开始：按 F5 即可开始调试！** diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..3e46a83 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,51 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "type": "java", + "name": "Application", + "request": "launch", + "mainClass": "org.springblade.Application", + "projectName": "BladeX-Boot" + }, + { + "type": "java", + "name": "Debug Spring Boot App (Dev)", + "request": "launch", + "mainClass": "org.springblade.Application", + "projectName": "blade-api", + "args": "--spring.profiles.active=dev", + "vmArgs": "-Dfile.encoding=UTF-8", + "console": "integratedTerminal", + "env": { + "SPRING_PROFILES_ACTIVE": "dev" + } + }, + { + "type": "java", + "name": "Debug Spring Boot App (Test)", + "request": "launch", + "mainClass": "org.springblade.Application", + "projectName": "blade-api", + "args": "--spring.profiles.active=test", + "vmArgs": "-Dfile.encoding=UTF-8", + "console": "integratedTerminal", + "env": { + "SPRING_PROFILES_ACTIVE": "test" + } + }, + { + "type": "java", + "name": "Debug Current Java File", + "request": "launch", + "mainClass": "${file}" + }, + { + "type": "java", + "name": "Attach to Remote JVM", + "request": "attach", + "hostName": "localhost", + "port": 5005 + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..7b016a8 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "java.compile.nullAnalysis.mode": "automatic" +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..4062db1 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,57 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Maven: Clean", + "type": "shell", + "command": "mvn clean", + "group": "build", + "problemMatcher": [] + }, + { + "label": "Maven: Compile", + "type": "shell", + "command": "mvn clean compile", + "group": "build", + "problemMatcher": [] + }, + { + "label": "Maven: Package (Skip Tests)", + "type": "shell", + "command": "mvn clean package -DskipTests -Dmaven.test.skip=true", + "group": { + "kind": "build", + "isDefault": true + }, + "problemMatcher": [] + }, + { + "label": "Maven: Install BladeX Framework", + "type": "shell", + "command": "cd /remote_dev/martial/martial-tool && mvn clean install -DskipTests", + "group": "build", + "problemMatcher": [], + "presentation": { + "echo": true, + "reveal": "always", + "focus": false, + "panel": "shared" + } + }, + { + "label": "Spring Boot: Run Dev", + "type": "shell", + "command": "source ~/.sdkman/bin/sdkman-init.sh && mvn spring-boot:run -Dspring-boot.run.profiles=dev", + "group": "none", + "problemMatcher": [], + "isBackground": true + }, + { + "label": "Kill Java Process on Port 8123", + "type": "shell", + "command": "lsof -ti:8123 | xargs kill -9 || echo 'No process on port 8123'", + "group": "none", + "problemMatcher": [] + } + ] +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..192a5f8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,332 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is a martial arts competition management system built on the **BladeX framework** (Spring Boot-based enterprise platform). The project is a monolithic Spring Boot application that manages martial arts competition events, including competitions, athletes, judges, schedules, venues, scores, and registration orders. + +**Technology Stack:** +- Spring Boot 3.x (managed by BladeX BOM) +- MyBatis-Plus (ORM) +- Java 17 +- MySQL database +- Redis for caching +- Knife4j/Swagger for API documentation +- BladeX 4.0.1.RELEASE enterprise framework + +## Build and Run Commands + +### Build Prerequisites + +**IMPORTANT:** This project depends on the BladeX-Tool framework which must be compiled first. + +**Step 1: Compile BladeX-Tool framework (required first time):** +```bash +cd /remote_dev/martial/martial-tool +mvn clean install -DskipTests +``` +This compiles all 44 BladeX framework modules and installs them to your local Maven repository (~/.m2). + +**Step 2: Compile martial-master project:** +```bash +cd /remote_dev/martial/martial-master +mvn clean package -DskipTests -Dmaven.test.skip=true +``` +Note: `-Dmaven.test.skip=true` is required to skip test compilation as some test dependencies are not configured. + +### Maven Build Commands + +```bash +# Clean and compile the project +mvn clean compile + +# Package the application (creates JAR in target/) +mvn clean package -DskipTests -Dmaven.test.skip=true + +# Run the application +mvn spring-boot:run +``` + +### Runtime Requirements + +Before running the application, ensure these services are available: + +**Required Services:** +- **MySQL**: 127.0.0.1:33066 (high port) with database `martial_db` + - Username: root + - Password: WtcSecure901faf1ac4d32e2bPwd + - Container: dev-mysql + +- **Redis**: 127.0.0.1:63379 (high port) + - Password: RedisSecure2024MartialXyZ789ABC + - Database: 8 + - Container: dev-redis + +**Services Management:** + +```bash +# MySQL 容器管理 +docker ps --filter "name=dev-mysql" +docker logs dev-mysql + +# Redis 容器管理 +cd /remote_dev/dev_tools/redis +docker-compose ps +docker-compose logs -f +docker-compose restart +``` + +**Application Server:** +- **Port**: 82 (configured in application.yml) +- **Main Class**: org.springblade.Application + +### Running the Application + +**Development mode:** +```bash +# Runs with dev profile (application-dev.yml) +mvn spring-boot:run -Dspring-boot.run.profiles=dev +``` + +**Or using the JAR file:** +```bash +cd /remote_dev/martial/martial-master +java -jar target/blade-api.jar --spring.profiles.active=dev +``` + +**Production mode:** +```bash +java -jar target/blade-api.jar --spring.profiles.active=prod +``` + +**Test mode:** +```bash +java -jar target/blade-api.jar --spring.profiles.active=test +``` + +**Access points after startup:** +- API Server: http://localhost:8123 +- Swagger UI: http://localhost:8123/doc.html +- Druid Monitor: http://localhost:8123/druid (username: blade, password: 1qaz@WSX) + +### Docker Commands + +```bash +# Build Docker image +mvn clean package +docker build -t martial-api:latest . + +# Run with Docker +docker run -p 8800:8800 martial-api:latest +``` + +## Database Setup + +**Database name:** `martial_db` + +**Connection Information:** +- Host: 127.0.0.1 +- Port: 33066 (high port) +- Username: root +- Password: WtcSecure901faf1ac4d32e2bPwd + +**Required setup steps:** +1. Database already created in dev-mysql container +2. Execute base BladeX schema (if not already present) +3. Execute martial arts tables: `doc/sql/mysql/martial-competition-tables.sql` +4. Execute menu configuration: `doc/sql/mysql/martial-competition-menu.sql` + +**Database connection configuration:** +- Dev: `src/main/resources/application-dev.yml` (已配置高位端口) +- Test/Prod: 需要根据环境调整端口和密码 + +**Redis configuration:** +- Dev: localhost:63379 (high port) +- Password: RedisSecure2024MartialXyZ789ABC +- Database: 8 + +## Code Architecture + +### Module Structure + +The application follows a **modular monolithic architecture** under `org.springblade.modules`: + +- **auth**: Authentication and authorization (token-based, multiple grant types: password, captcha, refresh, social) +- **system**: Core system functionality (users, roles, menus, departments, dictionaries, tenants) +- **resource**: Resource management (attachments, SMS, OSS storage) +- **desk**: Dashboard and notification features +- **develop**: Code generation and datasource management +- **martial**: **Martial arts competition domain** (main business module) + +### Martial Arts Module Structure + +Located in `src/main/java/org/springblade/modules/martial/`: + +``` +martial/ +├── entity/ # Domain entities (9 tables) +│ ├── Athlete.java +│ ├── Competition.java +│ ├── Judge.java +│ ├── Project.java +│ ├── RegistrationOrder.java +│ ├── Result.java +│ ├── Schedule.java +│ ├── Score.java +│ └── Venue.java +├── mapper/ # MyBatis mappers +├── service/ # Service interfaces (extend BaseService) +├── controller/ # REST controllers (extend BladeController) +├── vo/ # View objects for API responses +└── dto/ # Data transfer objects +``` + +### BladeX Framework Conventions + +**Base Classes:** +- All entities extend `org.springblade.core.mp.base.BaseEntity` (provides: id, createUser, createDept, createTime, updateUser, updateTime, status, isDeleted) +- All services extend `BaseService` from MyBatis-Plus +- All controllers extend `BladeController` for standard CRUD operations + +**Multi-tenancy:** +- Enabled by default with `tenant_id` column +- Use `@TenantDS` annotation on controllers for tenant data isolation +- Excluded tables configured in `application.yml` under `blade.tenant.exclude-tables` + +**API Response Format:** +- All endpoints return `R` wrapper (contains code, success, data, msg) +- Success: `R.data(entity)` or `R.status(boolean)` +- Failure: `R.fail(message)` + +**Security:** +- Token-based authentication (stateless by default: `blade.token.state=false`) +- Skip authentication URLs configured in `blade.secure.skip-url` +- `/api/martial/**` endpoints are publicly accessible (configured in skip-url) + +### MyBatis-Plus Configuration + +**Mapper XML locations:** `classpath:org/springblade/**/mapper/*Mapper.xml` + +**ID Generation:** Snowflake (`assign_id`) + +**Logical delete:** +- Deleted: `is_deleted = 1` +- Not deleted: `is_deleted = 0` + +**Field strategies:** NOT_NULL for insert/update operations + +## Common Development Patterns + +### Creating a New CRUD Module + +1. **Create Entity** in `entity/` extending BaseEntity +2. **Create Mapper** interface in `mapper/` extending BaseMapper +3. **Create Service** interface in `service/` extending BaseService +4. **Create ServiceImpl** in `service/impl/` extending ServiceImpl +5. **Create Controller** in `controller/` extending BladeController +6. **Add VO** (optional) in `vo/` for custom response formats +7. **Add Mapper XML** (optional) in `src/main/resources/org/springblade/modules/{module}/mapper/` for complex queries + +### Standard Controller Pattern + +```java +@TenantDS +@RestController +@RequestMapping("/api/martial/{resource}") +@AllArgsConstructor +@Api(value = "Resource Management", tags = "Resource API") +public class ResourceController extends BladeController { + + private final IResourceService resourceService; + + @GetMapping("/detail") + public R detail(@RequestParam Long id) { + return R.data(resourceService.getById(id)); + } + + @GetMapping("/list") + public R> list(Resource resource, Query query) { + IPage pages = resourceService.page( + Condition.getPage(query), + Condition.getQueryWrapper(resource) + ); + return R.data(pages); + } + + @PostMapping("/submit") + public R submit(@RequestBody Resource resource) { + return R.status(resourceService.saveOrUpdate(resource)); + } + + @PostMapping("/remove") + public R remove(@RequestParam String ids) { + return R.status(resourceService.deleteLogic(Func.toLongList(ids))); + } +} +``` + +## Configuration Profiles + +**Available profiles:** +- `dev`: Development (application-dev.yml) +- `test`: Testing (application-test.yml) +- `prod`: Production (application-prod.yml) + +**Server port:** 8123 (configured in application.yml) + +**Knife4j API 文档:** +- Enabled in all environments +- Access URL: `http://localhost:8123/doc.html` +- Basic auth: Disabled by default (可在配置中启用) +- Language: 中文 (Chinese) +- Features: + - Swagger Models 展示 + - 文档管理 + - 请求缓存 + - 自定义页脚 + +## Key Dependencies + +- **blade-core-boot**: Core framework components +- **blade-starter-tenant**: Multi-tenancy support +- **blade-starter-swagger**: API documentation +- **mybatis-plus-generator**: Code generator (scope: provided) +- **blade-starter-oss**: Object storage (MinIO, Aliyun OSS, Tencent COS, QiNiu) +- **blade-starter-sms**: SMS support (Aliyun, Tencent, YunPian) +- **easy-captcha**: Captcha generation + +## Working with the Code + +### Finding Files + +**Entities:** Use pattern `src/main/java/**/entity/*.java` +**Mappers:** Use pattern `src/main/java/**/mapper/*.java` +**Controllers:** Use pattern `src/main/java/**/controller/*.java` +**SQL scripts:** Check `doc/sql/mysql/` for schema definitions + +### Authentication Development + +**Token grant types** (in `modules.auth.granter`): +- `PasswordTokenGranter`: Username/password login +- `CaptchaTokenGranter`: Captcha-based login +- `RefreshTokenGranter`: Refresh token +- `SocialTokenGranter`: Third-party OAuth login + +**Token endpoint:** `BladeTokenEndPoint` at `/blade-auth/token` + +### Cache Management + +**Cache names** defined in `CacheNames.java`: +- User cache, dict cache, menu cache, etc. +- Use `CacheUtil.clear(CACHE_NAME)` after modifications + +**Redis serialization:** Protostuff (configured in `blade.redis.serializer-type`) + +## Project-Specific Notes + +- The martial arts competition module entities are fully created but **Service implementations and some Controller methods may need completion** +- Menu permissions for martial module are configured via SQL in `doc/sql/mysql/martial-competition-menu.sql` +- API endpoints under `/api/martial/` are **publicly accessible** (no authentication required) as configured in skip-url +- The frontend is a separate Vue.js project (not in this repository) +- Mock data and test scripts available in `doc/doc/` diff --git a/pom.xml b/pom.xml index 9fb0dc5..b292681 100644 --- a/pom.xml +++ b/pom.xml @@ -191,10 +191,10 @@ yunpian-java-sdk - - - - + + org.springblade + blade-starter-liteflow +