smartbooking/frontend-changes.md

# Frontend Changes - Liberatorie Feature

## Overview

This document describes the frontend changes made to implement the "Liberatorie" (waivers) feature in the user booking form. This feature allows users to view and accept required waivers associated with facilities before submitting a booking.

## Date

2025-12-12

## Files Modified

### 1. TypeScript Component

**File:** `src/main/webapp/app/entities/prenotazione/prenotazione-form-user.component.ts`

#### Changes Made:

**Imports Added (lines 10-18):**

- `LiberatoriaService` - Service for managing waiver acceptances
- `ModelloLiberatoriaService` - Service for managing waiver templates
- `ILiberatoria` and `Liberatoria` - Liberatoria model interface and class
- `IModelloLiberatoria` - ModelloLiberatoria model interface

**Service Injections Added (lines 40-47):**

- `liberatoriaService` - Injected service for Liberatoria CRUD operations
- `modelloLiberatoriaService` - Injected service for ModelloLiberatoria CRUD operations
- `modelloLiberatorias` - Ref array to store all waiver templates
- `userLiberatorias` - Ref array to store user's accepted waivers
- `isLoadingLiberatorie` - Ref boolean for loading state
- `selectedModello` - Ref for the currently selected waiver template in modal

**Computed Properties Added (lines 71-96):**

- `liberatorieStatus` - Computed property that:
  - Filters ModelloLiberatoria by selected struttura
  - Maps each template to include acceptance status
  - Returns array with structure: `{ modello, liberatoria, isAccepted }`
- `allLiberatorieAccepted` - Computed property that:
  - Returns true if no waivers required OR all waivers are accepted
  - Used for form validation

**Data Loading Function Added (lines 98-119):**

- `loadLiberatorieData()` - Async function that:
  - Fetches all ModelloLiberatoria records
  - Fetches all Liberatoria records
  - Filters Liberatoria by current user ID (client-side filtering)
  - Handles loading states and errors

**initData() Modified (lines 121-142):**

- Added call to `loadLiberatorieData()` after fetching user and strutture
- Ensures liberatorie data is loaded on component mount

**Return Statement Updated (lines 155-179):**

- Added all new refs and computed properties to expose them to the template:
  - `liberatoriaService`
  - `modelloLiberatoriaService`
  - `modelloLiberatorias`
  - `userLiberatorias`
  - `isLoadingLiberatorie`
  - `selectedModello`
  - `liberatorieStatus`
  - `allLiberatorieAccepted`

**Methods Added (lines 181-254):**

1. **`save()` Modified (lines 182-211):**
   - Added validation check for liberatorie acceptance
   - Blocks form submission if `!allLiberatorieAccepted`
   - Shows error message to user if waivers not accepted

2. **`showLiberatoriaModal()` Added (lines 213-216):**
   - Sets selected waiver template
   - Opens modal using ref

3. **`closeLiberatoriaModal()` Added (lines 218-221):**
   - Clears selected waiver template
   - Closes modal

4. **`acceptLiberatoria()` Added (lines 223-253):**
   - Creates new Liberatoria instance
   - Sets `accettata` to current date
   - Associates with current user and selected template
   - Calls backend API to create record
   - Updates local state with new acceptance
   - Closes modal and shows success message
   - Handles errors gracefully

---

### 2. Vue Template

**File:** `src/main/webapp/app/entities/prenotazione/prenotazione-form-user.vue`

#### Changes Made:

**Liberatorie Section Added (lines 223-273):**

- New card section with title "Liberatorie"
- Conditional rendering based on `v-if="prenotazione.struttura"` - only shows when facility is selected
- Three states handled:
  1. **Loading State** (lines 229-233): Shows spinner while fetching data
  2. **No Waivers State** (lines 235-237): Shows info alert when no waivers required
  3. **Waivers List State** (lines 239-266): Displays list of waivers with:
     - Green badge + check icon for accepted waivers
     - Yellow badge + warning icon for pending waivers
     - Clickable link to open modal for pending waivers
     - Acceptance date for accepted waivers (formatted in Italian)
- Warning alert (lines 268-271): Shows when not all waivers are accepted

**Modal Added (lines 290-337):**

- Bootstrap Vue modal with ref `liberatoriaModal`
- Large size (`size="lg"`)
- Closes on hidden event
- **Modal Header (lines 292-294):**
  - Displays waiver template name
- **Modal Body (lines 296-326):**
  - Shows waiver text in bordered container with pre-wrap formatting (lines 298-303)
  - Download button for attached document if present (lines 305-316)
  - Acceptance statement with user's full name (lines 318-325)
  - Italian text: "Il sottoscritto {nome} {cognome} presa visione della documentazione proposta accetta le condizioni ivi indicate"
- **Modal Footer (lines 328-336):**
  - Cancel button - closes modal
  - Accept button - calls `acceptLiberatoria()` method
  - Both buttons disabled during save operation

**Submit Button Updated (line 281):**

- Added `!allLiberatorieAccepted` to disabled condition
- Button now disabled if: validation fails OR saving OR not all waivers accepted

---

### 3. Internationalization

**File:** `src/main/webapp/i18n/it/prenotazione.json`

#### Changes Made:

**New Translation Keys Added (lines 41-46):**

- `liberatorie`: "Liberatorie" - Section title
- `noLiberatorieRequired`: "Nessuna liberatoria richiesta per questa struttura" - Info message
- `liberatorieWarning`: "È necessario accettare tutte le liberatorie richieste prima di inviare la prenotazione" - Warning message
- `liberatorieRequired`: "Devi accettare tutte le liberatorie richieste" - Error message
- `acceptanceStatement`: "Dichiarazione di accettazione" - Modal acceptance statement label
- `accept`: "Accetta" - Accept button text

---

## Feature Functionality

### User Flow

1. **User navigates to new booking form** (`/prenotazione/nuova`)
2. **Form loads with existing sections:**
   - Booking Details (struttura selection, dates, participants, etc.)
   - User Data (personal information display)
3. **User selects a facility (struttura)**
4. **Liberatorie section appears** (if facility has associated waivers)
5. **System displays waiver status:**
   - ✅ Green check = already accepted
   - ⚠️ Warning icon + clickable link = pending acceptance
6. **User clicks on pending waiver link**
7. **Modal opens showing:**
   - Waiver name
   - Waiver text content
   - Document download link (if available)
   - Acceptance statement with user's name
8. **User clicks "Accetta" button**
9. **System creates Liberatoria record** with:
   - Current timestamp (`accettata`)
   - User reference
   - Waiver template reference
10. **Modal closes automatically**
11. **Liberatorie section updates** - waiver now shows as accepted
12. **User can submit form** once all waivers are accepted

### Validation Logic

**Form submission is blocked if:**

- Standard Vuelidate validation fails (struttura is required)
- Not all required waivers are accepted (`!allLiberatorieAccepted`)

**Visual feedback:**

- Submit button is disabled when waivers are pending
- Warning alert appears in Liberatorie section
- Error message shown if user attempts to submit without all acceptances

### Data Management

**Client-Side Filtering:**

- All ModelloLiberatoria records fetched on load
- All user's Liberatoria records fetched on load
- Filtered in `liberatorieStatus` computed property based on selected struttura

**State Updates:**

- When waiver is accepted, new Liberatoria is added to `userLiberatorias` array
- Computed property `liberatorieStatus` automatically recalculates
- UI updates reactively without page reload

**Reactive Behavior:**

- Changing struttura selection automatically updates displayed waivers
- No additional API calls needed (data is pre-loaded)

---

## Technical Details

### Dependencies

- **Services:** LiberatoriaService, ModelloLiberatoriaService
- **Models:** ILiberatoria, Liberatoria, IModelloLiberatoria
- **Vue:** Composition API with ref, computed
- **Bootstrap Vue Next:** b-modal component
- **Vuelidate:** Form validation
- **Font Awesome:** Icons (check, exclamation-triangle, download)

### API Endpoints Used

- `GET /api/modello-liberatorias` - Fetch all waiver templates
- `GET /api/liberatorias` - Fetch all waiver acceptances
- `POST /api/liberatorias` - Create new waiver acceptance

### Data Structures

**liberatorieStatus (computed property):**

```typescript
[
  {
    modello: IModelloLiberatoria,     // Waiver template
    liberatoria: ILiberatoria | null, // User's acceptance (null if not accepted)
    isAccepted: boolean               // True if accepted
  },
  ...
]
```

**Liberatoria creation:**

```typescript
{
  accettata: Date,                    // Current timestamp
  utente: IUtenteApp,                 // Current user
  modelloLiberatoria: IModelloLiberatoria  // Selected template
}
```

---

## Performance Considerations

### Current Implementation (Client-Side Filtering)

- **Advantages:**
  - No backend changes required
  - Works immediately
  - Simple implementation
- **Disadvantages:**
  - Fetches ALL ModelloLiberatoria (could be many)
  - Fetches ALL Liberatoria (could be thousands)
  - Network overhead on initial load
  - Client-side filtering overhead

### Future Optimization (Backend Filtering)

For production environments with large datasets, consider adding backend endpoints:

- `GET /api/modello-liberatorias?strutturaId={id}` - Filter templates by facility
- `GET /api/liberatorias?utenteId={id}` - Filter acceptances by user

---

## Edge Cases Handled

1. **No Struttura Selected:** Liberatorie section remains hidden
2. **Struttura with No Waivers:** Shows "Nessuna liberatoria richiesta" message
3. **Struttura Changed:** Computed property automatically updates displayed waivers
4. **User Already Accepted Some Waivers:** Shows correct status for each
5. **API Failures:** Error messages displayed via alert service
6. **Modal State Management:** selectedModello cleared on close to prevent stale data
7. **Concurrent Operations:** isSaving flag prevents multiple simultaneous actions

---

## Browser Compatibility

- **Date Formatting:** Uses `toLocaleDateString('it-IT')` for Italian date format
- **Modal:** Bootstrap Vue Next modals compatible with modern browsers
- **Icons:** Font Awesome icons render correctly in all modern browsers

---

## Testing Recommendations

### Manual Testing Checklist

- [ ] Form loads successfully
- [ ] Liberatorie section hidden when no struttura selected
- [ ] Liberatorie section appears when struttura selected
- [ ] Correct waivers displayed for each struttura
- [ ] Accepted waivers show green check
- [ ] Pending waivers show warning icon and link
- [ ] Clicking pending waiver opens modal
- [ ] Modal displays waiver name, text, and document
- [ ] Acceptance statement shows correct user name
- [ ] Accept button creates Liberatoria
- [ ] Modal closes after acceptance
- [ ] Waiver status updates to accepted
- [ ] Submit button disabled when waivers pending
- [ ] Error message shown when trying to submit without acceptances
- [ ] Form submits successfully when all waivers accepted
- [ ] Changing struttura updates waiver list

### Integration Testing

- Test with strutture that have 0, 1, and multiple waivers
- Test with users who have already accepted some waivers
- Test API error scenarios (network failure, server error)
- Test modal close on Escape key
- Test keyboard navigation

---

## Known Limitations

1. **No Backend Filtering:** All records fetched and filtered client-side
2. **No Date Validation:** ModelloLiberatoria `validoDal`/`validoAl` not currently enforced
3. **No Versioning:** No tracking of which version of waiver was accepted
4. **No Revocation:** Users cannot revoke acceptances
5. **Document Type Assumption:** Download link assumes PDF extension

---

## Future Enhancements

1. **Backend Optimization:** Add filtered query endpoints
2. **Date Validation:** Filter by validity period
3. **Versioning:** Track waiver template versions
4. **Revocation Feature:** Allow users to revoke and re-accept
5. **Document Preview:** Inline PDF viewer
6. **Audit Trail:** Show full acceptance history
7. **Notifications:** Email confirmation of waiver acceptance

---

## Summary

This implementation successfully adds a complete waiver management system to the user booking form. Users must review and accept all required waivers before submitting a booking. The solution is fully reactive, handles edge cases gracefully, and provides clear visual feedback throughout the process.

The feature follows Vue 3 Composition API best practices, integrates seamlessly with the existing JHipster application structure, and maintains consistency with the application's UI/UX patterns.

---

# Frontend Changes: Struttura Availability Configuration Feature

## Date

2025-12-15

## Overview

Implemented a feature that allows users with ADMIN or INCARICATO roles to configure availability (opening and closure times) for facilities (Struttura). This enables system administrators to manage when facilities are available or closed, which will be used to validate booking requests.

## Files Modified

### 1. Authority Enum

**File:** `src/main/webapp/app/shared/security/authority.ts`

**Changes:**

- Added new `INCARICATO = 'ROLE_INCARICATO'` role to the Authority enum
- This role grants users access to facility availability configuration alongside ADMIN users

### 2. Struttura List View

**File:** `src/main/webapp/app/entities/struttura/struttura.vue`

**Changes:**

- Added a new clock icon button in the action buttons column of the Struttura list table
- Button navigates to the availability configuration page for the selected facility
- Button placed before the "View" button in the button group
- Uses FontAwesome clock icon with label "Disponibilità"

### 3. Router Configuration

**File:** `src/main/webapp/app/router/entities.ts`

**Changes:**

- Added lazy-loaded component import for `StrutturaDisponibilitaConfig`
- Added new route:
  - Path: `struttura/:strutturaId/disponibilita`
  - Name: `StrutturaDisponibilitaConfig`
  - Authorization: `[Authority.ADMIN, Authority.INCARICATO]`
- Route placed after the `StrutturaView` route definition

## Files Created

### 4. Availability Configuration Component (TypeScript)

**File:** `src/main/webapp/app/entities/struttura/struttura-disponibilita-config.component.ts`

**Features:**

- Uses Vue 3 Composition API with TypeScript
- Injects `StrutturaService` and `DisponibilitaService` for data operations
- Manages state for:
  - Current facility (struttura)
  - New availability form (disponibilita)
  - List of existing availabilities (disponibilitas)
  - Loading and saving states
- Implements custom Vuelidate validation:
  - Required fields: `tipo`, `oraInizio`, `oraFine`
  - Custom validator ensures exactly one of `dataSpecifica` OR `giornoSettimana` is filled
- Uses `useDateFormat` composable for Instant field conversion
- Provides CRUD operations:
  - Create new availability
  - Delete existing availability
  - Auto-refresh list after create/delete
- Defaults new availabilities to `tipo = 'CHIUSURA'` (closure)

### 5. Availability Configuration Component (Vue Template)

**File:** `src/main/webapp/app/entities/struttura/struttura-disponibilita-config.vue`

**Layout Sections:**

**Header:**

- Page title: "Configurazione Disponibilità"

**Struttura Details Card (Read-only):**

- Displays facility information:
  - Nome (name)
  - Descrizione (description)
  - Indirizzo (address)
  - Capienza Max (maximum capacity)
  - Attiva (active status)

**Add Disponibilita Form Card:**
Organized in 5 sections as per requirements:

1. **Tipo Disponibilità** (Type)
   - Select dropdown with enum values
   - Default value: CHIUSURA
   - Options: DISPONIBILE, CHIUSURA

2. **Time Range**
   - Two datetime-local inputs side by side (oraInizio, oraFine)
   - Uses Instant fields with conversion functions
   - Both fields required

3. **Data Specifica** (Specific Date)
   - Date input for specific calendar dates
   - Optional (mutually exclusive with Giorno Settimana)
   - Help text explains the XOR requirement

4. **Giorno Settimana** (Day of Week)
   - Select dropdown with day names
   - Optional (mutually exclusive with Data Specifica)
   - Includes placeholder option "Seleziona un giorno"
   - Options: LUNEDI through DOMENICA

5. **Note**
   - Textarea for additional notes
   - Optional field

**Form Buttons:**

- "Annulla" (Cancel) - navigates back to Struttura list
- "Inserisci disponibilità" (Insert availability) - submits form
  - Disabled when form is invalid or saving

**Existing Disponibilita List Card:**

- Table displaying all availabilities for the current facility
- Columns:
  - Tipo (with enum translation)
  - Ora Inizio
  - Ora Fine
  - Data Specifica
  - Giorno Settimana (with enum translation)
  - Note
  - Actions (delete button)
- Empty state message when no availabilities configured
- Delete button with confirmation (uses FontAwesome times icon)

### 6. Italian Translations - Struttura

**File:** `src/main/webapp/i18n/it/struttura.json`

**Keys Added:**

```json
{
  "configDisponibilita": "Disponibilità",
  "disponibilitaConfig": {
    "title": "Configurazione Disponibilità",
    "strutturaDetails": "Dettagli Struttura",
    "addDisponibilita": "Aggiungi Disponibilità",
    "existingDisponibilita": "Disponibilità Esistenti",
    "noDisponibilita": "Nessuna disponibilità configurata"
  }
}
```

### 7. Italian Translations - Disponibilita

**File:** `src/main/webapp/i18n/it/disponibilita.json`

**Keys Added:**

```json
{
  "validation": {
    "exactlyOneRequired": "Specificare esattamente uno tra Data Specifica o Giorno Settimana"
  },
  "insertButton": "Inserisci disponibilità",
  "selectGiorno": "Seleziona un giorno",
  "help": {
    "dataSpecificaOrGiorno": "Compilare Data Specifica O Giorno Settimana (non entrambi)"
  }
}
```

## User Experience Flow

1. **Access:** User with ADMIN or INCARICATO role navigates to Struttura list
2. **Selection:** User clicks clock icon button on desired facility row
3. **View:** System displays facility details (read-only) at top of page
4. **Configure:** User fills availability form:
   - Selects tipo (DISPONIBILE or CHIUSURA)
   - Sets time range with datetime pickers
   - Chooses either specific date OR day of week (not both)
   - Optionally adds notes
5. **Submit:** User clicks "Inserisci disponibilità"
6. **Validation:** System validates:
   - Required fields are filled
   - Exactly one of dataSpecifica/giornoSettimana is set
7. **Save:** System creates availability record
8. **Refresh:** Form resets and list updates to show new availability
9. **Manage:** User can delete existing availabilities using delete button

## Form Validation Rules

- **Required Fields:**
  - `tipo` (Tipo Disponibilità)
  - `oraInizio` (Start time)
  - `oraFine` (End time)

- **Conditional Requirement (XOR):**
  - Exactly ONE of the following must be filled:
    - `dataSpecifica` (specific calendar date)
    - `giornoSettimana` (recurring day of week)
  - Cannot fill both
  - Cannot leave both empty

- **Submit disabled when:**
  - Any required field is empty
  - XOR validation fails
  - Save operation in progress

## Technical Details

### Date/Time Handling

- Uses Instant fields (`oraInizio`, `oraFine`) rather than String fields
- Frontend converts between Date objects and datetime-local input format
- Leverages `useDateFormat` composable:
  - `convertDateTimeFromServer()` for display
  - `updateInstantField()` for user input

### Authorization

- Route protected with `meta.authorities: [Authority.ADMIN, Authority.INCARICATO]`
- Only users with ADMIN or INCARICATO role can access the page
- Unauthorized users redirected to /forbidden page

### Data Management

- Filters disponibilitas by struttura ID client-side after fetching
- Creates new disponibilita with struttura relationship pre-set
- Deletes individual disponibilita with immediate list refresh
- Form reset after successful creation

### Styling

- Uses Bootstrap Vue Next components (cards, forms, tables)
- Responsive layout with mobile-friendly button labels (hidden on small screens)
- Form validation CSS classes (valid/invalid states)
- Consistent with existing JHipster application styling

## Future Considerations

This frontend implementation provides the UI for availability configuration. The backend will use this data to:

- Validate booking requests against closure periods
- Check for conflicts with confirmed bookings
- Determine facility availability for specific dates/times

The availability check endpoint (backend) will reference:

- Only CONFERMATA bookings (confirmed, not pending)
- CHIUSURA disponibilita (closures)
- Time range overlaps between requests and existing bookings/closures

## Testing Recommendations

1. **Authorization Testing:**
   - Verify ADMIN users can access the page
   - Verify INCARICATO users can access the page
   - Verify USER role users are blocked

2. **Form Validation Testing:**
   - Test required field validation
   - Test XOR validation for dataSpecifica/giornoSettimana
   - Test form submission with valid data
   - Test form submission with invalid data

3. **CRUD Operations Testing:**
   - Create new availability with specific date
   - Create new availability with day of week
   - Delete existing availability
   - Verify list refresh after operations

4. **UI/UX Testing:**
   - Verify clock button appears in Struttura list
   - Verify navigation to configuration page
   - Verify facility details display correctly
   - Verify empty state message
   - Verify responsive behavior on mobile devices

5. **i18n Testing:**
   - Verify all labels are translated correctly
   - Verify enum values are translated (TipoDisponibilita, GiornoSettimana)
   - Verify validation messages display in Italian

## Summary

This implementation successfully adds a complete availability configuration system for facilities. Authorized users (ADMIN and INCARICATO) can manage both specific date closures and recurring day-of-week availability patterns. The solution is fully reactive, handles edge cases gracefully, and provides clear visual feedback throughout the process.

The feature follows Vue 3 Composition API best practices, integrates seamlessly with the existing JHipster application structure, and maintains consistency with the application's UI/UX patterns.

---

# Frontend Changes: User Profile Management Feature

## Date

2025-12-16

## Overview

This document describes the frontend changes made to implement the user profile management feature for the Smartbooking application. This feature allows registered users to complete and manage their UtenteApp profile information, which is essential for making reservations.

## Feature Summary

After registration, users can access a dedicated interface to input and modify their UtenteApp data. The interface consists of two sections:

1. **Personal Information** (required): nome, cognome, data di nascita, luogo di nascita, residente, telefono
2. **Company/Organization Information** (optional): nome società, sede, codice fiscale, telefono società, email società

A profile completion check is shown on the home page to prompt users to complete their profile if incomplete.

## Files Created

1. `src/main/webapp/app/account/profile/profile.component.ts` - TypeScript component logic
2. `src/main/webapp/app/account/profile/profile.vue` - Vue template
3. `src/main/webapp/i18n/it/profile.json` - Italian translations

## Files Modified

1. `src/main/webapp/app/entities/utente-app/utente-app.service.ts` - Added saveCurrentUserProfile() method
2. `src/main/webapp/app/router/account.ts` - Added /account/profile route
3. `src/main/webapp/app/core/jhi-navbar/jhi-navbar.vue` - Added profile link in menu
4. `src/main/webapp/i18n/it/global.json` - Added profile menu translation
5. `src/main/webapp/app/core/home/home.component.ts` - Added profile completion check
6. `src/main/webapp/app/core/home/home.vue` - Added warning alert
7. `src/main/webapp/i18n/it/home.json` - Added incomplete profile messages
8. `src/main/webapp/app/main.ts` - Registered UtenteAppService provider

## Backend Integration

**New Endpoint Created:**

- `POST /api/utente-apps/current` - Save current user's profile
- File: `src/main/java/it/sw/pa/comune/artegna/web/rest/UtenteAppResource.java`

## Testing Status

- ✅ Frontend build: SUCCESSFUL
- ✅ No TypeScript compilation errors
- ✅ All translations present
- ✅ Profile component generated in build output

## User Flow

1. User registers and logs in
2. Home page checks for complete profile
3. Warning displays if profile incomplete
4. User clicks link or navigates to Profile in menu
5. Form loads with username/email pre-filled (disabled)
6. User completes required personal fields
7. Optionally fills company information
8. User saves profile
9. Warning disappears from home page

## Key Features

- Two-section form layout (personal + company)
- Comprehensive validation with Vuelidate
- Real-time validation feedback
- Success/error messages
- Profile completion check on home page
- Bootstrap responsive design
- Complete Italian translations
- Security: users can only edit their own profile