# MetLAB — Metrology Laboratory Management System
### Ghana Standards Authority — Scientific Metrology Division

---

## Overview

MetLAB is a complete web-based Laboratory Management Portal supporting nine metrology
laboratories. It includes role-based access control, request management, generic lab work
forms, PDF certificate generation, DCC-compliant XML certificate generation, and full
activity logging.

---

## System Requirements

| Component | Minimum |
|-----------|---------|
| PHP       | 8.1+    |
| MySQL     | 8.0+    |
| Apache    | 2.4+ (with mod_rewrite) |
| wkhtmltopdf | Optional — enables true PDF output |

---

## Project Structure

```
metlab/
├── index.php                  ← Front controller / router
├── ajax.php                   ← AJAX endpoints (dropdowns)
├── .htaccess                  ← Apache config
│
├── config/
│   ├── config.php             ← App constants (DB, paths, etc.)
│   └── database.php           ← PDO singleton
│
├── controllers/
│   ├── AuthController.php
│   ├── DashboardController.php
│   ├── UserController.php
│   ├── LabController.php
│   ├── CompanyController.php
│   ├── ContactController.php
│   ├── EquipmentController.php
│   ├── RequestController.php
│   ├── WorkFormController.php
│   ├── CertificateController.php
│   ├── LogController.php
│   └── ProfileController.php
│
├── helpers/
│   └── functions.php          ← Auth, CSRF, OTP, logging, helpers
│
├── views/
│   ├── auth/
│   │   ├── login.php
│   │   └── otp.php
│   ├── shared/
│   │   ├── header.php         ← Main layout (sidebar + topbar)
│   │   ├── footer.php
│   │   ├── dashboard.php
│   │   ├── requests_index.php
│   │   ├── request_form.php
│   │   ├── request_view.php
│   │   ├── profile.php
│   │   └── 404.php
│   ├── admin/
│   │   ├── users_index.php
│   │   ├── users_form.php
│   │   ├── labs_index.php
│   │   ├── lab_form.php
│   │   └── logs.php
│   ├── frontdesk/
│   │   ├── companies_index.php
│   │   ├── company_form.php
│   │   ├── company_view.php
│   │   ├── contact_form.php
│   │   ├── equipment_index.php
│   │   └── equipment_form.php
│   └── lab/
│       ├── workform.php       ← Generic lab work form (all 9 labs)
│       ├── certificates_index.php
│       └── certificate_view.php
│
├── public/
│   ├── css/style.css
│   ├── js/app.js
│   └── uploads/signatures/   ← Officer signature images
│
├── certificates/              ← Generated PDF & XML files (writable)
│
└── database/
    └── schema.sql             ← Full database schema + seed data
```

---

## Installation

### Step 1 — Clone / Copy Files
Place the `metlab/` folder inside your web root, e.g.:
- XAMPP: `C:\xampp\htdocs\metlab\`
- Ubuntu: `/var/www/html/metlab/`

### Step 2 — Create the Database
```sql
-- In phpMyAdmin or MySQL CLI:
SOURCE /path/to/metlab/database/schema.sql;
```

### Step 3 — Configure the App
Edit `config/config.php`:
```php
define('DB_HOST',  'localhost');
define('DB_NAME',  'metlab_db');
define('DB_USER',  'your_db_user');
define('DB_PASS',  'your_db_password');
define('APP_URL',  'http://localhost/metlab');
```

### Step 4 — Set Directory Permissions
```bash
chmod 755 metlab/certificates/
chmod 755 metlab/public/uploads/signatures/
```
Both directories must be **writable** by the web server.

### Step 5 — Default Admin Login
| Field    | Value             |
|----------|-------------------|
| Email    | admin@gsa.gov.gh  |
| Password | Admin@12345       |

> **Important:** Change the admin password immediately after first login.
> The bcrypt hash in schema.sql must be regenerated for your password:
> ```php
> echo password_hash('YourNewPassword', PASSWORD_BCRYPT, ['cost' => 12]);
> ```

### Step 6 — Optional: PDF Generation
Install wkhtmltopdf for true PDF output:
```bash
# Ubuntu/Debian
sudo apt install wkhtmltopdf

# The system auto-detects it. If not found, HTML certificates are downloaded instead.
```

---

## Default Laboratories (Pre-seeded)

| Code | Laboratory |
|------|-----------|
| MRQL | Mass and Related Quantities Laboratory |
| LDM  | Length and Dimensional Metrology |
| THL  | Temperature and Humidity Laboratory |
| EQL  | Electrical Quantities Laboratory |
| PVL  | Pressure and Vacuum Laboratory |
| FML  | Flow Measurement Laboratory |
| FTL  | Force and Torque Laboratory |
| OPL  | Optical and Photometry Laboratory |
| CAL  | Chemical and Analytical Laboratory |

---

## User Roles

| Role | Permissions |
|------|-------------|
| **Admin** | Full access — manage users, labs, view all data and logs |
| **Front Desk Officer** | Manage companies, equipment, contacts; create requests |
| **Laboratory Officer** | View/process requests assigned to their lab(s); fill work forms; generate certificates |

### Key Access Control Rule
A Lab Officer **only sees** requests and data belonging to laboratories they are
assigned to. Assignment is managed by Admin in the Users section.

---

## Certificate Generation

When a Lab Officer submits a completed work form, the system:
1. Assigns a unique certificate number: `GSA/{LAB_CODE}/{YEAR}/{SEQ}`
2. Generates a **DCC-compliant XML** file (schema: ptb.de/dcc v3.2.1)
3. Generates a **printable HTML/PDF** certificate with:
   - Company and equipment information
   - Environmental conditions
   - Reference standards used
   - Measurement results table
   - Uncertainty statement
   - Officer signature
4. Marks the request as **Completed**
5. Both files are downloadable from the Certificates module

---

## OTP Verification

On every login:
1. User enters email and password
2. A 6-digit OTP is generated and stored (bcrypt-hashed, expires in 10 minutes)
3. In **development mode**, the OTP is shown on screen
4. In **production**, integrate an SMS gateway in `helpers/functions.php`:
   ```php
   // Replace $_SESSION['dev_otp'] = $otp; with:
   sendSMS($user['phone_number'], "Your MetLAB OTP: $otp. Valid for 10 minutes.");
   ```

---

## Security Features

- Password hashing: bcrypt with cost factor 12
- CSRF tokens on all forms
- Prepared statements throughout (no SQL injection)
- Session regeneration on login
- HttpOnly, SameSite=Strict session cookies
- Role-based access control (RBAC)
- Lab-level access isolation for officers
- Certificate files protected from direct URL access via `.htaccess`

---

## Activity Logging

All significant actions are automatically logged:

| Action | Module |
|--------|--------|
| login / logout | auth |
| create/update/delete user | users |
| create/update company | companies |
| add equipment | equipment |
| create/process request | requests |
| save work form | workform |
| generate certificate | certificates |

Logs are viewable by Admin under **Activity Logs** with module filtering and pagination.

---

## Extending for Lab-Specific Forms

Currently one generic work form covers all nine labs. To add lab-specific forms:
1. Create a new view: `views/lab/workform_{lab_code}.php`
2. In `WorkFormController.php`, detect `$request['lab_code']` and load the specific view
3. Extend `lab_work_forms` table with lab-specific columns as needed

---

## Support & Contact

Ghana Standards Authority — Scientific Metrology Division
P.O. Box MB 245, Shiashie, Accra, Ghana
Email: scientificmetrology@gsa.gov.gh
Tel: +233-302-500065
