02939ca828
Addresses spec drift items #3, 5, 6, 7, 8, 9, 10, 11, 12 from #147: - transactional-emails: Resend → Nodemailer + SMTP - infrastructure: CX21 → cx23 - secret-management: single secrets.env → split app/infra files - brouter-integration: 5s failover delay → instant via clientID election - brouter-integration: 2 profiles → 5 (trekking, fastbike, safety, shortest, car) - observability: add version field to health response - observability: add brouter_request_duration_seconds metric - planner-session: remove 30-day max ceiling (not enforced) - shared-packages: clarify map package scope vs planner-specific features Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
130 lines
6 KiB
Markdown
130 lines
6 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Create collaborative session
|
|
The Planner SHALL allow creating a new editing session that generates a unique shareable URL. Sessions SHALL be created either from the Planner directly (empty route) or via a Journal callback (with initial GPX data).
|
|
|
|
#### Scenario: Create empty session
|
|
- **WHEN** a user navigates to planner.trails.cool
|
|
- **THEN** a new Yjs session is created with an empty waypoint list and the user is redirected to `/session/<session-id>`
|
|
|
|
#### Scenario: Create session from Journal callback
|
|
- **WHEN** the Journal opens `planner.trails.cool/new?callback=<url>&token=<jwt>&gpx=<encoded-gpx>`
|
|
- **THEN** a new Yjs session is created with waypoints parsed from the GPX and the callback URL is stored for later save operations
|
|
|
|
### Requirement: Join session via link
|
|
The Planner SHALL allow any user (including guests without accounts) to join an existing session by navigating to its URL.
|
|
|
|
#### Scenario: Join active session
|
|
- **WHEN** a user navigates to `planner.trails.cool/session/<session-id>`
|
|
- **THEN** the user connects to the Yjs document and sees the current route state with all other participants' cursors
|
|
|
|
#### Scenario: Join expired session
|
|
- **WHEN** a user navigates to a session URL that has expired
|
|
- **THEN** the system displays an error message indicating the session no longer exists
|
|
|
|
### Requirement: Real-time collaborative editing
|
|
The Planner SHALL synchronize waypoint edits across all connected participants in real-time using Yjs CRDTs.
|
|
|
|
#### Scenario: Add waypoint
|
|
- **WHEN** participant A adds a waypoint to the map
|
|
- **THEN** participant B sees the waypoint appear within 500ms
|
|
|
|
#### Scenario: Reorder waypoints
|
|
- **WHEN** participant A drags a waypoint to reorder it
|
|
- **THEN** participant B sees the updated waypoint order within 500ms
|
|
|
|
#### Scenario: Concurrent edits
|
|
- **WHEN** participant A and B both add waypoints simultaneously
|
|
- **THEN** both waypoints appear for both participants without conflict
|
|
|
|
### Requirement: Session persistence
|
|
The Planner SHALL persist Yjs session state to PostgreSQL so that sessions survive server restarts.
|
|
|
|
#### Scenario: Server restart recovery
|
|
- **WHEN** the Planner server restarts while a session is active
|
|
- **THEN** reconnecting clients recover the full session state from PostgreSQL
|
|
|
|
### Requirement: Session expiry
|
|
The Planner SHALL automatically expire sessions after a configurable period of inactivity (default: 7 days, no hard ceiling enforced).
|
|
|
|
#### Scenario: Session expires
|
|
- **WHEN** no edits are made to a session for 7 days
|
|
- **THEN** the session is deleted from PostgreSQL and its URL returns a 404
|
|
|
|
### Requirement: Manual session close
|
|
The session owner (initiator) SHALL be able to manually close a session.
|
|
|
|
#### Scenario: Owner closes session
|
|
- **WHEN** the session owner clicks "Close Session"
|
|
- **THEN** all connected participants are notified, the session triggers auto-save if a callback exists, and the session becomes inaccessible
|
|
|
|
### Requirement: User presence
|
|
The Planner SHALL display presence indicators showing which users are currently connected to a session, including live cursors on the map.
|
|
|
|
#### Scenario: Show connected users
|
|
- **WHEN** multiple users are connected to a session
|
|
- **THEN** each user sees a list of other connected users with assigned colors
|
|
|
|
#### Scenario: Live map cursors
|
|
- **WHEN** a user moves their mouse over the map
|
|
- **THEN** other participants see a labeled cursor at that position on their map, colored to match the user's assigned color
|
|
|
|
#### Scenario: Cursor disappears on leave
|
|
- **WHEN** a user disconnects from the session
|
|
- **THEN** their cursor disappears from all other participants' maps within 5 seconds
|
|
|
|
### Requirement: Planner home page
|
|
The Planner home page SHALL explain the tool's purpose and provide a one-click way to start planning.
|
|
|
|
#### Scenario: First-time visitor
|
|
- **WHEN** a user visits planner.trails.cool for the first time
|
|
- **THEN** they see a landing page explaining collaborative route planning, key features, and a prominent "Start Planning" button
|
|
|
|
#### Scenario: Start a session
|
|
- **WHEN** a user clicks "Start Planning"
|
|
- **THEN** a new anonymous session is created and the user is redirected to the session view
|
|
|
|
#### Scenario: Journal link
|
|
- **WHEN** a user wants to save routes permanently
|
|
- **THEN** a secondary CTA links to trails.cool for account creation
|
|
|
|
### Requirement: No user data collection
|
|
The Planner SHALL NOT collect, store, or track any personal user data. Sessions are anonymous by default.
|
|
|
|
#### Scenario: Anonymous session participation
|
|
- **WHEN** a user joins a session without any account
|
|
- **THEN** the user is assigned a random color and temporary display name with no data persisted about their identity
|
|
|
|
### Requirement: Session participant awareness
|
|
Users in a planning session SHALL see who else is present and be able to identify themselves.
|
|
|
|
#### Scenario: Participant list visible
|
|
- **WHEN** multiple users are in a session
|
|
- **THEN** the header shows each participant's name and color
|
|
|
|
#### Scenario: Host badge
|
|
- **WHEN** a participant is the routing host
|
|
- **THEN** their entry in the participant list shows a host indicator
|
|
|
|
#### Scenario: Edit own name
|
|
- **WHEN** a user clicks their own name in the participant list
|
|
- **THEN** an inline text input appears to change their display name
|
|
|
|
#### Scenario: Name persisted
|
|
- **WHEN** a user changes their name
|
|
- **THEN** the name is saved to localStorage and immediately visible to all other participants via awareness
|
|
|
|
#### Scenario: Join notification
|
|
- **WHEN** a new participant joins the session
|
|
- **THEN** a brief toast shows "[name] joined"
|
|
|
|
#### Scenario: Leave notification
|
|
- **WHEN** a participant leaves the session
|
|
- **THEN** a brief toast shows "[name] left"
|
|
|
|
### Requirement: Planner session data model
|
|
The Yjs document SHALL include noGoAreas and notes fields alongside waypoints and routeData.
|
|
|
|
#### Scenario: Session with all fields
|
|
- **WHEN** a Planner session is active
|
|
- **THEN** the Yjs doc contains: waypoints (Y.Array), routeData (Y.Map), noGoAreas (Y.Array), notes (Y.Text)
|