# GSB Construction ERP — End-to-End System Workflow Test Cases

## 1. Purpose

This document defines the complete business-workflow test plan for the GSB Construction ERP. It covers authentication, contractor tenancy, roles, projects, bidding, project execution, materials, finance, approvals, dashboards, and cross-role visibility.

This is a test specification. Discovered defects must be recorded in the defect log and must not be fixed during the test run.

## 2. Test Rules

- Use a disposable or staging database only.
- Use the same test records across a workflow so each state transition can be verified.
- Follow Arrange → Act → Assert for every case.
- Record the user, role, contractor, project, route, request payload, response, database state, and screenshot for failures.
- A workflow passes only when the UI result, server response, authorization rule, and database state agree.
- Do not mark a case passed because a page loads; verify the action and resulting data.

## 3. Test Environment

| Item | Requirement |
|---|---|
| Backend | Laravel application with migrations loaded |
| Frontend | Vite development build or compiled production assets |
| Database | Disposable database with seed data plus test fixtures |
| Browser | Chromium/Chrome, desktop width, responsive width |
| Browser checks | Console free of uncaught exceptions; network requests return expected status |
| Build checks | `npx tsc --noEmit`, `npm run build`, `php artisan test` |
| Date/time | Confirm expected timezone and date formatting before testing reports and deadlines |

## 4. Required Test Accounts and Data

Create these accounts before execution. Replace the placeholder emails with unique test emails.

| ID | Account | Role | Contractor |
|---|---|---|---|
| U-01 | Platform owner | Super Admin | None |
| U-02 | Platform administrator | admin | None |
| U-03 | Project manager | Project Manager | None |
| U-04 | Main contractor administrator | Main Contractor Admin | C-01 |
| U-05 | Main contractor user | Main Contractor User | C-01 |
| U-06 | Site technical user | Site Technical | C-01 |
| U-07 | Construction supervisor | Construction Supervisor | C-01 |
| U-08 | Site operations user | Site Operations | C-01 |
| U-09 | Subcontractor administrator | Sub Contractor Admin | C-02, child of C-01 |
| U-10 | Unrelated contractor user | Contractor User | C-03 |

Create at least:

| ID | Fixture | Required state |
|---|---|---|
| C-01 | Great SwissMetal Builders Corporation | Active main contractor |
| C-02 | C-01 subcontractor | Active child contractor |
| C-03 | Unrelated contractor | Active separate tenant |
| P-01 | Main construction project | Draft, then initialized at wizard step 7 |
| P-02 | C-01 active project | `planning` or `in_progress` |
| P-03 | C-03 project | Must never appear to C-01 users |
| M-01 | Material catalog item | Active, with unit and cost |
| L-01 | Labor record | Active labor/trade |
| E-01 | Equipment record | Active equipment |

## 5. Role and Tenant Access Matrix

Run the matrix against every protected module. “Own tenant” means the user’s contractor and permitted contractor hierarchy. “Related project” means a project directly owned by, linked to, or assigned to that contractor according to the application rule.

| Area | Super Admin/admin | Project Manager | Contractor Admin | Site Technical/Supervisor/Operations | Unrelated contractor |
|---|---:|---:|---:|---:|---:|
| Dashboard | Global | Assigned/allowed scope | Contractor dashboard | Related project scope | Own scope only |
| Users | Global administration | According to permission | Own contractor users | No administration unless explicitly granted | Own contractor only |
| Projects | Global | Project scope | Own contractor scope | Related project scope | Own contractor scope |
| Bid package management | Yes | Yes | According to configured role rule | No | No |
| Bid submissions | Yes | Yes | Yes for invited contractor | No | Only invited packages |
| Material requisitions | Global | Create/approve as assigned | Own contractor/project | Create on related project | Own scope |
| Purchase orders | Global | Create/approve as assigned | Own contractor/project | Operate related project | Own scope |
| Cash advances | Global approver | Approve other users’ requests | Own contractor rules | Create, not self-approve | Own scope |
| Invoice/retention approvals | Global | As configured | As configured | No approval unless configured | Own scope |
| Documents/daily reports/tasks | Global | Assigned/managed projects | Own contractor projects | Related projects only | Own scope |

Any deviation must be logged as a defect, including both unexpected access and missing access.

## 6. End-to-End Workflow Cases

### WF-01 — Authentication and account lifecycle

| Field | Test |
|---|---|
| Preconditions | U-01 through U-10 exist; active and inactive accounts are available |
| Steps | Log in with valid credentials; log out; attempt invalid password; attempt inactive account; reset password; complete forced password change |
| Expected | Valid users reach the correct dashboard; invalid users receive a safe error; inactive users are blocked; password reset and forced password change complete successfully |
| Security | No password or sensitive token appears in the UI, URL, response, or logs |

### WF-02 — Contractor onboarding and tenant assignment

| Field | Test |
|---|---|
| Actor | U-01 or U-02 |
| Steps | Create C-01 with administrator; verify administrator is linked to C-01; create C-02 as child contractor; create U-05/U-06/U-07 under C-01; create U-09 under C-02 |
| Expected | Contractor records, user records, roles, profile records, and contractor IDs are consistent; users created by a contractor admin inherit that contractor |
| Negative | Attempt to assign a contractor user to C-03 from a C-01 admin account; request is rejected and no cross-tenant change is saved |

### WF-03 — User management and role enforcement

| Field | Test |
|---|---|
| Actor | U-01, U-04, U-09 |
| Steps | List users; create user; edit user; assign each supported role; deactivate user; attempt to view/edit a user from another contractor |
| Expected | Platform users see global users; contractor admins see only their permitted contractor tree; role names and permissions persist; deactivated users cannot log in |
| Negative | Site technical and supervisor accounts cannot access user-management actions unless explicitly permitted |

### WF-04 — Project creation and initialization wizard

| Field | Test |
|---|---|
| Actor | U-02, U-03, U-04 |
| Steps | Create P-01; enter project information; add milestones; add tasks; add materials; add labor; add equipment; review financial submission; submit final initialization |
| Expected | Each step saves; back/next navigation preserves data; validation rejects incomplete required data; step number advances correctly; initialized project is visible to permitted users |
| Database assertions | `projects.current_wizard_step`, project status, contractor ID, milestones, tasks, estimates, labor, equipment, and personnel links are correct |
| Negative | A draft project is not treated as an initialized execution project; an unrelated contractor cannot open P-01 |

### WF-05 — Project visibility and cross-role reflection

| Field | Test |
|---|---|
| Actor | U-04 creates/updates; U-05/U-06/U-07/U-08 verify |
| Steps | U-04 initializes or updates P-01; sign in as every C-01 role; inspect Projects, project details, tasks, daily reports, documents, inventory, finance, and dashboard |
| Expected | All permitted C-01 roles see the same contractor-related project state; restricted actions remain hidden or forbidden; C-03 users never see P-01 |
| Important | Verify both a fresh login and navigation from an already-open session. Record whether updates require manual refresh according to the intended product behavior |

### WF-06 — Bid package lifecycle

| Field | Test |
|---|---|
| Actor | U-03 or authorized contractor project-management role |
| Steps | Create package for initialized P-01; verify initial draft; add scope, criteria, dates, and documents; invite C-01/C-02/C-03 as appropriate; publish; edit while allowed; close/cancel; award |
| Expected | Package remains draft until published; draft cannot accept submissions; published package is visible only to invited contractors; status transitions follow allowed rules; awarded package records winner |
| Negative | Contractor User, Site Operations, Site Technical, and Supervisor cannot create/manage packages unless policy explicitly grants it; a draft package must not be displayed as an open bid |

### WF-07 — Contractor bid submission and evaluation

| Field | Test |
|---|---|
| Actor | Invited contractor user/admin and U-03 |
| Steps | Open invitation; submit proposal and price; edit before closing; attempt duplicate submission; evaluate using simple mode; evaluate using scored criteria; award/reject |
| Expected | Only invited contractor can submit; required fields validate; duplicate and late submissions are handled correctly; scores and totals are persisted; award updates package and submission status |
| Database assertions | Invitations, submissions, evaluation criteria, scores, total score, award fields, and timestamps match the UI |

### WF-08 — Tasks, milestones, and progress

| Field | Test |
|---|---|
| Actor | U-03, U-06, U-07 |
| Steps | Create task under milestone; move Pending → In Progress → Completed; test Blocked and Closed; open information modal; add materials, labor, and equipment; assign user; record activity |
| Expected | Only valid transitions are available; transition buttons appear in the information modal; blocked/closed rules work; costs and progress recalculate; activity log records actor and time |
| Negative | Invalid transitions and unauthorized updates return a controlled error and preserve the previous state |

### WF-09 — Daily reports and resource roll-up

| Field | Test |
|---|---|
| Actor | U-06/U-07 |
| Steps | Create multiple daily reports for P-01 on different dates; add multiple labor rows, trades, equipment rows, materials, activities, and issues; edit one report; inspect dashboard ResourceSummary |
| Expected | Dashboard labor totals use all intended daily-report labor records; trade totals aggregate correctly; equipment counts follow the documented aggregation rule; blockers and activity feed show permitted reports |
| Negative | Reports from P-03 or unrelated contractors never affect C-01 dashboard totals |

### WF-10 — Material requisition approval workflow

| Field | Test |
|---|---|
| Actor | Site role creates; Project Manager/executive role approves |
| Steps | Create draft requisition; add materials; save; submit; inspect approver availability; approve; reject a second request; inspect sidebar badge for each role |
| Expected | Draft is visible to its creator; submitted request is visible to the correct approvers; Project Manager and executive approver rules work; approval changes status and audit history; unrelated roles do not receive irrelevant alerts |
| Negative | No-approver condition is reported clearly and does not create a falsely submitted request |

### WF-11 — Purchase order workflow

| Field | Test |
|---|---|
| Actor | Authorized logistics user; Project Manager/executive approver |
| Steps | Create PO from requisition or manually; add supplier/items; submit; approve/reject; mark delivered; upload receipt; mark paid; inspect list/detail pages |
| Expected | PO status transitions are valid; approver list follows configured roles; delivery and payment buttons appear only when applicable; receipt and payment data persist; tenant restrictions hold |
| Negative | Site roles cannot approve or update finance-sensitive states without permission; null project/supplier relations do not crash the page |

### WF-12 — Inventory, warehouse, movements, and transfers

| Field | Test |
|---|---|
| Steps | Receive delivered PO; verify warehouse stock; create movement; transfer between warehouses; inspect project inventory and available quantities; attempt insufficient-stock transfer |
| Expected | Quantities, on-hand, allocated, received, and transferred values remain consistent; invalid quantities are rejected; users see only permitted warehouses and projects |

### WF-13 — Cash advance direct approval

| Field | Test |
|---|---|
| Actor | Site/contractor user creates; Project Manager or executive approves |
| Steps | Submit cash advance; verify pending status; inspect Approvals page; attempt self-approval; approve as authorized PM/executive; reject another request |
| Expected | Cash advances appear directly in the approvals workspace without an approval-chain record if that is the configured rule; self-approval is blocked; approval/rejection records approver and timestamp |

### WF-14 — Invoice and retention approval

| Field | Test |
|---|---|
| Steps | Create/submit invoice with retention; inspect approval item; open breakdown; approve; verify invoice status and retention hold; reject another invoice; inspect retention page |
| Expected | Invoice and retention information appears in approvals; approved invoice updates status and retention ledger exactly once; rejected invoice remains rejected; null project relations render safely |

### WF-15 — Documents, drawings, and technical records

| Field | Test |
|---|---|
| Steps | Upload document to P-01; categorize; view/download; update status; attempt access from C-03; inspect project Documents and sidebar navigation |
| Expected | File metadata and project/contractor relation persist; permitted roles can view/download; unrelated tenant receives 403/404 according to policy; missing files produce controlled errors |

### WF-16 — Dashboard role routing and data accuracy

| Field | Test |
|---|---|
| Steps | Log in as U-01 through U-10; inspect dashboard heading and cards; compare every displayed count with database queries for the same scope; inspect Site, PM, Contractor, and Executive layouts |
| Expected | Super Admin/admin → Executive; Project Manager → PM; Contractor Admin/Main/Sub Contractor roles → Contractor; site roles → Site; contractor admin with `user_type=admin` remains Contractor when its assigned role is contractor-based |
| Data checks | Project counts use valid project statuses; labor uses intended daily-report aggregation; finance, approvals, documents, inventory, and bidding metrics are tenant/project scoped |

### WF-17 — Sidebar navigation and role visibility

| Field | Test |
|---|---|
| Steps | Capture sidebar for every role; open every visible parent and child item; directly request hidden routes; inspect badges after creating drafts/submissions/approvals |
| Expected | Navigation matches permissions and role policy; Bidding is absent from site operations roles where required; badges are relevant to the current role; direct URL access is denied even if a link is hidden |

### WF-18 — Security and tenant isolation regression

| Field | Test |
|---|---|
| Steps | From U-04/U-05/U-06/U-07/U-08/U-09, request P-03, its tasks, reports, inventory, invoices, requisitions, POs, documents, bids, and users by URL/ULID; repeat with guessed numeric IDs |
| Expected | No cross-tenant record is returned, modified, or deleted; response is 403/404 as designed; no sensitive data leaks through Inertia props, JSON, exports, or error messages |

### WF-19 — Validation, error handling, and null relationships

| Field | Test |
|---|---|
| Steps | Submit empty forms; invalid dates; negative quantities; missing project; deleted/null related user, contractor, supplier, or project; duplicate codes/numbers; expired invitation |
| Expected | Server validation is returned to the form; no uncaught React error occurs; pages show a safe fallback such as “Unavailable”; no partial transaction remains in the database |

### WF-20 — Responsive and browser workflow

| Field | Test |
|---|---|
| Steps | Repeat critical pages at desktop, tablet, and mobile widths; open sidebar; open modals; scroll tables; use keyboard navigation; test dark mode if enabled |
| Expected | Grids collapse correctly; buttons remain reachable; modals fit viewport; tables remain usable; focus states and labels are available; no horizontal overflow blocks actions |

## 7. Execution Record

Use one row per case execution.

| Case ID | Date | Build/commit | Actor | Result | Evidence | Defect ID |
|---|---|---|---|---|---|---|
| WF-01 |  |  |  | NOT RUN |  |  |
| WF-02 |  |  |  | NOT RUN |  |  |
| WF-03 |  |  |  | NOT RUN |  |  |
| WF-04 |  |  |  | NOT RUN |  |  |
| WF-05 |  |  |  | NOT RUN |  |  |
| WF-06 |  |  |  | NOT RUN |  |  |
| WF-07 |  |  |  | NOT RUN |  |  |
| WF-08 |  |  |  | NOT RUN |  |  |
| WF-09 |  |  |  | NOT RUN |  |  |
| WF-10 |  |  |  | NOT RUN |  |  |
| WF-11 |  |  |  | NOT RUN |  |  |
| WF-12 |  |  |  | NOT RUN |  |  |
| WF-13 |  |  |  | NOT RUN |  |  |
| WF-14 |  |  |  | NOT RUN |  |  |
| WF-15 |  |  |  | NOT RUN |  |  |
| WF-16 |  |  |  | NOT RUN |  |  |
| WF-17 |  |  |  | NOT RUN |  |  |
| WF-18 |  |  |  | NOT RUN |  |  |
| WF-19 |  |  |  | NOT RUN |  |  |
| WF-20 |  |  |  | NOT RUN |  |  |

## 8. Defect Log

Record defects without changing code during this test pass.

| Defect ID | Case | Severity | Preconditions | Steps to reproduce | Expected | Actual | Evidence | Status |
|---|---|---|---|---|---|---|---|---|
| D-001 | WF-02 | Major | Fresh test database; guest contractor registration | Submit the contractor registration form with valid data | Registration redirects successfully, creates pending contractor/admin records, and assigns the configured role | HTTP 500: `Spatie\\Permission\\Exceptions\\PermissionDoesNotExist` because `users.access` is missing when `ContractorOnboardingController.php:66` calls `givePermissionTo('users.access')` | `tests/Feature/ContractorOnboardingTest.php::test_guest_can_register_as_contractor` | Resolved |
| D-002 | WF-13 | Major | Comprehensive E2E fixture; supervisor and initialized project | Submit a cash advance and query the created request | A pending cash advance exists for the submitted amount | `CashAdvance::where('amount', 750.50)->firstOrFail()` finds no record at `ComprehensiveSystemE2ETest.php:156` | `tests/Feature/ComprehensiveSystemE2ETest.php::test_e2e_cash_advance_full_lifecycle_and_security_rules` | Open |
| D-003 | WF-04 | Major | Project at wizard step 6; no approver IDs | Submit final project initialization with `approver_ids: []` | Validation error is returned for `approver_ids` | Response does not contain the expected session validation error | `tests/Feature/ProjectWizardFlowTest.php::submit_fails_without_approvers` | Open |

Severity guide: Blocker = workflow cannot continue or data/security risk; Critical = major business flow or tenant isolation failure; Major = important function incorrect; Minor = non-blocking UI or copy issue.

## 9. Automated Baseline

At the time this document was created:

| Check | Result | Notes |
|---|---|---|
| `npx tsc --noEmit` | PASS | TypeScript completed successfully during the current verification run |
| `npm run build` | PASS | Vite production build completed successfully during the current verification run |
| `php artisan test --testsuite=Feature --stop-on-failure --debug` | FAIL | 23 passed, 2 failed, 85 pending; first confirmed failure is D-001 |
| `php artisan test tests/Feature/ContractorOnboardingTest.php --debug` | FAIL | 4 passed, 1 failed; D-001 reproduced in 3.90s |
| Existing `ComprehensiveSystemE2ETest` | PARTIAL COVERAGE | Covers page traversal, cash advance, invoice/retention, and part of project wizard; it does not cover all workflows in this document |

## 10. Exit Criteria

The whole-system workflow is ready for sign-off only when:

- All WF-01 through WF-20 have a recorded result.
- No Blocker or Critical defects remain open.
- Tenant isolation cases pass for main contractors, subcontractors, site roles, and unrelated contractors.
- Project wizard, bidding, requisition, PO, inventory, cash advance, invoice/retention, and dashboard flows pass end-to-end.
- Browser console has no uncaught errors on tested pages.
- Database assertions and UI states agree for every completed workflow.
- Failed automated tests are either rerun successfully or documented with an approved exception.
