# Customers Purchase History Specification ## Purpose The system provides a read-only, paginated HTML screen listing every order a given customer has placed, with an optional filter by product category. It is accessible only to authenticated administrators and renders under the admin back-office layout. ## Requirements ### Requirement: Authentication Gate The system SHALL redirect any unauthenticated request for `GET /customers/{customer}/orders` to `auth/login` with HTTP `302` before any other processing occurs. (Implemented in `routes/web.php:23-28,54`) #### Scenario: Unauthenticated request is redirected - **GIVEN** a request with no authenticated admin session - **WHEN** `GET /customers/{customer}/orders` is called with any customer id - **THEN** the response is `302` redirecting to `auth/login` --- ### Requirement: Customer Resolution The system SHALL resolve the target customer by the `{customer}` route parameter and return HTTP `404` if the id does not correspond to an existing, non-soft-deleted customer record. (Implemented in `app/Http/Controllers/CustomerController.php:200`) #### Scenario: Valid customer id returns the orders page - **GIVEN** an authenticated administrator and a customer with at least one order - **WHEN** `GET /customers/{id}/orders` is called with that customer's id - **THEN** the response is HTTP `200` and the page is scoped to that customer's orders #### Scenario: Unknown customer id returns 404 - **GIVEN** an authenticated administrator - **WHEN** `GET /customers/{id}/orders` is called with an id that does not exist in the database - **THEN** the response is HTTP `404` #### Scenario: Soft-deleted customer id returns 404 - **GIVEN** an authenticated administrator and a customer that has been soft-deleted - **WHEN** `GET /customers/{id}/orders` is called with that customer's id - **THEN** the response is HTTP `404` --- ### Requirement: Paginated Order List The system SHALL return the resolved customer's orders ordered by `id` descending, paginated at 20 records per page, honoring the `page` query parameter. (Implemented in `app/Http/Controllers/CustomerController.php:204,208`) #### Scenario: First page shows the 20 most recent orders - **GIVEN** an authenticated administrator and a customer with 25 orders - **WHEN** `GET /customers/{id}/orders` is called without a `page` parameter - **THEN** the response contains exactly 20 orders, the 20 with the highest ids among that customer's orders #### Scenario: Subsequent page shows remaining orders - **GIVEN** an authenticated administrator and a customer with 25 orders - **WHEN** `GET /customers/{id}/orders?page=2` is called - **THEN** the response contains the remaining 5 orders, with lower ids than any order on page 1 #### Scenario: Out-of-range page returns an empty list - **GIVEN** an authenticated administrator and a customer with 5 orders - **WHEN** `GET /customers/{id}/orders?page=99` is called - **THEN** the response is HTTP `200` and the order list is empty --- ### Requirement: All Order Statuses Included The system SHALL include orders of every status in the listing; no status filter is applied. (Implemented in `app/Http/Controllers/CustomerController.php:204`) #### Scenario: Draft and done orders both appear - **GIVEN** an authenticated administrator and a customer who has exactly one order with status `draft` and one with status `done` - **WHEN** `GET /customers/{id}/orders` is called - **THEN** both orders appear in the response list --- ### Requirement: Category Filter The system SHALL, when a truthy `category` query parameter is supplied, restrict the order list to orders that contain at least one line-item product belonging to the specified category; each qualifying order SHALL appear exactly once in the result. When `category` is absent or empty, the system SHALL return all orders without restriction. (Implemented in `app/Http/Controllers/CustomerController.php:205-207`) #### Scenario: Category filter narrows the list to matching orders - **GIVEN** an authenticated administrator and a customer whose orders include some with products in category C and some without - **WHEN** `GET /customers/{id}/orders?category=` is called - **THEN** only orders that have at least one product in category C are listed, and each such order appears exactly once #### Scenario: An order with multiple products in the filtered category appears only once - **GIVEN** an authenticated administrator and a customer with one order containing two products both in category C - **WHEN** `GET /customers/{id}/orders?category=` is called - **THEN** that order appears exactly once in the response #### Scenario: Absent category parameter returns all orders - **GIVEN** an authenticated administrator and a customer with orders across multiple categories - **WHEN** `GET /customers/{id}/orders` is called without a `category` parameter - **THEN** all orders are listed regardless of their products' categories #### Scenario: Empty category parameter returns all orders - **GIVEN** an authenticated administrator and a customer with orders across multiple categories - **WHEN** `GET /customers/{id}/orders?category=` is called with an empty string value - **THEN** all orders are listed regardless of their products' categories --- ### Requirement: Category Dropdown Scope The system SHALL populate the category filter dropdown with an "all categories" sentinel as the first option, followed exclusively by child categories (those having a non-null `parent_id`); parent categories SHALL NOT appear as selectable options. (Implemented in `app/Http/Controllers/CustomerController.php:202`) #### Scenario: Dropdown first option is the all-categories sentinel - **GIVEN** an authenticated administrator viewing the orders page for any customer - **WHEN** the page is rendered - **THEN** the category dropdown's first option has an empty value representing "all categories" #### Scenario: Dropdown lists only child categories - **GIVEN** an authenticated administrator viewing the orders page and a category hierarchy with both parent and child categories - **WHEN** the page is rendered - **THEN** the category dropdown contains only child categories (those with a parent), and no top-level parent categories appear as options