Admin
386ca99889
Some checks failed
CI / verify (push) Has been cancelled
CI / print-rust (push) Has been cancelled
Desktop Release / Windows x64 NSIS (push) Has been cancelled
Desktop Release / Linux x64 DEB (push) Has been cancelled
Desktop Release / Publish tagged desktop release (push) Has been cancelled
82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# FieldLens
|
|
|
|
FieldLens is the Arrowstack-hosted production application around the reusable, local-first FieldLens Core.
|
|
|
|
## Repository boundary
|
|
|
|
- `apps/web` owns Arrowstack browser authentication, sync, station/device status and the production PWA shell.
|
|
- `apps/api` owns JWT/RBAC, sync ingestion, PostgreSQL, device/station registration and server-side provider adapters.
|
|
- `packages/contracts` is the versioned network contract shared by the browser and API.
|
|
- `packages/fieldlens-core` is a pinned vendor copy of the public reusable core.
|
|
- `migrations` contains versioned PostgreSQL schema changes.
|
|
|
|
The public source of truth is `dmparrow/feildlens-core` (spelling intentional). The initial vendor import is pinned to commit:
|
|
|
|
`90d38751eea2bed79f4c9f54c75687ea9aba350a`
|
|
|
|
The private prototype `dmparrow/net` is not a production dependency and is not modified by this repository.
|
|
|
|
## Local-first invariant
|
|
|
|
Capture writes to IndexedDB first. Remote authentication, API availability, PostgreSQL availability and reference-data availability are not prerequisites for scanner, EAN pallet, OCR/conformity or local review workflows.
|
|
|
|
## Configuration
|
|
|
|
See the root and app-specific `.env.example` files. Never commit production secrets.
|
|
|
|
## Validation
|
|
|
|
```bash
|
|
npm install
|
|
npm run verify
|
|
docker build -t fieldlens .
|
|
```
|
|
|
|
For Arrowstack `database-per-tenant` deployments, the restricted application runtime identity owns DDL inside its dedicated database. The API applies versioned migrations at startup under a PostgreSQL advisory lock before it begins listening; applied migration filenames and checksums are recorded so startup is idempotent and changed historical migrations fail closed.
|
|
|
|
|
|
## FieldLens Print desktop companion
|
|
|
|
`apps/print` is a Tauri desktop companion that turns an outgoing print stream into FieldLens scan events without requiring a physical barcode scan.
|
|
|
|
Capture routes:
|
|
|
|
- **RAW 9100 proxy** — listen locally (default `127.0.0.1:9100`), extract supported barcode fields from ZPL, and forward the original bytes unchanged to the real printer.
|
|
- **Spool / virtual-printer folder** — watch a local folder for `.zpl`, `.raw`, `.prn`, or `.spl` jobs produced by a print-to-file or virtual-printer route. Parsed jobs can also be forwarded to the physical printer.
|
|
- **Both** — run both adapters at the same time.
|
|
|
|
The first parser handles ZPL barcode commands for Code 128, Code 39, Code 93, EAN-8/13, UPC-A/E, ITF, QR, Data Matrix, and PDF417. Non-ZPL raster/EMF/XPS rendering is intentionally a later fallback; unsupported jobs are retained in recent-job diagnostics instead of being treated as successful scans.
|
|
|
|
Authentication uses Keycloak OAuth Device Authorization Grant with the public `fieldlens-print` client. No client secret is embedded in the desktop executable. Access and refresh tokens are kept in memory only; unsynced barcode events are stored locally under the Tauri app-data directory.
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm install
|
|
npm run build --workspace @fieldlens/print
|
|
npm run tauri --workspace @fieldlens/print -- dev
|
|
```
|
|
|
|
The Windows NSIS bundle is configured for `currentUser` installation, so installing FieldLens Print itself does not require elevation. Configuring or changing a Windows printer queue/port may still require IT/admin rights depending on machine policy.
|
|
|
|
|
|
### Desktop release artifacts
|
|
|
|
The `.gitea/workflows/desktop-release.yml` workflow packages FieldLens Print on changes to the desktop app, on `main`, and on `fieldlens-print-v*` tags.
|
|
|
|
Artifacts:
|
|
|
|
- **Windows x64:** NSIS current-user installer from `apps/print/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/nsis/*-setup.exe`
|
|
- **Linux x64:** Debian package from `apps/print/src-tauri/target/release/bundle/deb/*.deb`
|
|
|
|
After a successful Gitea Actions run, download the corresponding `fieldlens-print-windows-x64` or `fieldlens-print-linux-x64-deb` artifact from the workflow run.
|
|
|
|
Local packaging commands:
|
|
|
|
```bash
|
|
npm run bundle:windows --workspace @fieldlens/print
|
|
npm run bundle:deb --workspace @fieldlens/print
|
|
```
|
|
|
|
The Windows package is cross-compiled with `cargo-xwin` and bundled with NSIS. MSI packaging is intentionally not part of the Linux runner workflow because WiX/MSI bundling requires Windows.
|