SLP_Software/slp-modular-cms
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Wiki Activity
Files
9e49489f7e0dd1bc31a7689c174a9ecabb15affb
slp-modular-cms/aidlc-docs/features/cms-frontend/inception/user-stories/stories.md
T

18 KiB
Raw Blame History

User Stories — CMS Frontend

Format: "As a [persona], I want to [action], so that [benefit]" Acceptance Criteria: Detailed checklist — happy path, error states, edge cases, and security constraints

Epic: Authentication & Session

US-01: Login with email and password

Persona: Owner, Admin, User

As an Owner/Admin/User, I want to log in with my email address and password, so that I can access the CMS platform securely.

Acceptance Criteria:

  • A /login page is displayed for unauthenticated users
  • The form contains an email field, a password field, and a submit button
  • Email field validates format before submission (invalid format shows inline error)
  • Password field enforces backend rules client-side: minimum 8 characters, at least 1 uppercase letter, 1 lowercase letter, 1 digit, and 1 non-alphanumeric character (e.g. !@#$%)
  • On valid credentials: access token is stored in memory, refresh token is set as httpOnly cookie, user is redirected to /
  • On invalid credentials: a generic error message is shown ("Invalid email or password") — no distinction between wrong email and wrong password
  • On network error: a user-friendly error message is shown ("Unable to connect. Please try again.")
  • The password field input is masked; a show/hide toggle is present
  • The submit button shows a loading state while the request is in progress
  • After successful login, the back button does NOT navigate back to the login page
  • The page is accessible when the system is initialized and the user is not logged in
  • Security: No token is stored in localStorage or sessionStorage
  • Security: The form does not autocomplete passwords in production (autocomplete="new-password" or "current-password" as appropriate)

US-02: Stay logged in across tab switches (session persistence via refresh token)

Persona: Owner, Admin, User

As an authenticated user, I want my session to be restored when I return to the app after a page refresh or browser restart, so that I do not have to log in repeatedly.

Acceptance Criteria:

  • On app load, the app calls POST /auth/refresh using the httpOnly cookie before rendering protected routes
  • If the refresh succeeds: the new access token is stored in memory and the user proceeds to their intended route
  • If the refresh fails (expired or missing cookie): the user is redirected to /login
  • During the session restoration check, a loading/spinner state is shown — no flash of the protected content or login page
  • A user who has never logged in sees the login page immediately (no loading delay)
  • Security: The refresh endpoint call uses credentials (cookies) — credentials: 'include' in fetch or equivalent

US-03: Logout and end session

Persona: Owner, Admin, User

As an authenticated user, I want to log out of the application, so that my session is terminated and no one else can use my account.

Acceptance Criteria:

  • A logout button/menu item is visible in the sidebar for all authenticated users
  • Clicking logout calls POST /auth/revoke with the current refresh token
  • After logout: in-memory access token is cleared, the browser is redirected to /login
  • If the revoke call fails (network error): the user is still redirected to /login and local state is cleared
  • After logout, navigating back (browser back button) to a protected page redirects to /login
  • Security: The httpOnly cookie is cleared upon logout (backend sets Set-Cookie with expired date)

US-04: Redirect to login when not authenticated

Persona: Anonymous Visitor

As an unauthenticated visitor, I want to be redirected to the login page when I try to access a protected route, so that I cannot access content I am not authorised to see.

Acceptance Criteria:

  • Navigating to any protected route (e.g. /, /users, /settings) without a valid session redirects to /login
  • After redirect, the originally requested URL is preserved (e.g. as a ?redirect=/users query param) so the user can be sent there after login
  • No protected page content is rendered, even briefly, before the redirect occurs
  • Security: The redirect happens client-side as a defence-in-depth measure; the API also enforces authorisation server-side

US-05: Automatic access token refresh on expiry

Persona: Owner, Admin, User

As an authenticated user, I want my access token to be refreshed automatically when it expires during an active session, so that I am not abruptly logged out while working.

Acceptance Criteria:

  • When an API call returns a 401 (Unauthorised), the app automatically calls POST /auth/refresh
  • If the refresh succeeds: the original API call is retried with the new access token
  • If the refresh fails (refresh token expired): the user is redirected to /login with a notification ("Your session expired. Please log in again.")
  • The original user action is not lost if possible (e.g. form data is preserved)
  • Only one refresh attempt is made per 401 — infinite retry loops are prevented
  • Security: The token refresh logic is centralised in the API client, not duplicated across components

Epic: System Initialization

US-06: Initialize system as first Owner

Persona: Anonymous Visitor

As the first visitor to a new CMS installation, I want to create an Owner account during system setup, so that the platform is ready for use.

Acceptance Criteria:

  • The /setup page contains a form with email and password fields
  • The form validates email format and password minimum length (8 characters)
  • On submit: POST /setup/owner is called with the provided credentials
  • On success: the user is redirected to /login with a success toast ("System initialized. Please log in.")
  • On failure (e.g. system already initialized): an appropriate error message is shown and the user is redirected to /login
  • Edge case: If the user navigates to /setup when the system is already initialized, they are redirected to /login
  • Security: The setup page is only reachable when GET /setup/status returns { initialized: false }

US-07: Redirect to setup when system is not initialized

Persona: Anonymous Visitor

As a visitor to an uninitialized CMS, I want to be automatically redirected to the setup page, so that I know the system needs configuration before use.

Acceptance Criteria:

  • On app startup, GET /setup/status is called before rendering any page
  • If initialized: false: all routes redirect to /setup
  • If initialized: true: normal routing applies (login, protected routes, etc.)
  • During the status check, a loading state is shown
  • Edge case: If the /setup/status call fails, an error page is shown with a retry option
  • Security: The /setup/owner endpoint is disabled server-side once initialized; the frontend check is defence-in-depth only

Epic: Dashboard

US-08: View dashboard after login

Persona: Owner, Admin, User

As an authenticated user, I want to see a dashboard after logging in, so that I get an overview of the system's state and quick access to key functions.

Acceptance Criteria:

  • The / (or /dashboard) route renders the dashboard page for all authenticated users
  • The dashboard displays a welcome message with the user's name and role
  • The dashboard displays at least one summary widget (e.g. system status indicator)
  • The layout uses the sidebar navigation from the example app design
  • Edge case: If user data fails to load, a graceful error state is shown

US-09: View system availability status on dashboard

Persona: Owner, Admin, User

As an authenticated user, I want to see the current system availability status on the dashboard, so that I am immediately aware of any maintenance or outage.

Acceptance Criteria:

  • The dashboard calls GET /availability/status on load
  • The status is displayed with a colour-coded indicator: Available (green), Maintenance (yellow), Unavailable (red)
  • The status message/reason is shown alongside the indicator if present
  • If the API call fails: the indicator shows "Unknown" with a retry option
  • The status is refreshed when the user navigates back to the dashboard

Epic: User Management

US-10: View list of users

Persona: Owner, Admin

As an Owner or Admin, I want to see a list of all platform users, so that I can manage team membership and access.

Acceptance Criteria:

  • The /users page is accessible to Owner and Admin roles only
  • The page displays a table/list with each user's name, email, role, and active status
  • If the user list is empty, an empty state message is shown
  • If the API call fails, an error state is shown with a retry option
  • Security: Navigating to /users as a User role redirects to an "Access Denied" page or back to /

US-11: Invite a new user

Persona: Owner, Admin

As an Owner or Admin, I want to invite a new user by providing their email address and selecting their role, so that they can join the platform.

Acceptance Criteria:

  • An "Invite User" button is visible on the /users page for Owner and Admin roles
  • Clicking the button opens a dialog/modal with an email field and a role selector (Admin, User)
  • The email field validates format before submission
  • The role selector does NOT allow selecting Owner (Admins cannot create other Owners; Owner-role invites are also restricted unless the inviter is an Owner — consider showing Owner option only when logged in as Owner)
  • On submit: POST /users/invite is called
  • On success: the dialog remains open and transitions to the "share link" step (US-12)
  • On failure (e.g. email already registered): an appropriate inline error is shown
  • Security: The invite action is only available to Owner and Admin; role selection is validated server-side

US-12: Share invite link after invitation is created

Persona: Owner, Admin

As an Owner or Admin, I want to see and copy the generated invite link after creating an invitation, so that I can share it with the invited person.

Acceptance Criteria:

  • After a successful invitation (US-11), the dialog shows the generated invite link
  • A "Copy to clipboard" button is present; clicking it copies the link and shows a success toast
  • The link is displayed as readable text (not just a button)
  • A "Done" button closes the dialog
  • Edge case: If the clipboard API is unavailable (e.g. non-HTTPS context), a fallback allows manual selection of the text

US-13: Complete account setup via invitation link

Persona: New Invited User

As a person who received an invitation link, I want to complete my account setup by setting a password, so that I can log in to the platform.

Acceptance Criteria:

  • Navigating to /invite/complete?token={token} triggers GET /users/validate-invitation?token={token}
  • If the token is valid: a form is shown with a display name field and a password field (with confirmation)
  • Password must meet the backend requirements: minimum 8 characters, at least 1 uppercase letter, 1 lowercase letter, 1 digit, and 1 non-alphanumeric character — these rules are enforced client-side before submission and validated server-side
  • Inline validation messages indicate which specific rule is not yet met (e.g. "Must contain at least 1 uppercase letter")
  • Password confirmation must match; mismatch shows an inline error
  • On submit: POST /users/complete-setup is called with the token, display name, and password
  • On success: a confirmation message is shown ("Your account is ready. You can now log in.") with a link to /login
  • The form shows a loading state during submission
  • Security: The token is sent to the backend for server-side validation; client-side token inspection is never used for access decisions

US-14: Handle expired or invalid invitation token

Persona: New Invited User

As a person with an expired or already-used invitation link, I want to see a clear error message, so that I understand why I cannot proceed and know what to do next.

Acceptance Criteria:

  • If GET /users/validate-invitation returns an error (expired, used, or invalid token): no setup form is shown
  • An error message is displayed: "This invitation link is invalid or has expired. Please contact your administrator for a new invite."
  • A link to /login is provided for users who already completed setup
  • Edge case: If the token query parameter is missing from the URL, the same error state is shown
  • Security: No partial form data is shown when token validation fails

Epic: Profile

US-15: View own profile information

Persona: Owner, Admin, User

As an authenticated user, I want to see my profile information, so that I can verify my account details.

Acceptance Criteria:

  • The /profile page is accessible to all authenticated users
  • The page displays the user's display name, email address, and role
  • All fields are read-only in v1
  • A placeholder/note indicates that profile editing will be available in a future version
  • Edge case: If the user data cannot be loaded, an error state is shown

Epic: System Settings

US-16: View system availability status in settings

Persona: Owner

As an Owner, I want to view the current system availability status in the System Settings page, so that I have a central place for system-level information.

Acceptance Criteria:

  • The /settings page is accessible to Owner only
  • The page displays the current system status (Available / Maintenance / Unavailable) and reason from GET /availability/status
  • The initialized status of the system is also shown (always "Initialized" when this page is reachable)
  • Placeholder sections for future settings categories are visible (e.g. "Module Settings", "CMS Configuration")
  • Edge case: If the availability API call fails, the status shows "Unknown" with a retry option

US-17: Access denied for System Settings for non-Owners

Persona: Admin, User

As an Admin or User, I want to be prevented from accessing the System Settings page, so that system-level configuration is protected.

Acceptance Criteria:

  • Navigating to /settings as an Admin or User redirects to an "Access Denied" page or to /
  • The System Settings item is NOT shown in the sidebar for Admin or User roles
  • Security: The redirect is enforced client-side as defence-in-depth; the backend also enforces authorisation

Epic: Navigation & Layout

US-18: See role-appropriate navigation items in sidebar

Persona: Owner, Admin, User

As an authenticated user, I want to see only the navigation items relevant to my role in the sidebar, so that the interface is uncluttered and I am not confused by inaccessible sections.

Acceptance Criteria:

  • Dashboard: visible to all authenticated users
  • User Management: visible to Owner and Admin only
  • System Settings: visible to Owner only
  • CMS Management: visible to Owner only (feature is for managing other client CMS instances; out of scope for v1 but access is restricted from the start)
  • Profile: visible to all authenticated users
  • Logout: visible to all authenticated users
  • The sidebar is responsive: collapses to an icon-only view or a hamburger menu on small screens
  • The currently active route is highlighted in the sidebar

US-19: Toggle dark/light theme

Persona: Owner, Admin, User

As an authenticated user, I want to switch between dark and light themes, so that I can use the interface comfortably in different lighting conditions.

Acceptance Criteria:

  • A theme toggle button is present in the UI (sidebar footer or top bar)
  • Clicking the toggle switches between light and dark mode immediately
  • The chosen theme is persisted in localStorage under a well-named key (e.g. cms-theme)
  • On app load, the persisted theme preference is applied before the first render (no flash)
  • If no preference is stored, the system (OS) preference is used as default
  • Security: Only theme preference is stored in localStorage — no auth data

Epic: CMS Management (Placeholder)

US-20: View CMS management placeholder page

Persona: Owner

As an Owner, I want to navigate to the CMS Management section, so that I know where multi-CMS management features will be available in the future.

Acceptance Criteria:

  • The /cms route renders a CMS Management page for Owner only
  • Navigating to /cms as Admin or User redirects to an "Access Denied" page or back to /
  • The CMS Management item is NOT shown in the sidebar for Admin or User roles
  • The page displays a clear "Work in Progress" or "Coming Soon" message
  • A brief description explains that this section will allow managing multiple client CMS instances
  • The page uses the same layout as other pages (sidebar, header)
  • Security: The access restriction is enforced client-side as defence-in-depth; the backend also enforces authorisation

Future Features (Brief Notes — Out of Scope for v1)

  • Profile editing (/profile): Change display name and password — backend endpoints not yet confirmed
  • Availability status management (/settings): Allow Owner to set status to Available/Maintenance/Unavailable — requires CMS availability master module
  • User deactivation/editing (/users): Deactivate or edit existing users — backend endpoints not yet confirmed
  • CMS content modules: Actual content management pages — dependent on backend CMS modules being built
Reference in New Issue View Git Blame Copy Permalink