# Maintenance API behavior

Routes are owned by maintenance.routes.ts, with controllers validating strict inputs and services owning transactions. Swagger documents the expanded shared DTOs and input contracts. Pilot Plant's existing WO identifiers, report handoff and read routes remain compatible. Authenticated users including VIEWER can read; active TECHNICIAN can start, record notes and complete; ADMIN/SUPERVISOR additionally create, cancel, manage plans and post usage. No technician assignment is accepted.

WO lifecycle: OPEN → IN_PROGRESS → COMPLETED, or OPEN/IN_PROGRESS → CANCELLED. Completion accepts an optional resolution (omission preserves existing notes, blank text clears them); cancellation accepts an optional reason (blank reasons are stored as null in history). Terminal work cannot be reopened. Scheduled/overdue are derived display states, never writable statuses. Future releaseAt orders are excluded from queue/detail; calendar distinguishes projections from persisted work. Queue ordering is createdAt descending then id descending. Summary ignores selected status and pagination but preserves other filters. createdFrom/createdTo filter createdAt; dueFrom/dueTo filter dueAt, using inclusive local end days.

All manual Maintenance writes require a UUID Idempotency-Key, with actor, operation, canonical payload and committed result stored atomically in MaintenanceRequest. Reuse the same key AND input after uncertain failure. Changed payload/operation/actor conflicts. Replay requires a currently active authorized actor. Version guards stale updates; successful WO writes increment version. Required history, audit, report state and calibration writes share the transaction.

Starting report work updates only the linked report to IN_REPAIR; completing resolves it; cancelling leaves ACCEPTED and linked to its original WO. If additional work is needed after cancellation, submit a new report, not acceptance of the old one. Other reports on the target remain unresolved.

Quarantine queue supports q, partId, status, workOrderState NONE/ACTIVE/TERMINAL and reportedFrom/reportedTo. Dates apply to reportedAt in facility timezone. Every detail includes original reporter, ledger-derived released/scrapped/remaining quantities, and linked WO summaries. Privileged review creates a corrective WO manually only when remaining > 0 and no OPEN/IN_PROGRESS WO exists. Part-first locking serializes reviewers, start, disposition and reversal. Completion/cancellation does not release stock. Release/scrap and case reversals are blocked during IN_PROGRESS repair. After closure, quantities may be released/scrapped separately, including CLOSED_MIXED outcomes. A case closed while its WO is OPEN cannot subsequently start repair without remaining goods.

WO usage is net posted ISSUE/RETURN physical deltas, including reversals, never a separately editable total. Privileged issues/returns require IN_PROGRESS, integer quantity, reason, current version and stable request key. Return cannot exceed net issued. Cancellation does not return consumed goods. Correct terminal consumption through explicit privileged Inventory return/reversal, retaining movement references. Public checkout is independent; never record the same withdrawal twice. No costs enter DTOs.

Plans support PREVENTIVE/CALIBRATION, Equipment/Item, ONCE/DAILY/WEEKLY/MONTHLY/YEARLY, startDate, optional endDate and priority. Targets must be active at creation/generation. Default lead days 0, first due=start; release is start of facility day and due is its final millisecond. Month/leap anchors remain stable. After first generation target/type/start/cycle cannot change; pause then create a new plan to reschedule. Exhausted plans cannot be reactivated without a next occurrence. Other changes are versioned and affect ungenerated work only.

Calendar GET is read-only, at most 366 inclusive days/5000 results, with explicit 422 on excess. `date` is the facility-local day; timestamps are UTC. Each actual occurrence has independent lifecycle/history. Scheduler command and deployment steps are in prisma/maintenance-deployment.md. Automatic OPEN history has actor null, displayed as “Sistem”; manual history always records the actual user. Calibration result storage is disabled. Completion of CALIBRATION work orders or submission of structured calibration results is rejected. Legacy work-order types remain available for compatibility.

`POST /work-orders/:id/cancel-delete` uses the cancellation payload (version, optional reason) and Idempotency-Key. Only ADMIN/SUPERVISOR may atomically cancel and soft delete an OPEN order without execution activity. Activity includes started history, nonblank resolution, comments, failure, stockouts and any movements. Deletion actor/time, cancellation history and audit are saved together; reports remain ACCEPTED and quarantine stock is unchanged. Deleted records remain readable for audit through existing links but disappear from operational queues, summary, calendar and analytics. PM occurrences remain reserved, preventing regeneration.