technical-services-exchange/docs/PHASE1_WORKFLOW_VALIDATION.md

# Phase 1 Workflow Validation

Use this checklist to validate the current Provider Exchange / Technical Services Exchange prototype against real buyer and provider workflows.

This is not a release checklist. It is a product-truth pass: record what works, what is confusing, and what blocks a real pilot.

## Setup

1. Refresh the local database only when destructive reset is acceptable:

   ```bash
   php artisan migrate:fresh --seed
   ```

2. Build assets:

   ```bash
   npm.cmd run build
   ```

3. Start the local server:

   ```bash
   php artisan serve --host=0.0.0.0 --port=8123
   ```

4. Use seeded demo users:

   - `admin@example.com`
   - `provider@example.com`
   - `buyer@example.com`
   - `hybrid@example.com`

   The shared seed password is documented in the private KeePass project entry.

## Seeded Scenario Set

The seeder provides these validation jobs:

- `Demo POS troubleshooting visit`: assigned work order with quote, review, and dispute records for end-to-end workflow checks.
- `Validation remote firewall rule review`: open, clear, remote, higher-level networking job for filter and quote checks.
- `Validation risky smart-hands dispatch`: open, risky, incomplete support/scope job for risk badge and hide-risk validation.

## Public Discovery

Validate without logging in first.

- Home page loads.
- Terms page loads.
- Provider directory loads and shows seeded provider.
- Buyer directory loads and shows seeded buyer.
- Job board loads and shows open public jobs.
- Job board filters work:
  - keyword;
  - work category;
  - technician level;
  - scope clarity;
  - support certified;
  - remote only;
  - hide risky.
- Provider profile shows public sections only.
- Buyer profile shows public sections only.
- Job detail shows scope, support/contact status, risk flags, quotes, comments, attachments, and report controls.

Record gaps in `docs/PHASE1_GAP_REPORT_TEMPLATE.md`.

## Buyer Workflow

Log in as `buyer@example.com`.

- Buyer dashboard loads.
- Buyer profile edit saves:
  - company details;
  - hiring regions;
  - hiring policies;
  - locations;
  - payment terms;
  - visibility controls.
- Buyer can create a clear job with:
  - category and specialty;
  - technician level;
  - work mode;
  - schedule;
  - structured scope;
  - deliverables;
  - support/contact certification;
  - terms summary.
- Created job appears on the job board.
- Buyer can review incoming quotes.
- Buyer can accept a quote and create a work order.
- Buyer can message on a work order.
- Buyer can approve completed work.
- Buyer can review provider.
- Buyer can open or respond to a dispute.
- Buyer can report profiles, jobs, or attachments for moderation.

## Provider Workflow

Log in as `provider@example.com`.

- Provider dashboard loads.
- Provider profile edit saves:
  - business identity;
  - service area;
  - services;
  - tool inventory;
  - certifications;
  - insurance;
  - rate card;
  - availability;
  - taxonomy tags;
  - imported history;
  - visibility controls.
- Provider can filter available jobs to find:
  - clear remote networking work;
  - risky jobs when hide-risk is off;
  - no risky jobs when hide-risk is on.
- Provider can submit a quote.
- Provider can update a quote before acceptance.
- Provider can transition assigned work:
  - en route;
  - onsite;
  - in progress;
  - completed.
- Provider can update checklist state.
- Provider can upload evidence.
- Provider can upload private Field Nation or WorkMarket source material in the import source vault.
- Provider can parse text-like Field Nation source material into a private imported-history draft.
- Provider can approve a parsed draft into a private imported-history summary.
- Provider can send work-order messages.
- Provider can log contact/support failure.
- Provider can request a change.
- Provider can open a dispute.
- Provider can respond to a buyer review.

## Hybrid Workflow

Log in as `hybrid@example.com`.

- Confirm the user can access both buyer and provider profile surfaces.
- Confirm role-specific actions still enforce participant boundaries.
- Confirm hybrid user does not accidentally gain admin moderation powers.

## Admin Workflow

Log in as `admin@example.com`.

- Admin dashboard loads.
- Counts are understandable.
- Recent users, jobs, work orders, disputes, imported histories, moderation reports, and audit logs are visible.
- Admin can verify imported provider history.
- Admin can identify whether imported-history proof came from a manual entry or a source batch once the urgent import lane is implemented.
- Admin can moderate reported reviews.
- Admin can triage moderation reports.
- Admin-only pages reject non-admin users.

## API Workflow

Use Sanctum tokens or existing API tests to validate:

- `GET /api/v1/me`
- `GET /api/v1/jobs`
- `GET /api/v1/work-orders`
- `GET /api/v1/work-orders/{workOrder}`
- `PATCH /api/v1/work-orders/{workOrder}/transition`
- `PATCH /api/v1/work-orders/{workOrder}/checklist`
- `POST /api/v1/work-orders/{workOrder}/messages`
- `POST /api/v1/work-orders/{workOrder}/evidence`
- `POST /api/v1/work-orders/{workOrder}/contact-events`
- `POST /api/v1/work-orders/{workOrder}/running-late`
- `POST /api/v1/work-orders/{workOrder}/schedule-updates`
- `POST /api/v1/work-orders/{workOrder}/disputes`

For every API check, confirm:

- token ability enforcement;
- buyer/provider/admin participant boundaries;
- audit record creation where expected;
- optional geolocation stays action-scoped.

## Live Deployment Check

Only run this section when live deployment validation is in scope.

- `https://christit.com/tse` loads.
- `https://christit.com/tse/login` loads.
- Seeded admin login works only if the deployment intentionally has seeded demo users.
- Public job board and directories render with correct `/tse` paths.
- Uploaded/public assets resolve under the deployment base path.
- `bash scripts/health-check.sh` passes on the server.

## Completion Criteria

Phase 1 is complete when:

- the checklist has been walked locally;
- any live check that was in scope has been recorded;
- gaps are captured with role, URL, expected result, actual result, severity, and proposed next phase;
- the roadmap has been adjusted if validation changes the priority order.