# Example: Frontend Web Specification Scope shape: a bulk review queue inside an internal operations console. Most risk sits in the surface section, because the state machine and the disabled, loading, and partial-failure states *are* the behavior. Section 2 is a contract this surface consumes but does not own. Values here are illustrative. Reuse the structure, not the names. ## 1. Requirement Overview **Background.** Reviewers currently open one flagged submission per browser tab and act on it individually. A reviewer handling 200 items a day spends most of the time on navigation, and there is no way to see that two reviewers are working the same item. **In scope.** A queue view with server-side filtering, multi-select, a bulk approve and bulk reject action, per-item outcome reporting for partial failures, and a soft lock that shows when another reviewer holds an item. **Out of scope.** The review policy itself, the flagging model, reviewer permissions administration, and any change to the submission data model. **Roles.** `Reviewer` acts on items. `Review Lead` additionally reassigns and overrides a lock. `Auditor` has read-only access to the queue and outcomes. **Glossary.** - *Queue Item*: one flagged submission in a reviewable state. - *Selection*: the reviewer's current multi-select set, scoped to the current filter and never spanning pages. - *Soft Lock*: an advisory claim held by a reviewer, with a server-side expiry. It warns; it does not block a `Review Lead`. - *Bulk Outcome*: the per-item result set returned by one bulk action, in which items may individually succeed or fail. ## 2. Consumed Interface Contract This surface owns no tables. It records what it needs and who owns it. **Owner.** Submission Review Service. `GET /v1/review-queue?status&flagType&assignee&cursor&limit` returns `{ items: QueueItem[], nextCursor: string | null, totalApprox: number }`. `QueueItem` fields consumed: | Field | Type | Null | Note | | --- | --- | --- | --- | | `id` | string | no | stable, used as the selection key | | `flagType` | enum | no | `SPAM`, `ABUSE`, `QUALITY`, `LEGAL` | | `submittedAt` | ISO 8601 | no | rendered in reviewer-local time | | `priority` | int | no | 1 highest, 5 lowest | | `lockedBy` | string | yes | reviewer display name, null when free | | `lockExpiresAt` | ISO 8601 | yes | null when `lockedBy` is null | | `version` | int | no | echoed back on every action | `POST /v1/review-queue/actions` accepts `{ action: 'APPROVE' | 'REJECT', items: [{ id, version }], reasonCode? }` and returns `{ results: [{ id, status: 'OK' | 'FAILED', errorCode? }] }`. The endpoint is partial-success by design: HTTP 200 with per-item failures is the normal case, not an error. `totalApprox` is explicitly approximate. The surface must never render it as an exact count or use it for pagination arithmetic. **Fields deliberately not consumed.** Full submission body, reporter identity, and internal risk score. The queue shows enough to triage; opening an item is a separate route. ## 3. Surface Specification: Operations Console **Skeleton.** Queue page = filter bar + selection toolbar + virtualized item table + outcome drawer. The item detail route is a separate page and out of scope here. **Component granularity.** - *Filter bar* owns filter state and writes it to the URL. It is the single source of truth for the current query. - *Item table* owns row rendering and virtualization only. It receives the selection set and emits selection intents; it holds no selection state itself. - *Selection toolbar* owns the selection set, the bulk action buttons, and the confirmation dialog. - *Outcome drawer* owns bulk result presentation and retry of failed items only. A component never reaches across this boundary. The table cannot clear the selection; it asks the toolbar to. **View state machine.** `Idle -> Loading` on mount or any filter change. `Loading -> Ready` on a successful page fetch. `Loading -> Error` on fetch failure, with a retry that returns to `Loading`. `Ready -> Empty` when the filter yields zero items. `Ready -> Submitting` on bulk action confirmation. The table becomes read-only. `Submitting -> Reviewing Outcome` once results return, whether or not all items succeeded. `Reviewing Outcome -> Loading` when the drawer is dismissed, which re-fetches. `Loading` and `Submitting` are distinct: `Loading` shows a skeleton table, `Submitting` keeps the current rows visible and disables interaction. Collapsing them into one boolean loses the fact that a reviewer must still see what they just acted on. **Actions and guards.** | Action | Role | Disabled when | | --- | --- | --- | | Select row | Reviewer, Review Lead | state is `Submitting` | | Select all on page | Reviewer, Review Lead | state is not `Ready` | | Bulk approve | Reviewer, Review Lead | selection empty, or state is `Submitting` | | Bulk reject | Reviewer, Review Lead | selection empty, or no reason code chosen | | Override lock | Review Lead only | item is unlocked | | Retry failed | Reviewer, Review Lead | no `FAILED` result in the drawer | `Auditor` sees the table with every action control absent, not present-but-disabled. **Interaction constraints.** - Filter state lives in the URL so a queue view is shareable and survives reload. - Changing any filter clears the selection. A selection that outlives its filter can act on rows the reviewer can no longer see. - The selection never spans pages, and the toolbar states the selected count explicitly. - Row height is fixed to keep virtualization stable; content that would wrap is truncated with the full value available on hover. - Every destructive bulk action requires a confirmation naming the exact count. ## 4. Business Rules - **BR-01.** The selection is scoped to the current filter and current page. Any filter change clears it. - **BR-02.** Bulk reject requires a reason code before the action is enabled. Bulk approve requires none. - **BR-03.** An item held by another reviewer's unexpired Soft Lock is selectable but renders a lock badge, and a `Reviewer` submitting it expects it may fail. - **BR-04.** A `Review Lead` may override an unexpired lock. The override is recorded with the previous holder. - **BR-05.** Each item is submitted with the `version` the surface rendered. A stale version fails that item without affecting the rest of the batch. - **BR-06.** Partial success is a normal outcome. The drawer always shows both the succeeded and the failed set, even when every item succeeded. - **BR-07.** Retry from the drawer resubmits only `FAILED` items, using versions refreshed at retry time rather than the stale rendered ones. - **BR-08.** Dismissing the drawer re-fetches the queue. The surface never patches rows locally from a bulk result, because the server may have changed adjacent state. - **BR-09.** Bulk selection is capped at 100 items per action. The cap is stated in the toolbar before it is reached, not as an error after submission. - **BR-10.** `totalApprox` renders with an explicit approximation affordance and is never used to compute page count. ## 5. Exception Scenarios - **E-01.** Queue fetch fails. State `Error`, message "Could not load the review queue." with a retry action. Code `QUEUE_FETCH_FAILED`. Existing rows are cleared rather than left stale. - **E-02.** Bulk action request fails entirely at transport level. State returns to `Ready` with the selection preserved and "No items were changed. Try again." Code `BULK_ACTION_UNAVAILABLE`. Preserving the selection matters: the reviewer must not rebuild a 100-item selection after a network blip. - **E-03.** Item fails on stale version. Drawer row shows "Changed by someone else. Refreshed for retry." Code `ITEM_VERSION_CONFLICT`. - **E-04.** Item fails on an active lock held by another reviewer. Drawer row shows "Locked by {name}." Code `ITEM_LOCKED`. - **E-05.** Item no longer in a reviewable state. Drawer row shows "Already resolved." Code `ITEM_NOT_REVIEWABLE`. This is not presented as a reviewer error. - **E-06.** Selection cap exceeded via select-all. Toolbar shows "Only the first 100 items are selected." and the action stays enabled. Code `SELECTION_CAP_APPLIED`. The cap is applied, not the action refused. - **E-07.** Reject submitted with no reason code, reachable only by direct API use. Code `REASON_CODE_REQUIRED`; the surface's own guard prevents it. - **E-08.** Session expires mid-action. The surface routes to re-authentication and restores the filter from the URL, but not the selection. Code `SESSION_EXPIRED`. The specification states the selection is lost so nobody implements a false recovery. - **E-09.** `Auditor` reaches the page. Actions are absent and no bulk endpoint is called. No error message is shown; read-only is a valid mode, not a failure. ## 6. Acceptance Criteria **Reviewer** - **AC-01** (BR-02, normal). Given three selected items, when the reviewer opens bulk reject, then submit stays disabled until a reason code is chosen, and the confirmation names three items. - **AC-02** (BR-01, boundary). Given a selection of ten items, when the reviewer changes the flag type filter, then the selection is cleared and the toolbar actions become disabled. - **AC-03** (BR-05, BR-06, E-03, exception). Given a batch of five where one item changed server-side, when the reviewer submits bulk approve, then four report `OK`, one reports `ITEM_VERSION_CONFLICT`, and the drawer shows both sets. - **AC-04** (BR-07, exception). Given a drawer with two `FAILED` items, when the reviewer retries, then only those two are resubmitted with refreshed versions and the succeeded items are not touched. - **AC-05** (BR-08, normal). Given a completed bulk action, when the reviewer dismisses the drawer, then the queue re-fetches and the state passes through `Loading` rather than patching rows in place. - **AC-06** (BR-09, E-06, boundary). Given a filter matching 340 items, when the reviewer uses select-all on the page, then at most 100 are selected and the cap notice is visible before submission. - **AC-07** (E-02, exception). Given a bulk submit that fails at transport level, when the error surfaces, then the selection is still intact and no item shows a changed outcome. **Review Lead** - **AC-08** (BR-04, normal). Given an item locked by another reviewer, when the lead overrides the lock, then the row updates to show the lead as holder and the previous holder is recorded. **Auditor** - **AC-09** (E-09, boundary). Given an auditor session, when the queue page loads, then rows render, no action control is present in the DOM, and no bulk endpoint is called. **Any role** - **AC-10** (BR-10, boundary). Given `totalApprox` of 340, when the queue renders, then the count carries an approximation affordance and pagination is driven by `nextCursor` alone. ## 7. Open Questions and Decision Record **Open.** - Whether the 100-item cap should be configurable per role. Owner: Review Lead group. Does not block BR-09, which implements a constant first. - Keyboard shortcut set for selection and bulk actions. Owner: Design. Deferred out of this iteration. **Decided.** - Selection clears on filter change. Preserving it across filters was rejected because it lets a reviewer act on rows they can no longer see. - Locks are advisory rather than blocking. Hard locking was rejected because an abandoned tab would strand items until expiry with no override path. - Partial success renders as a normal outcome drawer rather than an error toast. A toast was rejected because it cannot carry per-item results or a retry. - The surface re-fetches instead of patching rows from bulk results. Local patching was rejected because the server can change adjacent items the response does not mention.