Add documentation and enhance Conferma entity with QR code tracking
Some checks failed
Build and Publish / build (push) Failing after 48s
Some checks failed
Build and Publish / build (push) Failing after 48s
- Add Claude Code documentation (CLAUDE.md) with project overview and development commands - Add specialized agent configurations (spring-boot-engineer, vue3-frontend-engineer) - Add feature specifications (check liberatorie, configurazione disponibilità, profilo utente) - Enhance Conferma entity with codiceQrLink and presenzaConfermata fields - Update Liquibase changelog and test data for Conferma changes - Update frontend Conferma component and model with new tracking fields 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
305
CLAUDE.md
Normal file
305
CLAUDE.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is a JHipster 9.0.0-beta.0 monolithic application named "smartbooking" - a booking management system for public facilities (Comune di Artegna). The application combines:
|
||||
|
||||
- Backend: Spring Boot with Java 17, Gradle, PostgreSQL, Spring Security (session-based authentication)
|
||||
- Frontend: Vue 3, Vite, TypeScript, Bootstrap Vue Next, Pinia for state management
|
||||
- Entities: AuditLog, Disponibilita, Notifica, Prenotazione, Conferma, Struttura, UtenteApp, Liberatoria, ModelloLiberatoria, Messaggio
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Backend Development
|
||||
|
||||
```bash
|
||||
# Start backend only (without frontend compilation)
|
||||
./gradlew -x webapp -x webapp_test
|
||||
|
||||
# Shorthand backend start
|
||||
./npmw backend:start
|
||||
|
||||
# Run backend tests
|
||||
./gradlew test integrationTest
|
||||
|
||||
# Unit tests only
|
||||
./npmw backend:unit:test
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
|
||||
```bash
|
||||
# Install dependencies (run when package.json changes)
|
||||
./npmw install
|
||||
|
||||
# Start frontend dev server with hot reload
|
||||
./npmw start
|
||||
|
||||
# Build frontend for production
|
||||
./npmw build
|
||||
```
|
||||
|
||||
### Full Development Workflow
|
||||
|
||||
```bash
|
||||
# Run both backend and frontend concurrently
|
||||
./npmw watch
|
||||
# OR in two separate terminals:
|
||||
./npmw backend:start
|
||||
./npmw start
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Frontend unit tests (Vitest)
|
||||
./npmw test
|
||||
|
||||
# Watch mode for tests
|
||||
./npmw test:watch
|
||||
|
||||
# E2E tests (Cypress)
|
||||
./npmw e2e
|
||||
|
||||
# Run E2E in headless mode
|
||||
./npmw e2e:headless
|
||||
|
||||
# Lighthouse audits
|
||||
./npmw run e2e:cypress:audits
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Lint JavaScript/TypeScript
|
||||
./npmw lint
|
||||
|
||||
# Lint with auto-fix
|
||||
./npmw lint:fix
|
||||
|
||||
# Format code with Prettier
|
||||
./npmw prettier:format
|
||||
|
||||
# Check formatting
|
||||
./npmw prettier:check
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
# Build production JAR
|
||||
./gradlew -Pprod clean bootJar
|
||||
|
||||
# Build production WAR
|
||||
./gradlew -Pprod -Pwar clean bootWar
|
||||
|
||||
# Run production JAR
|
||||
java -jar build/libs/*.jar
|
||||
```
|
||||
|
||||
### Docker Operations
|
||||
|
||||
```bash
|
||||
# Start required services (PostgreSQL)
|
||||
docker compose -f src/main/docker/services.yml up -d
|
||||
|
||||
# Stop services
|
||||
docker compose -f src/main/docker/services.yml down
|
||||
|
||||
# Build Docker image
|
||||
npm run java:docker
|
||||
|
||||
# Build for ARM64 (Apple Silicon)
|
||||
npm run java:docker:arm64
|
||||
|
||||
# Start entire application in Docker
|
||||
docker compose -f src/main/docker/app.yml up -d
|
||||
```
|
||||
|
||||
### Database Management
|
||||
|
||||
```bash
|
||||
# Start PostgreSQL for development
|
||||
./npmw docker:db:up
|
||||
|
||||
# Stop PostgreSQL
|
||||
./npmw docker:db:down
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Backend Structure (Java/Spring Boot)
|
||||
|
||||
**Package: `it.sw.pa.comune.artegna`**
|
||||
|
||||
- **`domain/`**: JPA entities with Hibernate mappings
|
||||
- Entities use `AbstractAuditingEntity` for audit fields (createdBy, createdDate, lastModifiedBy, lastModifiedDate)
|
||||
- `User` and `Authority` for authentication/authorization
|
||||
- Business entities: Struttura, Prenotazione, Disponibilita, etc.
|
||||
|
||||
- **`repository/`**: Spring Data JPA repositories
|
||||
- Extend `JpaRepository` for CRUD operations
|
||||
- Custom queries using Spring Data query methods
|
||||
|
||||
- **`service/`**: Business logic layer
|
||||
- Service interfaces and implementations (annotated with `@Service`)
|
||||
- `UserService` for user management
|
||||
- `MailService` for email notifications
|
||||
|
||||
- **`service/dto/`**: Data Transfer Objects
|
||||
- DTOs for API communication
|
||||
- `AdminUserDTO`, `UserDTO`, `PasswordChangeDTO`, etc.
|
||||
|
||||
- **`service/mapper/`**: MapStruct mappers
|
||||
- Entity to DTO conversions
|
||||
- Uses MapStruct annotation processor
|
||||
|
||||
- **`web/rest/`**: REST API controllers
|
||||
- `@RestController` with `/api` prefix
|
||||
- `AccountResource`, `UserResource`, entity resources
|
||||
- Security enforcement via Spring Security
|
||||
|
||||
- **`security/`**: Security configuration
|
||||
- `SecurityConfiguration`: Main security setup with session authentication
|
||||
- `SecurityUtils`: Helper methods for accessing security context
|
||||
- `AuthoritiesConstants`: Role definitions (ADMIN, USER)
|
||||
- Custom CSRF handler for SPA: `SpaCsrfTokenRequestHandler`
|
||||
|
||||
- **`config/`**: Application configuration
|
||||
- `ApplicationProperties`: Custom application properties
|
||||
- `SecurityConfiguration`: Spring Security setup
|
||||
- `LiquibaseConfiguration`: Database migration
|
||||
- `WebConfigurer`: Web layer configuration
|
||||
|
||||
### Frontend Structure (Vue 3 + TypeScript)
|
||||
|
||||
**Path: `src/main/webapp/app/`**
|
||||
|
||||
- **`router/`**: Vue Router configuration
|
||||
- `index.ts`: Main router setup with history mode
|
||||
- Routes split into: `account`, `admin`, `entities`, `pages`
|
||||
- Route guards for authentication/authorization
|
||||
|
||||
- **`core/`**: Core application components
|
||||
- `home/`: Landing page
|
||||
- `jhi-navbar/`: Navigation bar
|
||||
- `jhi-footer/`: Footer
|
||||
- `error/`: Error page component
|
||||
|
||||
- **`shared/`**: Reusable components and utilities
|
||||
- `config/store/`: Pinia stores for global state
|
||||
- `composables/`: Vue composables for shared logic
|
||||
- `sort/`: Sorting utilities and components
|
||||
- `alert/`: Alert/notification service
|
||||
|
||||
- **`account/`**: User account management
|
||||
- `login-form/`: Login component
|
||||
- `register/`: Registration
|
||||
- `settings/`: User settings
|
||||
- `change-password/`: Password change
|
||||
- `activate/`, `reset-password/`: Account activation and password reset
|
||||
|
||||
- **`admin/`**: Admin panel components
|
||||
- `user-management/`: User administration
|
||||
- `health/`, `metrics/`, `configuration/`: Monitoring
|
||||
- `docs/`: API documentation (Swagger UI)
|
||||
- `logs/`: Log level management
|
||||
|
||||
- **`entities/`**: CRUD interfaces for business entities
|
||||
- Each entity has: list view, details, create/update, delete
|
||||
- Uses Vue Router for navigation
|
||||
- Components: `{entity}.vue`, `{entity}-details.vue`, `{entity}-update.vue`
|
||||
|
||||
### State Management
|
||||
|
||||
- **Pinia stores** in `src/main/webapp/app/shared/config/store/`
|
||||
- **Translation store** (`translation-store.ts`): i18n management
|
||||
- Entity-specific stores typically in entity directories
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
1. Session-based authentication via Spring Security
|
||||
2. Login endpoint: `POST /api/authentication` (form login)
|
||||
3. Logout endpoint: `POST /api/logout`
|
||||
4. Account info: `GET /api/account`
|
||||
5. CSRF protection using cookie-based tokens for SPA
|
||||
6. Remember-me functionality with persistent tokens in database
|
||||
|
||||
### API Security
|
||||
|
||||
- Most `/api/**` endpoints require authentication
|
||||
- Admin endpoints (`/api/admin/**`) require `ADMIN` role
|
||||
- Public endpoints: `/api/authenticate`, `/api/register`, `/api/activate`, password reset
|
||||
- CSRF protection enabled with cookie repository
|
||||
|
||||
### Database Schema
|
||||
|
||||
- Managed by Liquibase
|
||||
- Changelog files: `src/main/resources/config/liquibase/`
|
||||
- Entity definitions in `.jhipster/*.json`
|
||||
- JPA/Hibernate for ORM with PostgreSQL
|
||||
|
||||
### Entity Relationships (Key Examples)
|
||||
|
||||
**Struttura** (Facility):
|
||||
|
||||
- One-to-many with Disponibilita (availability slots)
|
||||
- One-to-many with ModelloLiberatoria (waiver templates)
|
||||
|
||||
**Prenotazione** (Booking):
|
||||
|
||||
- Many-to-one with UtenteApp (user)
|
||||
- Many-to-one with Struttura (facility)
|
||||
- One-to-one with Conferma (confirmation)
|
||||
- Enum: StatoPrenotazione (RICHIESTA, CONFERMATA, RIFIUTATA, ANNULLATA)
|
||||
|
||||
### Important Files
|
||||
|
||||
- **`.yo-rc.json`**: JHipster configuration (application type, auth, database, etc.)
|
||||
- **`.jhipster/*.json`**: Entity definitions for JHipster generator
|
||||
- **`build.gradle`**: Gradle build configuration with Spring Boot plugin
|
||||
- **`package.json`**: Node.js dependencies and npm scripts
|
||||
- **`src/main/resources/config/application.yml`**: Spring Boot configuration
|
||||
- **`vite.config.mts`**: Vite build configuration
|
||||
|
||||
### Code Generation
|
||||
|
||||
This is a JHipster-generated application. To add/modify entities:
|
||||
|
||||
```bash
|
||||
# Generate a new entity
|
||||
jhipster entity <EntityName>
|
||||
|
||||
# Regenerate existing entities
|
||||
jhipster
|
||||
```
|
||||
|
||||
Entity modifications should be done via JHipster generators to maintain consistency between backend and frontend.
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
- **Backend**: JUnit 5, Spring Boot Test, Testcontainers for integration tests
|
||||
- Unit tests: `*Test.java`
|
||||
- Integration tests: `*IT.java`
|
||||
- Test containers for PostgreSQL in `@IntegrationTest` annotated classes
|
||||
|
||||
- **Frontend**: Vitest for unit tests, Cypress for E2E
|
||||
- Component tests: `*.spec.ts` next to components
|
||||
- E2E tests: `src/test/javascript/cypress/`
|
||||
|
||||
### Internationalization
|
||||
|
||||
- Backend: Spring MessageSource, properties files in `src/main/resources/i18n/`
|
||||
- Frontend: Vue I18n, JSON files in `src/main/webapp/i18n/it/`
|
||||
- Native language: Italian (`it`)
|
||||
|
||||
## Development Notes
|
||||
|
||||
- Use `./npmw` wrapper instead of `npm` for Node.js version consistency
|
||||
- Gradle automatically installs Node.js and npm locally
|
||||
- Frontend runs on port 9000 (dev server)
|
||||
- Backend runs on port 8080
|
||||
- API endpoints are proxied from frontend to backend during development
|
||||
- Spring Docker Compose integration auto-starts required services in dev mode
|
||||
Reference in New Issue
Block a user