# Spec Delta

## Purpose

Menyediakan dashboard operasional berbasis data Maintenance dan Inventory yang konsisten, menjelaskan kepatuhan PM tepat waktu, backlog aktif, kondisi stok, dan WO yang membutuhkan perhatian.

## ADDED Requirements

### Requirement: Authenticated overview
The system SHALL expose `GET /api/v1/dashboard/overview` to all active authenticated application roles using the existing success/error envelope and request ID. The response SHALL contain period, timezone, asOf, four KPIs, five chart datasets, and up to five work orders. It SHALL NOT expose technician assignments or calibration data.

#### Scenario: Authorized read
- **WHEN** an active authenticated user requests the overview
- **THEN** the response contains the global operational overview without technician fields or CALIBRATION records

#### Scenario: Anonymous access
- **WHEN** a caller without a valid active session requests the overview
- **THEN** the existing authentication error is returned without dashboard data

### Requirement: Current month and current operational scope
The system SHALL use the current calendar month in the facility timezone for period analytics and return its inclusive start and exclusive end as UTC instants. All WO datasets SHALL exclude unreleased orders. Current backlog and inventory SHALL be independent of the monthly period. This version SHALL offer no custom date filter.

#### Scenario: Local month boundary
- **WHEN** the facility local date enters a new month while the UTC date remains in the previous month
- **THEN** monthly cohorts use the facility month and the response identifies its timezone and boundaries

#### Scenario: Old backlog
- **WHEN** an active released PM was due in a previous month
- **THEN** it remains in the current overdue KPI but not in this month's PM cohort

#### Scenario: Unsupported date filter
- **WHEN** a caller supplies dateFrom or dateTo to this endpoint
- **THEN** the API returns the existing validation error rather than silently ignoring the requested period

### Requirement: On-time PM compliance
PM compliance SHALL use released, non-cancelled PREVENTIVE WOs with dueAt in the current month and dueAt at or before asOf. Its numerator SHALL count COMPLETED orders with completedAt at or before dueAt. The response SHALL include numerator, denominator, and percentage rounded to one decimal, or null when the denominator is zero.

#### Scenario: Late completion does not improve compliance
- **WHEN** ten PMs have reached their deadlines, six completed on time, two completed late, and two remain active
- **THEN** compliance is 60.0 percent with numerator six and denominator ten

#### Scenario: Exact deadline
- **WHEN** a PM is completed exactly at its dueAt and dueAt is at or before asOf
- **THEN** it counts as completed on time

#### Scenario: No eligible deadlines
- **WHEN** all PMs are cancelled, unreleased, without dueAt, or due in the future
- **THEN** the denominator is zero and compliance is null rather than zero or 100 percent

#### Scenario: Missing completion timestamp
- **WHEN** a completed PM in the eligible cohort lacks completedAt
- **THEN** it remains in the denominator but is not counted as on-time

### Requirement: Current maintenance KPIs
PM overdue SHALL count released PREVENTIVE orders with status OPEN or IN_PROGRESS and dueAt strictly before asOf. Active corrective SHALL count released CORRECTIVE orders with either active status, including both PILOT_PLANT and WAREHOUSE_QUARANTINE sources. Completed, cancelled, and legacy calibration orders SHALL NOT count.

#### Scenario: Deadline and status boundaries
- **WHEN** orders include a future deadline, a null deadline, a completed overdue order, and an active PM whose dueAt is before asOf
- **THEN** only the last order counts as overdue; a deadline equal to asOf is not yet overdue

#### Scenario: Corrective on sparepart
- **WHEN** a released quarantine-source corrective WO is IN_PROGRESS
- **THEN** it counts in active corrective without needing a technician or equipment target

### Requirement: Monthly maintenance charts
The WO type chart SHALL count released, non-cancelled PM and CM created in the current month and their completed subset. The PM status chart SHALL count released, non-cancelled PM due in that month as completed, overdue, open, or in-progress, with active overdue taking precedence. Both charts SHALL identify their cohort basis; PM completion SHALL NOT be presented as on-time compliance.

#### Scenario: Different cohorts are explicit
- **WHEN** a PM was created last month and is due this month
- **THEN** it is included in the PM status chart but not the WO type chart, whose label states creation month

#### Scenario: Future deadline in PM chart
- **WHEN** a released PM is due later this month and is IN_PROGRESS
- **THEN** it appears in the in-progress segment but not yet in the compliance denominator

### Requirement: Available inventory and critical SKU counts
Inventory datasets SHALL use non-archived parts and aggregate their balances before classifying each SKU. Available stock SHALL equal physical minus quarantined. Critical stock KPI SHALL count each SKU once when available is zero or below minimumStock. Critical chart buckets SHALL count empty, positive-but-low, minimumStock zero, and quarantined-positive SKUs; the last two buckets can overlap others.

#### Scenario: Quarantine and pending checkout
- **WHEN** a SKU has physical ten, quarantined four, minimum seven, and a pending checkout of two
- **THEN** available is six, the SKU contributes once to the critical KPI and low-stock bucket, and pending checkout causes no extra deduction

#### Scenario: No configured minimum
- **WHEN** a SKU has minimumStock zero and positive available stock
- **THEN** it counts in the zero-minimum bucket but not in the critical KPI

#### Scenario: Archived part and missing balance
- **WHEN** an archived part has stock and an active part has no balances
- **THEN** the archived part is excluded and the active part has zero available stock

### Requirement: Inventory chart units and overlap
Available quantity charts SHALL group by part group and stored unit, displaying the unit and never summing incompatible units. Condition charts SHALL count SKUs per group in mutually exclusive available-stock states safe, low, or empty, plus quarantined-positive as an overlapping state. The interface SHALL explain this overlap and SHALL NOT present the sum as unique SKU count.

#### Scenario: Mixed units
- **WHEN** one group contains ten Pcs and five Meter of available stock
- **THEN** the chart shows separate labeled quantities rather than fifteen units

#### Scenario: Available and damaged stock together
- **WHEN** a SKU has positive available stock at or above minimum and quarantined stock above zero
- **THEN** it counts once as safe and once as quarantined, with the overlap explanation visible

### Requirement: Urgent and recent work orders
The overview SHALL return up to five distinct released, non-cancelled PM/CM orders. Active overdue orders SHALL rank first, then other active URGENT orders, then remaining orders by creation recency. Rows SHALL expose ID, number, type, source, target, priority, actual status, dueAt, and isOverdue. Technician assignment SHALL NOT be required or returned.

#### Scenario: Stable urgent ranking
- **WHEN** multiple active orders are overdue
- **THEN** they sort by earliest dueAt, then priority URGENT/HIGH/MEDIUM/LOW, then newest createdAt and descending ID

#### Scenario: Quarantine target and archived history
- **WHEN** a selected WO refers to a quarantined sparepart or an archived pilot plant target
- **THEN** its appropriate target name/code remains visible and it is not excluded solely because the target was archived

### Requirement: Honest dashboard consumer states
The Home page SHALL use the overview response for all KPI values, charts, and table rows, without dummy fallback. It SHALL show initial loading, empty datasets, and a retryable initial failure distinctly. On refresh failure it SHALL retain the last successful data with a stale-data indication. Null compliance SHALL display an em dash with an explanation.

#### Scenario: Empty database
- **WHEN** the overview returns zero counts and empty datasets
- **THEN** the page shows zero operational counts, unavailable compliance, and empty chart/table states without fabricated rows

#### Scenario: Failed refresh
- **WHEN** a background refresh fails after a successful response
- **THEN** the previous data remains visible with a message that it could not be refreshed

### Requirement: Dashboard presentation scope
The dashboard SHALL remove calibration and Technician presentation, support URGENT priority and a separate overdue indicator, and identify both pilot plant and sparepart targets. Existing View all SHALL navigate to Maintenance. Labels SHALL distinguish monthly statistics from current counts and shall not claim a compliance target was met without a configured target.

#### Scenario: Existing dashboard becomes data driven
- **WHEN** the user opens Home
- **THEN** the existing four KPI cards, five chart areas, and WO table display the agreed data with no calibration series, technician column, new filter, or export feature

### Requirement: Read-only consistent overview
The overview SHALL read a consistent database snapshot using one captured asOf and SHALL NOT generate WO occurrences, create notifications, change approvals, or mutate stock. Aggregates SHALL cover all qualifying records rather than a paginated list. Planned occurrences not materialized as WOs SHALL be excluded and the PM scope SHALL be disclosed.

#### Scenario: Scheduler has not generated occurrences
- **WHEN** a plan has future or overdue projected occurrences without actual WO records
- **THEN** the dashboard excludes those projections, explains that PM metrics cover created WOs, and does not generate them

#### Scenario: Concurrent stock posting
- **WHEN** an inventory transaction commits during an overview request
- **THEN** the returned stock KPI and charts reflect one consistent snapshot rather than different sides of that transaction