driver-vault/DriverVault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35e6c511b7ad7fb099ec506825ecb2de066e9085
DriverVault/API Server/README.md
T
tajniak81andClaude Opus 5 35e6c511b7 Changed parts: the list is the car's, not the app's 
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>
2026-08-22 23:30:08 +02:00

442 lines
23 KiB
Markdown
Raw Blame History

# DriverVault — API Server
The central API Server for the DriverVault project. Written in Go (standard
library only, module `drivervault/apiserver`). It is the **single gateway**
between all clients (web app, phone app, Home Assistant plugin, ESP32 device)
and the PocketBase database — **clients never talk to PocketBase directly**. The
API Server authenticates to PocketBase as a superuser and all collection access
rules are left null, so data is only reachable through this server.
It also serves the **superadmin web panel** at the server root (`/`).
## Layout
```
cmd/server/main.go # entry point
internal/
├── api/ # HTTP handlers + router (server.go)
│ ├── auth.go # PocketBase token proxy + role gates
│ ├── users.go # user management (role/org scoped)
│ ├── orgs.go # organization management
│ ├── settings.go # runtime PocketBase connection (pb-config)
│ ├── plugins.go # plugin management endpoints
│ ├── status.go # upstream health probes
│ ├── health.go respond.go panel.go
│ ├── cars.go records.go services.go parts.go shares.go me.go
│ ├── technical.go fuel.go charging.go maintenance.go documents.go
│ ├── reminders.go
│ ├── attachments.go # one optional file per record (shared handlers)
│ ├── integrations*.go # per-user Toyota / Anker Solix settings + OCPP control
│ └── dist/ # built panel, embedded via go:embed
├── config/config.go # env + .env load, .env write-back
├── models/models.go # domain types + derived-field computation
├── ocpp/ # OCPP 1.6J Central System (Anker Solix charging control)
├── pb/client.go # PocketBase superuser client (runtime-retargetable)
└── plugins/ # plugin system — see plugins/README.md
├── plugin.go manager.go external.go doc.go
└── builtin/ # built-in connectors: toyota, ankersolix
panel/ # Vue 3 + Tailwind panel source
scripts/ # Node/Python maintenance scripts
bin/api-server.exe # prebuilt binary the deployment runs
```
## Auth & access control
Authentication is **PocketBase's own**. `POST /api/auth/login` is proxied to the
PocketBase users collection and the client keeps the token PocketBase minted;
this server does not issue its own JWT. Every protected request re-resolves that
token against PocketBase (`auth-refresh`), so a role change or a deletion takes
effect **immediately** rather than lingering until a token expires.
```
POST /api/auth/login { "email": "...", "password": "..." } -> PocketBase { token, record }
GET /api/auth/me (Authorization: <token>) -> { id, email, name, role }
GET /api/identity (Authorization: <token>) -> + organization
```
Both `Authorization: Bearer <token>` and a raw `Authorization: <token>` are
accepted (PocketBase's own SDKs send the latter).
### Roles
`users.role` is `user` | `admin` | `superadmin` (empty is treated as `user`).
| Role | Can |
|---|---|
| **user** | their own cars, service records, parts, profile |
| **admin** | the above, plus manage users **within their own organization** |
| **superadmin** | everything, across all organizations, plus the PocketBase connection and plugins |
Guards worth knowing: an admin cannot create or edit a superadmin, cannot move
users between organizations, and nobody can change their own role or delete
their own account. An organization cannot be deleted while it still has members.
### Organizations
`organizations` is the tenant collection; `users.organization` is the
membership. A superadmin spans all organizations; an admin is scoped by the
server to their own. Users may have no organization at all.
Creating one is self-service: any user who does not already belong to an
organization may `POST /api/orgs`, and becomes that organization's **admin** and
first member in the same request (if the promotion fails the new organization is
rolled back, so it is never left with nobody able to administer it). A user who
already belongs to one is refused — membership is a single relation, so creating
a second would mean silently abandoning the first.
A superadmin is the exception: they create organizations without joining them,
since they already span every tenant.
From there an admin manages **their own** organization — rename it, or delete it
once they are its only member. Deleting it detaches and demotes them back to a
plain `user` before the record is removed, so the organization is empty when it
goes. A superadmin may rename or delete any organization, but still only once it
has no members at all.
### Per-user car ownership + sharing
Cars are not a global list. `cars.owner` marks ownership and `car_shares` grants
other users `read` or `write` access. Every car/service/part handler is gated by
`requireCarAccess`:
- **read** — view the car, its service records and parts.
- **write** — edit the car and full service/part CRUD.
- **owner only** — delete the car and manage its shares.
## Data model
| Collection | Purpose | Key fields |
|---|---|---|
| `cars` | one per car | name, make, model, year, registration, `registrationCountry`, vin, `fuelType`, `buildDate`, `firstRegistrationDate`, `currentKm`, `serviceIntervalDays` (365), `serviceIntervalKm` (15000), `technicalCheckIntervalDays` (365), `oilSpec`, `transmissionOilSpec`, `differentialOilSpec`, `brakeFluidSpec`, `coolantSpec`, `owner` |
| `service_records` | the service log | car, date, km, changed_oil, changed_engine_air_filter, changed_cabin_air_filter, notes |
| `technical_checks` | roadworthiness inspections (przegląd techniczny / MOT / TÜV) | car, date, `result` (passed \| failed), cost, station, `valid_until`, notes |
| `parts` | per-car parts catalog | car, name, part_number, category, notes |
| `fuel_entries` | refuelling log (efficiency derived on read) | car, date, km, liters, cost, `full_tank`, `missed_fill`, station, notes |
| `charging_sessions` | EV charging log, the same shape as the refuelling one (kWh/100km derived on read) | car, date, km, kwh, cost, `full_charge`, `missed_session`, location, notes |
| `maintenance_entries` | workshop visits & repairs (outside routine service) | car, date, km, type, status, workshop, parts_used, labor_cost, parts_cost, invoice_number, warranty_until, notes |
| `car_documents` | paperwork (insurance, registration, road tax, …) | car, type, title, provider, reference, issue_date, expiry_date, cost, notes |
| `reminders` | date/odometer reminders (some auto-derived) | car, title, type, due_date, due_km, repeat_days, repeat_km, done, done_at, notes |
| `car_shares` | grants another user access to a car | car, user, `permission` (read \| write) |
| `organizations` | tenants | name (unique) |
| `control_audit` | OCPP control-command audit trail | user, charger, action, result, timestamp |
| `users` | login + profile (built-in auth collection) | name, email, avatar, `role` (user \| admin \| superadmin), `organization`, bio, theme, locale, date_format, currency, font_size, deletion_requested_at |
Every record collection except `car_shares` / `organizations` / `control_audit`
carries **one optional file attachment**, served only through the API Server
(`GET /api/{records}/{id}/file`) — never a public PocketBase URL.
**Spreadsheet formulas** (from the original `Car Service.xlsx`), reproduced by
the API on read:
```
Next Service Date = service date + serviceIntervalDays (Excel: =A+365)
Next Service Km = service km + serviceIntervalKm (Excel: =B+15000)
```
These come back on each service record as `nextServiceDate` / `nextServiceKm`.
## Endpoints
```
# public
GET /healthz
GET /api/health
GET /api/status # health of PocketBase + Web App, probed server-side
POST /api/auth/login
GET /api/auth/validate
# identity
GET /api/auth/me
GET /api/identity
# current user (profile / appearance / drag lock / garage order / avatar / data /
# account lifecycle)
GET /api/me PATCH /api/me DELETE /api/me
POST /api/me/password
POST /api/me/avatar GET /api/me/avatar DELETE /api/me/avatar
POST /api/me/verify/request
GET /api/me/export POST /api/me/import
POST /api/me/delete POST /api/me/delete/cancel
# users + organizations (admin or superadmin; POST /api/orgs is open to any user)
GET /api/users POST /api/users
PATCH /api/users/{id} DELETE /api/users/{id}
GET /api/orgs POST /api/orgs
PATCH /api/orgs/{id} DELETE /api/orgs/{id}
# superadmin — connection + plugin management
GET /api/admin/pb-config PUT /api/admin/pb-config POST /api/admin/pb-config/test
GET /api/admin/webapp-config PUT /api/admin/webapp-config POST /api/admin/webapp-config/test
GET /api/admin/server-config PUT /api/admin/server-config
GET /api/admin/plugins POST /api/admin/plugins
GET /api/admin/plugins/{name} PUT /api/admin/plugins/{name}
DELETE /api/admin/plugins/{name} POST /api/admin/plugins/{name}/health
# integrations (per-user plugin settings; superadmin → org admin → user cascade)
GET /api/integrations/toyota PUT /api/integrations/toyota POST /api/integrations/toyota/health
GET /api/integrations/toyota/vehicles
GET /api/integrations/anker-solix PUT /api/integrations/anker-solix POST /api/integrations/anker-solix/health
GET /api/integrations/anker-solix/chargers
# Anker Solix OCPP charging control (own/proxy mode + a live CSMS session)
GET /api/integrations/anker-solix/chargers/{sn}/control
POST /api/integrations/anker-solix/chargers/{sn}/control/token
DELETE /api/integrations/anker-solix/chargers/{sn}/control/token
POST /api/integrations/anker-solix/chargers/{sn}/{action}
GET /ocpp/{serial} # charger dials in here (OCPP Basic auth, not bearer)
# vehicle providers — create a car from a manufacturer service; per-car provider tab
GET /api/vehicle-providers
GET /api/vehicle-providers/{provider}/vehicles
POST /api/vehicle-providers/{provider}/import
# cars + sharing (GET /api/cars returns the garage in the user's saved order,
# which PATCH /api/me {carOrder} sets)
GET /api/cars POST /api/cars
GET /api/cars/{id} PATCH /api/cars/{id} DELETE /api/cars/{id}
PUT /api/cars/{id}/view # which tabs, Information rows, service-history
# columns and service parts this car shows, and the
# order of the tabs, the rows, the columns and the
# provider readings
GET /api/cars/{id}/provider POST /api/cars/{id}/provider
POST /api/cars/{id}/provider/sync
GET /api/cars/{id}/service-records GET /api/cars/{id}/technical-checks
GET /api/cars/{id}/parts GET /api/cars/{id}/fuel-entries GET /api/cars/{id}/fuel-stats
GET /api/cars/{id}/charging-sessions GET /api/cars/{id}/charging-stats
GET /api/cars/{id}/maintenance GET /api/cars/{id}/documents GET /api/cars/{id}/reminders
GET /api/cars/{id}/shares POST /api/cars/{id}/shares DELETE /api/cars/{id}/shares/{userId}
# per-record collections — each is GET(list) POST / GET PATCH DELETE {id}
/api/service-records /api/technical-checks /api/parts
/api/fuel-entries /api/charging-sessions /api/maintenance
/api/car-documents
/api/reminders (+ POST /api/reminders/{id}/complete)
# attachments — one optional file per record, on every collection that takes one.
# {records} = car-documents | service-records | technical-checks | maintenance
# | fuel-entries | charging-sessions | parts
POST /api/{records}/{id}/file GET /api/{records}/{id}/file DELETE /api/{records}/{id}/file
```
`GET /api/cars` returns the caller's owned cars plus any shared with them, each
annotated with an `access` field. The per-record list endpoints also accept a
`?car={id}` filter (e.g. `GET /api/service-records?car={id}`).
> **Gotcha:** `updateCar` rewrites **all** car columns from the payload, so a
> `PATCH /api/cars/{id}` must send the **full** car object — omitted spec fields
> get blanked. (The phone's odometer quick-edit sends the whole car for this
> reason.) The two exceptions are `owner` and the provider link (`provider`,
> `provider_vehicle_id`), which `carPayload` deliberately leaves out so an
> ordinary edit can neither reassign the car nor break its connected service.
### Vehicle providers
`internal/api/vehicleproviders.go` turns a manufacturer-service plugin into a car
you can create from your own account with that service, plus a per-car tab showing
everything the service currently knows about it. Toyota (MyToyota) is the first
provider; adding the next one means writing a `vehicleSource` adapter and
appending it to `vehicleSources()` — no new endpoints and no Web App changes.
Two properties shape the design:
- **Credentials are always the caller's.** Every provider call resolves through
the same global → org → user cascade as the integration settings, so a car
shared with someone else shows them provider data only when that vehicle is on
*their* manufacturer account. The owner's credentials are never borrowed.
- **Upstream shapes are not modelled.** These are unofficial APIs. Rather than
hard-coding field paths, the layer searches payloads by key name for the handful
of readings worth promoting (odometer, fuel, battery, range) and flattens the
rest to dotted key/value pairs, shipping the raw payload alongside. A renamed
field costs one blank value instead of a broken page.
`POST .../import` takes `{vehicleId, name?, include?}`, where `include` selects
which groups to pull (`identity`, `fuelType`, `dates`, `odometer`). Omitting it
means "everything available". `POST /api/cars/{id}/provider/sync` takes the same
selection, and only ever moves the odometer forward — a reading that appears to go
backwards is a stale provider, not a car driven in reverse.
## The panel (`/`)
A Vue 3 + Tailwind app (source in `panel/`, built into `internal/api/dist` and
embedded at compile time). It is the superadmin console:
- **Overview** — live health of the API Server, PocketBase and the Web App.
- **Users / Organizations** — full management, scoped to the caller's role.
- **PocketBase** — retarget the database connection at runtime; test before
saving. Applied immediately **and** persisted to `.env`, so it survives a
restart. This is the escape hatch when the configured PocketBase is wrong or
unreachable — the settings endpoints deliberately do **not** require a working
service account.
- **Plugins** — enable/disable/configure integrations, run health checks,
register external plugins.
- **API** — the endpoint reference.
Log in with any DriverVault account; the sections you see depend on your role.
```powershell
cd panel
npm install
npm run dev # localhost:5174, proxies /api to localhost:8080
npm run build # -> ../internal/api/dist (then rebuild the Go binary)
```
Editing panel source alone does nothing to the served panel — run `npm run build`
and then rebuild the Go binary, since `dist` is embedded.
## Plugins
An extension system for integrating third-party services, managed by a
superadmin. Two kinds share one contract: **built-in** (Go, compiled in) and
**external** (any HTTP service, registered at runtime, **no rebuild**). Enable
state and global config persist to PocketBase, in the `app_settings` singleton —
the same place the per-org and per-user layers of the cascade live.
See **[`internal/plugins/README.md`](internal/plugins/README.md)** for the full
guide. Two built-in connectors ship today — **Toyota Connected** (`toyota`,
read-only MyToyota vehicle data) and the **Anker Solix** V1 EV charger
(`anker-solix`) — and any number of external HTTP plugins can be registered at
runtime with no rebuild.
### Integrations & charging control
Beyond the superadmin plugin registry, the built-in connectors are exposed
per-user through `/api/integrations/*` under a **superadmin → org admin → user**
cascade (each layer supplies defaults the next can override). For Anker Solix
chargers the server additionally runs an **OCPP 1.6J Central System**
(`internal/ocpp`): when the owner sets a control mode of own/proxy, the charger
dials back in at `GET /ocpp/{serial}` (authenticated with OCPP Basic auth using a
per-charger control token, not a bearer token) and the owner can start/stop and
set charge limits, with every command rate-limited and written to a
`control_audit` trail.
## Configuration
Copy `.env.example` to `.env` and fill in. Summary:
| Variable | Default | Purpose |
|---|---|---|
| `API_ADDR` | `:8080` | listen address (bare port accepted) |
| `POCKETBASE_URL` | `http://10.2.1.10:8027` | PocketBase base URL |
| `POCKETBASE_ADMIN_EMAIL` / `_PASSWORD` | — | superuser service account |
| `CORS_ALLOW_ORIGINS` | `*` | comma-separated browser origins |
| `WEBAPP_URL` | `http://localhost:8090` | probed by `/api/status` |
| `AUTH_USERS_COLLECTION` | `users` | PocketBase auth collection |
| `OCPP_REQUIRE_TLS` | `true` | reject chargers that did not connect over TLS |
| `OCPP_PUBLIC_URL` | — | canonical `ws(s)://` base to point chargers at |
| `PB_BOOTSTRAP` | `true` | run the on-boot schema create/reconcile (leave on across upgrades) |
| `DRIVERVAULT_SUPERADMIN_EMAIL` / `_PASSWORD` / `_NAME` | — / — / `Administrator` | first `superadmin`, created on boot when absent |
`PB_URL`, `PB_ADMIN_EMAIL`, `PB_ADMIN_PASSWORD`, `PORT` and `CORS_ORIGINS` are
still honoured for older deployments; the modern names win when both are set.
The server keeps **no state on disk**: plugin settings, like everything else it
owns, live in PocketBase. A `.env` in the working directory is read at startup as
a local-development convenience, and the panel writes back to it when a
superadmin retargets PocketBase or the Web App — but in Docker there is no volume
behind it, so those two screens apply for the life of the container only. Set the
environment variables to change them permanently; see [`Dockerfile`](Dockerfile)
and [`../Docker`](../Docker).
`CORS_ALLOW_ORIGINS` only matters for **browser** clients (the web app). Native
mobile apps are not subject to CORS.
The service account is **optional at startup**: without it the server still runs
and a superadmin can log in and configure it from the panel, while management
endpoints return 503.
## Scripts (`scripts/`)
```powershell
node scripts/setup-pocketbase.mjs # create/reconcile collections (idempotent)
node scripts/create-user.mjs <email> <pw> "Name" # create an app login
node scripts/set-role.mjs <email> user|admin|superadmin
node scripts/backfill-car-owners.mjs # one-off: assign owner to legacy cars
python scripts/seed_from_excel.py "C:/Users/jania/Desktop/Car Service.xlsx"
```
The Node scripts read `POCKETBASE_URL` / `POCKETBASE_ADMIN_EMAIL` /
`POCKETBASE_ADMIN_PASSWORD` (or the legacy `PB_*` names) from the environment.
> **PocketBase note:** collections created by the setup script do **not** get
> automatic `created`/`updated` autodate fields in this PocketBase version —
> sorting on `created` fails unless an explicit `F.autodate(...)` is added. When
> adding a new car spec field, extend `DESIRED.cars` in `setup-pocketbase.mjs`,
> add it to `models.Car` + the record mapping in `records.go`, then rebuild.
> **Startup bootstrap:** the server also runs this same create/reconcile on boot
> (`internal/bootstrap`, a Go mirror of `setup-pocketbase.mjs`) whenever a service
> account is configured, so the Docker prod stack needs no manual setup step. It
> is idempotent and gated by `PB_BOOTSTRAP` (default `true`; set to `false` to
> skip). With `DRIVERVAULT_SUPERADMIN_EMAIL` + `DRIVERVAULT_SUPERADMIN_PASSWORD`
> set it also creates the first `superadmin` user when absent. **Keep the two
> schemas in sync:** a change to `DESIRED` in the script must be mirrored in
> `internal/bootstrap/schema.go` (guarded by `TestSchemaConsistency`).
## First-time setup
1. **Create the PocketBase collections** (idempotent — safe to re-run on an
existing deployment; it adds `organizations`, `users.organization`, and grows
`users.role` to include `superadmin`):
```powershell
$env:POCKETBASE_URL="http://10.2.1.10:8027"
$env:POCKETBASE_ADMIN_EMAIL="you@example.com"
$env:POCKETBASE_ADMIN_PASSWORD="secret"
node scripts/setup-pocketbase.mjs
```
2. **Mint the first superadmin.** The panel's management screens need one, and
only a superadmin can promote another — so the first has to come from the
script:
```powershell
node scripts/create-user.mjs admin@example.com "a-long-password" "Admin"
node scripts/set-role.mjs admin@example.com superadmin
```
3. **Run the server** — `go run ./cmd/server`, or build and run the binary.
4. **Open the panel** at `http://localhost:8080/` and sign in.
5. **(Optional) Seed from the spreadsheet** with the server running (see scripts).
## Build & run
```powershell
go build -o bin/api-server.exe ./cmd/server
```
The deployment runs the **prebuilt binary** `bin/api-server.exe` (not `go run`),
started detached so it survives the shell:
```powershell
Start-Process -FilePath ".\bin\api-server.exe" -WorkingDirectory "." `
-WindowStyle Hidden -RedirectStandardOutput api-server.out.log `
-RedirectStandardError api-server.err.log
```
Go's `log` package writes to **stderr**, so check `api-server.err.log` for
request logs and errors. After editing any Go source, rebuild and restart the
process — editing source alone does nothing until the binary is rebuilt.
## Migrating from the JWT build
Earlier builds minted their own HS256 JWT and tracked a `sessions` collection
for "active devices" / remote logout. That is gone — the server now relays
PocketBase tokens. Consequences:
- **`AUTH_SECRET` is obsolete** and ignored.
- **Login returns PocketBase's envelope** — `{token, record}`, not `{token, user}`.
- **`GET|DELETE /api/sessions*` are gone.** PocketBase tokens are stateless, so
there is nothing to revoke per-device. To lock every device out of an account,
change its password: PocketBase rotates the user's token key, which
invalidates every token already issued.
- **User management moved** from `/api/admin/users*` to `/api/users*`, and the
separate password-reset endpoint folded into `PATCH /api/users/{id}`
(`{"password": "..."}`). Responses are enveloped: `{users}` / `{user}`.
- **Existing tokens are invalid** — every client must log in once more.
- The `sessions` collection is left in PocketBase rather than dropped; delete it
by hand if you want it gone.
The Web App and Phone App in this repo are already updated for all of the above.
Reference in New Issue View Git Blame Copy Permalink