HC_APTBS/docs/ui-structure.md

# HC_APTBS — UI Structure Reference

Defines the top-level page structure, operator intent, content scope, and design
guidelines for each page. Use this as the authoritative reference when designing
or implementing any page or UserControl.

---

## Guiding principles

- **Operator intent first.** Navigation reflects what the operator is trying to
  accomplish, not which components exist or which service owns a feature.
- **Separation of concerns.** Bench hardware and ECU diagnostics are logically
  different domains and live on different pages — never mix them.
- **Progressive disclosure.** Dashboard is read-first. Controls deepen as the
  operator navigates inward. Settings are last and guarded.
- **State-driven flow.** The Test page is not a free-form panel — it guides the
  operator through a linear sequence: Plan → Preconditions → Running → Done.
- **Safety is visible.** Alarms, interlocks, and precondition failures are
  surfaced prominently, never hidden in status bars or tooltips.

---

## Navigation layout

```
┌──────┬─────────────────────────────────────────┐
│      │                                         │
│  ⌂   │  PAGE CONTENT                           │
│  ⚙B  │                                         │
│  ⚡E  │                                         │
│  ▶T  │                                         │
│  ■R  │                                         │
│  ──  │                                         │
│  ⚙S  │                                         │
└──────┴─────────────────────────────────────────┘
```

Left sidebar, icon + label, collapsed to icon-only below a width threshold.
Settings pinned to the bottom, separated by a divider.

Global status bar at the top of the content area (not the sidebar):
CAN heartbeat indicator · K-Line session indicator · alarm count badge ·
logged-in user · app version.

---

## Pages

### 1. Dashboard

**Intent:** Confirm the bench is ready before doing anything.

**Design tone:** Read-first. Dense information, minimal interaction. Should be
readable at a glance from across the workbench.

**Content:**

| Section | Detail |
|---------|--------|
| Bench state | RPM (live), T-in, T-out, T-tank, P1, P2, QDelivery |
| Connection status | CAN: last frame timestamp / "offline"; K-Line: session open / closed |
| Active alarms | List with criticality badge (critical / warning / info). Empty state = green banner. |
| Test summary | Active test name + current phase, or last completed test name + overall pass/fail |
| Quick actions | **Start Test** (→ Test page), **Stop**, **Emergency Stop** |

**Guidelines:**
- E-Stop is the only destructive control allowed here. Style it as red, always
  visible, never hidden by scroll.
- No configuration inputs on this page.
- Alarm list shows the full description text, not just a bit number.
- Offline indicators use a distinct color (e.g. amber) separate from alarm red.
- Quick-action buttons are disabled with a tooltip when prerequisites are unmet
  (e.g. Start Test disabled if no pump selected or CAN offline).

**Existing components to embed:** none — this page is new.

---

### 2. Bench

**Intent:** Manually drive the hardware. Feels like an HMI panel.

**Design tone:** Control-heavy, tactile. Large inputs, clear feedback, live
values always visible alongside their controls.

**Content:**

| Group | Controls / Displays |
|-------|---------------------|
| RPM / Drive | Target RPM input, ramp rate, Start/Stop drive, direction toggle |
| Temperature | T-in / T-out / T-tank live readings, cooler relay, heater relay, PID setpoint |
| Pressure / Flow | P1, P2 live gauges, QDelivery, QOver, oil pump relay |
| Encoder / Angle | PSG, INJ, Manual angle live displays, Lock Angle input |
| Relay outputs | DepositCooler, DepositHeater, Counter, Pulse4Signal, Flasher — toggle buttons with state indicator |
| Live plots | Flowmeter chart (QDelivery, QOver vs time), pressure trace — always rendering |

**Guidelines:**
- No ECU concepts on this page (no ME, FBKW, DFI, K-Line).
- Relay buttons must show current state (on/off) as well as the toggle action.
- Live plots persist while the operator adjusts controls — they are not
  collapsible or tab-hidden.
- RPM input should warn (not block) if above configured safety limit
  (`AppSettings.MaxRpm`).
- Oil pump interlock: if oil pump relay is off and RPM > threshold, show
  a dismissible inline warning (not a blocking dialog).

**Existing components to embed:**
- `BenchControlView` (RPM, direction, oil pump)
- `BenchParamConfigView` (bench parameter live readings)
- `FlowmeterChartView` (always-on in manual context)
- `AngleDisplayView` (encoder monitoring)

---

### 3. ECU

**Intent:** Diagnose and interact with the pump's electronic control unit via
K-Line. Logically separate from the mechanical bench.

**Design tone:** Diagnostic tool. Tabular data, structured forms, raw values
accessible but not leading.

**Sub-sections (tabs or left sub-nav within the page):**

#### 3a. Identification
- Pump model search/select from database
- K-Line read: serial number, model reference, SW version
- BIP status
- "Read ECU" button — requires K-Line session open

#### 3b. DTCs
- Fault code list (code, description, freeze-frame if available)
- Read DTCs / Clear DTCs actions
- Error history log with timestamps

#### 3c. Live Data
- ECU variable table: ME, FBKW, Temp, Tein, Status word
- Status word bit grid (bit index, label, state, color-coded per
  `PumpStatusDefinition`)
- Refresh rate selector

#### 3d. Adaptation
- ME / FBKW / PreIn sliders (manual ECU output control)
- DFI read / write / auto-adjust
- Requires user authentication before write actions

#### 3e. Unlock *(Ford VP44 only)*
- Unlock type selector (Type 1 / Type 2)
- Phase 1 countdown (600.5 s) with progress bar
- Phase 2 TestUnlock with live status
- Verification result display
- Full UI spec in `docs/gap-ford-unlock-ui.md`

**Guidelines:**
- K-Line session state (open / closed) is always shown at the top of this page.
  If closed, write actions are disabled with a "Session not open" tooltip.
- Adaptation and Unlock sub-sections require authenticated user
  (`UserCheckDialog`).
- Raw K-Line bytes are shown only in a collapsible "Engineering" panel — not
  in the primary view.
- Pump selection (3a) is a prerequisite for everything else. If no pump is
  selected, show a banner on all other sub-sections.

**Existing components to embed:**
- `PumpIdentificationView` → 3a
- `StatusDisplayView` → 3c
- `DfiManageView` → 3d
- `PumpControlView` (ME/FBKW/PreIn) → 3d

---

### 4. Test

**Intent:** Run the automated test procedure. Procedural and task-oriented.

**Design tone:** Wizard-like linear flow. The operator should always know where
they are in the sequence and what comes next.

**State machine — sub-sections are sequential, not freely navigable:**

```
[Plan]  ──►  [Preconditions]  ──►  [Running]  ──►  [Done]
              (blocked if           (blocked         (summary,
               checklist             until all        → Results)
               fails)                checks pass)
```

#### 4a. Plan
- Test suite dropdown (selects from pump's `TestDefinition` list)
- Phase list: enable/disable individual phases, view tolerance bands
- Estimated duration
- "Next: Check Preconditions" button

#### 4b. Preconditions
Enforced checklist before the sequence starts. Each item is checked
automatically where possible, or confirmed manually:

| Check | Source |
|-------|--------|
| Pump selected | ECU page — pump DB record loaded |
| CAN bus live | `PcanAdapter` heartbeat |
| K-Line session open | `KwpService` state |
| RPM = 0 | `BenchParameterNames.RPM` |
| Oil pump on | Relay state |
| No critical alarms | Alarm list |
| User authenticated | If test requires auth |

Start button is disabled until all required checks pass. Failed checks
show inline fix links (e.g. "Go to Bench → start oil pump").

#### 4c. Running
- Phase timeline: vertical step list, current phase highlighted
- Live measurement table: parameter, current value, tolerance band, pass/fail
- Embedded: `FlowmeterChartView` + `AngleDisplayView` (visible during run)
- Controls: **Pause**, **Abort**, **Retry current phase**, **Skip phase**
- Running timer (elapsed + estimated remaining)

#### 4d. Done
- Inline summary: overall pass/fail, phase-by-phase verdict
- "View Full Results" → navigates to Results page
- "Run Again" → back to 4a (Plan) with same configuration

**Guidelines:**
- Back-navigation within the state machine is allowed (Plan ↔ Preconditions)
  but not once Running has started unless the test is aborted.
- Abort requires confirmation dialog.
- QOver zero-flow safety: if `QOver == 0` while RPM > 300 and oil pump is on,
  trigger emergency stop and display a blocking alert (see Known gaps in
  CLAUDE.md — HIGH priority).
- Pump parameters (ME/FBKW/PreIn) must be zeroed between phases
  (see Known gaps — HIGH priority).
- Per-sample real-time UI callback must update the live measurement table
  during Running (see Known gaps — HIGH priority).

**Existing components to embed:**
- `TestPanelView` → 4a (Plan)
- `TestDisplayView` → 4c (Running)
- `FlowmeterChartView` → 4c (Running, inline)
- `AngleDisplayView` → 4c (Running, inline)
- `ResultDisplayView` → 4d (Done, summary) + Results page (full)

---

### 5. Results

**Intent:** Review, compare, and document completed tests.

**Design tone:** Data-focused. Clean tables, exportable. No live hardware data.

**Content:**

| Section | Detail |
|---------|--------|
| History list | Completed tests: date, pump model, serial, overall pass/fail |
| Result detail | Selected test: per-phase table, per-parameter pass/fail, measured vs tolerance |
| Trend / comparison | Same pump over multiple runs — delta on key parameters (future) |
| Report preview | PDF rendered inline or in a preview pane |
| Export | PDF export, notes/observations field before export |

**Guidelines:**
- History is read-only. No controls that affect the bench or ECU.
- PDF export requires a report dialog (operator name, client, notes) before
  generating. Reuse `ReportDialog` / `ReportViewModel`.
- Observations/notes field must be present before PDF generation
  (see Known gaps in CLAUDE.md — MEDIUM priority).
- Empty state (no completed tests this session): show a prompt to run a test.
- Test history persistence across sessions requires a future storage layer
  (not yet implemented — scope to session-only for now).

**Existing components to embed:**
- `ResultDisplayView` (full detail view)
- `ReportDialog` (triggered by Export action)

---

### 6. Settings

**Intent:** Infrequent configuration. Not for daily operators unless necessary.

**Design tone:** Form-based. Grouped, labeled, validated. No live hardware
data visible here.

**Sub-sections:**

| Section | Content |
|---------|---------|
| Machine | CAN bitrate, K-Line COM port, encoder mode, motor direction |
| Sensors | ADC calibration per channel (min/max voltage → engineering units) |
| Limits & Protection | Safety RPM max, alarm criticality reactions, PID tuning constants |
| Alarms | Alarm bit definitions, descriptions, criticality levels |
| Users | User list, roles, password management (future: hashed) |
| Report | Company name, logo, branding colors, default template |
| Storage | Config file paths, backup/restore |

**Guidelines:**
- Changes are not applied until "Save" is clicked — no live-apply side effects.
- Sensor calibration changes require confirmation (affects all future readings).
- User management (`UserManageDialog`) is accessible from here.
- Settings are not accessible while a test is Running (nav item disabled or
  shows a "test in progress" tooltip).
- All inputs use `CultureInfo.InvariantCulture` for double parsing (see Rules
  in CLAUDE.md).

**Existing components to embed:**
- `SettingsDialog` content (migrate from dialog to full page)
- `DfiManageView` is in ECU > Adaptation, not here

---

## Component placement summary

| UserControl / Dialog | Page | Sub-section |
|----------------------|------|-------------|
| `BenchControlView` | Bench | RPM / Drive + Relays |
| `BenchParamConfigView` | Bench | Pressure / Flow readings |
| `FlowmeterChartView` | Bench (manual) · Test (running) | Live plots · 4c Running |
| `AngleDisplayView` | Bench · Test (running) | Encoder group · 4c Running |
| `PumpIdentificationView` | ECU | 3a Identification |
| `StatusDisplayView` | ECU | 3c Live Data |
| `DfiManageView` | ECU | 3d Adaptation |
| `PumpControlView` | ECU | 3d Adaptation |
| `TestPanelView` | Test | 4a Plan |
| `TestDisplayView` | Test | 4c Running |
| `ResultDisplayView` | Test (summary) · Results (full) | 4d Done · detail view |
| `ReportDialog` | Results | Export action |
| `UserCheckDialog` | ECU (auth gate) · Test (auth gate) | on write actions |
| `UserManageDialog` | Settings | Users sub-section |
| `KlineErrorsDialog` | ECU | triggered on DTC read errors |
| `ProgressDialog` | ECU · Test | long K-Line operations, unlock phase |
| `UnlockProgressDialog` | ECU | 3e Unlock |
| `OilPumpConfirmDialog` | Bench · Test (preconditions) | oil pump interlock |
| `RpmSafetyWarningDialog` | Bench · Test | RPM limit breach |
| `VoltageWarningDialog` | Bench | analog sensor out of range |

---

## Pages to build (status)

| Page | Status | Notes |
|------|--------|-------|
| Dashboard | **Not started** | New page, new ViewModel |
| Bench | `BenchPage.xaml` exists | Expand with live plots, angle view |
| ECU | `PumpPage.xaml` exists | Rename, add sub-sections 3b–3e |
| Test | `TestsPage.xaml` exists | Add preconditions state machine |
| Results | **Not started** | New page, new ViewModel |
| Settings | Partial (`SettingsDialog`) | Migrate from dialog to full page |