feat(billing): invoice by tasks or project with composed line notes (rework PR 3, backend)

[gdarko]

Backend half of the reworked PR 3: billing/prepare learns the task-centric
selections, and an invoice line finally describes the work behind it. No
frontend changes here; resources/js is untouched and the UI half follows once
the UI PR merges.

Selections

POST billing/prepare now takes exactly one of:

body	means
entry_ids: int[]	these entries, exactly (unchanged)
task_ids: int[]	every stopped, billable, unbilled entry of these tasks
project_id: int	the same, for every task filed under the project

grouping is optional and defaults to task. Naming two shapes, or none, is a
422 with validation errors on the fields involved.

A task or a project selection resolves through the same rule the unbilled list
uses, including the live-invoice rule: an entry whose invoice was deleted in the
host counts as unbilled again. An explicit entry_ids list keeps its stricter
reading, where a row that cannot be billed is an error rather than a quietly
shorter invoice.

New value object app/Application/BillingSelection.php (fromEntryIds,
fromTaskIds, fromProject), resolved by
BillingService::resolveEntries(int $companyId, BillingSelection $selection).

Refusals

• Nothing left to bill: new NothingToInvoice, 422, error key
  nothing_to_invoice, message "No unbilled billable time on the selected
  tasks."
• Several customers: the existing MixedBillingSelection (422), and the body
  now also carries customer_ids: int[] so the UI can name them. A domain
  refusal may carry structured context, which DomainExceptionRenderer merges
  beside message and error (never over them).
• A task or a project of another company: 404, the same answer its own endpoint
  gives.

confirm, billing/customers and billing/unbilled are unchanged.

Line composition

New app/Application/InvoiceLineComposer.php, used by prepare for every
grouping.

• name: #{number} {task name} for the task grouping; the project name,
  the member label and Time as before for the others.
• description: ## {project name} when invoice_project_heading is on, then
  the task description when invoice_task_description is on (task grouping
  only), then one line per entry ordered by started_at, built from the parts
  that are on: invoice_entry_dates gives Y-m-d, invoice_entry_times gives
  HH:MM-HH:MM when both stamps exist, invoice_entry_hours gives {h.hh} h,
  invoice_entry_descriptions gives the entry description. Parts are joined by
  two spaces; an entry with no enabled part produces no line.
• Capped at 2,000 characters, truncated on a line boundary, with
  and {n} more entries appended.

Quantity stays 2 dp (verified: the host's invoice_items.quantity is
decimal(15,2)); price keeps the blended rate rule; total = round(quantity * price).

Behaviour change to note

The old line description was the de-duplicated entry descriptions joined by
newlines. The composer replaces it, so with the shipped defaults
(invoice_task_description, invoice_entry_dates and invoice_entry_hours on)
a line that used to read null now reads 2026-09-01 1.00 h. The
BillingServiceTest and BillingApiTest expectations that asserted the old
format were updated; the tests that are about quantities, groups or rates now
switch every note part off so they say what they are about.

ISO dates are deliberate: the company's date format lives in the host and is not
reachable from a module, and an unambiguous date beats a wrong-looking one.

Tests

composer run test: 312 green, up from 293. New coverage: selection by task
ids, by project, the live-invoice rule through the fake host reader, mixed
customers with customer_ids, nothing to invoice, 404 for another company's
task or project, the three selection shapes over HTTP, "exactly one selection"
validation, and the composer for each toggle, both headings, an entry with
nothing to say, and the 2,000 character cap with its and N more entries
suffix.

vendor/bin/pint, composer run lint, validate-module and validate-package
all pass.

Live check

Against the dev stack (company 2), a throwaway task on project 1 with one
30-minute billable entry:

POST billing/prepare {"task_ids":[5]}
  name        "#5 PR3 live check"
  description "2026-09-15  0.50 h"
  quantity    0.5
  price       9000
  total       4500

{"project_id":1} returned the same single line. Naming both task_ids and
project_id returned 422 with errors on both fields, an unknown task id
returned 404, and a task with no unbilled time returned 422
nothing_to_invoice. The task and the entry were deleted afterwards and no host
invoice was created.

Open nit

and {n} more entries is the wording the plan specifies, so n = 1 reads "and
1 more entries". Say the word and it can singularise, or move behind a lang
string for the UI PR.

https://claude.ai/code/session_01DCf36XDKprZifej8dc2r1E

[gdarko]

Superseded by #14, which carries this stack consolidated into three commits on top of main.