# Spec Delta

## Purpose

Menyediakan laporan teknis periodik Maintenance dan Inventory yang dapat ditelusuri, difilter, dan diekspor berdasarkan data operasional tanpa perhitungan keuangan.

## ADDED Requirements

### Requirement: Authenticated read-only reporting
The system SHALL expose authenticated GET endpoints under /api/v1/reports for work-orders, corrective, inventory, compliance, and export-data to active application roles using existing response and error conventions. Reports SHALL NOT mutate business data or expose financial, technician-assignment, or calibration fields.

#### Scenario: Anonymous request
- **WHEN** an anonymous caller requests a report or export
- **THEN** authentication fails without returning report data

#### Scenario: Read without business effects
- **WHEN** an authenticated user requests reports
- **THEN** no WO, stock, approval, notification, or schedule record is changed

### Requirement: Period and query contract
Reports SHALL accept dateFrom/dateTo as inclusive facility-local calendar dates, resolve an exclusive next-day end, and return timezone, boundaries, generatedAt, and cutoff. Future-only or reversed ranges and ranges exceeding 366 days SHALL fail validation. Current periods SHALL stop at request time. Detail pagination SHALL default to 20 with a maximum of 100 and deterministic ordering.

#### Scenario: Local day boundary
- **WHEN** a report selects a single local date
- **THEN** records at its local start are included and records at the next local midnight are excluded

### Requirement: Historical interpretation
Reports SHALL reconstruct end-of-period completion and cancellation from recorded timestamps or status history, preserve archived targets, and disclose use of current target metadata and due dates. Reports SHALL NOT claim to be immutable historical snapshots. Unreleased WOs and legacy calibration SHALL be excluded.

#### Scenario: Completion after period
- **WHEN** a WO is released in September and completed in October
- **THEN** it remains backlog at the end of September and is not a September completion

#### Scenario: Later cancellation
- **WHEN** a WO is cancelled after the selected cutoff
- **THEN** that later cancellation does not remove it from backlog at the selected cutoff

### Requirement: Work order analysis
WO reports SHALL show creation and completion counts using their respective timestamps, backlog at cutoff, completion trend by PM/CM, and mean calendar duration for valid startedAt/completedAt pairs completed in the period. Detail rows SHALL identify their cohort and expose WO number, target, source, type, period status, dates, and duration. Source/type filters SHALL apply consistently.

#### Scenario: Invalid or missing duration
- **WHEN** a completed order lacks startedAt or has completedAt before startedAt
- **THEN** its completion is counted but its duration is excluded with an excluded-sample count; no valid samples yields null

### Requirement: Corrective analysis by target
Corrective reports SHALL count non-cancelled-at-cutoff CM WOs created within the period and group Pilot Plant by typed target ID and quarantine work by part ID. They SHALL show distinct targets, target ranking, completed subset at cutoff, and mean duration of valid completed cohort members. They SHALL label these as WO counts, not physical failures, and omit MTBF and downtime.

#### Scenario: Multiple quarantine cases for one SKU
- **WHEN** two corrective WOs refer to different quarantine cases for the same part
- **THEN** that part has two corrective WOs and one distinct target, regardless of quarantined quantity

### Requirement: Posted inventory activity
Inventory reports SHALL use postedAt for period membership and exclude unposted movements. They SHALL show original receipt/issue transaction counts, distinct issued SKUs, top ten issue frequencies, and per-SKU quantities for receipts, issues, returns, and signed physical corrections. Stored units SHALL remain explicit. Quarantine-only transfers SHALL NOT be classified as physical issues.

#### Scenario: Pending anonymous checkout
- **WHEN** a checkout is pending or rejected without postedAt
- **THEN** it contributes neither issue count nor issued quantity

#### Scenario: Mixed units
- **WHEN** matching parts use Pcs and Meter
- **THEN** quantities remain separated by unit and are not summed into a single total

### Requirement: Reversal period treatment
Reports SHALL preserve original posted activity in its original period and show linked reversal physical deltas as corrections in the reversal posting period. Reversals SHALL NOT count as new receipt/issue frequency. Scrap and other physical adjustments SHALL remain separately identifiable in correction details.

#### Scenario: Reversal next month
- **WHEN** an issue of five posts in September and its reversal posts in October
- **THEN** September shows five issued and October shows a positive-five reversal correction without inventing an October issue or receipt

### Requirement: On-time preventive compliance
Compliance SHALL use released PM due within the selected period and at or before cutoff, excluding cancellation effective by cutoff and missing deadlines. It SHALL classify eligible WOs as completed on time, completed late, unfinished, or unknown completion time. On-time percentage SHALL be numerator/eligible rounded to one decimal, or null for zero eligible WOs. Future projected occurrences SHALL NOT be generated or counted.

#### Scenario: Compliance example
- **WHEN** twenty eligible PMs include fifteen on-time, three late, and two unfinished
- **THEN** compliance is 75.0 percent and each category has its respective count

#### Scenario: Exact deadline and missing dates
- **WHEN** one eligible WO completes exactly at dueAt and another is completed without a recoverable completion timestamp
- **THEN** the first is on time and the second remains in the denominator as unknown, never silently on time

### Requirement: Overdue detail
PM details SHALL show dueAt, completion date, period result, and lateness. Late completion uses completion time and unfinished work uses cutoff. Lateness SHALL be elapsed calendar duration, not technician working time. Completion after cutoff SHALL be treated as unfinished at cutoff.

#### Scenario: Deadline not reached
- **WHEN** a released PM is due later in the current period
- **THEN** it is not yet eligible or overdue at the current cutoff

### Requirement: Report consumer and navigation
The Reports page SHALL provide four tabs named Analisis Work Order, Analisis Corrective, Pergerakan Inventory, and Kepatuhan PM with date presets/range, relevant filters, paginated details, and navigation to source features. It SHALL distinguish loading, empty, failed, and stale states without dummy fallback. Changed filters SHALL reset pagination and never label previous-filter data as current results.

#### Scenario: Replaced unsupported presentation
- **WHEN** Reports loads successfully
- **THEN** technician workload, estimated costs, stockout count, MTBF, downtime, failure-category dummy charts, and Audit labeling are absent

### Requirement: Complete consistent export
Excel SHALL include all four report tabs with rendered chart images and a Data Grafik worksheet containing their source datasets; PDF SHALL directly download screenshot-based KPIs, Recharts charts, and tables for all four tabs using react-to-pdf and bounded html2canvas captures. Both formats SHALL render charts from the export snapshot. Excel graphics are static images rather than editable native charts. Export SHALL capture all matching rows from one consistent read and one frozen filter set, independent of table page. Both formats SHALL show period, timezone, generation time, filters, and historical limitations. Empty datasets SHALL export successfully.

#### Scenario: Paginated screen
- **WHEN** there are 65 matching rows and page size is 20
- **THEN** export contains all 65 rows rather than the current 20

#### Scenario: Export limit
- **WHEN** the combined export would exceed 10000 detail rows
- **THEN** it fails with an actionable request to narrow the filters and never silently truncates

#### Scenario: Filter change during export
- **WHEN** filters change while an export request is running
- **THEN** the downloaded report consistently identifies the captured filters and does not mix datasets from the new selection


#### Scenario: Long chart or empty dataset
- **WHEN** a chart contains more equipment than fits in one printed section
- **THEN** it is split into readable sections with the same scale and no omitted rows
- **AND** empty charts show an explanatory message without failing the export

#### Scenario: Safe export labels
- **WHEN** a chart label contains XML markup characters
- **THEN** PDF and Excel render it as text without interpreting it as markup


#### Scenario: Capture without changing the visible page
- **WHEN** the user exports a report while viewing any tab or using a dark theme
- **THEN** the exporter captures the frozen snapshot in an isolated document using supported colors, waits for Recharts layout, and removes temporary elements on success or failure
- **AND** PDF downloads without a popup or browser print dialog

#### Scenario: Long table
- **WHEN** all matching rows span many pages
- **THEN** PDF captures measured batches with repeated column headers instead of allocating one unbounded canvas, and Excel retains numeric/raw cells