diff --git a/specs/002-at-the-moment/checklists/requirements.md b/specs/002-at-the-moment/checklists/requirements.md new file mode 100644 index 0000000..32e8266 --- /dev/null +++ b/specs/002-at-the-moment/checklists/requirements.md @@ -0,0 +1,104 @@ +# Requirements Checklist: Product Selection Landing Page + +**Feature**: 002-at-the-moment +**Created**: 2025-10-17 +**Status**: Draft + +## Functional Requirements + +### Core Landing Page Functionality +- [ ] **FR-001**: System MUST display a landing page at the root URL (`/`) showing all active products available for feedback submission +- [ ] **FR-002**: System MUST retrieve product list from the file-based storage (`data/products/*/config.yaml`) +- [ ] **FR-003**: System MUST filter products to show ONLY those with `status: active` in their config.yaml +- [ ] **FR-004**: System MUST display for each product: product name (`name` field from config.yaml) +- [ ] **FR-005**: System MUST provide a clickable link/button for each product that navigates to `/submit/{submission_url_slug}` + +### Data Handling & Edge Cases +- [ ] **FR-006**: System MUST handle products without descriptions gracefully (show name only or placeholder) +- [ ] **FR-007**: System MUST maintain existing direct URL functionality (`/submit/{product-slug}` continues to work) +- [ ] **FR-009**: System MUST sort products in a consistent, predictable order (alphabetical by name recommended) +- [ ] **FR-010**: System MUST handle the case where no active products exist (display appropriate message) + +### Security & Technical Constraints +- [ ] **FR-008**: Landing page MUST be accessible to anonymous users (no authentication required) +- [ ] **FR-011**: Product listing MUST be server-side rendered (consistent with project's no-JavaScript requirement) +- [ ] **FR-012**: System MUST escape all product names and descriptions to prevent XSS attacks +- [ ] **FR-013**: Landing page MUST use the same minimal HTML/CSS styling as the rest of the application (no frameworks) +- [ ] **FR-014**: System MUST log when the landing page is accessed (for monitoring/analytics) + +## User Stories + +### P1: Browse and Select Product +- [ ] Visitor can view landing page at root URL +- [ ] All active products are displayed with names +- [ ] Product descriptions are shown (if available) +- [ ] Clicking a product navigates to its submission form +- [ ] Products are visually distinguishable + +### P2: Product Availability Status +- [ ] Only active products appear in the list +- [ ] Archived products do not appear (or clearly marked) +- [ ] Visitor can trust listed products accept feedback + +### P3: Direct Navigation Compatibility +- [ ] Direct URLs to `/submit/{product-slug}` still work +- [ ] Visitors can quickly identify known products +- [ ] Large product lists remain navigable + +## Success Criteria + +### Performance & Usability +- [ ] **SC-001**: Visitors can access submission form in ≤2 clicks from landing page +- [ ] **SC-002**: Landing page loads in <1 second for up to 100 products +- [ ] **SC-003**: Active products appear on landing page within 5 seconds of status change +- [ ] **SC-008**: Users can distinguish between 5+ products visually + +### Reliability & Security +- [ ] **SC-004**: Zero direct URL submissions broken (backwards compatibility) +- [ ] **SC-005**: Appropriate message shown when no active products exist +- [ ] **SC-006**: Product names/descriptions properly escaped (no XSS) +- [ ] **SC-007**: Landing page renders without JavaScript + +## Edge Cases Coverage + +- [ ] No active products scenario handled +- [ ] All products archived scenario handled +- [ ] Products without descriptions handled +- [ ] Authenticated user accessing landing page handled +- [ ] Long product names handled (truncation/wrapping) +- [ ] Special characters in product names handled (escaping) +- [ ] Multiple similar product names handled (differentiation) +- [ ] Missing/invalid submission_url_slug handled + +## Testing Requirements + +### Contract Tests Required +- [ ] GET `/` returns 200 with HTML product list +- [ ] Products filtered by status=active only +- [ ] Product links navigate to correct submission forms +- [ ] No active products shows appropriate message +- [ ] XSS prevention (product names with HTML/script tags) + +### Integration Tests Required +- [ ] Complete user journey: landing page → product selection → submission form +- [ ] Backwards compatibility: direct submission URLs work +- [ ] Product list updates when product status changes +- [ ] Authenticated vs anonymous access behavior + +### Performance Tests Required +- [ ] Landing page load time with 100 products <1s +- [ ] Product listing rendering performance + +## Definition of Done + +- [ ] All functional requirements implemented and tested +- [ ] All user stories have passing acceptance tests +- [ ] All success criteria validated +- [ ] All edge cases handled with appropriate error messages +- [ ] Contract tests written and passing +- [ ] Integration tests written and passing +- [ ] Performance tests written and passing +- [ ] Code follows project conventions (Python, Flask, no JS) +- [ ] Security requirements met (XSS prevention, access control) +- [ ] Documentation updated (if needed) +- [ ] Feature committed to branch 002-at-the-moment diff --git a/specs/002-at-the-moment/spec.md b/specs/002-at-the-moment/spec.md new file mode 100644 index 0000000..fe2da8d --- /dev/null +++ b/specs/002-at-the-moment/spec.md @@ -0,0 +1,112 @@ +# Feature Specification: Product Selection Landing Page + +**Feature Branch**: `002-at-the-moment` +**Created**: 2025-10-17 +**Status**: Draft +**Input**: User description: "At the moment visitors of the website need to know the link to the product submission page when they want to submit a feedback. The now should be able to see a list of all active products in order to choose what product they want to give a feedback." + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Browse and Select Product (Priority: P1) + +A visitor arrives at the Reklamator platform without knowing the specific product URL. They want to discover which products accept feedback and navigate to the appropriate submission form for the product they're interested in. + +**Why this priority**: This is the core functionality that enables product discoverability. Without this, the system requires users to have prior knowledge of product URLs, creating a significant barrier to feedback submission. This directly addresses the user's stated problem. + +**Independent Test**: Can be fully tested by visiting the root landing page, seeing a list of active products with their names and descriptions, clicking on a product, and being redirected to that product's submission form. Delivers immediate value by making the feedback system discoverable. + +**Acceptance Scenarios**: + +1. **Given** a visitor arrives at the platform root URL (`/`), **When** they view the page, **Then** they see a list of all active products with product names and brief descriptions +2. **Given** multiple active products exist in the system, **When** a visitor views the landing page, **Then** all active products are displayed in a clear, organized list +3. **Given** a visitor sees the product list, **When** they click on a product name or "Submit Feedback" button, **Then** they are redirected to that product's submission form (`/submit/{product-slug}`) +4. **Given** a product has a descriptive summary, **When** displayed on the landing page, **Then** the summary helps the visitor understand what the product is +5. **Given** a visitor is on the landing page, **When** they review the products, **Then** they can easily distinguish between different products + +--- + +### User Story 2 - See Product Availability Status (Priority: P2) + +A visitor wants to understand which products are currently accepting feedback and which might be archived or inactive, so they don't waste time trying to submit feedback to a product that's no longer active. + +**Why this priority**: Provides transparency about product status and prevents user frustration. This is secondary to basic discovery but improves user experience by setting clear expectations. + +**Independent Test**: Can be tested independently by creating products with different statuses (active, archived) and verifying that only active products appear on the landing page, or that archived products are clearly marked as not accepting feedback. + +**Acceptance Scenarios**: + +1. **Given** a product has status "active", **When** the landing page loads, **Then** the product appears in the list +2. **Given** a product has status "archived", **When** the landing page loads, **Then** the product does NOT appear in the list (or appears with clear "not accepting feedback" indicator) +3. **Given** some products are active and some are archived, **When** the landing page loads, **Then** only active products are shown by default +4. **Given** a visitor views the landing page, **When** they see a product listed, **Then** they can trust that clicking it will allow them to submit feedback + +--- + +### User Story 3 - Direct Navigation with Known Product (Priority: P3) + +A visitor who already knows which product they want to submit feedback for can quickly find it in the list or use existing direct URL functionality without interference. + +**Why this priority**: Ensures backwards compatibility and doesn't disrupt existing user workflows. Users with bookmarked URLs or shared links should continue to work seamlessly. + +**Independent Test**: Can be tested by directly navigating to `/submit/{product-slug}` and verifying it still works, or by using a search/filter on the landing page to quickly locate a known product. + +**Acceptance Scenarios**: + +1. **Given** a visitor has a direct link to `/submit/product-name`, **When** they visit that URL, **Then** they go directly to the submission form (existing behavior preserved) +2. **Given** a visitor knows the product name, **When** they view the landing page, **Then** they can quickly identify their product in the list +3. **Given** many products exist (10+), **When** a visitor has a specific product in mind, **Then** they can find it efficiently (via alphabetical sorting or search if implemented) + +--- + +### Edge Cases + +- **What happens when there are no active products?** Display a message: "No products are currently accepting feedback. Please check back later." +- **What happens when all products are archived?** Same as no active products - show appropriate message explaining no products available +- **What happens when a product has no description?** Display product name only, or show placeholder text like "No description available" +- **What happens when a visitor accesses the landing page while authenticated as a product owner?** They should still see the landing page (authentication doesn't affect anonymous submission access), or optionally redirect to dashboard +- **What happens when product names are very long or contain special characters?** Ensure proper text truncation/wrapping and HTML escaping for XSS prevention +- **What happens when multiple products have similar names?** Display them all clearly - let descriptions help differentiate +- **What happens if a product's submission_url_slug is missing or invalid?** Skip that product in the listing with error logged, or show error state + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: System MUST display a landing page at the root URL (`/`) showing all active products available for feedback submission +- **FR-002**: System MUST retrieve product list from the file-based storage (`data/products/*/config.yaml`) +- **FR-003**: System MUST filter products to show ONLY those with `status: active` in their config.yaml +- **FR-004**: System MUST display for each product: product name (`name` field from config.yaml) +- **FR-005**: System MUST provide a clickable link/button for each product that navigates to `/submit/{submission_url_slug}` +- **FR-006**: System MUST handle products without descriptions gracefully (show name only or placeholder) +- **FR-007**: System MUST maintain existing direct URL functionality (`/submit/{product-slug}` continues to work) +- **FR-008**: Landing page MUST be accessible to anonymous users (no authentication required) +- **FR-009**: System MUST sort products in a consistent, predictable order (alphabetical by name recommended) +- **FR-010**: System MUST handle the case where no active products exist (display appropriate message) +- **FR-011**: Product listing MUST be server-side rendered (consistent with project's no-JavaScript requirement) +- **FR-012**: System MUST escape all product names and descriptions to prevent XSS attacks +- **FR-013**: Landing page MUST use the same minimal HTML/CSS styling as the rest of the application (no frameworks) +- **FR-014**: System MUST log when the landing page is accessed (for monitoring/analytics) + +### Key Entities + +- **Product**: Existing entity from 001-build-an-application. Key attributes relevant to this feature: + - `product_id`: Unique identifier + - `name`: Display name for the product + - `submission_url_slug`: URL segment for submission form + - `status`: "active" or "archived" - determines visibility on landing page + - `description` (optional): Brief description to help users identify the product + +- **Landing Page View**: New view/route that aggregates active products and presents them to visitors + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: Visitors can discover and access any active product's feedback submission form in 2 clicks or less (landing page → product selection → submission form) +- **SC-002**: Landing page loads with product list in under 1 second for up to 100 active products +- **SC-003**: 100% of active products in the system appear on the landing page within 5 seconds of being marked active +- **SC-004**: Zero direct URL submissions are broken by this feature (backwards compatibility maintained) +- **SC-005**: Landing page displays appropriate message when zero active products exist (no blank page or error) +- **SC-006**: Product names and descriptions are properly escaped (no XSS vulnerability when product names contain HTML/script tags) +- **SC-007**: Landing page renders correctly without JavaScript (consistent with application architecture) +- **SC-008**: Users can visually distinguish between products when 5+ products are listed (clear visual separation)