web: the Dashboard's Recent sales rows have no eggs-and-grade cell because the orders list carries no grade name

[mforce]

Amendment (2026-09-19): This scope is implemented in draft PR #912, pending review and merge. See the scope and contract amendment for the API choice, current-name semantics and remaining work.

Part of #674. Found by #829 (#883) on 2026-09-16.

The confirmed Dashboard direction (docs/designs/864-visual-language/DIRECTION.md, "Recent sales rows: customer with the order number under it, eggs and grade, peso amount, status, action") has an eggs-and-grade cell ("3,600 Large"). #883 renders every other column and leaves that one out, because the orders list the Dashboard reads carries no grade name: OrderItem in web/src/api/cluckwork.ts (~L328) has quantity, quantityBase and eggGradeId only.

Two ways to close it, for the owner to pick:

1. API: include the grade name on each order line in the orders list response (the order aggregate already resolves the grade when it allocates), so the Dashboard renders "3,600 Large" from the row it already has. One response shape change, one field, no extra request.
2. SPA: the Dashboard fetches listEggGrades() once and joins by eggGradeId. No API change, one more request on the morning screen, and a second place that has to agree with the grade list.

Option 1 is the smaller cost on the screen a worker opens every morning and keeps the grade name where the order was priced. Either way the cell is a single line per order (the mockup's row shows one grade per order; an order with several grades shows the first and "+N"), and the Dashboard tests pin it on text.

[mforce]

Owner picked option 1 (2026-09-16): the orders list response carries the grade name on each order line. The list endpoint already does one bulk customer-name read per page (SaleEndpoints.cs, #512 T048), so the grade name is the same shape: one bulk read keyed by EggGradeId, one new field on SalesOrderItemResponse, and the Dashboard renders "3,600 Large" from the row it already has.

[mforce]

The field the Dashboard needs (documented for #906, owner decision 2026-09-17: the API returns it)

Where: the orders list response, per order line. SalesOrderItemResponse in src/Cluckwork.Api/Endpoints/Sales/SaleEndpoints.cs gains one field:

string EggGradeName

beside the existing EggGradeId. web/src/api/cluckwork.ts's OrderItem mirrors it as eggGradeName: string.

How it is read: one bulk read per page keyed by the distinct EggGradeIds on the page, in the list endpoint that already does one bulk customer-name read per page (SaleEndpoints.cs, the GetDisplayNamesAsync call, #512 T048). No per-row query, no extra request from the SPA.

What the Dashboard renders from it (the Operations Desk direction, #906): one line per order in Recent Orders, "{quantity} {gradeName}" such as 3,600 Large; an order with several grades shows the first line's grade and +N. The Dashboard tests pin it on text.

Semantics to record: the name is the grade's current name at read time, resolved from the account's grade list, not the name at the time the order was priced. Grades are user-renamable (#283), so a renamed grade shows its new name on old orders, which matches how the Sales page and the stock ledger already show grades. A missing grade (deleted or from a data repair) yields an empty name and the row renders the quantity alone.

Cost: one indexed WHERE Id IN (...) read per list page, bounded by the page's distinct grade count (at most the farm's grade count, typically under ten). No new endpoint, no schema change, no migration.

Alternative declined: the SPA calling listEggGrades() on the Dashboard and joining by id; one more request on the morning screen and a second place that must agree with the grade list.

[mforce]

#906 absorbs this work in PR #912, currently a draft pending review and merge. The owner's API choice is implemented: list and detail return EggGradeName per item through one bulk grade read, and the Dashboard shows quantity plus grade name, with +N for extra lines. Missing names render quantity alone.

The name is the grade's current name at read time, including inactive grades. A rename changes the display on an old order; there is no historical-name snapshot. No extra SPA request is added. The integration cases cover list/detail, rename and deactivation; Dashboard tests cover the row text and fallback.

No separate #887 implementation remains once #912 merges. The alternative SPA grade lookup is deliberately not implemented, following the owner's decision. This comment records implementation in the PR, not a claim that it has shipped to main.