97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
|
# 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
|