# Procurement Module — Installation Guide

## Overview

Internal-only procurement system for Aatrral Industries LLC.

- **URL:** `https://aatrral.com/internal/procurement/login`
- **Login:** `procurement@aatrral.com` / `ChangeMe2026!` ← **change this immediately**
- **Auth:** Completely separate from the ecommerce system (own guard, own table)
- **Tables:** All prefixed `procurement_` — zero collision risk

---

## Step 1 — Copy the Module

```bash
cp -r /path/to/Procurement /var/www/aatrral/Modules/Procurement
```

---

## Step 2 — Register Middleware Aliases

Open `app/Http/Kernel.php` and add to the `$middlewareAliases` array:

```php
'procurement.auth'  => \Modules\Procurement\Http\Middleware\ProcurementAuth::class,
'procurement.guest' => \Modules\Procurement\Http\Middleware\ProcurementGuest::class,
```

---

## Step 3 — Enable the Module

```bash
cd /var/www/aatrral
php artisan module:enable Procurement
```

Or add manually to `modules_statuses.json`:

```json
"Procurement": true
```

---

## Step 4 — Run Migrations

```bash
php artisan migrate --path=Modules/Procurement/Database/Migrations
```

This creates 15 tables:

| Table | Purpose |
|---|---|
| `procurement_users` | Login accounts (isolated from ecommerce) |
| `procurement_projects` | Products (SSW100, future products) |
| `procurement_runs` | Production runs (Run 1/2/3) |
| `procurement_suppliers` | Supplier contacts, account numbers |
| `procurement_avl` | Approved Vendor List |
| `procurement_components` | BOM — part#, alts, cost, MOQ, tariff, HS code |
| `procurement_component_revisions` | Auto-logged field changes |
| `procurement_price_history` | Price tracking with qty breaks |
| `procurement_stock` | On-hand inventory per component |
| `procurement_exchange_rates` | CNY/USD and other rates |
| `procurement_purchase_orders` | POs with full cost breakdown |
| `procurement_po_line_items` | Line items with tariff, MOQ, replenish qty |
| `procurement_receiving` | Goods receipt log (auto-updates stock) |
| `procurement_invoices` | Invoice tracking with tariff + customs |
| `procurement_documents` | File attachments (polymorphic) |

---

## Step 5 — Seed Data

```bash
php artisan db:seed --class=Modules\\Procurement\\Database\\Seeders\\ProcurementSeeder
```

The seeder creates:
- Login user: `procurement@aatrral.com`
- SSW100 project + Run 1 (50u), Run 2 (300u), Run 3 (500u)
- 6 suppliers (TI, Mouser, Codaca, JLCPCB, FTDI, Microchip)
- Full 12-component SSW100 BOM with AVL, stock records, and initial price history
- CNY↔USD exchange rates

---

## Step 6 — Change the Default Password

**Do this immediately.** Via Tinker:

```bash
php artisan tinker
>>> \Modules\Procurement\Models\ProcurementUser::where('email','procurement@aatrral.com')
      ->update(['password' => bcrypt('YourNewStrongPassword')]);
```

---

## Step 7 — Set Up Document Storage

Documents are stored in `storage/app/procurement/documents/`.

Make sure this path is writable:

```bash
mkdir -p /var/www/aatrral/storage/app/procurement/documents
chmod -R 775 /var/www/aatrral/storage/app/procurement
```

---

## Step 8 — Clear Caches

```bash
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear
```

---

## Step 9 — Verify

Navigate to `https://aatrral.com/internal/procurement/login`

Log in with `procurement@aatrral.com` and your new password. You should see:

- Dashboard with SSW100 BOM cost and 12 components pre-loaded
- Projects → SSW100 with 3 runs
- Components → 12 BOM items with part numbers, alt parts, lead times, tariffs
- Suppliers → 6 suppliers with contacts

---

## Key Behaviors

**Auto-revision tracking** — When a component's `part_number`, `unit_cost`, `supplier`, `status`, `alt_part_number_1`, `alt_part_number_2`, or `manufacturer` changes, a revision record is automatically created in `procurement_component_revisions`.

**Auto-stock update** — When a receiving record is created with `condition = good`, the component's stock `qty_on_hand` is automatically incremented and the PO line item `qty_received` is updated.

**Auto-PO total** — PO totals recalculate automatically when line items are saved.

**Invoice overdue detection** — Invoices with `status = unpaid` and `due_date` in the past are flagged overdue on the dashboard and invoice list.

**Document storage** — Documents upload to `storage/app/local` (not public). They are tracked by filename/path only; direct download links are not implemented in v1 — add a download route if needed.

---

## Security Notes

- The `/internal/procurement` prefix is not linked from anywhere on the main site
- The procurement auth guard is completely isolated — compromising the ecommerce session does not grant procurement access
- No robots.txt exclusion is added automatically — consider adding `/internal/*` to your robots.txt to avoid indexing
- All procurement tables are separate — no foreign keys to ecommerce tables

---

## Robots.txt

Add this to `/var/www/aatrral/public/robots.txt` to prevent indexing:

```
User-agent: *
Disallow: /internal/
```