HC_APTBS/CLAUDE.md

# HC_APTBS

## What this is
WPF desktop application (.NET 10 / x64) that controls a VP44 diesel injection pump test bench.
- Reads/writes bench sensors (temperature, RPM, flow) via CAN bus (PCAN-Basic, 500 kbps)
- Communicates with the pump ECU via K-Line/KWP2000 (FTDI USB adapter, 9600 bps)
- Runs automated multi-phase test sequences with PID temperature control
- Generates PDF test reports (QuestPDF)
- Supports Ford VP44 immobilizer unlock via CAN (Types 1 & 2)

## Build
Windows only, .NET 10 x64. `dotnet build -r win-x64` from solution root. SDK pinned in `global.json`. No WSL/Linux — native DLLs (`PCANBasic.dll`, `ftd2xx.dll`) are x64 Windows binaries. No test project; validation is code review + manual hardware testing.

## Stack
- C# / .NET 10, WPF, XAML
- CommunityToolkit.Mvvm: `[ObservableProperty]`, `[RelayCommand]`
- Microsoft.Extensions.DependencyInjection / Hosting for bootstrap
- QuestPDF 2025.3.2 (requires `LicenseType.Community` in constructor)
- LiveChartsCore.SkiaSharpView.WPF 2.0.0-rc3.5 for real-time charts
- Extended.Wpf.Toolkit 4.6.1 (AvalonDock, NumericUpDown, BusyIndicator)
- Native DLLs in output: `PCANBasic.dll`, `ftd2xx.dll` (x64 only)

## Architecture
```
Infrastructure/
  Pcan/PcanBasic.cs          — Vendor P/Invoke file. NEVER modify.
  Pcan/PcanAdapter.cs        — CAN read thread, OEM legitimation, frame decode, IIR filter, liveness tracking
  Kwp/FtdiInterface.cs       — FTDI D2XX wrapper (manual LoadLibrary, not NativeLibrary.Load)
  Kwp/KwpCommon.cs           — 5-baud slow-init, complement-ACK byte I/O
  Kwp/KW1281Connection.cs    — KWP/KW1281 protocol state machine
  Kwp/Packets/               — 10 packet types (Ack, Nak, FaultCodes, Eeprom R/W, Custom, etc.)
  Logging/AppLogger.cs       — Daily rotating log files (ERR/WAR/MSG/DBG)

Services/
  ICanService.cs             — CAN bus abstraction (parameter map, frame routing, liveness)
  IBenchService.cs           — Test orchestration, RPM/temp control, relay control
  IKwpService.cs             — K-Line ECU diagnostics (keep-alive, EEPROM, DTCs, DFI)
  IUnlockService.cs          — Ford VP44 immobilizer unlock state machine
  IConfigurationService.cs   — XML persistence for all config files
  ICalibrationService.cs     — Sensor calibration operations
  IPdfService.cs             — PDF test report generation
  IAutoTestOrchestrator.cs   — Dashboard "Connect & Auto Test" state machine (K-Line → read → unlock → bench on → test)

Services/Impl/
  BenchService.cs            — Test orchestration, temperature PID, relay control (background Task)
  BenchPidController.cs      — Discrete-time PID for RPM ramp (derivative-on-measurement, anti-windup)
  KwpService.cs              — All KWP operations; persistent session with keep-alive loop
  UnlockService.cs           — Ford unlock: 600.5s Phase 1 + TestUnlock Phase 2 + verification
  ConfigurationService.cs    — XML persistence for pumps, bench, config, clients, sensors, alarms, status
  CalibrationService.cs      — Sensor calibration
  PdfService.cs              — QuestPDF report generation (multi-page, charts, verdict)
  ReportChartRenderer.cs     — SVG chart rendering for PDF tolerance-band visualizations
  ReportTheme.cs             — Report styling constants
  AutoTestOrchestrator.cs    — Linear auto-test sequence; E-stops past TurningOnBench, aborts cleanly before

Models/
  CanBusParameter.cs         — CAN parameter model + BenchParameterNames/PumpParameterNames/KlineKeys constants
  BenchConfiguration.cs      — Bench config + embedded AppSettings (PID, timers, safety limits)
  PumpDefinition.cs          — Pump model, CAN params, tests, K-Line data
  TestDefinition.cs          — Test type + phase list + tolerance evaluation
  PhaseDefinition.cs         — Phase readies/sends/receives/results
  TestParameter.cs           — Measurement point (name, value, tolerance)
  TestResult.cs              — Accumulated result with samples and pass/fail evaluation
  MeasurementSample.cs       — Single timestamped measurement
  SensorConfiguration.cs     — ADC calibration (voltage → engineering units)
  Relay.cs                   — Relay output + RotationDirection/EncoderMode/BaudrateSelection constants
  Alarm.cs                   — Alarm condition (bit, description, criticality, active state)
  PumpStatusDefinition.cs    — Status word bit definitions with color-coded states
  RpmVoltageRelation.cs      — RPM → voltage lookup table entry
  KLineConnectionState.cs    — K-Line session state enum

Converters/
  BoolToPassFailBrushConverter.cs
  HexColorToBrushConverter.cs

ViewModels/                  — [ObservableProperty] / [RelayCommand], no UI logic
  MainViewModel.cs           — Central orchestrator, event marshalling, child VMs
  PumpIdentificationViewModel.cs — Pump selection + K-Line ECU read
  DfiManageViewModel.cs      — DFI calibration read/write/auto-adjust
  TestPanelViewModel.cs      — Test suite management (phase enable/disable)
  TestDisplayViewModel.cs    — Current test execution progress
  ResultDisplayViewModel.cs  — Test result table (per-phase pass/fail)
  PumpControlViewModel.cs    — Manual pump control sliders (ME, FBKW, PreIn)
  BenchControlViewModel.cs   — Bench control (rotation, RPM ramp, oil pump)
  FlowmeterChartViewModel.cs — Real-time flowmeter charts
  AngleDisplayViewModel.cs   — Encoder angle monitoring (PSG, INJ, Manual, Lock Angle)
  StatusDisplayViewModel.cs  — Pump status word display
  Dialogs/                   — KlineErrors, OilPumpConfirm, Progress, Report, RpmSafetyWarning,
                               Settings, UnlockProgress, UserCheck, VoltageWarning ViewModels

Views/
  MainWindow.xaml            — Root UI (multi-panel layout)
  Dialogs/                   — KlineErrorsDialog, OilPumpConfirmDialog, ProgressDialog,
                               ReportDialog, RpmSafetyWarningDialog, SettingsDialog,
                               UnlockProgressDialog, UserCheckDialog, VoltageWarningDialog
  UserControls/              — AngleDisplay, BenchParamConfig, DfiManage, FlowmeterChart,
                               PumpControl, PumpIdentification, ResultDisplay, StatusDisplay,
                               TestDisplay, TestPanel
```

## Configuration files
All XML files stored in `%UserProfile%\.HC_APTBS\config\`:

| File | Purpose |
|------|---------|
| `config.xml` | Global settings: temp limits, PID tuning, refresh rates, safety limits, encoder, motor, company info, K-Line port, language, users, RPM-voltage relations |
| `pumps.xml` | Pump database: per-pump identity, CAN parameters (P1–P6 legacy), test definitions with phases |
| `bench.xml` | Bench CAN parameters (Factor/Offset model) + relay definitions. Embedded default fallback in code |
| `sensors.xml` | ADC sensor calibrations (channel → voltage → engineering units) |
| `clients.xml` | Client/operator directory (name → contact) |
| `alarms.xml` | Alarm definitions (bit position, description, criticality) |
| `status.xml` | Pump status word bit definitions with color-coded states |

## Constants quick reference
Defined in `Models/CanBusParameter.cs`:
- `BenchParameterNames` — RPM, Counter, BaudRate, BenchTemp, T-in, T-out, T4, QDelivery, QOver, Alarms, Pressure, AnalogSensor2, encoders (PSG/INJ/Manual)
- `PumpParameterNames` — me, FBKW, mepi, RPM, Temp, Tein, MemoryRequest, TestUnlock, TestImmo, Status, Empf3
- `KlineKeys` — pumpID, SerialNumber, ModelReference, DFI, ErrorCodes, SWV1, SWV2, PumpControl, DataRecord, result
- `RelayNames` — Electronic, OilPump, DepositCooler, DepositHeater, Counter, Direction, TinCooler, Pulse4Signal, Flasher (in `Models/Relay.cs`)

## Rules for all edits

**Always:**
- Read the file before editing it
- Keep XML doc comments on all public types and members
- Use `BenchParameterNames` / `PumpParameterNames` / `KlineKeys` / `RelayNames` constants — no magic strings
- Marshal to the UI thread when consuming `IBenchService` or `IKwpService` events (they fire on background threads)
- Use `CultureInfo.InvariantCulture` when parsing/formatting doubles in XML (avoid locale bugs)
- Log skipped or malformed XML elements — never silently swallow parse failures
- New bench parameters must use Factor/Offset calibration, not P1–P6 (legacy model is for pump params only)

**Never:**
- Modify `Infrastructure/Pcan/PcanBasic.cs` (vendor file, intentionally untouched)
- Modify anything under `old_source/` (archived reference only)
- Add logic to View code-behind files
- Add `Thread.Sleep`, allocations, or logging inside the per-byte K-Line loops in `KwpCommon`/`KW1281Connection`

## Protocol constants
Do not change without knowing why. Use `/protocol-ref` skill for full reference including DFI encoding, IIR filter, OEM legitimation, and K-Line timing.

## Conventions
- ViewModels in `/ViewModels`, Views in `/Views`, Models in `/Models`
- Async methods use `Async` suffix
- Commit format: `feat:`, `fix:`, `refactor:` (conventional commits)
- Git remote: self-hosted Gitea at 192.168.8.130

## Known gaps (from old_source comparison)
See `docs/` guidelines for full specs. Priority: CRITICAL > HIGH > MEDIUM > LOW.

**CRITICAL:**
- No config XML validation — malformed files silently produce partial/default state

**HIGH — Missing safety features:**
- No QOver zero-flow safety check (old: emergency stop if QOver==0 while RPM>300 + oil pump on)
- Alarm bit collection during tests not wired up (`PhaseDefinition.RecordErrorBit` never called)
- No per-sample real-time UI callback during measurement (old fired per-sample events for live charts)
- Pump parameters (ME/FBKW/PreIn) not zeroed between test phases

**HIGH — Missing features:**
- No encryption (old encrypted user passwords with AES-256 + pump data with Rijndael; new stores plaintext)
- No KlineIDs auto-mapping (old remembered K-Line ID → pump ID associations)

**MEDIUM — Missing UI components:**
- WConfigPanel (full settings dialog)
- WUsersManage (user CRUD — only auth dialog exists)
- KlineIDSelection (COM port selection for K-Line)
- BitDisplay / SingleBit (bit-level status toggles)
- TimerDisplay (test timer/countdown)
- FilteredComboBox (searchable dropdown)
- PDF report observations/notes section missing from interface

**LOW:**
- 4ms PeriodicTimer may fire at ~15ms on Windows (old MultimediaTimer had ~1ms precision)
- Sensor calibration divide-by-zero when MaxVolt==MinVolt (no guard)
- P1–P6 transfer function can produce Infinity/NaN (no denominator check)
- CAN parameter byteh/bytel not bounds-checked to 0–7

## Known debt
Do not worsen before addressing deliberately. See memory file `project_known_debt.md` for details.

Additional debt items:
- `KW1281Connection` allocates `List<byte>` per packet — GC pressure under long K-Line sessions
- `PcanAdapter.DrainMessageQueue` polls with `Thread.Sleep(2)` — hardcoded, was configurable in old
- No unit tests exist yet
- Users stored as plaintext `user:password` in config.xml
- Config file format has no version tracking or migration logic
- Pump ID uniqueness not enforced on load
- `ParseEcuText()` depends on exact spacing format (fragile)
- AppSettings properties have no bounds validation (timer intervals, safety limits)
- `SaveSettings()` triggers `SaveSensors()` + `SaveClients()` as side effects

## CFG/pump data migration
The old system had 32 CFG files defining pump-specific data NOT present in the new XML model:
- Status bit **reaction codes** (0=none, 1=abort, 2=warning, 3=log) — controlled test flow on errors
- **BIP-STATUS** definitions (needle-motion detection) — absent from new system entirely
- **Diagnostic RAM addresses** (solenoid timing, temperature compensation, learning procedures)
- **Flow regulator sensitivity parameters** (measurement time adjustment, tolerance, FM sensitivity)
- **EEPROM/EPROM/RAM passwords** per pump family
- **CAN-BUS-KENNUNG** protocol variant code (0/1/2/6/10) — derived implicitly in new code
See `docs/gap-pump-data-migration.md` for migration field mapping.