0cf87b72ab
- authentication-methods: document completeAuth mode param ("redirect"|"json");
clarify add-passkey nudge (no dismiss mechanism, disappears on passkey add)
- journal-auth: session maxAge is 30 days; terms allow-list uses /legal/ prefix
matching (broader than fixed list of paths)
- session-notes: mark awareness isolation and UndoManager isolation as not yet
implemented (shared instances in current code)
- activity-feed: add fan-out scenario for visibility change to public
- explore: note that ?perPage is not yet implemented (hardcoded page size)
- multi-day-routes: add per-day GPX track split scenario (splitByDays option);
document overnight vs isDayBreak naming gap
- osm-poi-overlays: debounce is 800ms + 2000ms min interval (not 500ms);
retry is not automatic (fires on next viewport change)
- brouter-integration: rate limit corrected to 300/hour; add segment-cache
requirement (client caches per-pair segments)
- wahoo-route-push: OAuth state shape uses camelCase (returnTo, pushAfter
object) not snake_case with push_after boolean
- komoot-import: document noop adapter / ConnectedServiceManager bypass;
note four Komoot-specific routes that bypass the generic OAuth framework
- background-jobs: exponential backoff not wired (retryLimit only); add SIGINT
- connected-services: add revoked status; name ConnectionNotActiveError
- infrastructure: add INTEGRATION_SECRET and SENTRY_DSN to env var lists;
split secret decryption scenario by workflow (cd-apps vs cd-infra)
- secret-management: correct CD decryption — cd-apps only decrypts app.env;
cd-infra decrypts both
- transactional-emails: welcome email is async (pg-boss job); magic-link email
includes 6-digit numeric code
- journal-route-detail: websites are https: links (not mailto:); opening_hours
is also displayed
- local-dev-environment: add mobile app (Expo) dev commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
134 lines
8 KiB
Markdown
134 lines
8 KiB
Markdown
## Purpose
|
|
|
|
Activity creation, chronological feed, detail views, and route linking in the Journal app.
|
|
## Requirements
|
|
### Requirement: Create activity
|
|
The Journal SHALL allow authenticated users to create an activity by uploading a GPX trace and adding a description.
|
|
|
|
#### Scenario: Create activity with GPX
|
|
- **WHEN** a user uploads a GPX file and enters a description
|
|
- **THEN** an activity is created with the GPS trace, computed distance and duration, and stored in the database
|
|
|
|
#### Scenario: Create activity linked to route
|
|
- **WHEN** a user creates an activity and selects an existing route
|
|
- **THEN** the activity is linked to that route (route_id foreign key)
|
|
|
|
### Requirement: Activity feed
|
|
The Journal SHALL display a chronological feed of the authenticated user's activities.
|
|
|
|
#### Scenario: View own activity feed
|
|
- **WHEN** a logged-in user navigates to their feed
|
|
- **THEN** they see their activities in reverse chronological order with name, date, distance, and duration
|
|
|
|
### Requirement: Activity detail page
|
|
The Journal SHALL display an activity detail page with map, stats, and description. Access depends on the activity's `visibility`: `public` activities are viewable by anyone including unauthenticated visitors, `unlisted` activities are viewable by anyone who has the URL, and `private` activities are viewable only by the owner.
|
|
|
|
#### Scenario: Owner views own activity
|
|
- **WHEN** a logged-in user navigates to an activity they own at any visibility
|
|
- **THEN** they see the activity name, description, a map with the GPS trace, distance, duration, and elevation stats
|
|
|
|
#### Scenario: Anyone views a public activity
|
|
- **WHEN** any visitor (including unauthenticated) navigates to a `public` activity's URL
|
|
- **THEN** they see the full activity detail page as above
|
|
|
|
#### Scenario: Anyone with the URL views an unlisted activity
|
|
- **WHEN** any visitor navigates directly to an `unlisted` activity's URL
|
|
- **THEN** they see the full activity detail page as above
|
|
|
|
#### Scenario: Non-owner is blocked from a private activity
|
|
- **WHEN** a visitor who is not the owner requests a `private` activity URL
|
|
- **THEN** the server responds with HTTP 404 (not 403), so the existence of the private activity is not leaked
|
|
|
|
#### Scenario: Public and unlisted activity pages emit social-share metadata
|
|
- **WHEN** a visitor loads a `public` or `unlisted` activity detail page
|
|
- **THEN** the response emits Open Graph and Twitter Card meta tags (`og:title`, `og:description`, `og:type="article"`, `og:site_name`, `twitter:card="summary"`)
|
|
|
|
### Requirement: Link activity to route
|
|
Users SHALL be able to link an existing activity to a route, or create a route from an activity trace.
|
|
|
|
#### Scenario: Link activity to existing route
|
|
- **WHEN** a user selects "Link to Route" on an activity and chooses a route
|
|
- **THEN** the activity's route_id is set to the selected route
|
|
|
|
#### Scenario: Create route from activity
|
|
- **WHEN** a user selects "Create Route from Activity"
|
|
- **THEN** a new route is created using the activity's GPX trace
|
|
|
|
### Requirement: Activity without route
|
|
Activities SHALL be allowed to exist without a linked route.
|
|
|
|
#### Scenario: Standalone activity
|
|
- **WHEN** a user imports a GPX activity without linking to a route
|
|
- **THEN** the activity is stored with route_id as null
|
|
|
|
### Requirement: Instance-wide public activity feed
|
|
The Journal SHALL expose a reverse-chronological feed of every activity on the instance with visibility `public`. This feed powers the visitor home page (see `journal-landing`) for anonymous traffic and the Public view of `/feed` (see `social-follows` spec, "Social activity feed") for signed-in viewers. `private` and `unlisted` activities SHALL NOT appear in this feed; `unlisted` stays reachable by direct URL only.
|
|
|
|
#### Scenario: Public activity appears in the visitor home feed
|
|
- **WHEN** an owner marks an activity as `public` and an anonymous visitor loads the home page
|
|
- **THEN** the visitor sees the activity in the instance feed, with the owner's display name, distance, and start date
|
|
|
|
#### Scenario: Public activity appears in the signed-in /feed?view=public view
|
|
- **WHEN** an owner marks an activity as `public` and a signed-in user loads `/feed?view=public`
|
|
- **THEN** the signed-in user sees the activity in the Public view, regardless of whether they follow the owner
|
|
|
|
#### Scenario: Private or unlisted activities stay out of the feed
|
|
- **WHEN** an activity's visibility is `private` or `unlisted`
|
|
- **THEN** it does not appear in the instance feed on either surface, regardless of who is viewing
|
|
|
|
### Requirement: Activity visibility
|
|
The Journal SHALL persist a `visibility` value on every activity and SHALL allow the owner to change it.
|
|
|
|
#### Scenario: New activities default to private
|
|
- **WHEN** an activity is created without an explicit visibility
|
|
- **THEN** the activity row is persisted with `visibility = 'private'`
|
|
|
|
#### Scenario: Owner changes an activity's visibility
|
|
- **WHEN** an activity owner selects a different visibility (`private`, `unlisted`, `public`) and saves
|
|
- **THEN** the stored visibility is updated and subsequent access checks use the new value immediately
|
|
|
|
### Requirement: Activity listings respect visibility
|
|
The Journal's own-activities feed SHALL show the owner everything regardless of visibility, while any cross-user listing SHALL only include activities with `visibility = 'public'`.
|
|
|
|
#### Scenario: Own activity feed is unchanged
|
|
- **WHEN** a logged-in user views their own activity feed
|
|
- **THEN** the feed includes all of their own activities regardless of visibility
|
|
|
|
#### Scenario: Public profile lists only public activities
|
|
- **WHEN** a visitor loads `/users/:username`
|
|
- **THEN** the rendered list of activities includes only the user's `public` activities; `unlisted` and `private` activities are omitted
|
|
|
|
|
|
### Requirement: Public activity creation fans out notifications
|
|
Creating an activity with `visibility = 'public'` SHALL enqueue a fan-out job that inserts an `activity_published` notification for every accepted follower of the activity owner. The fan-out SHALL run asynchronously so the activity-creation request returns immediately. See `notifications` spec for the notification row shape and the idempotency rules.
|
|
|
|
#### Scenario: Public activity fans out
|
|
- **WHEN** a user with N accepted followers creates an activity with `visibility = 'public'`
|
|
- **THEN** a pg-boss job is enqueued, and on completion N notifications exist with `type = 'activity_published'`, `recipient_user_id` ∈ accepted-followers, `actor_user_id` = activity owner, `subject_id` = activity id
|
|
|
|
#### Scenario: Private or unlisted activity does not fan out
|
|
- **WHEN** a user creates an activity with `visibility = 'private'` or `'unlisted'`
|
|
- **THEN** no fan-out job is enqueued and no notifications are created
|
|
|
|
#### Scenario: Visibility change to public fans out
|
|
- **WHEN** an activity owner changes an existing activity's visibility from `private` or `unlisted` to `public`
|
|
- **THEN** a fan-out job is enqueued for the visibility change, creating `activity_published` notifications for all accepted followers — the same fan-out as on initial public creation
|
|
|
|
#### Scenario: No accepted followers means no notifications
|
|
- **WHEN** a user with zero accepted followers creates a public activity
|
|
- **THEN** the fan-out job runs and inserts zero rows
|
|
|
|
### Requirement: Synthetic activity flag
|
|
The Journal SHALL persist a `synthetic` boolean on every activity so automated / demo content can be distinguished from user-created content.
|
|
|
|
#### Scenario: User-created activities default to non-synthetic
|
|
- **WHEN** an activity is created through any user-facing flow (GPX upload, sync import, Planner handoff)
|
|
- **THEN** the activity row is persisted with `synthetic = false`
|
|
|
|
#### Scenario: Bot inserts flag their rows as synthetic
|
|
- **WHEN** the demo-activity-bot inserts an activity
|
|
- **THEN** the row is persisted with `synthetic = true`
|
|
|
|
#### Scenario: Synthetic flag is not user-editable
|
|
- **WHEN** an activity owner edits the activity via any user-facing action
|
|
- **THEN** the stored `synthetic` value is not changed by the edit
|