update

2026-08-02 20:21:35 +07:00
parent 3e1ed72727
commit b957be735d
1 changed files with 630 additions and 0 deletions
@@ -0,0 +1,630 @@
+# 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.