# Invoice Generator

## Objective

Produce a proper numbered invoice document that a customer can download and file.

Issued invoice records with sequential numbering, frozen totals, and a downloadable document per invoice.

## 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. Separate the draft from the issued invoice. A draft is editable; issuing assigns the number, freezes the content, and produces the document.
2. Render the document through the app's existing PDF Export pipeline rather than adding a second renderer. If the app already syncs to an accounting system, treat that integration as the source of record and this as the customer-facing document, not a competing ledger.
3. Copy the seller and buyer details, line items, tax rates, and currency onto the invoice at issue time. Do not reference live customer or product records, because a later address change would silently rewrite last year's paperwork.
4. Store every issued document and keep it retrievable for the retention period the business needs, with access limited to the buyer and authorised staff.
5. Do not attempt to compute tax rules for every jurisdiction. Take the applicable rate and label as input, apply it consistently, and record what was applied.

## 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

- Invoice numbers must run in an unbroken sequence, and two invoices created at the same instant must not claim the same one. Allocate the number inside a database transaction with a real lock, not from a count of existing rows.
- Totals, tax, and addresses that read from live records will shift retroactively when a price or an address changes. Snapshot every displayed value at issue time so a reprint today matches the copy the customer filed last year.
- An issued invoice must not be editable. Corrections happen through a credit note or a replacement invoice that references the original, so both sides keep a trail of what changed and why.
- Currency symbols, decimal separators, thousands separators, tax labels, and date order differ by country, and a European buyer reading a US-formatted date will file it in the wrong period. Format per the buyer's locale and never abbreviate the date.
- Long line item lists overflow the first page and break the layout. Repeat the column headers on each page, keep totals and the payment block together rather than stranded alone, and number the pages.
- Rounding applied per line and rounding applied to the total produce different answers. Pick one rule, apply it everywhere, and make sure the printed lines add up to the printed total.
- A zero-value or fully discounted invoice is legitimate and must render without a division error or an empty totals block.
- The download link must not be guessable from the invoice number. Anyone with the URL should not be able to enumerate other customers' invoices.

## 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

- [ ] Issuing an invoice assigns the next number with no gaps and no duplicates under concurrent creation.
- [ ] An issued invoice reproduces identically after customer, price, or tax settings change.
- [ ] Issued invoices cannot be edited; corrections are made by credit note or replacement.
- [ ] Currency, tax labels, and dates render according to the buyer's country.
- [ ] Invoices with many line items paginate with repeated headers and an intact totals block.
- [ ] Printed line totals sum exactly to the printed invoice total.
- [ ] Invoice documents are readable only by the buyer and authorised staff.
- [ ] 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.