Econ systemdocumentation

This documentation covers how Econ works end to end - for office staff on this web dashboard, field workers on the mobile app, and equipment owners. Use the menu on the left to jump to a specific operation (creating a project, starting a site, scanning QR, approving trip issues, generating reports, and more).

Scope

• How to set up a company, project, site, and field team from zero.
• LINEAR (chainage) vs AREA (map polygon) projects - when to use each.
• All 12 trip process types: standard QR, no-loader, paper QR, offline, exceptions, weighbridge, and more.
• How GPS verification works for loader, driver, and unloader on LINEAR and AREA sites.
• Weighbridge / scale weight capture and how net weight becomes product quantity.
• Inter-company (ICT) partner handoff between sender and receiver companies.
• How to read reports, approve trip issues, and close a site.

Shorter topic pages are also available from the home menu: Platform, Trips, Trip issues, Office dashboard, Roles.

Office (this website)  →  ComapySass API  →  projects, sites, reports, users
Field (mobile app)     →  Field API         →  trips, QR, offline queues, equipment

Both share the same business story: projects consume equipment and record every delivery trip.

A typical day

• Morning - office: log in, switch company, check dashboard KPIs, add a site or adjust members.
• Morning - site: foreman opens Work, syncs after poor coverage, starts site or opens loader/driver screens.
• Handoff - loader shows QR; driver scans; unloader completes at destination.
• Evening - office: products/equipment reports; approve trip issues; generate site report.
• Evening - owner: mobile Reports tab for machine trip history.

Econ connects equipment owners, construction companies, and field workers through one trip-tracking story. Work proceeds in phases - skip one and field actions will block with validation errors.

Registration → Company users → Project + site setup → Foreman starts site
→ Phase 8 trips (QR / no-loader / paper / offline / weighbridge / ICT)
→ Reports, GPS verification, trip-issue approval, site Done

Registration today means: your phone is already in company_workers (or a platform user record), and you authenticate with a Telegram one-time code. Public /register does not create workers - an admin must add you first (Phase 4).

1. 1
   Open login

   Web /login or mobile login. Same phone rules on both surfaces.

2. 2
   Enter phone

   Prefer international digits (e.g. 2519…). Mobile normalizes 09… and 9-digit local to 251…; strips spaces and +.

3. 3
   Request code

   Backend looks up user by phone (± leading +). Sends 6-digit code via Telegram bot linked to that phone.

4. 4
   Enter code

   On success: web stores JWT (company-scoped); mobile stores long-lived session. Land on dashboard or five tabs.

5. 5
   If login fails

   “User not found” → phone not in directory. Wrong/expired code → request again. Bot never started → user must open Telegram bot once.

Multi-company workers

The same phone/user may belong to more than one company. On web, switch company in the header after login - JWT is re-issued for the selected company. On mobile Work, project lists are scoped to memberships for that user’s companies.

Equipment owners use the mobile marketplace to list trucks and machines. This is separate from company project work but feeds the pool companies can assign to drivers (alongside company fleet registered on Nearby Equipment).

1. 1Home - browse with filters (category, location, type); open detail / contact.
2. 2Add Post - 5-step wizard: category → type → specs → up to 4 images → details (phone required). Tab bar hides during wizard.
3. 3Account - profile, my equipment, update GPS for nearby features.
4. 4Reports - trip history per machine by date range (usage analytics, not favorites).

Phase 3 - Company registration

• Ops / system admin creates the company record (name, settings).
• Attach first owner / admin workers.
• Enable feature flags as needed: area_projects, weighbridge_weights, inter_company_trips, etc.
• Without company context, project creation and company-scoped APIs fail.

Important feature flags

Phase 4 - Add company workers

Route: /dashboard/CompanyUsers - HR adds people to the company directory. Same person can be added to multiple companies (unique per phone+company / userId+company).

Field roles vs dashboard roles

Every project has a project type that controls geometry, sites, places, and GPS verification. Choose once at create time - field and office UIs branch on this type.

1. 1Create project with type AREA (company must have area_projects).
2. 2Draw or upload the project boundary polygon on the map - this is the outer allowed zone.
3. 3Add products (DELIVERY and/or DISPOSAL) with units and targets.
4. 4Add product places with latitude/longitude (and optional geofence radius) - LOADING / UNLOADING / DISPOSAL.
5. 5Create a site by drawing a site zone polygon that sits inside the project boundary.
6. 6Link products/places to the site; assign members; set dates and flags as on LINEAR.
7. 7Foreman starts the site on mobile the same way; unloaders confirm GPS inside the zone instead of chainage.

A disposal site (isDisposalSite) models pickup of spoil/waste inside a zone and optional dump destinations.

1. 1Create/select a DISPOSAL product and DISPOSAL places (dump destinations with GPS).
2. 2Mark the site as disposal; link the pickup zone (often the site polygon on AREA).
3. 3Select which dump places are allowed for this site.
4. 4Assign unloaders per dump place when destinations must be staffed (disposalPlaceId on personnel).
5. 5Field: loaders/drivers work pickup; unloaders complete at selected dump or pickup-only flow.

1. 1
   Open disposal site

   Work → project → disposal / loading site marked for disposal products.

2. 2
   Pickup

   Loader/driver operate inside the pickup zone (site polygon on AREA). Weighbridge may apply if product has weight type.

3. 3
   Choose dump

   When destinations exist, select disposal place before or during unload per site UI.

4. 4
   Complete

   Unloader scans/completes with GPS. Verification follows AREA DISPOSAL rules (place vs PASS).

Phase 8 covers every trip process type. Configure the site/product first, then train the matching scenario. Weighbridge (8.1.12) can combine with standard, no-loader, or offline paths.

Standard:  loading → driving → unloaded → (needs checking) → approved
Exception: ↘ issue_reported → pending_approval → approved | reject→issue_reported
Weighbridge: loader gross ↔ unloader gross → netWeight → quantity (product unit)
ICT (extra): A unloaded → handoff QR → B driving → B unloaded (separate trip_link)

The default flow when the site does not allow driver-only trips. Every load passes loader → driver → unloader with a QR handoff at load start.

Prerequisites (before first trip)

[Loader Show QR]     [Driver scan]      [Unloader complete]
     loading      →      driving      →      unloaded
                            ↓
              needs checking → approved  (GPS, optional)

Loader - step by step

1. 1Work → project → Loader sites (Loading only; Not Started uses Start loading first).
2. 2Open Loader site detail - pull to refresh trucks/drivers.
3. 3Select driver + product (driver must be on site personnel).
4. 4If weighbridge on product: capture loader gross (OCR/manual) + evidence if required.
5. 5Tap Show QR - app captures GPS, POST scanQRCode → trip status loading; shows LoaderQRCodeDialog + optional loader verification code.
6. 6Driver scans; regenerating QR for same load keeps the same identifier (updates trip, does not duplicate).

Driver - step by step

1. 1Work → Driver sites → Scan QR / Accept load.
2. 2Camera decrypts payload; optional verify loader code; confirm car/plate if prompted.
3. 3POST acceptTrip with driver GPS → status driving.
4. 4Transport (no API) until unload.

Unloader - step by step

1. 1Work → Unloading sites → Unloader site detail.
2. 2Scan QR or pick trip from list.
3. 3LINEAR: enter chainage inside site start/end. AREA: confirm GPS in zone / dump place.
4. 4If weighbridge: capture unloader gross (+ evidence).
5. 5POST completeTrip → unloaded; office reports update.

Loader outcomes

Driver outcomes

Unloader outcomes

Drivers start trips without loader QR when office enabled the site flag and foreman started with supervisor only (no loader teams required). Delivery-oriented path.

Prerequisites

Field steps

1. 1Foreman: Site starter → assign supervisor only → Start site → Loading.
2. 2Driver: site detail → Create trip without loader → pick product + equipment → confirm.
3. 3Trip goes directly to driving (no loading status from loader).
4. 4Transport; unloader completes as in 8.1.1 (chainage/GPS; weighbridge if configured).

Outcomes

For yards without phones at the loading point, office generates a printed QR from site detail. Driver scan creates and accepts the trip in one step.

Prerequisites

• Site exists and is Loading (or ready for field).
• Office generated Loader paper QR from site detail (payload includes paper marker).
• QR printed and posted at loading point.
• Driver assigned to site / project.

Office - generate & print

1. 1Open site detail → Loader paper QR section.
2. 2Generate QR (product/place encoded as configured).
3. 3Print and post at the physical loading point.
4. 4Rotate / regenerate old prints when products or site change.

Field - driver scan

1. 1Driver scans paper QR (no loader phone).
2. 2Backend creates new trip + accepts → driving.
3. 3Unloader completes as standard (8.1.1 E).

Outcomes

When a site has 2+ product places, each place can have its own loader running parallel independent trips.

1. 1Office: site links multiple places per product (or multiple products/places).
2. 2Foreman Site starter: assign one loader per place (+ supervisor, drivers, unloaders).
3. 3Start site → Loading.
4. 4Each loader opens their place context and generates independent QR → separate trip rows.
5. 5Drivers must scan the QR from their assigned loader/place (wrong place QR = wrong product/place on trip).
6. 6Unloaders complete each trip independently (chainage/GPS as usual).

Numeric codes sit alongside QR for poor connectivity, verbal confirmation, or sites that require a second factor. Codes expire (~2 minutes typical) - regenerate by re-showing QR or re-accepting per safety rules.

When to use codes vs QR only

• QR-only: good connectivity, standard visual handoff (8.1.1).
• Codes: backup when camera fails, bright sun, or process requires spoken confirmation.
• Expired codes: UI shows expired - regenerate; do not reuse old screenshots.
• Deployments may allow skipping codes - then QR-only path applies.

Mobile queues failed mutations locally. When back online, Work → Sync all uploads them in a defined order. Weight fields, evidence URLs, and GPS travel with offline payloads when present.

Sync algorithm

1. 1User taps sync badge on Work (must be online).
2. 2Pass 1: Q1 creations → Q2 accepts → Q3 driver trips → Q4 completes.
3. 3Pass 2: retry failures caused by ordering (e.g. accept before create landed) - ties to buffered accept 8.1.7.
4. 4Refresh cached site data (up to ~15 sites per project).
5. 5If N failed: stay online, sync again, or contact support with timestamp and queue names.

Idempotency & guards

• alreadyAccepted / alreadyCompleted treated as success.
• Duplicate / abuse guards may block or flag repeated offline payloads.
• Unloader-first offline chains can embed loader+driver payloads (closeFromOfflineChain).
• ICT handoff offline uses pendingHandoffLink - sync separately after local trip is ready.

When a driver scans before the loader trip reaches the server (loader offline, driver online), the accept may be stored in pending_offline_events instead of failing permanently.

1. 1Loader offline: shows QR locally; trip sits in Q1.
2. 2Driver online: scans QR → server may buffer accept (not a second trip).
3. 3Loader syncs Q1 → trip created on server.
4. 4Next sync/pass applies buffered accept → driving.
5. 5Unloader proceeds as usual once driving exists on server.

Foreman or coordinator can change personnel while the site is Loading.

1. 1Site detail → remove driver from site personnel or change assignment.
2. 2Add new driver from the project member pool (must already be a project member with equipment if required).
3. 3Optionally reassign loaders per place the same way.
4. 4In-flight trips (loading/driving) keep the original driver until complete or exception.
5. 5New loader QR / create-trip flows use only the newly selected driver.

When a delivery goes wrong, the driver flags an issue; the foreman classifies; office approves or rejects. Exception trips are excluded from product totals until approved with a report value.

NONE → issue_reported → pending_approval → approved
                              ↓ (reject)
                        issue_reported  (foreman may re-classify)

Exception types & report values

Full loop

1. 1Driver reports issue on own trip only (non-drivers forbidden).
2. 2Foreman sees banner on site/trip - must match site foremanId for that company.
3. 3Foreman POST resolve with exceptionType → pending_approval.
4. 4Office (owner, sys_admin, project_manager, product_manager, office_engineer, site_engineer) approves or rejects on web.
5. 5Approve applies reportValue; reject clears classification back to issue_reported.

Outcomes

Office engineers correct trips and site data after field work without re-running mobile QR flows.

Where to work

Post-trip actions

1. 1Refresh site trip table after field complete - unloaded visible.
2. 2Edit trip (quantity, times, plate, locations) for data-entry errors.
3. 3Change trip status manually if stuck (e.g. driving → unloaded).
4. 4View site statistics; Generate site report when segment complete.
5. 5Second generate when report exists - handle report-exists messaging.
6. 6Mark site Done when work finished.
7. 7For material went wrong place: prefer exception approval over silent quantity edits.

GPS captured at load, accept, and complete feeds automated compliance. Trips may show needs checking until approved. Chainage validation on LINEAR is separate but part of unload compliance.

Capture points

LINEAR (CENTERLINE)

• Loader: vs loading reference (LOADING place GPS or chainage-derived point).
• Driver unload: vs alignment point at unloadedChainagePoint.
• Unloader: vs same alignment point.
• Typical radius ~100 m (place geofence where configured).

AREA (polygon + places)

“Site polygon” = site boundary if set, otherwise project boundary. Buffer default ~20 m (meters converted to degrees for WGS84 - never buffer by “20 degrees”).

Statuses & outcomes

• Field: allow location; enter correct chainage (LINEAR); work inside drawn zones (AREA).
• Office: monitor needs checking; use trip tools / cron.
• Deep UI detail: GPS trip verification section under Reports.

Prerequisite: company feature weighbridge_weights. Product must have a weight measurement type (camera OCR, manual scale, ticket OCR, kg or tonnes). Site may have a weighbridge profile (digit layout, decimals, unit, capacity, mismatch %).

With loader - mode split

Loader  → WeightCaptureDialog (OCR/manual + evidence if required)
        → QR includes weight fields (s/t/u/v)
        → Driver scans → DRIVING
Unloader → One weighbridge reading + unload evidence
        → complete with unloaderWeight + GPS/chainage
Server  → netWeight + quantity; optional weightMismatchFlag

1. 1Loader selects driver/car → if product weighbridge enabled, open weight dialog before/with QR.
2. 2Scan ROI + consensus (camera types) or enter manual; Accept stores gross + optional photo.
3. 3Driver transport unchanged.
4. 4Unloader after scan: one gross capture → complete.

No loader - mode unloader_both

Driver   → Creates trip without loader (8.1.2)
Unloader → First gross → “Load dropped?” confirm → second gross
        → complete with weightCaptureMode=unloader_both
Server   → netWeight + quantity; optional mismatch flag

Server net & quantity

• Negative signed net (inverted readings) still stores absolute netWeight and sets weightMismatchFlag.
• Readings beyond site mismatch tolerance % also set weightMismatchFlag.
• quantity is in the product unit (m³, ton, …); scale unit stays on weight fields/profile.
• Reports: if netWeight set → prefer trip quantity; else legacy car size - see Weighbridge & quantity.
• Offline: weight + evidence + confidence travel with complete/sync chain.

Goal: Project exists, materials defined, sites created, people assigned - before field work begins. Do this once per project; adjust sites as segments open.

Detailed order for a new LINEAR project

1. 1Create project from CSV or map points - verify chainage range on project card.
2. 2Add each material as a product with unit and target quantity.
3. 3If weighbridge: set weight measurement type + weightUnitsPerProductUnit when unit is not pure mass.
4. 4For DELIVERY: add LOADING places along chainage; optional UNLOADING places.
5. 5For DISPOSAL: add DISPOSAL dump places; mark disposal sites later.
6. 6Assign all field workers as project members; pick truck plate for each driver.
7. 7Create sites: chainage must sit inside project range; link products/places; set allowDriverTripWithoutLoader only if agreed.
8. 8Site detail: foreman, average speed, loading/unloading times, optional weighbridge profile, paper QR if needed.

Detailed order for a new AREA project

1. 1Confirm company has area_projects; re-login after enabling.
2. 2Create AREA project - draw closed boundary polygon.
3. 3Add products; for each place enter lat/lng + geofence (no chainage).
4. 4Assign project members as above.
5. 5Manage Sites - draw site polygon inside project boundary (or whole project area).
6. 6Verify site area on dashboard map overlay; GPS verification will use polygon + places.

Phase B - Field start (mobile)

Phase C - Daily operations (mobile)

1. 1Loader: pick driver + product; capture weighbridge gross if required; show QR (or use paper QR from web).
2. 2Driver: scan QR → driving; or Create trip without loader when flag on; transport; report issues if needed.
3. 3Unloader: scan/complete with chainage (LINEAR) or GPS (AREA); capture unloader weight / unloader_both if weighbridge.
4. 4Foreman: reassign personnel for new trips only; classify trip issues → pending_approval.
5. 5ICT: after sender unloaded, generate partner handoff QR; receiver loader/unloader scans per lane intakeMode.
6. 6Offline: when back online, Work → sync badge - uploads Q1→Q4 (and handoff queue if used).

1. 1
   Open /login

   Enter phone number in international format as your organization standardizes.

2. 2
   Request code

   Backend sends a one-time code; user reads it in Telegram.

3. 3
   Enter 6-digit code

   App stores JWT and redirects to /dashboard.

4. 4
   Switch company (if applicable)

   Header → Company dropdown → pick company → new token for that company → dashboard reloads.

5. 5
   Logout

   Sidebar Logout clears session; use on shared PCs.

Quick actions (large tiles)

• Projects → project list
• Products → products report (not in narrow sidebar)
• Users → Company Users
• Account → account settings

What you see on the dashboard

• Overview cards: total cars, users, projects, active sites.
• Material delivery: each product row - planned vs delivered, progress bar; tap row for product analysis.
• Trip statistics: counts by loading, driving, unloading, unloaded, needs checking, approved.
• Site statistics: not started, loading, done, with/without foreman.
• Recent trips, sites, projects - useful for daily standups.

Route: /dashboard/CompanyUsers - used by HR / admin.

Mode A - By phone (Telegram user)

1. 1Open Add User → choose By phone.
2. 2Enter country code and phone; fetch preview if offered.
3. 3Select role from directory → Save under current company.

Mode B - Without Telegram

1. 1Choose Without Telegram - read warning: user becomes Loader_load only; role cannot be changed later.
2. 2Enter name, phone, optional username → Save.

1. 1Sidebar → Projects (/dashboard/projectsHome).
2. 2Search filters project names on the current loaded page (10 per page).
3. 3+ New project opens creation dialog.
4. 4Export CSV downloads Project Name, Cars, Workers, KPI %, Points, Chainage Range for the current filtered page - paginate if you need all projects.

Prerequisite

Login must have an active company. If the dialog says company is missing, re-login or switch company.

Mode A - Upload CSV

1. 1Tab Upload CSV → enter project name.
2. 2File must end with .csv.
3. 3Required columns: chainage, easting, northing, elevation.
4. 4Example row: 13+800,500000.0,1200000.0,1500.5
5. 5Submit Create - wait for success - page reloads.

Mode B - From map points

1. 1Tab From map points → project name.
2. 2Set interval in meters (e.g. 50) for derived chainage along the polyline.
3. 3Optional starting chainage: 0+000, 13+800, or plain meters; empty = 0+000 at first point.
4. 4Enter at least two points per line as longitude,latitude (WGS84), e.g. 38.123456,9.012345.
5. 5Optionally click the map to append points.
6. 6Submit Create project.

Route: /dashboard/projectsHome/[id]

Recommended order for a new project

1. 1Products - create each material (name, unit, targets).
2. 2Product places - for each product, define places along chainage.
3. 3+ Add / Manage Users - attach company workers; drivers must pick plate/equipment when required.
4. 4Manage Sites - create sites (see next section).
5. 5Cars dialog - maintain project vehicles as needed.

Assign existing worker to project

1. 1Open + Add / Manage Users.
2. 2Select worker from available list.
3. 3If role is driver - pick equipment / plate before assign.
4. 4Assign to project - confirm row in members table.

Invite by phone from project dialog

1. 1Enter country code and phone → fetch preview.
2. 2Choose role and status → Save (may create company worker then assign).
3. 3Tell user to log in on mobile with same phone.

Open Manage Sites from project detail. For LINEAR projects the dialog shows allowed chainage range. For AREA projects use the map-based site dialog - see AREA projects section.

After save, open the site from the table for trip management and reports.

Route: .../sites/[siteId]

Trips table

• Monitor statuses: loading, driving, unloading, unloaded, needs checking, approved.
• Trip issue banners show when driver reported an issue or foreman classified - waiting for backoffice.
• Edit trip fields where permissions allow (quantity, times, plates).

Site settings

• Set foreman / supervisor.
• Average car speed, loading time, unloading time - often required before save.

Loader paper QR

Generate printable QR for yards without phones at the loading point (paper QR creates a new trip on driver scan - see QR scenarios).

Generate report

1. 1Check whether a report already exists for the site/day.
2. 2Click Generate Report when eligible trips are complete - recalculates equipment-per-trip scores for that calendar day.
3. 3Approving a trip issue can run the same logic for that single trip only.

Finish site

When work is truly complete, use the action to set site status Done.

NONE → ISSUE_REPORTED → PENDING_APPROVAL → APPROVED
                              ↘ reject → ISSUE_REPORTED (foreman may re-classify)

Step by step

1. 1
   Driver reports issue

   Mobile - trip owner flags problem. Status: issue_reported. Excluded from product totals.

2. 2
   Foreman classifies

   Mobile or dashboard - picks one of four resolution types. Status: pending_approval.

3. 3
   Backoffice approves or rejects

   Dashboard Trip Exception panel on site/project - roles: owner, sys_admin, project_manager, office_engineer, site_engineer.

4. 4
   On approve

   reportValue snapshotted from classification. Reached intended / new useful location → trip may become unloaded + per-trip equipment report generated.

5. 5
   On reject

   Returns to issue_reported; classification cleared; foreman can submit again.

See Trip issues (exceptions) below for classification values and report impact.

1. 1Dashboard quick action → Products (/dashboard/products-report).
2. 2View aggregates across projects: target vs current, active trips hints.
3. 3Use search and filters.
4. 4Click a product for Product analysis - charts, progress, logistics views.
5. 5Approved trip issues contribute fixed report values; pending issues contribute zero.

1. 1Sidebar → Equipment Report.
2. 2Choose date range (calendar).
3. 3Select project (required); optionally filter by site.
4. 4Optional: Show disposal trips report (kind=disposal vs delivery).
5. 5Generate Report → expandable driver → project → site → trip tree.
6. 6Download Excel - multi-sheet engineer pack (Summary, Drivers, By Project, By Site, Trip Ledger).

1. 1Sidebar → Nearby Equipment - list/filter company + marketplace equipment.
2. 2Click a card → equipment activity report (period: today / 7d / 4w / 12m).
3. 3Work report KPIs: trips, quantity, average performance, average score + trip list.
4. 4Register company fleet (office / product_manager) with images - sets companyId.
5. 5Assign fleet unit to a driver from company fleet cards only.

1. 1Feature inter_company_trips must be on for both companies.
2. 2/dashboard/inter-company - partnerships, trade lanes, handoff status.
3. 3CompanyUsers → Partner drivers - receivers registering partner drivers from handoffs.
4. 4Field: sender generates handoff QR only after trip is unloaded; receiver scans per lane intake mode.

Full rules under Inter-company trips (ICT) below.

• Install from Play Store or internal channel your company provides.
• If forced update modal appears, install latest build from store.
• Grant camera (QR) and location (nearby projects, trip payloads).

Sign in

1. 1Enter phone - app normalizes 09… to 2519…, 9-digit local to 251…, keeps 251… as-is.
2. 2Send code → read Telegram → enter 6 digits on passcode screen.
3. 3Five tabs appear on success.
4. 4Logout: Account → Log out on shared phones.

• Title: Projects - subtitle Online or Offline · using saved data.
• Filter chips: All, Active, Upcoming, Completed (from material progress).
• Sync badge (top right): pending queue count; uploads when online.
• Project cards: name, dates, site count, progress - tap into role UI.
• Pull-to-refresh on site screens after sync or teammate actions.

Role priority (multiple hats)

Mixed assignments filter Work in order: Loader → Driver → Unloader → generic coordinator. Multi-hat users must open the correct project/site path even when the shell looks “loader-first”.

1. 1
   Work → project

   Sites list with Active / Done / All.

2. 2
   Not Started - Site starter

   Loader per place + supervisor (+ drivers/unloaders). Start when validation passes.

3. 3
   No-loader sites

   Flag on → Start with supervisor only (no loader teams).

4. 4
   Disposal sites

   Pickup loaders + dump unloaders (disposalPlaceId).

5. 5
   Loading / Done - Site detail

   Manage teams; reassign for new trips only (8.1.8).

6. 6
   Classify trip issues

   Driver reported → pick exceptionType → pending_approval (must match site foremanId).

1. 1
   Work → project

   Loader-assigned projects only.

2. 2
   Loader sites

   Loading sites (Start loading if still Not Started).

3. 3
   Site detail

   Refresh → driver + product → optional weighbridge → Show QR + loader code.

4. 4
   Regenerate QR

   Same load identifier - updates trip, does not duplicate (8.1.1 C2).

5. 5
   Offline strip

   Network fail at QR → local Q1 until Work sync.

6. 6
   ICT receiver (loader_scan)

   On company B, Scan partner handoff when lane intakeMode is loader_scan.

1. 1
   Driver sites

   Cards show progress, pending cars, status.

2. 2
   Scan QR

   Loader or paper QR → confirm car → driving (no duplicate).

3. 3
   Transport & codes

   Follow site verification-code process.

4. 4
   Report issue

   Own trips only → issue_reported for foreman.

5. 5
   Create without loader

   Flag on → product + equipment; cache trucks with one online visit first.

6. 6
   ICT handoff QR

   After unloaded on sender site → Partner handoff QR for active lane.

1. 1
   Unloading sites

   My sites list → site detail (incoming vs unloaded).

2. 2
   Scan / select trip

   Correct QR or trip row.

3. 3
   LINEAR complete

   Chainage inside site range + GPS.

4. 4
   AREA complete

   GPS inside zone / dump place (no chainage).

5. 5
   Weighbridge

   split: one gross. unloader_both: first → load dropped → second.

6. 6
   ICT no_loader intake

   Scan partner handoff when intakeMode is no_loader.

7. 7
   Offline

   Complete → Q4; sync from Work.

Full queue semantics are in 8.1.6. This is the field checklist.

Sync all

1. 1Online → Work → sync badge.
2. 2Order: creations → accepts → driver trips → completes (may repeat for races).
3. 3Refresh cached sites (up to ~15 per project).
4. 4alreadyAccepted / alreadyCompleted = success.
5. 5If failures remain: stay online, sync again, escalate with queue names + time.

Numeric codes sit alongside QR for poor connectivity or verbal confirmation. See also 8.1.5.

• Loader shows loader verification code with expiry after scanQRCode.
• Driver enters/confirms driver code after accept when required.
• Unloader uses unloader code on car row before complete.
• Expired codes: regenerate via re-show QR / re-accept - do not reuse screenshots.
• Some deployments allow skipping codes → QR-only path.

PHASE 5 - Office: project, products, places, sites, members (+ weighbridge / ICT flags)
PHASE 6 - Office: foreman, speed, times, site flags, weighbridge profile, paper QR
PHASE 7 - Foreman: Site starter → teams → Start site (Loading)
PHASE 8 - Field scenarios 8.1.1–8.1.12 (QR / no-loader / paper / offline / WB / …)
PHASE 9 - Office: GPS check, trip issues, Excel reports, site Done
ICT extra - A unloaded → handoff QR → B trip → B unloaded

End-to-end journey map

ISSUE_REPORTED, PENDING_APPROVAL: excluded from product totals (contribution 0). APPROVED: uses snapshotted reportValue.

• On approve for +1 outcomes: per-trip equipment report runs (same logic as Generate Report for that day, that trip only).
• reportGenerated = true on the approved trip.
• Foreman can re-classify until backoffice approves or rejects.

1. 1Mobile Reports tab - pick start/end date.
2. 2Equipment list with trip counts for range.
3. 3Tap equipment → trip list with times, locations, quantity.
4. 4Web office uses dashboard + equipment report + site generate-report instead.

Econ runs automatic GPS verification after a trip reaches unloaded. The goal is to confirm that load and unload actions happened in the right place - either along a LINEAR alignment (chainage) or inside an AREA site zone polygon. Scenario framing: 8.1.11 above.

When verification runs

• Runs periodically for trips with status unloaded and not yet checked.
• Writes per-role results to the trip: loader/driver/unloader GPS checks plus an overall tripStatus label.
• Office sees the badges in Trip Details; mobile sees them as informational.

LINEAR projects (alignment / chainage)

LINEAR verification uses the survey parquet (from the project CSV) as the source of truth.

• Loader: loader GPS is compared to the selected LOADING product place (point + radius or chainage-derived point).
• Driver (unload): driver unloading GPS is compared to the survey point at the unloaded chainage.
• Unloader: unloader GPS is compared to the same survey point at the unloaded chainage.
• Typical radius: ~100m (configurable via place geofence where applicable).

AREA projects (closed polygon sites)

AREA verification combines product places (where loading happens) with the site polygon (where unloading must occur).

GPS capture points

Per-role outcomes

Verification statuses on trip

• unloaded - field work complete.
• needs checking - GPS rule mismatch; awaiting review.
• approved - passed automated or manual review; counts in compliance reports.
• tripStatus labels: verified, loader_red, driver_red, unloader_red, etc.

Spatial buffer (AREA polygons)

Polygon checks use a tolerance buffer (default 20m). DuckDB converts meters to degrees for WGS84 - otherwise far-away points could incorrectly pass.

Company feature weighbridge_weights must be enabled before weight UI and APIs appear. Without it, trips stay on the normal QR path with no weight dialog.

1. 1Enable weighbridge_weights on the company (ops / company_feature); re-login so JWT includes the flag.
2. 2On each product: choose a weight measurement type - weighbridge camera, manual scale, axle/portable camera, ticket OCR (kg or tonnes variants).
3. 3Set weightUnitsPerProductUnit when the product unit is not pure mass (example: 1800 kg per 1 m³). Leave blank for automatic kg↔ton conversion.
4. 4On the site: optionally open Weighbridge profile - digit count, decimal places, unit, capacity min/max, mismatch tolerance %.
5. 5Train field: split (with loader) vs unloader_both (no-loader sites).

Loader gross ──┐
               ├── signedNet (by product type) → netWeight = |signedNet|
Unloader gross ┘
               → quantity = convert(netWeight → product unit)
               → weightMismatchFlag if inverted or beyond tolerance %

split (loader present)

1. 1Loader opens WeightCaptureDialog (OCR ROI consensus or manual entry).
2. 2Accept stores loader gross (+ evidence photo when requiresCamera).
3. 3QR carries weight fields; driver accepts normally.
4. 4Unloader captures one gross + evidence → complete with GPS/chainage.

unloader_both (no-loader sites)

1. 1Driver creates trip without loader (site flag on).
2. 2Unloader: first gross → confirm “Load dropped?” → second gross.
3. 3Complete with weightCaptureMode=unloader_both.

• Inverted readings still store absolute netWeight and set weightMismatchFlag.
• Beyond site mismatch tolerance % also flags the trip for QS follow-up.
• Offline: weight, evidence URLs, and confidence travel with the complete/sync payload.
• Office product reports show weight flags; Excel export includes them.

Move material from Company A (sender) to Company B (receiver) without merging tenants. Each side keeps its own trip; a trip_link ties them after the sender trip is unloaded. Feature key: inter_company_trips.

A: loading → driving → unloaded → handoff QR
B: scan handoff → receiver trip DRIVING → unloader completes on B
Shared: trip_link (+ optional partner driver on B)

Ops scenario catalog

1. 1Enable inter_company_trips on A and B; refresh token so sidebar Inter-company and Users → Partner drivers appear.
2. 2A requests partnership with B; B approves → status active (pending / suspended block new links).
3. 3Create trade lane (inter_company_link): sender company/site/product → receiver company/site/product.
4. 4Set intakeMode: loader_scan (receiver loader scans; preferred) or no_loader (receiver unloader scans).
5. 5Optional: weightTolerancePct for reconciliation; handoffTokenTtlHours (default 48h); status active/paused/closed.
6. 6Office paths: /dashboard/inter-company; partner drivers under CompanyUsers.

Sender (Company A)

1. 1Run a normal local trip to unloaded (any 8.1.x path - GPS/weighbridge/exceptions unchanged).
2. 2Driver (or authorized sender field user) opens Partner handoff QR / HandoffQRDialog.
3. 3Select active lane (or auto-pick if one); server validates feature, partnership, lane, unloaded, not linked elsewhere.
4. 4Show encrypted QR (t: handoff, link id, expiry, plate, sender company name, net weight, …).

Receiver loader_scan (Company B)

1. 1Loader on receiver site scans handoff QR + GPS.
2. 2Server resolves actor as loader on B (multi-company safe).
3. 3Auto-register partner driver on B when resolvable: same userId, role driver, registrationSource=inter_company_handoff, originCompanyId=A; assign site driver + project member.
4. 4Create receiver trip DRIVING + trip_link; sender stays unloaded.
5. 5Unloader on B completes receiver trip normally.

Receiver no_loader

1. 1Unloader on B scans handoff QR.
2. 2Receiver trip created DRIVING (driverId may be null).
3. 3Complete unload on B as usual.

Failures & guards

On site detail → Products section. Totals prefer weighbridge quantity when netWeight is set; otherwise legacy car size.

• IN vs OUT: DISPOSAL product type = OUT; otherwise IN (delivery).
• weightMismatchFlag trips surface in the flags view for QS follow-up.
• Excel: ECON-branded workbook via ExcelJS (navy #002347 + orange #FF8E00), embedded icon, frozen headers, filters.
• Pending trip issues contribute 0 until approved; approved use snapshotted reportValue.

Aggregate engineer compliance: /dashboard/equipment-report. Per-machine activity: Nearby Equipment card click.

1. 1Select date range (single day or range).
2. 2Select project (required), site (optional).
3. 3Optional: Show disposal trips report (kind=disposal vs delivery).
4. 4Generate Report → expandable driver → project → site → trip tree (GPS checks, codes, red flags).
5. 5Download Excel - multi-sheet engineer pack.

Nearby Equipment activity dialog

• Periods: Today / last 7 days / last 4 weeks / last 12 months.
• Work report KPIs: trips, quantity, average performance, average score.
• Trip list: product, quantity, times, route, project/site.
• Matching: equipmentId on trip or matching plateNo when fleet plate is set.

Owner / marketplace (mobile & field web)

1. 1Home: browse equipment with filters.
2. 2Add Post: 5 steps - category, type, specs, up to 4 images, details (phone required).
3. 3Account: profile, my equipment, update location for nearby features.
4. 4Reports: usage and trips per machine (not the web Hearted placeholder).

• Nearby click opens equipment activity report - not marketplace-only detail.
• Assignment uses project_driver_equipments (project-scoped).
• Field prefers assigned plate, then personal trucks; unassigned fleet is not shown to all drivers.
• List scope for drivers: personal (companyId null) OR current company fleet.

• Phone + Telegram one-time code for web and mobile.
• Web: JWT in browser storage, company-scoped token, ~24h session guard with refresh.
• Mobile: long-lived session in device storage with refresh on 401.
• RBAC: dashboard areas (users, trip approve, reports) depend on company role keys.
• Multi-company: switch company on web header only.

Privacy policy

Can one person be loader on one project and driver on another?

Yes on server; mobile Work shows loader view if any assignment is loader (see role priority).

Where are favorites on mobile Reports tab?

Reports tab is equipment usage history, not favorites (internal name Hearted).

Who creates the site?

Geometry and products on web; starting site for field work is usually mobile foreman.

Can drivers work without loaders?

Only if office enabled Allow driver to create trip without loader on that site.

What is the difference between LINEAR and AREA?

LINEAR uses chainage along a centerline. AREA uses map polygons and GPS coordinates for places and site zones. See Project types section.

Do I need chainage on AREA projects?

No. Sites show area (m²) instead of chainage. Product places require latitude and longitude.

What happens if GPS verification fails?

Trip shows fail badges per role. Office reviews in Trip Details. Field should allow location permission and work inside the defined site zone or loading place.

When does weighbridge appear on mobile?

Company feature weighbridge_weights must be on, and the product must have a weight measurement type. Without that, trips stay on the normal QR path with no weight dialog.

How do inter-company (partner) trips work?

Sender completes to unloaded, then generates a handoff QR. Receiver scans it to create their own trip. Tenants stay separate - linked by trip_link. Both companies need the feature and an active trade lane.

Web

• /register does not submit - use User Management.
• Main /hearted is not office analytics.
• Projects status filter may be incomplete server-side.
• CSV export is current page only.

Mobile

• Forced update if store version ahead of app check.
• Role priority can confuse loader+driver users.
• Driver-create-trip offline needs one online session to cache equipment list.