Econ systemtutorial

This tutorial explains 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).

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.

Goal: Project exists, materials defined, sites created, people assigned — before field work begins.

Phase B — Field start (mobile)

Phase C — Daily operations (mobile)

1. 1Loader: assign driver, display QR (or use printed loader paper QR from web site page).
2. 2Driver: scan QR to accept trip — status becomes driving.
3. 3Driver: transport; use verification codes if your process requires them.
4. 4Unloader: scan or verify to complete unloading — trip becomes unloaded.
5. 5If offline: when back online, Work → tap sync badge to upload queued actions.

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. Dialog shows allowed chainage range for the project.

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. 3Optionally filter by project and site.
4. 4Generate / refresh — driver-centric compliance-style summary.
5. 5Click equipment row for individual machine view (period may default to today — check on-screen labels).

• 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 (derived from material progress on cards).
• Sync badge (top right): upload offline queues when online.
• Project cards: name, dates, site count, progress — tap to continue.

Role priority (multiple hats)

If user has mixed roles, Work filters in order: Loader first, else Driver, else Unloader, else generic coordinator list.

1. 1
   Work → project

   Generic routing → Sites list with Active / Done / All.

2. 2
   Not Started site

   Site starter: assign loader per product place, assign supervisor, Start site when enabled.

3. 3
   Driver without loader sites

   Start may enable with supervisor only when office enabled the flag.

4. 4
   Loading / Done site

   Site detail — manage drivers, loaders, unloaders, view trucks.

5. 5
   Classify trip issues

   When driver reported issue — pick resolution type → pending_approval for backoffice.

1. 1
   Work → project

   See loader-assigned projects only.

2. 2
   Loader sites

   Lists sites in Loading status (Not Started may use Start loading flow first).

3. 3
   Loader site detail

   Refresh trucks → select driver → show QR in LoaderQRCodeDialog.

4. 4
   Wait for driver scan

   Online: immediate accept. Offline: show QR, sync later from Work.

5. 5
   Pending trips strip

   If offline at QR time, local pending items until sync succeeds.

1. 1
   Work → project → Driver sites

   Cards show chainage, pending cars, coarse status.

2. 2
   Scan QR

   Camera → scan loader QR → confirm → trip becomes driving (same trip, no duplicate).

3. 3
   Transport & codes

   Use car info and verification codes per site process.

4. 4
   Report trip issue

   If delivery went wrong — flags issue_reported for foreman.

5. 5
   Create trip without loader

   Only if site.allowDriverTripWithoutLoader — pick product + equipment; may need one online session to cache trucks.

1. 1
   Work → project → Unloading sites

   My unloading sites list.

2. 2
   Unloader site detail

   See incoming vs unloaded trucks.

3. 3
   Scan / complete unload

   Correct QR for trip → confirm → unloaded.

4. 4
   Refresh & sync

   Pull to refresh if stale; Work → sync after offline complete.

Sync all

1. 1Be online → Work → tap sync badge.
2. 2Upload order: creations → accepts → driver trips → completes (may repeat once).
3. 3Refreshes cached site data (bounded: up to 15 sites per project).
4. 4If N failed, stay online and sync again or contact support.

Some deployments use numeric codes alongside or instead of QR:

• Loader may show loader verification code with expiry on trip card.
• Driver enters or confirms driver code after scan.
• Unloader uses unloader verification code on car row.
• Expired codes show expired in UI — request regeneration per safety rules.

Office: project, site, workers, products
    ↓
Foreman: Site starter → loaders per place + supervisor → Start site
    ↓
Loader: assign driver → QR (or paper QR)
    ↓
Driver: scan QR → driving → transport
    ↓
Unloader: verify / scan → unloaded
    ↓
Office: optional GPS check → needs checking / approved
    ↓
Reports: dashboard, site generate-report, owner mobile Reports

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.

ComapySass backend can verify unloaded trips against survey Parquet (from project CSV):

• Runs periodically for trips with status unloaded and not yet checked.
• Compares driver/unloader GPS to survey point within ~100 m (Haversine).
• Trips may show needs checking until verified, then approved.

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).

• 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.

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.