fix: stabilize backend dev startup flow

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help dev dev-all dev-down dev-all-down dev-all-reset dev-logs dev-status build test clean web-install dev-server dev-web build-web test-web typecheck-web lint-web generate-api db-reset validate-release-config staging staging-down staging-logs pr parallel-init parallel-sync parallel-up parallel-down
+.PHONY: help dev dev-all dev-down dev-all-down dev-all-reset dev-logs dev-status build test clean web-install dev-server dev-server-restart dev-web build-web test-web typecheck-web lint-web generate-api db-reset validate-release-config staging staging-down staging-logs pr parallel-init parallel-sync parallel-up parallel-down
 
 DEV_DIR := .dev
 DEV_SERVER_PID := $(DEV_DIR)/server.pid
@@ -11,8 +11,8 @@ STAGING_API_URL := http://localhost:8080
 STAGING_WEB_URL := http://localhost
 STAGING_SERVER_IMAGE := skillhub-server:staging
 DEV_PROCESS := python3 scripts/dev_process.py
-DEV_SERVER_PREPARE := ./mvnw -pl skillhub-app -am compile -DskipTests >/dev/null
+DEV_SERVER_PREPARE := true
-DEV_SERVER_CMD := ./mvnw -pl skillhub-app spring-boot:run -Dspring-boot.run.profiles=local
+DEV_SERVER_CMD := ./scripts/run-dev-app.sh
 PARALLEL_BASE_REF ?= origin/main
 PARALLEL_WORKTREE_ROOT ?=
 DEV_COMPOSE_PROJECT_NAME ?= skillhub
@@ -102,6 +102,21 @@ dev-all: ## 一键启动本地开发环境（依赖 + 后端 + 前端）
 dev-server: ## 启动后端开发服务器
 	cd server && /bin/sh -lc '$(DEV_SERVER_PREPARE) && exec $(DEV_SERVER_CMD)'
 
+dev-server-restart: ## 重启后端开发服务器
+	@mkdir -p $(DEV_DIR)
+	@$(DEV_PROCESS) stop --pid-file $(DEV_SERVER_PID)
+	@$(DEV_PROCESS) start --pid-file $(DEV_SERVER_PID) --log-file $(DEV_SERVER_LOG) --cwd server -- /bin/sh -lc '$(DEV_SERVER_PREPARE) && exec $(DEV_SERVER_CMD)' >/dev/null
+	@echo "Waiting for backend on $(DEV_API_URL) ..."
+	@for i in $$(seq 1 30); do \
+		if curl -sf $(DEV_API_URL)/actuator/health >/dev/null; then \
+			echo "Backend ready."; \
+			exit 0; \
+		fi; \
+		sleep 2; \
+	done; \
+	echo "Backend failed to become ready. Check $(DEV_SERVER_LOG)"; \
+	exit 1
+
 dev-down: ## 停止本地开发环境
 	$(DEV_COMPOSE) down --remove-orphans
 

docs/dev-workflow.md

@@ -26,15 +26,19 @@ This starts:
 
 SkillHub now pins a shared Docker Compose project name for local development, so multiple git worktrees can reuse the same dependency containers instead of fighting over `5432`, `6379`, and `9000`.
 
-### Hot reload
+### Backend restarts
 
 **Frontend:** Vite HMR is enabled by default. Save a file and the browser updates instantly.
 
-**Backend:** Spring Boot DevTools is configured. After editing Java code:
+**Backend:** the local server now runs from a packaged Spring Boot jar instead of `spring-boot:run`. This avoids mixed classpaths across `skillhub-app`, `skillhub-auth`, `skillhub-domain`, and other sibling modules.
-1. In IntelliJ IDEA: press `Cmd+F9` (Build Project)
+
-2. If you changed code in another backend module such as `skillhub-domain` or `skillhub-search`, make sure the whole server project is rebuilt, not just `skillhub-app`
+After editing backend code, restart the backend explicitly:
-3. The backend restarts automatically in 3-8 seconds
+
-4. Watch the terminal running `make dev-server` for the restart log
+```bash
+make dev-server-restart
+```
+
+If you are running the server in a foreground terminal instead of `make dev-all`, stop it and run `make dev-server` again. Expect a full restart in about 5-10 seconds, including rebuilding the backend modules.
 
 ### Mock authentication
 
@@ -55,6 +59,7 @@ Two mock users are available in local mode (no password needed):
 | `make dev-logs`                  | Tail backend logs                |
 | `SERVICE=frontend make dev-logs` | Tail frontend logs               |
 | `make dev-all-reset`             | Full reset (clears data volumes) |
+| `make dev-server-restart`        | Restart backend after Java changes |
 | `make db-reset`                  | Reset database only              |
 
 ### Claude + Codex parallel workflow

scripts/check-openapi-generated.sh

@@ -34,16 +34,7 @@ docker compose up -d --wait postgres redis
 
 (
   cd "$SERVER_DIR"
-  ./mvnw -pl skillhub-app -am compile -DskipTests
+  SPRING_PROFILES_ACTIVE=local ./scripts/run-dev-app.sh
-) >"$BUILD_LOG" 2>&1 || {
-  echo "Failed to prepare backend modules. See $BUILD_LOG" >&2
-  print_log_tail "$BUILD_LOG"
-  exit 1
-}
-
-(
-  cd "$SERVER_DIR"
-  SPRING_PROFILES_ACTIVE=local ./mvnw -pl skillhub-app spring-boot:run
 ) >"$API_LOG" 2>&1 &
 SERVER_PID=$!
 

server/scripts/run-dev-app.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SERVER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PROFILE="${SPRING_PROFILES_ACTIVE:-local}"
+
+cd "$SERVER_DIR"
+
+./mvnw -pl skillhub-app -am package -DskipTests >/dev/null
+
+APP_JAR="$(find skillhub-app/target -maxdepth 1 -type f -name 'skillhub-app-*.jar' ! -name '*.original' | head -n 1)"
+if [[ -z "$APP_JAR" ]]; then
+  echo "Could not locate packaged skillhub-app jar under skillhub-app/target" >&2
+  exit 1
+fi
+
+exec "${JAVA_BIN:-java}" -jar "$APP_JAR" --spring.profiles.active="$PROFILE" "$@"

server/skillhub-app/pom.xml

@@ -101,15 +101,6 @@
             <plugin>
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
-                <configuration>
-                    <additionalClasspathElements>
-                        <additionalClasspathElement>${project.parent.basedir}/skillhub-domain/target/classes</additionalClasspathElement>
-                        <additionalClasspathElement>${project.parent.basedir}/skillhub-auth/target/classes</additionalClasspathElement>
-                        <additionalClasspathElement>${project.parent.basedir}/skillhub-infra/target/classes</additionalClasspathElement>
-                        <additionalClasspathElement>${project.parent.basedir}/skillhub-search/target/classes</additionalClasspathElement>
-                        <additionalClasspathElement>${project.parent.basedir}/skillhub-storage/target/classes</additionalClasspathElement>
-                    </additionalClasspathElements>
-                </configuration>
             </plugin>
         </plugins>
     </build>