# Spec Delta

## Purpose

Turn attributed damage reports into reviewed maintenance work while preventing duplicate Work Orders and retaining review history.

## ADDED Requirements

### Requirement: Submit report before work
ADMIN, SUPERVISOR, and TECHNICIAN SHALL submit reports against active sub-items with a trimmed description of 1-3000 characters and priority LOW, MEDIUM, HIGH, or URGENT. The server SHALL derive reporter and time and set OPEN. Submission SHALL NOT create a Work Order. VIEWER submissions SHALL return 403.

#### Scenario: Technician reports damage
- **WHEN** a technician submits a valid description and priority
- **THEN** the API returns 201 with an OPEN report attributed to that user and no linked WO
- **AND** the equipment condition becomes NOTED

### Requirement: Review visibility and authority
Authenticated users SHALL read report details and per-asset history. ADMIN/SUPERVISOR SHALL access a paginated review queue and accept or dismiss reports. Filters SHALL support status, unit, priority, and report time ordering. Review mutations SHALL verify the authenticated actor and current report state on the server.

#### Scenario: Unauthorized acceptance
- **WHEN** a TECHNICIAN invokes the Accept endpoint directly
- **THEN** the API returns 403 and creates no Work Order

### Requirement: Atomic acceptance
Accepting an OPEN report SHALL atomically create one CORRECTIVE, PILOT_PLANT Work Order in OPEN state, link the same asset and report, record reviewer/time, set the report to ACCEPTED, and append audit/history records. Original reporter and complaint SHALL remain attributable. A failed required write SHALL roll back all changes.

#### Scenario: Successful review
- **WHEN** a supervisor accepts an OPEN report
- **THEN** the response is 201 with the report and generated WO and a Location header for that WO
- **AND** the WO is immediately visible in the maintenance read API

#### Scenario: Failed transaction
- **WHEN** creating the required audit record fails during acceptance
- **THEN** the report remains OPEN and no WO or review change is committed

### Requirement: One report one Work Order
A report SHALL link to at most one WO for its lifetime. Accept retries with the same normalized review input SHALL return 200 with the existing WO without new writes or audit events. Changed retry input or incompatible state SHALL return 409. Concurrent Accept and Dismiss SHALL commit only one decision.

#### Scenario: Two reviewers accept simultaneously
- **WHEN** two reviewers accept the same report with identical effective input
- **THEN** one creates the WO and the other receives the same WO as a replay
- **AND** the first committed reviewer attribution is preserved

#### Scenario: Accept races with dismissal
- **WHEN** Accept and Dismiss target the same OPEN report concurrently
- **THEN** only one transition commits and the other receives 409

### Requirement: Attributed dismissal
ADMIN/SUPERVISOR SHALL dismiss an OPEN report with a trimmed reason of 1-1000 characters. Dismissal SHALL record the reviewer and time, preserve the report, and create no WO. Identical dismissal retries SHALL succeed without duplicate audit events; conflicting decisions SHALL return 409.

#### Scenario: Dismiss duplicate complaint
- **WHEN** an admin dismisses a duplicate report with a reason
- **THEN** the report is DISMISSED and remains available in history with that reason

### Requirement: Maintenance handoff and unresolved cancellation
Accepted WOs SHALL be readable through authenticated maintenance list/detail endpoints with their report and asset references. Cancellation SHALL NOT resolve the report or permit a second WO. Any future maintenance transition implementation SHALL keep report state synchronized: IN_PROGRESS maps to IN_REPAIR, resolved completion to RESOLVED, and cancellation to ACCEPTED pending review.

#### Scenario: Generated WO appears in Maintenance
- **WHEN** the user navigates from an accepted report to its WO
- **THEN** the persisted corrective WO is displayed without requiring refresh of browser-local demo data

#### Scenario: Cancelled work remains unresolved
- **WHEN** a future authorized maintenance operation cancels linked work
- **THEN** the report remains active as ACCEPTED, retains its WO link, and is not counted as resolved