MEGAINFRA-WEBAPP/docs/setup/user-access.md

User access

Named PocketBase sign-in is required in every environment. Shared PIN sign-in is disabled, even if an old environment file still contains AUTH_MODE=pin.

Account type	App access	Site scope	User settings
Admin	Dashboard, Management, Ask, Clock	All sites	Manage users
Site manager	Operational dashboard and Clock	Assigned sites	Create and list clock accounts within assigned sites
Clock user	Clock only: worker/fleet scans and document uploads	Assigned sites	None
Office user	Selected dashboard sections with full actions	Assigned sites or All sites	None

Management planning

Management sits below Overview in the navigation. Its Turnover Overview, Project Planning, Retention and Year Comparison pages require a named admin account. Operational Site manager accounts and Office accounts have no access, including those with all sites or every operational section enabled. Future pages under /dashboard/management/ inherit this restriction.

The initial data comes from src/lib/management/workbook-snapshot.json, extracted from the supplied turnover workbook. data.ts checks access before loading it; model.ts calculates results independently. Replace the provider's source when connecting the planning database. Never import the snapshot into a client component or put it in public/.

The overview preserves the workbook's reported monthly income and cost summaries, including its manual values. Project detail remains separate and the reconciliation shows the differences. All amounts are ZAR. The main plan follows March–February headings from the workbook titled 2025, without inventing exact reporting years. Retention releases have their own supplied November 2025–October 2026 dates. Year Comparison follows the source's actual January–December 2024 and 2025 columns, including its estimates. There is no live actuals feed or planning editor yet.

Office setup

In Settings · Users, choose Office user, then an access preset (Workforce, Financial, or Plant) or select sections individually. At least one section is required. Each section includes its overview, details, imports, corrections, and future pages under the same section. Selecting several sections gives the user all of those sections. Overview is the company dashboard overview; Workforce's own overview is included with Workforce.

Choose All sites for head-office work spanning the company. This includes new sites automatically. Turn it off to select specific sites. Site lookup names and the site selector still work within enabled sections; this does not grant access to the Sites management section. Ask and user administration remain unavailable to Office users.

For Julius, after deploying this version, edit his existing account:

• Account type: Office user.
• Preset: Workforce (only Workforce selected).
• Site scope: All sites if his remit covers the company; otherwise select his sites.

He starts on Workforce overview and sees Workers, Timesheets, and On site now. Worker details, rates, sick notes, calendars, timesheet imports/upload status, and missed-clock-out corrections inherit Workforce access. Other section URLs redirect him to his first enabled section, and other section APIs return 403.

Schema rollout

Existing account roles, passwords, and sites are preserved. The additive migration adds office_user to users.role, multi-select users.modules (overview, sites, workforce, plant, financial), and Boolean users.all_sites. Existing non-office accounts retain their role defaults; office fields do not grant extra access to clock or site-manager accounts.

Run the dry run against the configured PocketBase environment:

python3 scripts/migrations/2026-10-07-office-access.py --env-file .env.local

Apply before deploying Office user settings, passing the exact URL printed by the dry run as --confirm-host:

python3 scripts/migrations/2026-10-07-office-access.py --env-file .env.local --apply --confirm-host "$POCKETBASE_URL"

This changes only the users collection fields. It does not convert Julius or any other existing account. Convert accounts after deploying, because the old app rejects the new Office user role.

Extending sections

src/lib/auth/path-access.ts is the shared page/API policy used by the proxy, navigation, and operation guard. New nested pages inherit their section root. Workforce employee, employer/broker and /api/workforce/ routes inherit Workforce access. Unknown API routes remain admin-only until assigned an explicit category.

A new /api/... route is invisible to site managers until it is named in src/lib/auth/proxy-path.ts. The proxy runs before the route handler, so an unclassified API path falls through to the admin-only default and the handler's own requireApiUser / canAccessSite checks never run. Symptom: an admin succeeds, a site manager gets {"error":"Not allowed"} (403) from the proxy, and the route's own tests still pass because they mock the guard. Name the route in classifyAuthPath and map it to a module in moduleForPath in the same change. npx vitest run src/lib/auth covers the policy.

Use getSiteScope(searchParams, "workforce") (or the relevant section) before loading page data, and requireApiUser("workforce") in its handlers. Shared operation routes use authorizeOperation(request) plus record/site checks. The only Financial handlers permitting clock accounts are document uploads and purchase-order upload status/retry; new dashboard operations must not use allowClock: true.