# Order History and Reorder

## Objective

Let customers browse past orders and rebuild one into the cart in a single action.

A per-customer list of past orders with their contents and documents, plus a control that adds a previous order's items back to the cart.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. List orders newest first with the details people scan for: date, total, item count, a thumbnail or two, and the current fulfilment status. Detail belongs on the order page.
2. Make reorder add items to the existing cart rather than replacing it, and show the resulting cart so the customer can review before paying.
3. Report what happened during a reorder. Say which items were added, which were unavailable, and which changed price, in one summary rather than a stack of separate alerts.
4. Reuse the app's existing PDF Export for invoices and receipts rather than generating documents a second way in this screen.
5. Do not copy the original prices or totals into the new cart. Reprice everything at today's catalogue prices, because the alternative is charging a price the business no longer offers.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Products get discontinued, deleted, or go out of stock. Add what is available, skip the rest, and name each skipped item with the reason instead of quietly returning a shorter cart.
- Repricing means the reorder total will often differ from the original. State the difference plainly before checkout rather than letting the customer discover it on the payment screen.
- Long histories need pagination, and returning from an order detail page must restore the page, filters, and scroll position the customer left. Losing those on back navigation makes the list unusable.
- Orders placed as a guest belong to the customer once they have an account with that verified email. Claim and merge them, and never attach an order on an unverified email match.
- Refunded and cancelled orders must keep their invoices and receipts downloadable, showing the refund rather than disappearing from the history.
- Variants change. If a previously purchased variant no longer exists, do not substitute a different one silently; flag it and let the customer choose.
- Order documents contain a customer's address and purchase history. Authorise every download against the signed-in customer, not against knowledge of the document URL.
- A customer clicking reorder twice must not double the quantities. Make the action idempotent for the duration of the request and disable the control while it runs.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] A customer sees their past orders newest first with status and totals.
- [ ] Reorder adds available items to the existing cart and shows the result before checkout.
- [ ] Unavailable and discontinued items are named as skipped with a reason.
- [ ] Cart lines are priced at current prices and any difference from the original order is stated.
- [ ] Pagination, filters, and scroll position survive navigating into an order and back.
- [ ] Guest orders appear once the account's email is verified.
- [ ] Invoices and receipts remain downloadable for refunded orders and only to their owner.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.