# Proposal

## Why

Pilot Plant currently stores its asset hierarchy, photos, and damage notes in each browser, preventing shared operational records and accountable maintenance follow-up. Users need to submit a report first, with ADMIN/SUPERVISOR acceptance creating exactly one corrective Work Order.

## What Changes

- Add persistent unit/category, equipment, and sub-item APIs with stable IDs, generated codes, scoped name uniqueness, protected metadata edits, and condition summaries.
- Add authenticated photo upload/replacement/removal with server-side image validation and durable storage references.
- Add damage reporting, a reviewer queue, Accept and Dismiss actions, reviewer attribution, and transactional creation of one Work Order per accepted report.
- Add ACCEPTED to damage status and database enforcement of the optional one-to-one report/WO relationship; preserve unresolved reports if work is cancelled.
- Integrate the Pilot Plant consumer and provide a read-only Maintenance handoff for generated corrective orders.
- **BREAKING**: Replace browser-only hierarchy writes with server persistence and ID-based DTOs. Existing IndexedDB data is not silently imported or deleted.
- Reuse the envelopes, error handling, pagination, language, and module boundaries from `establish-core-api-architecture`; its implementation is a prerequisite.

## Capabilities

### New Capabilities

- `pilot-plant-assets`: Persistent two-level asset hierarchy, permissions, search, and consistent condition projections.
- `asset-photos`: Validated and access-controlled photos for plant units and assets.
- `damage-report-review`: Report submission and review, atomic one-report/one-WO acceptance, and maintenance visibility.

### Modified Capabilities

None. Core API capabilities currently exist in an active proposal rather than durable specs; this change depends on them without duplicating their deltas.

## Impact

API modules, Prisma schema and a new migration, shared DTOs, OpenAPI, tests, and the Pilot Plant consumer are affected. A bounded read-only integration in Maintenance exposes generated corrective WOs; full maintenance execution, scheduling, cancellation/reopening UI, stock consumption, and spare-part editing remain future changes. No asset deletion/move endpoints or automatic local-data import are included.

Frontend/shared companion edits require a monorepo-authorized workspace. Photo storage requires a persistent server volume for the initial single-instance pilot. The existing baseline change must be delivered before this feature is released; no baseline files are modified by this proposal.