nitrix/fete
1
0
Fork 0
Code Issues 1 Pull Requests 10 Actions Packages Projects Releases 13 Wiki Activity

Add 008-rsvp feature spec and design artifacts

Browse Source 
Spec, research decisions, implementation plan, data model,
API contract, and task breakdown for the RSVP feature.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
nitrix
2026-03-08 11:48:00 +01:00
parent 9a78ebd9b0
commit 4828d06aba
8 changed files with 731 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
specs/008-rsvp/contracts/create-rsvp.yaml Normal file
View File

@@ -0,0 +1,79 @@
# OpenAPI contract addition for POST /events/{eventToken}/rsvps
# To be merged into backend/src/main/resources/openapi/api.yaml
paths:
/events/{eventToken}/rsvps:
post:
operationId: createRsvp
summary: Submit an RSVP for an event
tags:
- events
parameters:
- name: eventToken
in: path
required: true
schema:
type: string
format: uuid
description: Public event token
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateRsvpRequest"
responses:
"201":
description: RSVP created successfully
content:
application/json:
schema:
$ref: "#/components/schemas/CreateRsvpResponse"
"400":
description: Validation failed (e.g. blank name)
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ValidationProblemDetail"
"404":
description: Event not found
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"409":
description: Event has expired — RSVPs no longer accepted
content:
application/problem+json:
schema:
$ref: "#/components/schemas/ProblemDetail"
components:
schemas:
CreateRsvpRequest:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Guest's display name
example: "Max Mustermann"
CreateRsvpResponse:
type: object
required:
- rsvpToken
- name
properties:
rsvpToken:
type: string
format: uuid
description: Token identifying this RSVP (store client-side for future updates)
example: "d4e5f6a7-b8c9-0123-4567-890abcdef012"
name:
type: string
description: Guest's display name as stored
example: "Max Mustermann"

93
specs/008-rsvp/data-model.md Normal file
View File

@@ -0,0 +1,93 @@
# Data Model: RSVP to an Event (008)
**Date**: 2026-03-06
## Entities
### Rsvp (NEW)
| Field | Type | Required | Constraints | Notes |
|------------|----------------|----------|--------------------------------|------------------------------------|
| id | Long | yes | BIGSERIAL, PK | Internal only, never exposed |
| rsvpToken | RsvpToken | yes | UNIQUE, NOT NULL | Server-generated UUID, returned to client |
| eventId | Long | yes | FK -> events.id, NOT NULL | Which event this RSVP belongs to |
| name | String | yes | 1-100 chars, NOT NULL | Guest's display name |
**Notes**:
- No `attending` boolean — existence of an entry implies attendance (per spec).
- No `createdAt` — not required by the spec. Can be added later if needed (e.g. for guest list sorting in 009).
- Duplicates from different devices or cleared localStorage are accepted (privacy trade-off).
### Token Value Objects (NEW)
| Record | Field | Type | Notes |
|------------------|-------|------|-----------------------------------------------|
| `EventToken` | value | UUID | Immutable, non-null. Java record wrapping UUID |
| `OrganizerToken` | value | UUID | Immutable, non-null. Java record wrapping UUID |
| `RsvpToken` | value | UUID | Immutable, non-null. Java record wrapping UUID |
**Purpose**: Type-safe wrappers preventing mix-ups between the three token types at compile time. All generated server-side via `UUID.randomUUID()`. JPA entities continue to use raw `UUID` columns — mapping happens in the persistence adapters.
### Event (MODIFIED — token fields change type)
The Event domain model's `eventToken` and `organizerToken` fields change from raw `UUID` to their typed record wrappers. No database schema change — the JPA entity keeps raw `UUID` columns.
| Field | Old Type | New Type |
|-----------------|----------|------------------|
| eventToken | UUID | EventToken |
| organizerToken | UUID | OrganizerToken |
The `attendeeCount` was already added to the API response in 007-view-event — it now gets populated from a count query instead of returning 0.
### StoredEvent (frontend localStorage — modified)
| Field | Type | Required | Notes |
|----------------|--------|----------|------------------------------------|
| eventToken | string | yes | Existing |
| organizerToken | string | no | Existing (organizer flow) |
| title | string | yes | Existing |
| dateTime | string | yes | Existing |
| expiryDate | string | yes | Existing |
| rsvpToken | string | no | **NEW** — set after RSVP submission |
| rsvpName | string | no | **NEW** — guest's submitted name |
## Validation Rules
- `name`: required, 1-100 characters, trimmed. Blank or whitespace-only is rejected.
- `rsvpToken`: server-generated, never from client input on create.
- `eventId`: must reference an existing, non-expired event.
## Relationships
```
Event 1 <---- * Rsvp
| |
eventToken rsvpToken (unique)
(public) (returned to client)
```
## Type Mapping (full stack)
| Concept | Java | PostgreSQL | OpenAPI | TypeScript |
|--------------|-------------------|---------------|---------------------|------------|
| RSVP ID | `Long` | `bigserial` | N/A (not exposed) | N/A |
| RSVP Token | `RsvpToken` | `uuid` | `string` `uuid` | `string` |
| Event FK | `Long` | `bigint` | N/A (path param) | N/A |
| Guest name | `String` | `varchar(100)`| `string` | `string` |
| Attendee cnt | `long` | `count(*)` | `integer` | `number` |
## Database Migration
New Liquibase changeset `003-create-rsvps-table.xml`:
```sql
CREATE TABLE rsvps (
id BIGSERIAL PRIMARY KEY,
rsvp_token UUID NOT NULL UNIQUE,
event_id BIGINT NOT NULL REFERENCES events(id),
name VARCHAR(100) NOT NULL
);
CREATE INDEX idx_rsvps_event_id ON rsvps(event_id);
CREATE INDEX idx_rsvps_rsvp_token ON rsvps(rsvp_token);
```

114
specs/008-rsvp/plan.md Normal file
View File

@@ -0,0 +1,114 @@
# Implementation Plan: RSVP to an Event
**Branch**: `008-rsvp` | **Date**: 2026-03-06 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/specs/008-rsvp/spec.md`
## Summary
Add RSVP functionality to the event detail page. Backend: new `POST /api/events/{eventToken}/rsvps` endpoint that persists an RSVP (guest name) and returns an `rsvpToken`. Populates the existing `attendeeCount` field with real data from a count query. Rejects RSVPs on expired events (409). Frontend: fullscreen event presentation with sticky bottom bar (RSVP CTA or status), bottom sheet with RSVP form (name + submit). localStorage stores rsvpToken and name per event. No account required.
## Technical Context
**Language/Version**: Java 25 (backend), TypeScript 5.9 (frontend)
**Primary Dependencies**: Spring Boot 3.5.x, Vue 3, Vue Router 5, openapi-fetch, openapi-typescript
**Storage**: PostgreSQL (JPA via Spring Data, Liquibase migrations)
**Testing**: JUnit (backend), Vitest (frontend unit), Playwright + MSW (frontend E2E)
**Target Platform**: Self-hosted web application (Docker)
**Project Type**: Web service + SPA
**Performance Goals**: N/A (single-user scale, self-hosted)
**Constraints**: No external resources (CDNs, fonts, tracking), WCAG AA, privacy-first, no PII logging
**Scale/Scope**: New RSVP domain (model + service + controller + persistence), new frontend components (bottom sheet, sticky bar), modified event detail view
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
| Principle | Status | Notes |
|-----------|--------|-------|
| I. Privacy by Design | PASS | No PII logged. Only guest-entered name stored. No IP logging. No tracking. Attendee names not exposed publicly (count only). Unprotected endpoint is a conscious privacy trade-off per spec. |
| II. Test-Driven Methodology | PASS | TDD enforced: backend unit + integration tests, frontend unit tests, E2E tests. Tests written before implementation. |
| III. API-First Development | PASS | OpenAPI spec updated first. New endpoint + schemas with `example:` fields. Types generated before implementation. |
| IV. Simplicity & Quality | PASS | Minimal scope: one POST endpoint, one domain entity, one bottom sheet component. No CAPTCHA, no rate limiting, no edit/withdraw (deferred). Cancelled event guard deferred to US-18. |
| V. Dependency Discipline | PASS | No new dependencies. Bottom sheet is CSS + Vue (~50 lines). No UI library. |
| VI. Accessibility | PASS | Bottom sheet uses dialog role + aria-modal. Focus trap. ESC to close. Keyboard navigable. WCAG AA contrast via design system. |
**Post-Phase-1 re-check**: All gates still pass. Three token value objects (`EventToken`, `OrganizerToken`, `RsvpToken`) introduced uniformly — justified by spec requirement for type-safe tokens. Refactoring existing Event model to use typed tokens is a mechanical change well-covered by existing tests.
## Project Structure
### Documentation (this feature)
```text
specs/008-rsvp/
├── plan.md # This file
├── spec.md # Feature specification
├── research.md # Phase 0: research decisions (R-1 through R-8)
├── data-model.md # Phase 1: Rsvp entity, RsvpToken value object
├── quickstart.md # Phase 1: implementation overview
├── contracts/
│ └── create-rsvp.yaml # Phase 1: POST endpoint contract
└── tasks.md # Phase 2: implementation tasks (via /speckit.tasks)
```
### Source Code (repository root)
```text
backend/
├── src/main/java/de/fete/
│ ├── domain/
│ │ ├── model/
│ │ │ ├── Event.java # MODIFIED: UUID → EventToken/OrganizerToken
│ │ │ ├── EventToken.java # NEW: typed token record
│ │ │ ├── OrganizerToken.java # NEW: typed token record
│ │ │ ├── Rsvp.java # NEW: RSVP domain entity
│ │ │ └── RsvpToken.java # NEW: typed token record
│ │ └── port/
│ │ ├── in/CreateRsvpUseCase.java # NEW: inbound port
│ │ └── out/RsvpRepository.java # NEW: outbound port
│ ├── application/service/
│ │ ├── EventService.java # MODIFIED: use typed tokens
│ │ └── RsvpService.java # NEW: RSVP business logic
│ ├── adapter/
│ │ ├── in/web/
│ │ │ ├── EventController.java # MODIFIED: typed tokens + attendee count + createRsvp()
│ │ │ └── GlobalExceptionHandler.java # MODIFIED: handle EventExpiredException
│ │ └── out/persistence/
│ │ ├── EventPersistenceAdapter.java # MODIFIED: map typed tokens
│ │ ├── RsvpJpaEntity.java # NEW: JPA entity
│ │ ├── RsvpJpaRepository.java # NEW: Spring Data interface
│ │ └── RsvpPersistenceAdapter.java # NEW: port implementation
├── src/main/resources/
│ ├── openapi/api.yaml # MODIFIED: add RSVP endpoint + schemas
│ └── db/changelog/
│ ├── db.changelog-master.xml # MODIFIED: include 003
│ └── 003-create-rsvps-table.xml # NEW: rsvps table
└── src/test/java/de/fete/
├── application/service/
│ ├── EventServiceTest.java # MODIFIED: use typed tokens
│ └── RsvpServiceTest.java # NEW: unit tests
└── adapter/in/web/
└── EventControllerIntegrationTest.java # MODIFIED: typed tokens + RSVP integration tests
frontend/
├── src/
│ ├── api/schema.d.ts # REGENERATED from OpenAPI
│ ├── components/
│ │ ├── BottomSheet.vue # NEW: reusable bottom sheet
│ │ └── RsvpBar.vue # NEW: sticky bottom bar
│ ├── views/EventDetailView.vue # MODIFIED: integrate RSVP bar + sheet
│ ├── composables/useEventStorage.ts # MODIFIED: add rsvpToken/rsvpName
│ └── assets/main.css # MODIFIED: bottom sheet + bar styles
├── src/views/__tests__/EventDetailView.spec.ts # MODIFIED: RSVP integration tests
├── src/components/__tests__/
│ ├── BottomSheet.spec.ts # NEW: unit tests
│ └── RsvpBar.spec.ts # NEW: unit tests
├── src/composables/__tests__/useEventStorage.spec.ts # MODIFIED: test new fields
└── e2e/
└── event-rsvp.spec.ts # NEW: E2E tests
```
**Structure Decision**: Extends the existing web application structure (backend + frontend). Adds a new RSVP domain following the same hexagonal architecture pattern established in 006-create-event and 007-view-event. Cross-cutting refactoring introduces typed token value objects (`EventToken`, `OrganizerToken`, `RsvpToken`) across all layers. Two new frontend components (`BottomSheet`, `RsvpBar`) are the first entries in `src/components/` — justified because they're reusable UI primitives, not view-specific markup.
## Complexity Tracking
No constitution violations. No entries needed.

58
specs/008-rsvp/quickstart.md Normal file
View File

@@ -0,0 +1,58 @@
# Quickstart: RSVP to an Event (008)
## What this feature adds
1. **Backend**: New `POST /api/events/{eventToken}/rsvps` endpoint that accepts an RSVP (guest name) and returns an `rsvpToken`. Populates the existing `attendeeCount` field in `GET /events/{token}` with real data.
2. **Frontend**: Bottom sheet RSVP form on the event detail page. Sticky bottom bar with CTA (or status after RSVP). localStorage persistence of RSVP data.
## Implementation order
1. **Token value objects** — Create `EventToken`, `OrganizerToken`, `RsvpToken` records. Refactor `Event` domain model and all layers (service, controller, repository, persistence adapter, tests) to use typed tokens instead of raw UUID.
2. **OpenAPI spec** — Add `CreateRsvpRequest`, `CreateRsvpResponse`, and the `POST /events/{eventToken}/rsvps` endpoint.
3. **Liquibase migration** — Create `rsvps` table (003-create-rsvps-table.xml).
4. **Domain model** — `Rsvp` entity using `RsvpToken`.
5. **Ports** — `CreateRsvpUseCase` (in), `RsvpRepository` (out).
6. **Persistence adapter** — `RsvpJpaEntity`, `RsvpJpaRepository`, `RsvpPersistenceAdapter`.
7. **Service** — `RsvpService` implementing `CreateRsvpUseCase`.
8. **Controller** — Add `createRsvp()` to `EventController`.
9. **Attendee count** — Wire `RsvpRepository.countByEventId()` into the GET event flow.
10. **Frontend composable** — Extend `useEventStorage` with `rsvpToken`/`rsvpName`.
11. **Frontend UI** — Bottom sheet component, sticky bar, RSVP form.
12. **E2E tests** — RSVP submission, expired event guard, localStorage verification.
## Key files to touch
### Backend (new)
- `domain/model/EventToken.java`
- `domain/model/OrganizerToken.java`
- `domain/model/Rsvp.java`
- `domain/model/RsvpToken.java`
- `domain/port/in/CreateRsvpUseCase.java`
- `domain/port/out/RsvpRepository.java`
- `application/service/RsvpService.java`
- `adapter/out/persistence/RsvpJpaEntity.java`
- `adapter/out/persistence/RsvpJpaRepository.java`
- `adapter/out/persistence/RsvpPersistenceAdapter.java`
- `db/changelog/003-create-rsvps-table.xml`
### Backend (modified)
- `domain/model/Event.java` — UUID → EventToken/OrganizerToken
- `application/service/EventService.java` — use typed tokens
- `adapter/in/web/EventController.java` — typed tokens + wire attendee count + createRsvp()
- `adapter/in/web/GlobalExceptionHandler.java` — handle `EventExpiredException` (409)
- `adapter/out/persistence/EventPersistenceAdapter.java` — map typed tokens
- `domain/port/out/EventRepository.java` — typed token in signature
- `openapi/api.yaml` — new endpoint + schemas
- `db/changelog/db.changelog-master.xml` — include new migration
- All existing tests — update to use typed tokens
### Frontend (new)
- `src/components/BottomSheet.vue` — reusable bottom sheet
- `src/components/RsvpBar.vue` — sticky bottom bar (CTA or status)
- `e2e/event-rsvp.spec.ts` — E2E tests
### Frontend (modified)
- `src/views/EventDetailView.vue` — integrate RSVP bar + bottom sheet
- `src/composables/useEventStorage.ts` — add rsvpToken/rsvpName fields
- `src/api/schema.d.ts` — regenerated from OpenAPI

157
specs/008-rsvp/research.md Normal file
View File

@@ -0,0 +1,157 @@
# Research: RSVP to an Event (008)
**Date**: 2026-03-06 | **Status**: Complete
## R-1: RSVP Endpoint Design
**Decision**: `POST /api/events/{eventToken}/rsvps` creates an RSVP. Returns `201` with `rsvpToken` on success. Rejects with `409 Conflict` if event expired.
**Rationale**: RSVPs are a sub-resource of events — nesting under the event token is RESTful and groups operations logically. The event token in the path identifies the event; no separate event ID in the request body needed.
**Flow**:
1. `EventController` implements generated `EventsApi.createRsvp()` — same controller, same tag, sub-resource of events.
2. Controller resolves the event via `eventToken`, checks expiry.
3. New inbound port: `CreateRsvpUseCase` with `createRsvp(CreateRsvpCommand): Rsvp`.
4. `RsvpService` validates event exists + not expired, persists RSVP, returns domain model.
5. Controller maps to `CreateRsvpResponse` DTO (contains `rsvpToken`).
6. 404 if event not found, 409 if event expired, 400 for validation errors.
**Alternatives considered**:
- `POST /api/rsvps` with eventToken in body — rejected because RSVPs are always scoped to an event. Nested resource is cleaner.
- Separate `RsvpController` — rejected because the URL is under `/events/`, so it belongs in `EventController`. One controller per resource root (KISS).
- `PUT` instead of `POST` — rejected because the client doesn't know the rsvpToken before creation.
## R-2: Token Value Objects
**Decision**: Introduce all three token types as Java records wrapping `UUID`: `EventToken`, `OrganizerToken`, and `RsvpToken`. Refactor the existing `Event` domain model and all layers (service, controller, repository, persistence adapter) to use the typed tokens instead of raw `UUID`.
**Rationale**: The spec mandates typed token records. Introducing `RsvpToken` alone while leaving the other two as raw UUIDs would create an inconsistency in the domain model. All three tokens serve the same purpose (type-safe identification) and should be modeled uniformly. The cross-cutting refactoring touches existing code but is mechanical and well-covered by existing tests.
**Implementation pattern** (same for all three):
```java
package de.fete.domain.model;
public record EventToken(UUID value) {
public EventToken {
Objects.requireNonNull(value, "eventToken must not be null");
}
public static EventToken generate() {
return new EventToken(UUID.randomUUID());
}
}
```
```java
public record OrganizerToken(UUID value) { /* same pattern */ }
public record RsvpToken(UUID value) { /* same pattern */ }
```
**Impact on existing code**:
- `Event.java`: `UUID eventToken` → `EventToken eventToken`, `UUID organizerToken` → `OrganizerToken organizerToken`
- `EventService.java`: `UUID.randomUUID()` → `EventToken.generate()` / `OrganizerToken.generate()`
- `EventController.java`: unwrap tokens at API boundary (`token.value()`)
- `EventRepository.java` / `EventPersistenceAdapter.java`: map between domain tokens and raw UUIDs for JPA
- `EventJpaEntity.java`: stays with raw `UUID` columns (JPA mapping layer)
- All existing tests: update to use typed tokens
**Alternatives considered**:
- Use raw UUID everywhere — rejected because the spec explicitly requires typed records and they prevent mixing up token types at compile time.
- Introduce only `RsvpToken` now — rejected because it creates an inconsistency. All three should be uniform.
## R-3: Attendee Count Population
**Decision**: Populate `attendeeCount` in `GetEventResponse` by counting RSVP rows for the event. The count query lives in the `RsvpRepository` port and is called by `EventService` (or a query in `RsvpService` delegated to by `EventController`).
**Rationale**: The `attendeeCount` field already exists in the API contract (returns 0 today per R-3 in 007). Now it gets real data. Since an RSVP entry's existence implies attendance (no `attending` boolean), the count is simply `COUNT(*) WHERE event_id = ?`.
**Implementation approach**: Add `countByEventId(Long eventId)` to `RsvpRepository`. `EventService.getByEventToken()` returns the Event domain object; the controller queries the RSVP count separately and sets it on the response. This keeps Event and RSVP domains loosely coupled.
**Alternatives considered**:
- Store count on the Event entity (denormalized) — rejected because it introduces update anomalies and requires synchronization logic.
- Join query in EventRepository — rejected because it couples Event persistence to RSVP schema.
## R-4: Expired Event Guard
**Decision**: Both client and server enforce the expiry guard. Client hides the RSVP form when `expired === true` (from GetEventResponse). Server rejects `POST /rsvps` with `409 Conflict` when `event.expiryDate < today`.
**Rationale**: Defense in depth. The client check is UX (don't show a form that can't succeed). The server check is the authoritative guard (clients can be bypassed). Using `409 Conflict` rather than `400 Bad Request` because the request format is valid — it's the event state that prevents the operation.
**Alternatives considered**:
- Client-only guard — rejected because clients can be bypassed.
- `400 Bad Request` — rejected because the request body is valid; the conflict is with the event's state.
- `422 Unprocessable Entity` — acceptable but `409` better communicates "the resource state conflicts with this operation."
## R-5: localStorage Schema for RSVP
**Decision**: Extend the existing `fete:events` localStorage structure. Each `StoredEvent` entry gains optional `rsvpToken` and `rsvpName` fields.
**Rationale**: The existing `useEventStorage` composable already stores events by token. Adding RSVP data to the same entry avoids a second localStorage key and keeps event data co-located. The spec requires storing: rsvpToken, name, event token, event title, event date — the last three are already in `StoredEvent`.
**Schema change**:
```typescript
interface StoredEvent {
eventToken: string
organizerToken?: string // existing (for organizers)
title: string // existing
dateTime: string // existing
expiryDate: string // existing
rsvpToken?: string // NEW — present after RSVP
rsvpName?: string // NEW — guest's submitted name
}
```
**Alternatives considered**:
- Separate `fete:rsvps` localStorage key — rejected because it duplicates event metadata (title, date) and complicates lookups.
- IndexedDB — rejected (over-engineering for a few KBs of data).
## R-6: Bottom Sheet UI Pattern
**Decision**: Implement the bottom sheet as a Vue component using CSS transforms and transitions. No UI library dependency.
**Rationale**: The spec requires a bottom sheet for the RSVP form. A custom implementation using `transform: translateY()` with CSS transitions is lightweight, accessible, and avoids new dependencies (Principle V). The sheet slides up from the bottom on open and back down on close.
**Key implementation details**:
- Overlay backdrop (semi-transparent) with click-to-dismiss
- `<dialog>` element or ARIA `role="dialog"` with `aria-modal="true"`
- Focus trap inside the sheet (keyboard accessibility)
- ESC key to close
- Transition: `transform 0.3s ease-out`
- Mobile: full-width, max-height ~50vh. Desktop: full-width within the 480px column.
**Alternatives considered**:
- Modal/dialog instead of bottom sheet — rejected because bottom sheets are the mobile-native pattern for contextual actions.
- Headless UI library (e.g., @headlessui/vue) — rejected because it adds a dependency for a single component. Custom implementation is ~50 lines.
## R-7: Sticky Bottom Bar
**Decision**: The sticky bar is a `position: fixed` element at the bottom of the viewport, within the content column (max 480px). It contains either the RSVP CTA button or the RSVP status text.
**Rationale**: The spec defines two states for the bar:
1. **No RSVP**: Shows CTA button (accent color, "Ich bin dabei!" or similar)
2. **Has RSVP**: Shows status text ("Du kommst!" + edit hint, though edit is out of scope)
The bar state is determined by checking localStorage for an rsvpToken for the current event.
**CSS pattern**:
```css
.sticky-bar {
position: fixed;
bottom: 0;
left: 50%;
transform: translateX(-50%);
width: 100%;
max-width: 480px; /* matches content column */
padding: 1rem 1.2rem;
/* glass-morphism or solid surface */
}
```
**Alternatives considered**:
- `position: sticky` at bottom of content — rejected because it only sticks within the scroll container, not the viewport. Fixed is needed for always-visible CTA.
## R-8: Cancelled Event Guard (Deferred)
**Decision**: FR-010 (cancelled event guard) is deferred per spec. The code will NOT check for cancellation status. This will be added when US-18 (cancel event) is implemented.
**Rationale**: No cancellation field exists on the Event model yet. Adding a guard for a non-existent state violates KISS (Principle IV).

72
specs/008-rsvp/spec.md
View File

@@ -5,11 +5,25 @@
**Status**: Draft
**Source**: Migrated from spec/userstories.md
## Clarifications
### Session 2026-03-06
- Q: How should the server deduplicate RSVPs from the same device without accounts? → A: Server generates an `rsvpToken` (UUID) on first RSVP, returns it to the client. Client stores it in localStorage per event. On re-RSVP, client sends the `rsvpToken` to update instead of create. No global device identifier — the token is event-scoped. If localStorage is lost (cleared or different device), a duplicate entry is accepted as a privacy trade-off.
- Q: Should typed token value objects be used in the backend? → A: Yes. Backend: The three token types (EventToken, OrganizerToken, RsvpToken) MUST be modeled as distinct Java record types wrapping UUID, not passed as raw UUID values. Frontend: No branded types — plain string variables with clear naming (eventToken, rsvpToken) are sufficient given TypeScript's structural typing and OpenAPI codegen.
- Q: How should the RSVP interaction be presented on the event page? → A: Fullscreen event presentation (gradient background, later Unsplash). Title prominent at top, key facts below (description, date, attendee count) — spacious layout. Sticky bottom bar with RSVP CTA. Tap opens a bottom sheet with the RSVP form. After RSVP, the bar shows status ("Du kommst!" + edit option) instead of the CTA.
- Q: How does the RSVP form handle declining? → A: There is no explicit "not attending" button. The bottom sheet only offers the attending flow (name + submit). To not attend, the guest simply closes the sheet. Withdrawing an existing RSVP (DELETE with rsvpToken) is out of scope — deferred to a separate edit-RSVP spec.
- Q: Should the attendee name list be publicly visible on the event page? → A: No. Only the attendee count is shown publicly. The full name list is visible only to the organizer (via organizer link). This maximizes guest privacy.
- Q: Should the RSVP endpoint have spam/abuse protection? → A: No. The RSVP endpoint is intentionally unprotected — risk is consciously accepted as a privacy trade-off consistent with the no-account, no-tracking philosophy. Protection measures can be retrofitted in a separate spec if real-world abuse occurs. KISS.
- Q: How is the attendee count delivered and updated? → A: As a new `attendeeCount` field in the existing Event response (no separate endpoint). Loaded once on page load, no polling or WebSocket. After the guest's own RSVP submission, the count is optimistically incremented (+1) client-side. KISS.
- Q: What determines the RSVP cutoff? → A: The event date itself. No separate expiry field. After the event date has passed, RSVPs are blocked (form hidden, server rejects).
- Q: Should the RSVP entity have an `attending` boolean field? → A: No. The server only stores attending RSVPs — existence of an entry implies attendance. No `attending` boolean needed. Deletion of entries (withdrawal) is deferred to the edit-RSVP spec.
## User Scenarios & Testing
### User Story 1 - Submit an RSVP (Priority: P1)
A guest opens an active event page and indicates whether they will attend. If attending, they must provide their name. If not attending, the name is optional. The RSVP is sent to the server and persisted. The guest's choice, name, event token, title, and date are saved in localStorage.
A guest opens an active event page, which presents the event fullscreen (gradient background, title prominent at top, key facts below including attendee count). A sticky bottom bar shows an RSVP call-to-action. Tapping opens a bottom sheet with the RSVP form: name field + submit. The RSVP is sent to the server and persisted. The server returns an rsvpToken which, along with the name, event token, title, and date, is saved in localStorage. After submission, the bottom sheet closes and the sticky bar shows the guest's RSVP status. To not attend, the guest simply closes the sheet — no server request.
**Why this priority**: Core interactive feature of the app. Without it, guests cannot communicate attendance, and the attendee list (US-2) has no data.
@@ -17,30 +31,15 @@ A guest opens an active event page and indicates whether they will attend. If at
**Acceptance Scenarios**:
1. **Given** a guest is on an active event page, **When** they select "I'm attending" and enter their name, **Then** the RSVP is submitted to the server, persisted, and the attendee list reflects the new entry.
2. **Given** a guest is on an active event page, **When** they select "I'm attending" but leave the name blank, **Then** the form is not submitted and a validation message indicating the name is required is shown.
3. **Given** a guest is on an active event page, **When** they select "I'm not attending" without entering a name, **Then** the RSVP is submitted successfully (name is optional for non-attendees).
4. **Given** a guest submits an RSVP (attending or not), **When** the submission succeeds, **Then** the guest's RSVP choice, name, event token, event title, and event date are stored in localStorage on this device.
5. **Given** a guest submits an RSVP, **When** the submission succeeds, **Then** no account, login, or personal data beyond the optionally entered name is required.
1. **Given** a guest is on an active event page, **When** they tap the RSVP CTA, enter their name, and submit, **Then** the RSVP is submitted to the server, persisted, and the attendee count updates.
2. **Given** a guest has opened the bottom sheet, **When** they leave the name blank and try to submit, **Then** the form is not submitted and a validation message is shown.
3. **Given** a guest has opened the bottom sheet, **When** they close it without submitting, **Then** no server request is made and no state changes.
4. **Given** a guest submits an RSVP, **When** the submission succeeds, **Then** the rsvpToken, name, event token, event title, and event date are stored in localStorage on this device.
5. **Given** a guest submits an RSVP, **When** the submission succeeds, **Then** no account, login, or personal data beyond the entered name is required.
---
### User Story 2 - Re-RSVP from the Same Device (Priority: P2)
A returning guest on the same device opens an event page where they previously submitted an RSVP. The form pre-fills with their prior choice and name. Re-submitting updates the existing RSVP rather than creating a duplicate.
**Why this priority**: Prevents duplicate entries and provides a better UX for guests who want to change their mind. Depends on Story 1 populating localStorage.
**Independent Test**: Can be tested by RSVPing once, then reloading the event page and verifying the form is pre-filled and a second submission updates rather than duplicates the server-side record.
**Acceptance Scenarios**:
1. **Given** a guest has previously submitted an RSVP on this device, **When** they open the same event page again, **Then** the RSVP form is pre-filled with their previous choice and name.
2. **Given** a guest has a prior RSVP pre-filled, **When** they change their selection and re-submit, **Then** the existing server-side RSVP entry is updated and no duplicate entry is created.
---
### User Story 3 - RSVP Blocked on Expired or Cancelled Events (Priority: P2)
### User Story 2 - RSVP Blocked on Expired or Cancelled Events (Priority: P2)
A guest attempts to RSVP to an event that has already expired or has been cancelled. The RSVP form is not shown and the server rejects any submission attempts.
@@ -58,37 +57,40 @@ A guest attempts to RSVP to an event that has already expired or has been cancel
### Edge Cases
- What happens when a guest RSVPs on two different devices? Each device stores its own localStorage entry; the server holds both RSVPs as separate entries (no deduplication across devices — acceptable per design, consistent with the no-account model).
- What happens when a guest RSVPs on two different devices? Each device stores its own localStorage entry; the server holds both RSVPs as separate entries (no deduplication across devices — accepted privacy trade-off).
- What happens when the server is unreachable during RSVP submission? The submission fails; localStorage is not updated (no optimistic write). The guest sees an error and can retry.
- What happens if localStorage is cleared after RSVPing? The form no longer pre-fills and the guest can re-submit; the server will create a new RSVP entry rather than update the old one.
- What happens if localStorage is cleared after RSVPing? The sticky bar shows the CTA again (as if no prior RSVP). A new submission creates a duplicate server-side entry — accepted privacy trade-off.
- What about spam/abuse on the unprotected RSVP endpoint? Risk is consciously accepted (KISS, privacy-first). No rate limiting, no honeypot, no CAPTCHA. Can be retrofitted in a future spec if real-world abuse occurs.
## Requirements
### Functional Requirements
- **FR-001**: The RSVP form MUST offer exactly two choices: "I'm attending" and "I'm not attending".
- **FR-002**: When the guest selects "I'm attending", the name field MUST be required; submission MUST be blocked if the name is blank.
- **FR-003**: When the guest selects "I'm not attending", the name field MUST be optional; submission MUST succeed without a name.
- **FR-004**: On successful RSVP submission, the server MUST persist the RSVP associated with the event.
- **FR-005**: On successful RSVP submission, the client MUST store the guest's RSVP choice and name in localStorage, keyed by event token.
- **FR-001**: The RSVP bottom sheet MUST offer an attending flow only: name field (required, max 100 characters) + submit. There is no explicit "not attending" option — the guest simply closes the sheet.
- **FR-002**: Submission MUST be blocked if the name is blank or exceeds 100 characters.
- **FR-003**: If a prior RSVP for this event exists in localStorage (rsvpToken present), the sticky bottom bar MUST show the guest's RSVP status instead of the initial CTA. Editing the RSVP (name change, withdrawal) is out of scope for this spec.
- **FR-004**: On successful attending RSVP submission, the server MUST persist the RSVP associated with the event and return an rsvpToken.
- **FR-005**: On successful RSVP submission, the client MUST store the guest's name and the server-returned rsvpToken in localStorage, keyed by event token.
- **FR-006**: On successful RSVP submission, the client MUST store the event token, event title, and event date in localStorage (to support the local event overview, US-7).
- **FR-007**: If a prior RSVP for this event exists in localStorage, the form MUST pre-fill with the stored choice and name on page load.
- **FR-008**: Re-submitting an RSVP from a device that has an existing server-side entry for this event MUST update the existing entry, not create a new one.
- **FR-013**: The event page MUST present the event fullscreen with a sticky bottom bar containing the RSVP call-to-action. Tapping the CTA MUST open a bottom sheet with the RSVP form.
- **FR-014**: After successful RSVP submission, the bottom sheet MUST close and the sticky bar MUST transition to showing the RSVP status.
- **FR-009**: The RSVP form MUST NOT be shown and the server MUST reject RSVP submissions after the event's expiry date has passed.
- **FR-010**: The RSVP form MUST NOT be shown and the server MUST reject RSVP submissions if the event has been cancelled [enforcement deferred until US-18 is implemented].
- **FR-011**: RSVP submission MUST NOT require an account, login, or any personal data beyond the optionally entered name.
- **FR-011**: RSVP submission MUST NOT require an account, login, or any personal data beyond the entered name.
- **FR-012**: No personal data or IP address MUST be logged on the server when processing an RSVP.
- **FR-015**: The event page MUST show only the attendee count publicly. The full attendee name list is out of scope (see 009-guest-list).
### Key Entities
- **RSVP**: Represents a guest's attendance declaration. Attributes: event token reference, attending status (boolean), optional name, creation/update timestamp. The server-side identity key for deduplication is the combination of event token and a device-bound identifier [NEEDS EXPANSION: deduplication mechanism to be defined during implementation].
- **RSVP**: Represents a guest's attendance declaration. Attributes: rsvpToken (server-generated UUID, returned to client), event reference, name (required), creation timestamp. Existence of an entry implies attendance — no `attending` boolean. The rsvpToken is returned to the client for future use (editing/withdrawal in a later spec). Duplicates from lost localStorage or different devices are accepted as a privacy trade-off.
- **RsvpToken**: A server-generated, event-scoped UUID identifying a single RSVP entry. Modeled as a distinct Java record type (alongside EventToken and OrganizerToken). Stored client-side in localStorage per event.
## Success Criteria
### Measurable Outcomes
- **SC-001**: A guest can submit an RSVP (attending with name, or not attending without name) from the event page without an account.
- **SC-002**: Submitting an RSVP from the same device twice results in exactly one server-side RSVP entry for that guest (no duplicates).
- **SC-001**: A guest can submit an RSVP (name + submit) from the event page without an account.
- **SC-002**: After submitting, the sticky bar shows the guest's RSVP status (not the CTA).
- **SC-003**: After submitting an RSVP, the local event overview (US-7) can display the event without a server request (event token, title, and date are in localStorage).
- **SC-004**: The RSVP form is not shown on expired events, and direct server submissions for expired events are rejected.
- **SC-005**: No name, IP address, or personal data beyond the submitted name is stored or logged by the server in connection with an RSVP.

190
specs/008-rsvp/tasks.md Normal file
View File

@@ -0,0 +1,190 @@
# Tasks: RSVP to an Event
**Input**: Design documents from `/specs/008-rsvp/`
**Prerequisites**: plan.md, spec.md, data-model.md, contracts/create-rsvp.yaml, research.md, quickstart.md
**Tests**: Included — constitution mandates Test-Driven Methodology (tests before implementation).
**Organization**: Tasks grouped by user story for independent implementation and testing.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2)
- Exact file paths included in descriptions
## Phase 1: Setup
**Purpose**: OpenAPI spec and database migration — shared infrastructure for all user stories
- [x] T001 Update OpenAPI spec with RSVP endpoint, request/response schemas, and `attendeeCount` population in `backend/src/main/resources/openapi/api.yaml`
- [x] T002 [P] Create Liquibase migration for rsvps table in `backend/src/main/resources/db/changelog/003-create-rsvps-table.xml`
- [x] T003 [P] Include new migration in `backend/src/main/resources/db/changelog/db.changelog-master.xml`
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Token value objects and cross-cutting refactoring — MUST complete before user stories
**Why blocking**: All new RSVP code uses typed tokens. Existing code must be refactored first to avoid mixing raw UUID and typed tokens.
- [x] T004 [P] Create `EventToken` record in `backend/src/main/java/de/fete/domain/model/EventToken.java`
- [x] T005 [P] Create `OrganizerToken` record in `backend/src/main/java/de/fete/domain/model/OrganizerToken.java`
- [x] T006 [P] Create `RsvpToken` record in `backend/src/main/java/de/fete/domain/model/RsvpToken.java`
- [x] T007 Refactor `Event` domain model to use `EventToken`/`OrganizerToken` in `backend/src/main/java/de/fete/domain/model/Event.java`
- [x] T008 Refactor `EventRepository` port to use typed tokens in `backend/src/main/java/de/fete/domain/port/out/EventRepository.java`
- [x] T009 Refactor `EventPersistenceAdapter` to map typed tokens in `backend/src/main/java/de/fete/adapter/out/persistence/EventPersistenceAdapter.java`
- [x] T010 Refactor `EventService` to use typed tokens in `backend/src/main/java/de/fete/application/service/EventService.java`
- [x] T011 Refactor `EventController` to unwrap/wrap typed tokens at API boundary in `backend/src/main/java/de/fete/adapter/in/web/EventController.java`
- [x] T012 Update `EventServiceTest` to use typed tokens in `backend/src/test/java/de/fete/application/service/EventServiceTest.java`
- [x] T013 Update `EventControllerIntegrationTest` to use typed tokens in `backend/src/test/java/de/fete/adapter/in/web/EventControllerIntegrationTest.java`
- [x] T014 Verify all existing tests pass after token refactoring (`cd backend && ./mvnw test`)
**Checkpoint**: All existing tests green with typed tokens. New RSVP domain work can begin.
---
## Phase 3: User Story 1 — Submit an RSVP (Priority: P1) MVP
**Goal**: A guest can open an active event page, tap the RSVP CTA, enter their name, submit, and see confirmation. Server persists the RSVP and returns an rsvpToken. localStorage stores RSVP data. Attendee count is populated from real data.
**Independent Test**: Open an event page, submit an RSVP with a name, verify attendee count updates, verify localStorage contains rsvpToken and name.
### Backend Tests for US1
- [x] T015 [P] [US1] Write unit tests for `RsvpService` (create RSVP, validation, event-not-found) in `backend/src/test/java/de/fete/application/service/RsvpServiceTest.java`
- [x] T016 [P] [US1] Write integration tests for `POST /events/{eventToken}/rsvps` (201 success, 400 validation, 404 not found) in `backend/src/test/java/de/fete/adapter/in/web/EventControllerIntegrationTest.java`
### Backend Implementation for US1
- [x] T017 [P] [US1] Create `Rsvp` domain entity in `backend/src/main/java/de/fete/domain/model/Rsvp.java`
- [x] T018 [P] [US1] Create `CreateRsvpUseCase` inbound port in `backend/src/main/java/de/fete/domain/port/in/CreateRsvpUseCase.java`
- [x] T019 [P] [US1] Create `RsvpRepository` outbound port with `save()` and `countByEventId()` in `backend/src/main/java/de/fete/domain/port/out/RsvpRepository.java`
- [x] T020 [P] [US1] Create `RsvpJpaEntity` in `backend/src/main/java/de/fete/adapter/out/persistence/RsvpJpaEntity.java`
- [x] T021 [P] [US1] Create `RsvpJpaRepository` (Spring Data) in `backend/src/main/java/de/fete/adapter/out/persistence/RsvpJpaRepository.java`
- [x] T022 [US1] Implement `RsvpPersistenceAdapter` in `backend/src/main/java/de/fete/adapter/out/persistence/RsvpPersistenceAdapter.java`
- [x] T023 [US1] Implement `RsvpService` (create RSVP logic, validate event exists) in `backend/src/main/java/de/fete/application/service/RsvpService.java`
- [x] T024 [US1] Add `createRsvp()` method to `EventController` in `backend/src/main/java/de/fete/adapter/in/web/EventController.java`
- [x] T025 [US1] Wire attendee count: add `countByEventId()` call to GET event flow, populate `attendeeCount` in response in `backend/src/main/java/de/fete/adapter/in/web/EventController.java`
- [x] T026 [US1] Verify backend tests pass (`cd backend && ./mvnw test`)
### Frontend Tests for US1
- [ ] T027 [P] [US1] Write unit tests for `BottomSheet` component in `frontend/src/components/__tests__/BottomSheet.spec.ts`
- [ ] T028 [P] [US1] Write unit tests for `RsvpBar` component in `frontend/src/components/__tests__/RsvpBar.spec.ts`
- [ ] T029 [P] [US1] Update unit tests for `useEventStorage` composable (rsvpToken/rsvpName fields) in `frontend/src/composables/__tests__/useEventStorage.spec.ts`
### Frontend Implementation for US1
- [ ] T030 [US1] Regenerate TypeScript types from updated OpenAPI spec (`frontend/src/api/schema.d.ts`)
- [ ] T031 [P] [US1] Extend `useEventStorage` composable with `rsvpToken` and `rsvpName` fields in `frontend/src/composables/useEventStorage.ts`
- [ ] T032 [P] [US1] Create `BottomSheet.vue` component (slide-up, backdrop, focus trap, ESC close, aria-modal) in `frontend/src/components/BottomSheet.vue`
- [ ] T033 [P] [US1] Create `RsvpBar.vue` sticky bottom bar (CTA state + status state) in `frontend/src/components/RsvpBar.vue`
- [ ] T034 [US1] Integrate `RsvpBar` + `BottomSheet` + RSVP form into `EventDetailView`, including error state when server is unreachable, in `frontend/src/views/EventDetailView.vue`
- [ ] T035 [US1] Add bottom sheet and sticky bar styles to `frontend/src/assets/main.css`
- [ ] T036 [US1] Update `EventDetailView` unit tests for RSVP integration in `frontend/src/views/__tests__/EventDetailView.spec.ts`
### E2E Tests for US1
- [ ] T037 [US1] Write E2E tests: RSVP submission flow, localStorage verification, attendee count update in `frontend/e2e/event-rsvp.spec.ts`
**Checkpoint**: US1 complete — guest can submit RSVP, see confirmation, attendee count populated. All backend + frontend tests green.
---
## Phase 4: User Story 2 — RSVP Blocked on Expired Events (Priority: P2)
**Goal**: Expired events hide the RSVP form and the server rejects RSVP submissions with 409 Conflict.
**Independent Test**: Attempt to RSVP to an expired event — verify form is hidden client-side and server returns 409.
### Tests for US2
- [ ] T038 [P] [US2] Write backend test for expired event rejection (409) in `backend/src/test/java/de/fete/application/service/RsvpServiceTest.java`
- [ ] T039 [P] [US2] Write integration test for `POST /events/{eventToken}/rsvps` returning 409 on expired event in `backend/src/test/java/de/fete/adapter/in/web/EventControllerIntegrationTest.java`
### Implementation for US2
- [ ] T040 [US2] Add expiry check to `RsvpService.createRsvp()` — throw `EventExpiredException` when event date has passed in `backend/src/main/java/de/fete/application/service/RsvpService.java`
- [ ] T041 [US2] Handle `EventExpiredException` in `GlobalExceptionHandler` — return 409 Conflict in `backend/src/main/java/de/fete/adapter/in/web/GlobalExceptionHandler.java`
- [ ] T042 [US2] Hide RSVP bar/form on expired events in `EventDetailView` (check `expired` field from API response) in `frontend/src/views/EventDetailView.vue`
- [ ] T043 [US2] Write E2E test for expired event: verify RSVP form hidden, direct API call returns 409 in `frontend/e2e/event-rsvp.spec.ts`
- [ ] T044 [US2] Verify all tests pass (`cd backend && ./mvnw test && cd ../frontend && npm run test:unit`)
**Checkpoint**: US2 complete — expired events block RSVPs client-side and server-side.
---
## Phase 5: Polish & Cross-Cutting Concerns
**Purpose**: Final verification across all stories
- [ ] T045 Run full backend verify (`cd backend && ./mvnw verify`)
- [ ] T046 Run frontend build and type-check (`cd frontend && npm run build`)
- [ ] T047 Run all E2E tests (`cd frontend && npx playwright test`)
- [ ] T048 Visual verification of RSVP flow using `browser-interactive-testing` skill
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: No dependencies — can start immediately
- **Foundational (Phase 2)**: Depends on T001 (OpenAPI spec) for schema awareness; T002-T003 (migration) independent
- **US1 (Phase 3)**: Depends on Phase 2 completion (typed tokens in place)
- **US2 (Phase 4)**: Depends on Phase 3 (RSVP creation must exist before expiry guard)
- **Polish (Phase 5)**: Depends on all user stories complete
### User Story Dependencies
- **US1 (P1)**: Can start after Phase 2 — no dependency on US2
- **US2 (P2)**: Depends on US1 (the RSVP endpoint and form must exist before adding the expiry guard)
### Within Each User Story
- Tests MUST be written first and FAIL before implementation
- Domain model/ports before persistence adapters
- Persistence before services
- Services before controllers
- Backend before frontend (API must exist for frontend to consume)
- Frontend components before view integration
- Unit tests before E2E tests
### Parallel Opportunities
**Phase 1**: T002 and T003 can run in parallel with T001
**Phase 2**: T004, T005, T006 in parallel; then T007-T013 sequentially (refactoring chain)
**Phase 3 Backend**: T015+T016 (tests) in parallel; T017+T018+T019+T020+T021 (domain/ports/JPA) in parallel; then T022→T023→T024→T025 sequential
**Phase 3 Frontend**: T027+T028+T029 (tests) in parallel; T031+T032+T033 in parallel; then T034→T035→T036→T037 sequential
**Phase 4**: T038+T039 (tests) in parallel; then T040→T041→T042→T043→T044 sequential
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 1: Setup (OpenAPI + migration)
2. Complete Phase 2: Foundational (token value objects + refactoring)
3. Complete Phase 3: User Story 1 (full RSVP flow)
4. **STOP and VALIDATE**: Guest can submit RSVP, see confirmation, attendee count works
5. Deploy/demo if ready
### Incremental Delivery
1. Setup + Foundational → Token refactoring complete, schema ready
2. Add US1 → Full RSVP flow works → Deploy/Demo (MVP!)
3. Add US2 → Expired events guarded → Deploy/Demo
4. Polish → All tests green, visual verification done
---
## Notes
- Cancelled event guard (FR-010) is deferred until US-18 — NOT included in tasks
- No CAPTCHA/rate-limiting per spec (KISS, privacy-first)
- RSVP editing/withdrawal deferred to separate edit-RSVP spec
- Frontend uses plain `string` for tokens (no branded types) per clarification
- Backend uses typed records (`EventToken`, `OrganizerToken`, `RsvpToken`) per clarification