# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Jog System — a modern blog CMS with Spring Boot 3 + Vue 3 (Java 21), JWT auth, MySQL + Redis + Flyway.

## Build & Run

**Important:** `jog-admin/pom.xml` bundles `frontend-maven-plugin` that downloads Node.js, runs `npm ci`, and `npm run build` during Maven's `generate-resources` phase. This means `mvn compile` / `mvn spring-boot:run` also trigger a full frontend build — heavyweight and slow. For daily development, run the backend from IDE instead.

```bash
# Backend — compile all modules (triggers frontend build via plugin, slow)
mvn clean compile -DskipTests

# Backend — run all tests (uses Mockito, tagged p0/p1)
mvn test

# Backend — run a single test class
mvn test -Dtest=AuthServiceImplP0P1Test

# Backend — run tests by tag
mvn test -Dgroups="p0"

# Backend — start dev server (port 8080)
# NOTE: triggers frontend-maven-plugin (slow). Recommended: run
# JogApplication.main() from IDE instead to skip frontend build.
mvn spring-boot:run -pl jog-admin

# Frontend — start dev server (port 5173, proxies /api → 8080)
cd jog-frontend && npm run dev

# Frontend — build (outputs to jog-admin/src/main/resources/static)
cd jog-frontend && npm run build

# Full production build (installs Node + npm ci + build via frontend-maven-plugin)
mvn clean package -DskipTests
```

## Project Structure

```
jog-admin/            # Spring Boot entry point (depends on all modules)
jog-common/           # Shared: annotations, enums, exceptions, models (ApiResult, PageResult)
jog-framework/        # Cross-cutting: security (JWT), config, AOP (logging, rate-limit), XSS filter
jog-module-system/    # Auth (login/register/refresh), user management
jog-module-blog/      # Articles, categories, tags, AI summary (DashScope), tag recommendation
jog-module-comment/   # Comments (nested, audit, like)
jog-frontend/         # Vue 3 + Vite + Element Plus + Pinia + Tiptap
```

Module dependency chain (top to bottom):
```
jog-admin → jog-module-{system,blog,comment} → jog-framework → jog-common
```

## Architecture Conventions

### Backend
- **Controller → Service (interface) → ServiceImpl → Mapper (MyBatis-Plus)**
- Controllers use `@RequiredArgsConstructor` + `final` field injection, no `@Autowired`
- Service implementations are `@Transactional` on mutation methods
- All controllers return `ApiResult<T>` (code/message/data/timestamp)
- Error codes via `ErrorCode` enum, thrown as `BusinessException`
- Three API tiers: `/api/public/**` (no auth), `/api/app/**` (USER/ADMIN), `/api/admin/**` (ADMIN only)
- Pagination: `PageResult<T>` wrapping MyBatis-Plus `Page<T>`
- JWT: access token (2h) + refresh token (24h / 14d with "remember me")
- DTOs use `jakarta.validation` annotations
- Lombok: `@Data`, `@Builder`, `@RequiredArgsConstructor` throughout

### Frontend
- `src/utils/request.js` — axios instance with auto Bearer token, 401 auto-refresh
- `src/api/*.js` — per-domain API functions, no direct axios calls in views
- `src/stores/user.js` — Pinia store for auth state (token, userInfo, isLoggedIn, isAdmin)
- `src/router/index.js` — route guards: `requiresAuth` redirects to login, `requiresAdmin` redirects to home
- Views: 3 layout groups — BlogLayout (public), AppLayout (user), AdminLayout (admin)

### Database
- Flyway migrations in `jog-admin/src/main/resources/db/migration/`
- MyBatis-Plus: camelCase mapping, `@TableLogic` for soft delete (deleted=1)
- Redis: used for rate limiting (AI summary), token blacklist

### Testing
- `@ExtendWith(MockitoExtension.class)` for unit tests — mock all mappers
- Test classes suffixed with `P0P1Test` or `Test`; live IT classes suffixed with `LiveIT`
- Test tags: `@Tag("p0")` (critical), `@Tag("p1")` (important)

### AI Features
- DashScope (阿里云百炼) via OpenAI-compatible API in `AiSummaryServiceImpl`
- Tag recommendation via `TagRecommendServiceImpl`
- Both rate-limited per-user via Redis
- Configurable via `dashscope.*` properties in `application.yml`

## Git Rules
- Only the user performs `git commit`, `git push`, or `git push -u` — Claude must not auto-execute these