Use-case UC0003 Implementation – Admin issues an invoice with line items

Initiating actor: Admin

Other actors: Client (the invoice recipient)

Description: The Admin issues an invoice to a client. The Admin selects the client from a list, sets the issue and due dates, and adds one or more itemized line items. The system computes the subtotal, tax, and total, then stores the invoice header together with its line items.

Scenario

1. Admin opens the "Invoices" → create form. To populate the client selector, the system lists the clients:

   SELECT id, name, company, email
   FROM project.users
   WHERE role = 'CLIENT'
   ORDER BY name;
   

   The Admin selects the client (Goran Trajkovski), sets the issue date (2026/07/01) and due date (2026/07/09), and adds a line item (Development / PWA, quantity 1, unit price 9000).
2. Admin submits the invoice. The system computes the totals (subtotal 9000, tax 18% = 1620, total 10620) and inserts the invoice header and its line item in one transaction:

   INSERT INTO project.invoices
     (invoice_number, client_id, amount, subtotal, tax_rate, tax_amount,
      due_date, issue_date, status, payment_terms)
   VALUES
     ('INV-2027', 4, 10620.00, 9000.00, 18, 1620.00,
      TIMESTAMP '2026-07-09', TIMESTAMP '2026-07-01', 'PENDING', 'Test')
   RETURNING id;
   
   INSERT INTO project.invoice_line_items (invoice_id, name, description, quantity, unit_price, sort_order)
   VALUES (<new_invoice_id>, 'Development', 'PWA', 1, 9000.00, 0);
   

3. System opens the invoice detail view, showing the client, dates, status (PENDING), the line item, and the computed subtotal, tax, and total, plus the payment tracking section.
4. System can also render the invoice as a downloadable PDF, showing the same stored data (client, line items, subtotal, tax, total) in a printable document.

The invoice header and its line items are inserted in one transaction, so an invoice is never stored without its lines. The totals shown in the UI and PDF are read back from the stored subtotal, tax_amount, and amount columns, which are internally consistent (subtotal × tax_rate/100 = tax_amount).