pleno-vue/README.md

# truckwashdashboardsfrontend

This template should help get you started developing with Vue 3 in Vite.

## Recommended IDE Setup

[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).

## Customize configuration

See [Vite Configuration Reference](https://vite.dev/config/).

## Project Setup

```sh
npm install
```

## Contributing Changes

Create a scoped feature branch, push it, and open a pull request targeting
`master`. Do not push directly to `master`. Merge only after the `Required CI`
check succeeds, all review conversations are resolved, and the branch is up to
date. Use squash merge so `master` retains linear history.

See [`.github/BRANCH_PROTECTION.md`](.github/BRANCH_PROTECTION.md) for the
repository policy, rollout checks, and emergency bypass procedure.

### Compile and Hot-Reload for Development

```sh
npm run dev
```

By default, the Vite dev server proxies `/api/*` to the remote stable API at
`https://api-v2.truckwash.io/master/api`. This lets the Vue app run locally
without a local PHP API container.

To develop against a local PHP API instead:

```powershell
$env:VITE_API_PROXY_TARGET="http://localhost"; npm run dev
```

To use another remote API route:

```powershell
$env:VITE_API_PROXY_BASE_PATH="/canary/api"; npm run dev
```

TLS certificate validation is enabled for proxied HTTPS APIs by default. If you
are using a trusted local HTTPS API with a self-signed certificate, you can opt
out explicitly:

```powershell
$env:VITE_API_PROXY_TARGET="https://local-api.test"; $env:VITE_API_PROXY_SECURE="false"; npm run dev
```

For compatible local gateways that expect the `/api` prefix to be preserved:

```powershell
$env:VITE_API_PROXY_TARGET="http://localhost"; $env:VITE_API_PROXY_STRIP_PREFIX="false"; npm run dev
```

### Compile and Minify for Production

```sh
npm run build
```

## Playwright Batched Chromium Runs

Run default e2e tests in deterministic 25-test shards across `chromium-desktop` and `chromium-mobile`:

```sh
npm run test:e2e:batched:chromium
```

Run the same flow and automatically re-run failed shards with `PLAYWRIGHT_WORKERS=1`:

```sh
npm run test:e2e:batched:chromium:rerun-failed
```

Optional overrides:

```sh
PLAYWRIGHT_BATCH_SIZE=25
PLAYWRIGHT_BATCH_WORKERS=2
PLAYWRIGHT_BATCH_DEV_PORT=5193
```

You can also forward Playwright args:

```sh
npm run test:e2e:batched:chromium -- --grep @smoke
```

Artifacts and summaries:

- `output/playwright/batched-chromium/last-run.json`
- `output/playwright/batched-chromium/failed-shards.json`
- `output/playwright/batched-chromium/report-index.html`
- `output/playwright/batched-chromium-shard-<i>-of-<n>/report/index.html`
- `output/playwright/batched-chromium-rerun-shard-<i>-of-<n>/report/index.html`

## Playwright Full E2E

Run the permanent grouped full-suite entrypoint with a hard max of 5 total workers across the browser-engine groups:

- Chromium
- WebKit
- Firefox

```sh
npm run test:e2e:ci
```

The full CI matrix is ordered by browser engine, then device class, then user role:

- browsers: `chromium`, `webkit`, `firefox`
- devices: `mobile`, `desktop`, `tablet`
- roles: `superuser`, `admin`, `customer`, `subuser`

Run a single full-suite slice for one role and one Playwright project:

```sh
npm run test:e2e:full:slice -- --role=admin --project=webkit-tablet
```

Default worker allocation:

```sh
PLAYWRIGHT_PARALLEL_WORKERS_CHROMIUM=2
PLAYWRIGHT_PARALLEL_WORKERS_FIREFOX=1
PLAYWRIGHT_PARALLEL_WORKERS_WEBKIT=1
```

Optional overrides:

```sh
PLAYWRIGHT_PARALLEL_BASE_PORT=5191
PLAYWRIGHT_PARALLEL_WORKERS_CHROMIUM=2
PLAYWRIGHT_PARALLEL_WORKERS_FIREFOX=1
PLAYWRIGHT_PARALLEL_WORKERS_WEBKIT=1
```

The runner fails fast if the combined worker count exceeds 5.

GitHub Actions keeps the full browser/device/role matrix stable by capping full-suite
matrix parallelism at 2 jobs, running each full slice with `PLAYWRIGHT_WORKERS=1`,
wrapping Docker Playwright runs with `systemd-inhibit` when available, and setting
`PLAYWRIGHT_VIDEO_MODE=off` for the full matrix. The E2E network harness serves
Font Awesome from local fixtures so WebKit page loads and visual snapshots do not
depend on CDN/TLS availability. Traces and screenshots are still retained on
failure.

Artifacts and summaries:

- `output/playwright/ci-parallel-report/index.html`
- `output/playwright/ci-parallel-chromium/report/index.html`
- `output/playwright/ci-parallel-firefox/report/index.html`
- `output/playwright/ci-parallel-webkit/report/index.html`
- `output/playwright/test-lists/<project>-<role>.txt`
- `output/playwright/test-lists/<role>-<project>.txt` (legacy compatibility copy)

## Android App Icon

The Play Store Android package is built from the Capacitor project in `android/`.
The legacy Bubblewrap/TWA project at the repository root is not used by
`npm run mobile:android:bundle`.

The native launcher and store icons use the opaque iOS marketing icon as their
shared master so Android and iOS keep the same white background:

```text
ios/App/App/Assets.xcassets/AppIcon.appiconset/AppIcon-1024.png
```

Regenerate the checked-in launcher assets after changing that source image:

```sh
npm run mobile:android:icons
```

Check that the generated Android launcher assets are current:

```sh
npm run mobile:android:icons:check
```

`npm run mobile:android:sync` runs the icon generator before building and syncing
the Capacitor Android project. The generator updates `android/app/src/main/res`
launcher assets, `public/icons/icon-192x192.png`, `public/icons/icon-512x512.png`,
and `store_icon.png`.

## Mobile Store Releases

Signed Android and iOS store artifacts are built through the GitHub Actions
`Mobile Store Artifacts` workflow. By default, current `master` after green
`Automated Tests` uploads Android to Google Play production and uploads iOS to
App Store Connect.

See `docs/mobile-artifacts.md` for workflow triggers, required secrets, and
local mobile checks. See `docs/app-store-release.md` for App Store Connect
release preparation and review notes. For a separate development-signed IPA
that can be installed on an approved iPhone from Ubuntu over USB, see
`docs/ios-device-debug.md`.

## Bubblewrap (TWA) Build and Install

To build and install the Trusted Web Activity (TWA) using Bubblewrap, use the following commands:

### Build the TWA

```sh
bubblewrap build
```

### Install the TWA on a connected device

```sh
bubblewrap install
```