# MyLIS-RSSA
### Microbiology Laboratory Information System

---

## Bahasa Indonesia

**MyLIS-RSSA** adalah ekosistem aplikasi Laboratory Information System untuk layanan mikrobiologi RSUD Dr. Saiful Anwar. Repo ini berisi aplikasi web/backend Laravel, aplikasi pendamping mobile/desktop Flutter, dan service listener Python untuk komunikasi alat laboratorium.

Sistem ini membantu alur kerja laboratorium mulai dari penerimaan order, registrasi sampel, pengelompokan pemeriksaan, input expertise, verifikasi hasil, pelaporan, notifikasi nilai kritis, sampai integrasi dengan SIMRS dan instrumen laboratorium.

---

### Aplikasi di Dalam Repo

#### 1. LIS Web & Backend (`htdocs`)

Aplikasi utama berbasis Laravel untuk operasional laboratorium. Modul ini menangani autentikasi, dashboard, pendaftaran pasien/sampel, daftar pemeriksaan, template hasil, expertise, laporan, label/barcode, logbook, biorepository, gudang BHP, API mobile, backup cloud, dan integrasi SIMRS.

Ringkasan fungsi:

- Registrasi order dari SIMRS melalui endpoint `registerpasien`, `registerulang`, dan `registerjson`.
- Pengelolaan pasien, dokter, poli/ruangan, user, template jawaban, dan subjawaban.
- Worklist pemeriksaan mikrobiologi berdasarkan buku/kategori sampel.
- Input dan cetak hasil pemeriksaan, adendum, label, form, dan laporan.
- Dashboard Early Warning System dan notifikasi nilai kritis.
- Modul logbook PPDS/SPV, biorepository, dan SIMBHP.
- API `/api/mobile` untuk aplikasi MyLIS Flutter.
- Utilitas backup/restore database ke cloud dan export/simulasi payload register API.

#### 2. MyLIS Flutter (`mylis`)

Aplikasi mobile/desktop pendamping untuk akses cepat ke LIS Laravel. Aplikasi ini dipakai untuk login, cek koneksi server, dashboard, pencarian sampel, scanner barcode, Early Warning System, penerimaan pekerjaan awal, daftar pemeriksaan, detail pemeriksaan, notifikasi nilai kritis, dan pengisian expertise native.

Screen expertise yang tersedia:

- `CCI`
- `Kultur`
- `Pewarna Langsung`
- `TBC`
- `Viral Load`
- `IgM IgG Leptospira`
- `PCR COVID`

#### 3. Listener Instrumen (`listener`)

Service Python untuk komunikasi dengan instrumen laboratorium, terutama jalur serial/TCP dan GeneXpert. Service ini membaca, memproses, dan mengirim pesan instrumen seperti ASTM/HL7, lalu menyimpan atau meneruskan data ke database LIS.

Ringkasan fungsi:

- Listener TCP untuk GeneXpert.
- Komunikasi serial untuk perangkat seperti Vitek dan BACTEC.
- Mapping kode pemeriksaan LIS ke host test code alat.
- Antrean order instrumen dan pemrosesan hasil.
- Logging harian dan log per thread untuk troubleshooting.

---

### Cara Kerja Aplikasi

Alur utama sistem:

```text
SIMRS / user web
  -> Laravel LIS menerima order dan data pasien
  -> Sampel masuk ke worklist mikrobiologi
  -> Petugas menerima, memproses, dan mengisi hasil/expertise
  -> Supervisor melakukan verifikasi atau finalisasi
  -> Hasil dicetak, dikirim, atau diekstrak kembali ke SIMRS
```

Alur mobile:

```text
MyLIS Flutter
  -> login ke Laravel melalui /api/mobile/login
  -> mengambil dashboard, worklist, detail pemeriksaan, dan template expertise
  -> menyimpan draft, preliminary, final, atau kirim ke SPV
  -> Laravel menyimpan perubahan ke database LIS
```

Alur instrumen:

```text
Instrumen laboratorium
  -> listener Python menerima ASTM/HL7/serial/TCP
  -> data diparse dan dicocokkan dengan order/sampel
  -> hasil atau status instrumen disimpan ke database
  -> Laravel menampilkan hasil untuk proses validasi dan pelaporan
```

Alur backup cloud:

```text
Server production
  -> pg_dump database
  -> upload file .backup secara chunked ke cloud
  -> restore dapat dilakukan dengan download backup terbaru dan pg_restore
```

Detail backup, restore, export payload `registerApi`, dan simulasi kirim data SIMRS tersedia di [htdocs/README.md](/Users/duidev/htdocs/lis/htdocs/README.md).

---

### Teknologi

- **Backend**: Laravel 10, PHP 8.1+ dengan platform Composer PHP 8.4.
- **API & Auth**: Laravel route API, token terenkripsi untuk mobile, Laravel Sanctum/Passport tersedia di dependency.
- **Frontend Web**: Blade, Bootstrap, jQuery, DataTables, Livewire 3, Vite.
- **Database**: konfigurasi `.env` mendukung MySQL; deployment/backup production juga memakai PostgreSQL untuk database `lismikro`.
- **Reporting & Dokumen**: TCPDF, FPDI, PhpSpreadsheet, QR/barcode generator.
- **Integrasi**: HL7, ASTM, serial communication, FTP, HTTP client Guzzle, bridging BPJS.
- **Mobile/Desktop**: Flutter, Dart, Material UI, HTTP client, shared preferences, URL launcher, mobile scanner.
- **Listener Engine**: Python 3, Flask, SQLAlchemy, psycopg2, pyserial, hl7.
- **Runtime Ops**: Artisan commands, cron backup, optional Docker Compose.

---

### Instalasi LIS Web & Backend (`htdocs`)

Prasyarat:

- PHP 8.1 atau lebih baru.
- Composer.
- Node.js dan npm.
- Database MySQL atau PostgreSQL sesuai konfigurasi deployment.
- Ekstensi PHP yang dibutuhkan Laravel dan package proyek.

Langkah instalasi:

```bash
cd htdocs
composer install
npm install
cp .env.example .env
php artisan key:generate
```

Sesuaikan konfigurasi utama di `.env`:

```env
APP_URL=https://lis.swandhana.test
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=db_lis
DB_USERNAME=root
DB_PASSWORD=
```

Jalankan migrasi bila database target memang disiapkan dari migration project:

```bash
php artisan migrate
```

Jalankan aplikasi lokal:

```bash
php artisan serve
npm run dev
```

Build aset production:

```bash
npm run build
```

Perintah verifikasi yang umum:

```bash
php artisan route:list
php artisan route:list --path=mobile
php -l app/Http/Controllers/MobileApiController.php
```

---

### Instalasi MyLIS Flutter (`mylis`)

Prasyarat:

- Flutter SDK sesuai `pubspec.yaml` (`Dart SDK ^3.12.2`).
- Android Studio/Xcode sesuai platform target.
- Server Laravel LIS yang bisa diakses dari device atau simulator.

Langkah instalasi:

```bash
cd mylis
flutter pub get
flutter run
```

Jalankan dengan URL Laravel tertentu:

```bash
flutter run --dart-define=LIS_BASE_URL=https://lis.swandhana.test/
```

Build aplikasi:

```bash
flutter build apk --debug
flutter build ios --debug --no-codesign
flutter build macos --debug
```

Verifikasi:

```bash
flutter analyze
flutter test
```

---

### Instalasi Listener Instrumen (`listener`)

Prasyarat:

- Python 3.
- Akses jaringan ke database LIS dan instrumen laboratorium.
- Akses port serial/TCP sesuai alat yang dipakai.

Langkah instalasi:

```bash
cd listener
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Jalankan listener utama:

```bash
python app.py
```

Jalankan listener GeneXpert khusus:

```bash
python geneexpert.py
```

Catatan konfigurasi:

- `app.py` dan `geneexpert.py` masih menyimpan mapping IP, port, perangkat, dan database di dalam file.
- Pastikan `DATABASE_URL`, `TARGET_MAPPING`, `DEVICE_CONFIGS`, port serial, dan port TCP sesuai lingkungan produksi.
- Default port penting: TCP GeneXpert `6001` dan HTTP trigger `6002`.

---

### API Mobile Utama

Prefix endpoint:

```text
/api/mobile
```

Endpoint utama:

- `GET /api/mobile/ping`
- `POST /api/mobile/login`
- `GET /api/mobile/dashboard`
- `GET /api/mobile/critical-values`
- `POST /api/mobile/critical-values/{id}/mark-read`
- `GET /api/mobile/early-warning`
- `GET /api/mobile/examinations/search`
- `GET /api/mobile/initial-work/samples`
- `POST /api/mobile/initial-work/samples/{id}/accept`
- `POST /api/mobile/initial-work/samples/{id}/reject`
- `GET /api/mobile/books/{master}/examinations`
- `GET /api/mobile/examinations/{id}`
- `GET /api/mobile/examinations/{id}/expertise`
- `POST /api/mobile/examinations/{id}/expertise/template`
- `POST /api/mobile/examinations/{id}/expertise`

---

### Manual Book

Panduan pengguna dapat diunduh melalui:

```text
http://10.10.123.218/manual.pdf
```

---

### Dukungan Pengembangan

Aplikasi ini dikembangkan oleh **CV. Swandhana**.

Alamat:

```text
Jl. Lamandau 18A, Bunulrejo, Blimbing, Malang
```

Kontak WhatsApp:

```text
081359108565
```

Pengembangan juga didukung oleh kolaborasi antara pengembang dan AI assistant seperti ChatGPT/Gemini untuk dokumentasi, refactoring, dan percepatan pekerjaan teknis.

---

### Lisensi

Proyek ini menggunakan lisensi **MIT**. Lihat file `LICENSE` jika tersedia di distribusi project.

---

## English Version

**MyLIS-RSSA** is a Laboratory Information System ecosystem for the microbiology service at RSUD Dr. Saiful Anwar. This repository contains a Laravel web/backend application, a Flutter mobile/desktop companion app, and a Python listener service for laboratory instrument communication.

The system supports laboratory workflows from order intake, sample registration, examination grouping, expertise entry, result verification, reporting, critical value notification, to SIMRS and instrument integration.

---

### Applications in This Repository

#### 1. LIS Web & Backend (`htdocs`)

The main Laravel application for laboratory operations. It handles authentication, dashboards, patient/sample registration, examination lists, result templates, expertise, reports, labels/barcodes, logbooks, biorepository, BHP inventory, mobile APIs, cloud backup, and SIMRS integration.

Main capabilities:

- Order registration from SIMRS through `registerpasien`, `registerulang`, and `registerjson`.
- Management of patients, doctors, clinics/rooms, users, answer templates, and sub-answers.
- Microbiology worklists grouped by sample book/category.
- Result entry, result printing, addendum, labels, forms, and reports.
- Early Warning System dashboard and critical value notifications.
- PPDS/SPV logbook, biorepository, and SIMBHP modules.
- `/api/mobile` endpoints for the MyLIS Flutter app.
- Cloud database backup/restore and register API payload export/simulation utilities.

#### 2. MyLIS Flutter (`mylis`)

A mobile/desktop companion app for fast access to the Laravel LIS. It supports login, server ping, dashboard, sample search, barcode scanning, Early Warning System, initial work acceptance, examination lists, examination details, critical value notifications, and native expertise entry.

Available expertise screens:

- `CCI`
- `Kultur`
- `Pewarna Langsung`
- `TBC`
- `Viral Load`
- `IgM IgG Leptospira`
- `PCR COVID`

#### 3. Instrument Listener (`listener`)

A Python service for laboratory instrument communication, especially serial/TCP and GeneXpert workflows. It receives, processes, and sends instrument messages such as ASTM/HL7, then stores or forwards the data to the LIS database.

Main capabilities:

- TCP listener for GeneXpert.
- Serial communication for devices such as Vitek and BACTEC.
- Mapping from LIS examination names to instrument host test codes.
- Instrument order queue and result processing.
- Daily logs and per-thread logs for troubleshooting.

---

### How the System Works

Main workflow:

```text
SIMRS / web user
  -> Laravel LIS receives orders and patient data
  -> samples enter the microbiology worklist
  -> staff accept, process, and enter results/expertise
  -> supervisor verifies or finalizes the result
  -> result is printed, sent, or extracted back to SIMRS
```

Mobile workflow:

```text
MyLIS Flutter
  -> logs in to Laravel through /api/mobile/login
  -> fetches dashboard, worklist, examination details, and expertise templates
  -> saves draft, preliminary, final, or sends to SPV
  -> Laravel persists the changes to the LIS database
```

Instrument workflow:

```text
Laboratory instrument
  -> Python listener receives ASTM/HL7/serial/TCP messages
  -> data is parsed and matched with orders/samples
  -> instrument results or statuses are stored in the database
  -> Laravel displays the result for validation and reporting
```

Cloud backup workflow:

```text
Production server
  -> pg_dump database
  -> uploads .backup file to cloud in chunks
  -> restore can download the latest backup and run pg_restore
```

Detailed backup, restore, `registerApi` payload export, and SIMRS payload simulation notes are available in [htdocs/README.md](/Users/duidev/htdocs/lis/htdocs/README.md).

---

### Technology Stack

- **Backend**: Laravel 10, PHP 8.1+ with Composer platform PHP 8.4.
- **API & Auth**: Laravel API routes, encrypted token for mobile, Laravel Sanctum/Passport available in dependencies.
- **Web Frontend**: Blade, Bootstrap, jQuery, DataTables, Livewire 3, Vite.
- **Database**: `.env` supports MySQL; production/backup deployment also uses PostgreSQL for the `lismikro` database.
- **Reporting & Documents**: TCPDF, FPDI, PhpSpreadsheet, QR/barcode generator.
- **Integrations**: HL7, ASTM, serial communication, FTP, Guzzle HTTP client, BPJS bridging.
- **Mobile/Desktop**: Flutter, Dart, Material UI, HTTP client, shared preferences, URL launcher, mobile scanner.
- **Listener Engine**: Python 3, Flask, SQLAlchemy, psycopg2, pyserial, hl7.
- **Runtime Ops**: Artisan commands, cron backup, optional Docker Compose.

---

### Installing LIS Web & Backend (`htdocs`)

Requirements:

- PHP 8.1 or newer.
- Composer.
- Node.js and npm.
- MySQL or PostgreSQL database depending on the target deployment.
- PHP extensions required by Laravel and this project's packages.

Installation:

```bash
cd htdocs
composer install
npm install
cp .env.example .env
php artisan key:generate
```

Adjust the main `.env` configuration:

```env
APP_URL=https://lis.swandhana.test
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=db_lis
DB_USERNAME=root
DB_PASSWORD=
```

Run migrations when the target database is meant to be prepared from this project's migrations:

```bash
php artisan migrate
```

Run locally:

```bash
php artisan serve
npm run dev
```

Build production assets:

```bash
npm run build
```

Common verification commands:

```bash
php artisan route:list
php artisan route:list --path=mobile
php -l app/Http/Controllers/MobileApiController.php
```

---

### Installing MyLIS Flutter (`mylis`)

Requirements:

- Flutter SDK matching `pubspec.yaml` (`Dart SDK ^3.12.2`).
- Android Studio/Xcode depending on the target platform.
- A Laravel LIS server reachable from the device or simulator.

Installation:

```bash
cd mylis
flutter pub get
flutter run
```

Run with a specific Laravel URL:

```bash
flutter run --dart-define=LIS_BASE_URL=https://lis.swandhana.test/
```

Build:

```bash
flutter build apk --debug
flutter build ios --debug --no-codesign
flutter build macos --debug
```

Verification:

```bash
flutter analyze
flutter test
```

---

### Installing Instrument Listener (`listener`)

Requirements:

- Python 3.
- Network access to the LIS database and laboratory instruments.
- Serial/TCP port access according to the target instruments.

Installation:

```bash
cd listener
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Run the main listener:

```bash
python app.py
```

Run the dedicated GeneXpert listener:

```bash
python geneexpert.py
```

Configuration notes:

- `app.py` and `geneexpert.py` still keep IP, port, device, and database mapping inside the files.
- Make sure `DATABASE_URL`, `TARGET_MAPPING`, `DEVICE_CONFIGS`, serial ports, and TCP ports match the production environment.
- Important default ports: GeneXpert TCP `6001` and HTTP trigger `6002`.

---

### Main Mobile API

Endpoint prefix:

```text
/api/mobile
```

Main endpoints:

- `GET /api/mobile/ping`
- `POST /api/mobile/login`
- `GET /api/mobile/dashboard`
- `GET /api/mobile/critical-values`
- `POST /api/mobile/critical-values/{id}/mark-read`
- `GET /api/mobile/early-warning`
- `GET /api/mobile/examinations/search`
- `GET /api/mobile/initial-work/samples`
- `POST /api/mobile/initial-work/samples/{id}/accept`
- `POST /api/mobile/initial-work/samples/{id}/reject`
- `GET /api/mobile/books/{master}/examinations`
- `GET /api/mobile/examinations/{id}`
- `GET /api/mobile/examinations/{id}/expertise`
- `POST /api/mobile/examinations/{id}/expertise/template`
- `POST /api/mobile/examinations/{id}/expertise`

---

### Manual Book

User manual:

```text
http://10.10.123.218/manual.pdf
```

---

### Development Support

This application is developed by **CV. Swandhana**.

Address:

```text
Jl. Lamandau 18A, Bunulrejo, Blimbing, Malang
```

WhatsApp:

```text
081359108565
```

Development is also supported by collaboration between developers and AI assistants such as ChatGPT/Gemini for documentation, refactoring, and technical acceleration.

---

### License

This project uses the **MIT** license. See the `LICENSE` file if it is available in the project distribution.