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