tajniak81andClaude Opus 5
35e6c511b7
The Changed parts section offered all three parts to every car. An EV changes no
oil, and a checkbox nobody will ever tick is one more thing to read past on every
service — so which parts a car records now belongs to the car, the same way its
tabs, its Information rows and its Service history columns already do.
It works the way those three do because a fourth mechanism for the same idea
would be a fourth to keep in step: hidden_service_parts on the car, validated by
the endpoint that already does this, stored as the hidden set so a part added in
a later release is on by default, and needing write access because the choice
belongs to the car and everyone it is shared with sees it.
There is no order beside it, which is the one place this departs from the other
three. Those arrange things whose position means something — a tab bar reads left
to right, a table's columns are read across. The parts are a checkbox list inside
a single column, and moving Cabin air filter above Oil says nothing. Adding one
later is the same shape as the others if that turns out to be wrong.
A part switched off leaves the form and the history together — the chips on the
phone's cards, the web column's summary and the panel it opens. "I don't record
this" means it stops taking up room, not that it takes up room saying nothing,
which is the rule a hidden column already follows. That is the judgment call
here: a car with five years of oil changes hides them all by switching the part
off. Nothing is written to the records, so switching it back on brings every one
of those chips back, which is what makes the call safe to reverse.
The part that would have been a silent data bug: the API rewrites all three
booleans from the body of a service update, so a form that simply stopped
sending a hidden part would set it false on the next edit of any old record.
Both forms therefore keep every part in their state and submit every one — only
the checkboxes are filtered. The mirror of that is a *new* record, where a hidden
part starts false rather than at its `initial`, since ticking a box nobody was
shown is not a default, it's a guess. Oil is the only part with initial: true, so
that case is live the moment anyone hides it.
Verified: go vet and go test ./... pass, with a new test covering that every part
is hideable (unlike the tabs and the columns — a service that changed nothing is
a real service), that the "parts" column key is refused as a part key and a part
key as a column key, and that no part is also a column. flutter analyze is clean
and flutter test passes 32 to 35, the new ones covering visibleParts, that a
hidden part's chips go while its stored boolean stays, and the picker's fourth
section. npm run build is clean.
Both apps were driven against throwaway stub APIs. Web: the picker saved
{"hiddenServiceParts":["oil"]}, the table's parts cell went from "Oil & Oil
filter +2" to "Engine air filter, Cabin air filter", the record whose only part
was oil went to an empty cell, the panel dropped to two rows, the add form
offered two unticked boxes where oil's initial: true would have ticked one, and
editing the three-part record sent changedOil:true back with a box that was never
on screen. Phone: the same car rendered chips "Engine air, Cabin air", "Changed
parts —" for the oil-only record, and an add sheet with exactly two unticked
boxes.
Not verified: no automated test guards the web behaviour — the web app still has
no test runner, so the above was read out of the live DOM and the outgoing
request bodies by hand. The phone's picker was checked by widget test and by
rendering, but its Save was not driven end to end. Neither app was run against
the real API Server: bootstrap appends the new field on the next start, and until
that start a client sending hiddenServiceParts takes a 400 — they deploy together
from this repo, but the server must go first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
220 lines
13 KiB
Markdown
220 lines
13 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, Information rows, Service
|
||
history columns and the parts a service can change on or off, and drag any of
|
||
the first three lists by its handle to reorder it. (The parts have no order —
|
||
they are a checkbox list inside one column, and their position says nothing a
|
||
tab's or a column's does.) (The web rearranges by dragging the tab bar and the
|
||
column headings themselves; on a touch screen those gestures belong to the tab
|
||
bar and the scroll, so every arrangement is made in the picker instead.) Two
|
||
things cannot be switched off: Information — a page with no tabs left would be
|
||
a dead end — and the service Date, since a history with the day taken out
|
||
stops being one. Both can still 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. The web lays those out as table
|
||
columns; a phone has no width for a seven-column table, so a card renders the
|
||
same columns as pieces — consecutive short ones share a wrapping line, and
|
||
the parts, the notes and the file each take a line of their own. It reads the
|
||
car's own hidden set and order, so a column switched off on either app is off
|
||
on both, and the arrangement decides the grouping: move Notes between Km and
|
||
Next date and the short columns split around it. Every part a service can
|
||
have changed shares the one **parts** column — they are a growing list, and a
|
||
column apiece would widen the web's table without end — and both that column
|
||
and the form's Changed parts section come from `lib/service_parts.dart`, the
|
||
twin of the web's `lib/serviceParts.js`. Which of them this car records is
|
||
the car's own choice as well: a part switched off leaves the form's
|
||
checkboxes and the cards' chips together, and nothing is written to the
|
||
records, so switching it back on brings the old chips back.
|
||
- **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. A blocked control says why rather
|
||
than only greying out: long-press a locked role picker, and the overflow menu
|
||
carries the reason under the action. Superadmins also choose which
|
||
organization a new account lands in (or none at all); an admin gets no picker,
|
||
because the server puts their members in their own organization regardless.
|
||
|
||
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.
|
||
|
||
Every screen reads its text from the language files, and `flutter test` fails if
|
||
a key exists in English but not in Polish or Danish. 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)
|
||
├── service_parts.dart # the parts a service can change, in one list
|
||
├── 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/columns a car shows + the catalogues
|
||
├── provider_tab.dart # the connected-service tab (MyToyota)
|
||
└── charging_screen.dart settings_screen.dart admin_users_screen.dart
|
||
```
|