# 01 — Cloud Module Installation

Installing LabCore + at least one vendor module on the cloud ERP. Do this
**before** anything happens at the clinic side.

## Prerequisites

- Laravel 9 ERP running (this app), PHP 8.2+, MySQL/MariaDB.
- Spatie Permissions package (already a dependency).
- Module system (`nwidart/laravel-modules`) — already installed.
- A user with the `superadmin` permission (you'll need this to install modules).

## What gets installed

LabCore creates **11 tables** prefixed `lab_` and **9 permissions** prefixed
`lab.`:

| Table | Purpose |
|---|---|
| `lab_agents` | Registered LabBridge Agents (clinic sites) |
| `lab_devices` | Registered analyzers — vendor, model, connection settings |
| `lab_worklist` | Pending orders for analyzers |
| `lab_test_sessions` | One per analyzer run (keyed by `uuid` — the agent's idempotency key) |
| `lab_test_results` | Individual analyte readings |
| `lab_analyte_map` | Vendor analyte code → canonical name + reference range |
| `lab_communication_logs` | Protocol-level event log |
| `lab_device_connections` | Runtime connection log |
| `lab_device_errors` | Device-reported errors |
| `lab_settings` | Per-business key/value settings |

Permissions: `lab.access_module`, `.manage_worklist`, `.view_results`,
`.manage_results`, `.manage_devices`, `.manage_agents`, `.view_logs`,
`.access_settings`, `.superadmin`.

## Install LabCore

### Option A — through the Modules admin screen (recommended)

1. Sign in as a superadmin.
2. Go to **Modules** in the admin sidebar (or navigate to
   `/install/modules`).
3. Find **LabCore** in the list (status = "Not Installed").
4. Click **Install**.

That single click runs the equivalent of:

```bash
php artisan module:migrate LabCore
php artisan module:publish LabCore
```

and assigns all `lab.*` permissions to the current business's `Admin#{id}`
role, then sets the `LabCore_version` system property.

### Option B — from the command line

```bash
php artisan module:migrate LabCore
php artisan tinker --execute='
  \App\System::addProperty("LabCore_version", "1.0.0");
  $perms = ["lab.access_module","lab.manage_worklist","lab.view_results",
            "lab.manage_results","lab.manage_devices","lab.manage_agents",
            "lab.view_logs","lab.access_settings","lab.superadmin"];
  foreach (Spatie\Permission\Models\Role::where("name","like","Admin#%")->get() as $r) {
      $r->givePermissionTo($perms);
  }'
```

Use this for non-interactive deployments (CI, scripted installs, etc.).

## Install a vendor module

LabCore on its own is just an engine. To actually recognise an analyzer
brand you install a **vendor module**. Each one declares
`"requires": ["LabCore"]` in its `module.json` and registers a driver with
LabCore's `DriverRegistry`.

### AbaxisLab (Abaxis / Zoetis VetScan family)

```bash
php artisan module:migrate AbaxisLab
php artisan tinker --execute='\App\System::addProperty("AbaxisLab_version","1.0.0");'
```

Or use the Modules admin screen (same flow as LabCore).

This seeds **31 VetScan analytes** (chemistry + hematology) into
`lab_analyte_map`. Models covered: VetScan VS2, HM5, HM2, VSpro, i-STAT
Alinity v, UA, SA.

### NX600Lab

Already-installed users: NX600Lab automatically advertises itself to LabCore
once LabCore is installed — no separate action needed. The NX600 driver
registers from `NX600LabServiceProvider::boot()`.

## Verify the install

```bash
php artisan tinker --execute='
  echo "LabCore_version: ".(\App\System::getProperty("LabCore_version") ?: "MISSING").PHP_EOL;
  echo "Drivers: ".implode(",", array_keys(
      Modules\LabCore\Entities\Services\DriverRegistry::all()
  )).PHP_EOL;
  echo "lab_agents exists: ".(\Schema::hasTable("lab_agents") ? "YES" : "NO").PHP_EOL;'
```

Expected output:

```
LabCore_version: 1.0.0
Drivers: abaxis,nx600           # vendor modules installed
lab_agents exists: YES
```

Then in the browser, navigate to `/lab` — the dashboard should render. The
"Registered Vendors" widget should list every installed vendor driver.

## Updating

To update LabCore (e.g. after pulling a new release):

```bash
php artisan module:migrate LabCore   # idempotent — only runs new migrations
```

The `LabCore_version` system property is set by the InstallController's
`update()` action; if you migrated via CLI, set it manually:

```bash
php artisan tinker --execute='\App\System::setProperty("LabCore_version","1.x.x");'
```

## Uninstall

Removing a vendor module:

```bash
php artisan tinker --execute='\App\System::removeProperty("AbaxisLab_version");'
```

This hides the vendor in the Modules admin screen but **does not** drop the
analyte-map seed rows it inserted into `lab_analyte_map`. Drop them
manually if you want a fully clean slate:

```sql
DELETE FROM lab_analyte_map WHERE vendor = 'abaxis';
```

Removing LabCore itself is destructive (it drops all `lab_*` data). If you
really mean it:

```bash
php artisan module:migrate-reset LabCore
php artisan tinker --execute='\App\System::removeProperty("LabCore_version");'
```

## Next

Now install the [LabBridge Agent](02-agent-installation.md) on at least one
clinic PC, then [wire up your first device](03-device-integration.md).
