tajniak81andClaude Opus 5
a2d9efec7e
The previous commit left the car screen half translated: its tab labels went
through t(), and everything underneath them did not. A Polish user opening a
car got translated tabs over English tiles, English forms and English
dialogs, which is worse than either extreme because it reads as a bug rather
than as a missing translation.
So the whole screen and everything it opens now reads from the language
files: the record tiles, the share and delete-car dialogs, the service and
part sheets it hosts, record_form_sheets.dart, car_form_sheet.dart, and the
attachment field whose buttons surface inside all of them.
Almost none of these strings are new. The Web App has said all of this in
three languages since b6bb6b1, so forms.*, enums.*, attachment.* and errors.*
are copied out of its language files the same way car.* was, and Polish and
Danish arrive complete. What is written here is only what the phone alone
needs, and the categories are worth naming because they are the reason the
two apps' files are not identical: tooltips, because the web labels its
buttons; the tiles' running prose, because the web lays the same data out as
table columns; client-side validation, because the web leans on the browser's
`required`; and the snackbars.
Three things changed shape rather than just wording.
The per-record delete prompts were one template with a noun slotted in -
"Delete this $what?" - which does not survive translation into a language
that inflects the noun. Each collection now names its own confirmation
string, which is what the web already had.
The delete-car dialog counted with a hand-rolled `"$n $noun${n == 1 ? '' :
's'}"`. Polish has three plural forms, so that could not be translated at
all; it now goes through the CLDR plurals in car.delete.*. It also only ever
named service records and parts, while the cascade takes maintenance, fuel,
charges and documents too - the translated body names all six, so it is now
passed the whole data set rather than two counts.
The enum labels (fuel types, maintenance type/status, document and reminder
types) were four const maps duplicated between the tiles and the pickers.
They are one lookup against enums.* now, with an unknown value falling back
to the raw key rather than a blank - the server owns that enum, and a value
added there should stay legible in an app that has not caught up.
Found and fixed while testing: the view picker rendered the literal string
"car.tabs.provider" as a row label on an unlinked car. That key does not
exist by design - a linked car's tab is named after the service, an unlinked
one falls back to car.tabs.connected - and the picker was the one caller that
did not know it.
Verified by flutter analyze (clean), flutter test - 19 pass, 7 of them new -
and flutter build apk --debug. The new tests cover what the analyzer cannot
see: the lookups built from a key at render time (car.tabs.$key,
enums.fuelType.$v, the delete dialog's plural counts, the connected service's
readings) are checked to have a real label in all three languages, so a
catalogue entry with no translation fails a test instead of reaching a screen
as a raw key path. That is the check that caught the bug above. A one-off
script also confirmed all 550 static t() keys resolve in en.json.
Not verified: still nothing run against a live API Server or on a device.
Known gaps, deliberately left: admin_users_screen.dart is still English, and
settings.integrations.* / charging.control.* exist in en.json only. The
second one is not the phone's alone - the Web App has exactly the same gap,
so translating that OCPP and connector vocabulary belongs to both apps in one
pass rather than letting the phone run ahead of the app the strings are
copied from. Both are now recorded in TRANSLATIONS.md, which had claimed the
car screen as untranslated and the web app as complete.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
199 lines
12 KiB
Markdown
199 lines
12 KiB
Markdown
# DriverVault — Phone App (Flutter)
|
||
|
||
A Flutter client for the DriverVault maintenance tracker. Talks **only** to the
|
||
API Server (same contract and auth as the web app — a PocketBase token relayed by
|
||
the server, not a JWT the server mints). At full feature parity with the web app.
|
||
|
||
Project name `drivervault_phone`, package id `com.drivervault.phoneapp`.
|
||
**Android is the supported target** — the older Flutter-web build path is
|
||
deprecated.
|
||
|
||
## Features
|
||
|
||
Once signed in, `RootShell` hosts the app behind a persistent **bottom
|
||
navigation bar** — Garage, Charging, Settings, and Users for admins — in an
|
||
`IndexedStack`, so each section keeps its state as you switch tabs.
|
||
|
||
- **Login** — email/password against `/api/auth/login`, password show/hide, and a
|
||
collapsible **Server settings** section to override the API base URL on-device.
|
||
- **Biometric / face sign-in + app lock** — see the dedicated section below.
|
||
- **Garage (dashboard)** — car list with next-due status badges (date + km,
|
||
worst-of), a "shared" chip on cars owned by someone else, pull-to-refresh and
|
||
an **Add car** FAB.
|
||
- **Car detail** — all spec fields (incl. VIN and transmission / differential /
|
||
brake / coolant specs), a **share** sheet (owner only), quick odometer update,
|
||
edit car, and delete car (type-to-confirm; cascades). Actions are gated by the
|
||
caller's access level (read-only vs write vs owner).
|
||
|
||
**Which tabs a car shows, and in what order, belongs to the car** — the same
|
||
arrangement the web app reads, so everyone it is shared with sees the same
|
||
page. Edit it under the **tune** icon: switch tabs and Information rows on or
|
||
off, and drag either list by its handle to reorder it. (The web rearranges by
|
||
dragging the tab bar itself; on a touch screen that gesture is the tab bar's,
|
||
so both arrangements are made in the picker instead.) Information cannot be
|
||
switched off — a page with no tabs left would be a dead end — but it can be
|
||
moved. The tabs, in their default order:
|
||
- **Connected service** — everything the manufacturer's own app knows about
|
||
this car, read live under *your* account: headline readings (odometer, fuel
|
||
or battery, range, charging state, position), the vehicle record, and one
|
||
card per capability the plugin exposes, rendered from the server's flattened
|
||
key/value pairs so a provider adding a field surfaces it without an app
|
||
change. Offers to take the provider's odometer when it is ahead of the
|
||
stored one. A car with no link yet gets a **connect** card instead, and the
|
||
tab is hidden entirely for a user with no manufacturer account connected.
|
||
Because the read runs under your own credentials, a car shared from someone
|
||
else shows data here only if that vehicle is on your account too — it says
|
||
so rather than failing.
|
||
- **Service history** — date/odometer plus which parts were changed, with the
|
||
next-due date/km derived by the server.
|
||
- **Technical check history** — the mandatory roadworthiness inspections
|
||
(przegląd techniczny, MOT, TÜV). Result, cost, station, and the certificate's
|
||
valid-until, which overrides the car's interval when present. A failed check
|
||
derives no next date.
|
||
- **Maintenance** — workshop visits and repairs outside the routine schedule:
|
||
type/status, workshop, parts used, labour + parts cost, invoice number and a
|
||
warranty-until badge.
|
||
- **Fuel** — refills with a summary panel (average / best / worst consumption,
|
||
cost per km, price per litre). Consumption is measured between full tanks, so
|
||
partial fills roll into the next full one and a flagged missed fill leaves its
|
||
window uncomputed rather than reporting a fictional figure.
|
||
- **Charging cost** — charges with a summary panel (average / best / worst
|
||
kWh/100km, cost per km, price per kWh). The electric twin of Fuel, and
|
||
derived the same way: consumption is measured between full charges, so a
|
||
top-up rolls into the next full one. Distinct from the **Charging** section
|
||
in the bottom bar, which is the charger network and OCPP control.
|
||
- **Documents** — insurance, registration, road tax and the rest, with a
|
||
renewal badge driven by the server's expiry assessment.
|
||
- **Parts catalog** — the per-car parts list.
|
||
- **Reminders** — date- and/or odometer-triggered, one-off or recurring, with a
|
||
**Mark done** action. Reminders the server derived from a document or service
|
||
record are shown read-only.
|
||
- **Attachments** — one optional file per service record, technical check,
|
||
workshop visit, refill, charge, document and part (PDF or image, up to 10MB). Picked
|
||
with `file_picker`, fetched back through the API Server — never a public URL —
|
||
and opened with the phone's own viewer via `open_filex`.
|
||
- **Charging** — mirrors the web `Charging.vue`, split into two tabs. **Public**
|
||
is a discovery map with a demo session and nearby stations: presentational
|
||
placeholders, because there is no public-charging API yet (same as the web).
|
||
**Home** carries the one real piece — an OCPP control card that drives your
|
||
own charger through the Anker Solix control endpoints, once you pick Own/Proxy
|
||
CSMS under Settings → Integrations.
|
||
- **Settings** — account (name / email verification / password), appearance
|
||
(theme + dark mode, **language**, **region**, date format, **currency**, font
|
||
size), profile (avatar via `image_picker`, bio), **integrations** (Toyota,
|
||
Anker Solix), **Security** (biometric toggle), **Organization** (create your
|
||
own — which makes you its admin — or rename/delete the one you administer),
|
||
**data export/import**, and the account-deletion state machine. Export writes
|
||
the account JSON into the app's own documents directory and offers to open it;
|
||
import picks a previously exported file and always creates new records, so it
|
||
asks first, with the number of cars the file actually holds. Auth relays PocketBase's own stateless
|
||
tokens, so there is no per-device session list to show or revoke.
|
||
- **Users (admin)** — user management tab (list / create / role / reset password
|
||
/ delete), shown only for the admin role.
|
||
|
||
Sharing/ownership: `Car.access` drives `isOwner` / `canWrite` / `isReadOnly`
|
||
getters that gate the UI, mirroring the server's access checks.
|
||
|
||
## Language, region & currency
|
||
|
||
Language and region are two pickers over the one stored BCP-47 tag (`en-US`), so
|
||
the pair can be mixed — English in Poland, say. Currency is display-only: nothing
|
||
is converted, so changing it reinterprets existing amounts rather than
|
||
recalculating them. All three lists mirror the API's (`validCurrencies` and the
|
||
locale pattern in `internal/api/me.go`), with two deliberate differences from the
|
||
web app:
|
||
|
||
- **Luxembourgish (`lb`) and Romansh (`rm`) are not offered.** `intl` ships no
|
||
date/number symbols for them and *throws* rather than falling back, which would
|
||
take out every date on screen. The browser has full ICU data behind it and has
|
||
no such limit, so the web app can list them.
|
||
- **Labels are hand-kept** (endonyms for languages, English for regions and
|
||
currencies) because Dart has no `Intl.DisplayNames`.
|
||
|
||
Because the server only validates a locale's *shape* (`^[a-z]{2}-[A-Z]{2}$`), a
|
||
tag the phone cannot render can still arrive from the web. `format.dart` resolves
|
||
through a supported-language check and falls back to `en-US` instead of throwing;
|
||
`test/models_format_test.dart` covers it.
|
||
|
||
The car screen and every sheet it opens read their text from the language files.
|
||
What is left in English is the **admin users** screen, and the Integrations and
|
||
charger-control strings — the latter being a gap the web app shares, so it
|
||
belongs to both apps at once. See [TRANSLATIONS.md](../TRANSLATIONS.md).
|
||
|
||
## Biometric / face sign-in & app lock
|
||
|
||
Fingerprint and face-recognition sign-in via `local_auth`, with credentials kept
|
||
in Android Keystore–backed secure storage (`flutter_secure_storage`).
|
||
|
||
- After a successful password login the app offers to **enable biometric login**;
|
||
the entered (known-good) credentials are stored securely.
|
||
- The login screen then shows **"Sign in with face recognition / fingerprint"**
|
||
buttons (labels reflect the enrolled biometric kinds) and auto-prompts once.
|
||
On success the stored credentials are replayed against the normal login API, so
|
||
each biometric sign-in mints a fresh session. Stale credentials (e.g. after a
|
||
password change) auto-disable biometric login.
|
||
- **App lock** — the token persists, so a valid session normally restores silently.
|
||
When biometric login is enabled the app instead starts **locked** (and re-locks
|
||
when backgrounded) and shows a lock screen requiring a biometric unlock. A
|
||
**30-second grace period** means quick app-switches don't re-lock; a full app
|
||
close (process kill) always locks on next launch. "Use password instead" on the
|
||
lock screen logs out and returns to the login form.
|
||
- Manage it under **Settings → Security** (enabling re-confirms the password).
|
||
|
||
Android host requirements (already configured, don't revert):
|
||
`MainActivity` extends **`FlutterFragmentActivity`** (required by `local_auth`),
|
||
and `AndroidManifest.xml` declares `android.permission.USE_BIOMETRIC`.
|
||
|
||
## Configure the API endpoint
|
||
|
||
The app talks to `kDefaultApiBase` (see `lib/config.dart`), default
|
||
`http://localhost:8080/api`. Override at build time with `--dart-define`, or at
|
||
runtime from the login screen's **Server settings** (persisted as `cc_server_url`).
|
||
|
||
## Run & build
|
||
|
||
```bash
|
||
flutter pub get
|
||
|
||
# run on a connected device against a LAN server
|
||
flutter run -d <device> --dart-define=API_BASE=http://10.2.1.101:8080/api
|
||
|
||
# build a debug APK for a real phone on the LAN
|
||
flutter build apk --debug --dart-define=API_BASE=http://10.2.1.101:8080/api
|
||
adb install -r build/app/outputs/flutter-apk/app-debug.apk
|
||
adb shell monkey -p com.drivervault.phoneapp -c android.intent.category.LAUNCHER 1
|
||
```
|
||
|
||
Notes:
|
||
- `android/gradle.properties` sets `kotlin.incremental=false` — required because
|
||
the project lives on drive `E:` while Gradle/Kotlin caches are on `C:` (the
|
||
incremental compiler can't compute cross-root relative paths on Windows).
|
||
- `AndroidManifest.xml` sets `android:usesCleartextTraffic="true"` because the API
|
||
base is a plain-HTTP LAN URL.
|
||
- The API Server must be running and reachable at the configured URL.
|
||
|
||
## Structure
|
||
|
||
```
|
||
lib/
|
||
├── config.dart # default API base URL (kDefaultApiBase)
|
||
├── models.dart # Car (+ access getters), the record types, integrations, profile
|
||
├── api.dart # ApiClient — the only thing that calls the API Server
|
||
├── auth.dart # AuthService (token persistence, app-lock flag, ChangeNotifier)
|
||
├── biometric.dart # BiometricAuth — local_auth + secure storage; biometricAuth singleton
|
||
├── app_settings.dart # AppSettings (theme/locale/date/font), persisted; drives MaterialApp
|
||
├── i18n.dart # translation lookup — t("key"); en/pl/da with en fallback
|
||
├── theme.dart # shared colours/tones (status badges, charging tiles)
|
||
├── format.dart # date/km formatting + next-service status (worst-of date/km)
|
||
├── main.dart # app root; routes Login / Lock / RootShell; lifecycle re-lock
|
||
├── widgets/
|
||
│ └── attachment_field.dart # pick / view / clear a record's attached file
|
||
└── screens/
|
||
├── root_shell.dart # bottom-nav shell: Garage, Charging, Settings, Users
|
||
├── login_screen.dart lock_screen.dart dashboard_screen.dart
|
||
├── car_detail_screen.dart car_form_sheet.dart record_form_sheets.dart
|
||
├── car_view_sheet.dart # which tabs/rows a car shows + the key catalogue
|
||
├── provider_tab.dart # the connected-service tab (MyToyota)
|
||
└── charging_screen.dart settings_screen.dart admin_users_screen.dart
|
||
```
|