# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

SteUP is an Integry .NET MAUI Blazor Hybrid app for field inspections ("ispezioni") of retail stores — the operator scans product barcodes (including via Honeywell handheld scanners), fills in inspection sheets ("schede"), attaches photos, and syncs with the Integry backend. Work is stored locally (offline-first via SQLite) and pushed to the server. The same Blazor UI also runs as a standalone WebAssembly app.

> Note: `README.md` is the leftover Microsoft sample template and does NOT describe this app. Ignore it.

## Design Context

For any UI/design work, read **`PRODUCT.md`** (strategy) and **`DESIGN.md`** (visual system) at the repo root first; they are the source of truth for the impeccable design skill.

- **Register:** product (a field tool; the UI serves the task, it is not a marketing surface).
- **Users:** field inspectors ("rilevatori") in stores — one-handed / gloved, outdoors in sunlight, often offline.
- **North Star:** "Il taccuino da campo" — works like paper and ink: always, offline, readable in full sun.
- **Core principles:** offline state is never ambiguous · thumb-first (touch ≥44px) · high contrast for sunlight · immediate feedback per scan · fewer steps, fewer errors.
- **Visual system:** MudBlazor · single font **Nunito** · accent `#ec4c41` (Arancio-Rosso Allerta, action/state only), anchor `#002339` (Blu Profondo) · rounded (9px/20px/1em) · locale `it-IT`.
- **Anti-references:** no dated/dense back-office look; no playful consumer-social aesthetic.

## Build & run

`global.json` pins SDK 8.0.0 with `rollForward: latestMajor`, but all projects target **.NET 10** (MAUI targets `net10.0-android` / `net10.0-ios`). A .NET 10 SDK must be installed.

NuGet restores from a **private Integry feed only** (`NuGet.Config` clears nuget.org and uses `nuget.studioml.it`). The `IntegryApiClient.*` packages come from there.

```bash
# MAUI app (primary target) — Android
dotnet build SteUp.Maui/SteUp.Maui.csproj -t:Run -f net10.0-android

# MAUI app — iOS (requires Mac build host; codesigning wired in csproj)
dotnet build SteUp.Maui/SteUp.Maui.csproj -f net10.0-ios

# Web (Blazor WASM) app
dotnet run --project SteUp.Web/SteUp.Web.csproj
```

There is **no test project** in the solution. There is no lint config beyond `Nullable`/`ImplicitUsings` enabled per csproj.

## Projects (5)

- **SteUp.Shared** — Razor Class Library holding almost everything: all Blazor pages/components, DTOs, entities, enums, the auth state provider, API service wrappers, messaging, and business orchestration (`SteupDataService`). Both MAUI and Web reference it. Uses MudBlazor + MudExtensions for UI.
- **SteUp.Maui** — the native host. Owns platform services (DI registration in `Core/CoreModule.cs`), the `BlazorWebView` host (`MainPage.xaml.cs`), file/logging/network/scanner implementations, and app config.
- **SteUp.Web** — Blazor WebAssembly host of the same shared UI. Its `Program.cs` mirrors a subset of the MAUI DI setup.
- **SteUp.Data** — EF Core + SQLite local database (`AppDbContext`, migrations, `IspezioniService`). References Shared for the entity types.
- **Steup.HoneywellScanner** — Android-only binding library wrapping Honeywell `DataCollection.aar`. Referenced by MAUI only on the Android target.

## Architecture

### Interface / implementation split (important convention)
Interfaces live in **SteUp.Shared** (`Core/Interface/...`) so the shared UI depends only on abstractions. Concrete platform implementations live in **SteUp.Maui** (`Core/Services`, `Core/System`) and are registered per-host:
- MAUI wires everything in `SteUp.Maui/Core/CoreModule.cs` via `Register*` extension methods called from `MauiProgram.cs`.
- Web wires a smaller subset directly in `SteUp.Web/Program.cs` (only `IFormFactor` + auth; it has no local DB, scanner, or file manager).

When adding a service consumed by the shared UI: define the interface in `SteUp.Shared/Core/Interface`, implement it in the host, and register it in **both** `CoreModule.cs` and (if the Web app needs it) `Program.cs`.

### Auth
`AppAuthenticationStateProvider` (Shared) bridges Integry's `IUserSession`/`IUserAccountService` (from `IntegryApiClient`) to Blazor's `AuthenticationStateProvider`, building `ClaimsPrincipal` from the JWT. Both hosts call `builder.UseIntegry(appToken, useLoginAzienda: true)` — the `AppToken` is the same GUID in `MauiProgram.cs` and `SteUp.Web/Program.cs`.

### Backend calls
Two service wrappers over `IIntegryApiRestClient`:
- `IntegrySteupService` — the app-specific `steup/*` endpoints (retrieve punti vendita, reparti, griglia PLU, barcode lookup, save/complete/delete schede, upload attachments).
- `IntegryApiService` — generic Integry endpoints (system health, activity descriptions, email).

### Offline-first data flow
`SteupDataService` (Shared) is the orchestrator: on `Init()` it runs EF migrations (`DbInitializer.InitializeAsync` → `db.Database.MigrateAsync()`), loads reference data from the API, reconciles inspection status, and prunes closed inspections older than 60 days. Local reads/writes go through `IspezioniService` (SteUp.Data).

### Local DB model
`AppDbContext`: `Ispezione` → `Scheda` → `SchedaArticolo`. `Ispezione` has a **composite key** `(CodMdep, Data, Rilevatore)` which is also the FK from `Scheda`. `Scheda.ImageNames` is a `List<string>` persisted as JSON via a value converter. DB file: `steup_db.db3` in `FileSystem.AppDataDirectory` (see `DbPathProvider`).

Add a migration (from repo root; `AppDbContextFactory` provides the design-time context using a throwaway `design-time.db3`):
```bash
dotnet ef migrations add <Name> --project SteUp.Data
```
Migrations are applied automatically at app startup, not via `database update`.

### Messaging (in-app events)
Uses `CommunityToolkit.Mvvm` `WeakReferenceMessenger`. Singleton "services" in `Shared/Core/Messages` (`NewSchedaService`, `OnScannerService`, `CompleteInspectionService`) publish/relay messages that decouple the barcode scanner and page components.

### Barcode scanning
`IBarcodeReaderService` is implemented by `HoneywellScannerService` (MAUI, partial class with Android-specific parts + the Honeywell binding lib). `IBarcodeManager`/`BarcodeManager` (Shared) is the host-agnostic front the UI talks to. Scans flow to the UI through the messaging services above.

### Attached images
Photos are served into the `BlazorWebView` through a custom scheme: `MainPage.xaml.cs` intercepts `WebResourceRequested` for `https://localfiles/attached/<file>` and streams files from `CacheDirectory/attached` (with path-traversal guards).

## Error tracking
Sentry is configured in both hosts (`.UseSentry(...)` in MAUI, Sentry package in Shared). MAUI also has a `GlobalExceptionHandler` (registered in `App.xaml.cs`) and a `FileLogger`/`FileLoggerProvider` writing to `AppDataDirectory/logs`.

## Versioning
App version lives in `SteUp.Maui.csproj` (`ApplicationDisplayVersion` + `ApplicationVersion`). Commit messages track releases (e.g. "-> v1.0.2 (3)"). Bump both when releasing. `ApplicationId` is `it.integry.SteUp`.