# Polymer Procurement System — Complete Setup & Testing Guide

## 1. System Overview
A complete Polymer Procurement and Approval Management System built with **Laravel 11**, **MySQL / MariaDB**, **Blade**, **Tailwind CSS**, and **Alpine.js**.

### Key Architecture Implementations:
- **Universal Global Status Tracker (`All Polymer Status`)**: Every internal role can view the live progress, NAV references, receipts, and stage owners for every polymer request in the company.
- **Strict Role Boundaries**: Global visibility does **NOT** grant global edit or approval permissions. All transitions are protected by middleware and policies.
- **Vendor Portal Isolation**: Vendors can only access their own active RFQ invitations, authorized PDFs, and issued orders. Non-awarded requests are hidden immediately.
- **Dual PDF Storage Routing**: 
  - `≤ 100,000 bytes` (100 KB) → Private local application storage (`storage/app/private/attachments/`)
  - `> 100,000 bytes` → Company Google Drive integration.
- **Square Inch Canonical Area & Decimal Pricing**:
  - Formulas: `mm ÷ 645.16`, `cm ÷ 6.4516`, `m ÷ 0.00064516`, `inches × 1`.
  - Deterministic pricing: `per_sqin`, `per_piece`, `fixed_line`.
  - Discount validation: Discount cannot exceed base amount.
- **Microsoft NAV Manual Reference Gates**:
  - Stores records NAV PR reference.
  - Commercial records NAV PO reference.
- **Physical Stores Receiving & Dimensional Variance Review**:
  - Live square inch recalculation on receipt. Nonzero variances hold receipt and route to Marketing Manager & Finance review.

---

## 2. Windows PowerShell Setup & Test Commands

Run the following commands in your PowerShell terminal to prepare the database and execute tests:

### Step 1: Clean Scaffold Migrations & Run Database Migrations
```powershell
cd C:\xampp\htdocs\polymer

# 1. Remove standard default scaffold migrations if present
Get-ChildItem -Path "database\migrations\*0001_01_01*" -ErrorAction SilentlyContinue | Remove-Item -Force

# 2. Run all 24 system migrations
& "C:\xampp\php\php.exe" artisan migrate --force
```

### Step 2: Seed Development Roles, Accounts & Sample Workflow Requests
```powershell
# Run all database seeders
& "C:\xampp\php\php.exe" artisan db:seed --force
```

### Step 3: Run Automated Acceptance Tests (PHPUnit)
```powershell
# Run the complete test suite
& "C:\xampp\php\php.exe" artisan test tests/Feature/PolymerProcurementWorkflowTest.php
```

---

## 3. Development Test Accounts (Password: `Password123!`)

All accounts are active and ready for end-to-end testing:

| Role | Name | Email | Accessible Portal & Permissions |
|---|---|---|---|
| **Administrator** | Admin User | `admin@polymer.local` | Full System Admin, User/Vendor management, Global Status |
| **Marketing Assistant** | Saman Perera | `marketing.asst@polymer.local` | Request Creation Wizard, Drafts, Vendor Invitations, Global Status |
| **Marketing Assistant 2** | Nimal Silva | `marketing.asst2@polymer.local` | Request Creation, Global Status |
| **Marketing Manager** | Dilini Jayawardena | `marketing.mgr@polymer.local` | Quotation Comparison, Vendor Selection, Technical Variance Review, Global Status |
| **Finance** | Priya Fernando | `finance@polymer.local` | Commercial Review, Finance Approval / Return / Reject, Financial Variance, Global Status |
| **Stores** | Ruwan Bandara | `stores@polymer.local` | NAV PR Entry, Goods Receiving, Plate Measurement, Physical Hold, Global Status |
| **Commercial** | Kasun Rajapaksa | `commercial@polymer.local` | NAV PO Entry & Release, Snapshot baseline lock, Global Status |
| **Internal Viewer** | Viewer User | `viewer@polymer.local` | Read-only Global Status Tracker across all company requests |
| **Vendor 1** | Alpha Polymer | `vendor1@alphapolymer.lk` | Vendor Portal (Quotations, Drafts, Orders) |
| **Vendor 2** | Sigma Printing | `vendor2@sigmaprint.lk` | Vendor Portal (Quotations, Drafts) |
| **Vendor 3** | Ceylon Flexo | `vendor3@ceylonflexo.lk` | Vendor Portal (Quotations, Drafts) |

---

## 4. How to Test the Complete End-to-End Workflow in the Browser

Open your browser and navigate to:
**`http://localhost/polymer/public/login`** (or through XAMPP Apache virtual host)

### Scenario A: Testing Universal Global Status
1. Log in as `viewer@polymer.local`.
2. Notice the **All Polymer Status** menu in the sidebar.
3. Open it: you will see requests created by all Marketing Assistants, with live stages (`Draft`, `Quotation Open`, `Marketing Review`, `Finance Pending`, `Awaiting Receipt`).
4. Confidential notes and competitor quotes are safely hidden from this projection.

### Scenario B: Marketing Request & PDF Routing
1. Log in as `marketing.asst@polymer.local`.
2. Click **New Polymer Request**.
3. Complete the 4-step wizard:
   - NAV Estimate Number: `EST-2024-00999`
   - Cost Payer: `Company` or `Customer`
   - Enter lines (e.g., 254mm × 127mm, Qty: 2).
   - Select Vendors: `Alpha Polymer Supplies` and `Sigma Printing`.
   - Click **Submit & Invite Vendors**.
4. Attach a PDF ≤ 100 KB: Stored locally in `storage/app/private/attachments/`.

### Scenario C: Vendor Quoting & Area Calculations
1. Log in as `vendor1@alphapolymer.lk`.
2. Notice the vendor dashboard has **NO** access to internal global status tracker (`/status` will return 403 Forbidden).
3. Open the active invitation and click **Draft / Submit Quotation**.
4. Enter dimensions: Length `254`, Width `127`, Unit `mm`, Rate `LKR 12`.
5. Observe live area calculation: `50.00 in²` per piece, `100.00 in²` total area, Base Amount: `LKR 1,200.00`.
6. Click **Final Submit Quotation**.

### Scenario D: Marketing Manager Side-by-Side Comparison
1. Log in as `marketing.mgr@polymer.local`.
2. Go to **My Action Queue** or **Marketing Requests**.
3. Open the request in `Marketing Review` stage.
4. Click **Compare Quotations**.
5. Inspect the side-by-side comparison, enter selection justification reason, and click **Approve & Award Vendor**.
6. Vendor 2's portal will now automatically hide this order without showing rejection tags.

### Scenario E: Finance Approval & NAV Integration
1. Log in as `finance@polymer.local` → Click **Approve**.
2. Log in as `stores@polymer.local` → Go to **Stores NAV PR** → Enter `PR-2024-999` & Date → Record PR.
3. Log in as `commercial@polymer.local` → Go to **Commercial NAV PO** → Enter `PO-2024-999` & Date → Release PO.

### Scenario F: Physical Stores Receiving & Variance
1. Log in as `stores@polymer.local` → Go to **Stores Receiving**.
2. Record physical plate delivery note and actual plate measurements.
3. If received measurements match ordered baseline → Request completes.
4. If measurements deviate → Request automatically moves to `Variance Pending` on hold for review.

---

## 5. Google Drive Integration Setup

When you are ready to configure live Google Drive uploads for PDFs `> 100,000 bytes`:

1. Obtain Google Cloud Service Account JSON credentials with Drive API access.
2. In `.env`:
   ```dotenv
   FILE_SIZE_THRESHOLD_BYTES=100000
   GOOGLE_DRIVE_ENABLED=true
   GOOGLE_DRIVE_FOLDER_ID="your-google-drive-folder-id"
   ```
3. Place your service account JSON file in `storage/app/google-credentials.json` and protect it outside version control.