🧪 Lab (LIS) First-Run Setup Screen

Implementation plan · built from a 7-agent deep analysis of the LIS module · 2026-06-19 · status: AWAITING APPROVAL

الخلاصة بالعربي
هنبني شاشة إعداد للمعمل (Lab Setup) تظهر أول مرة يشتغل فيها البرنامج، وفيها لينك دائم نوصلها منه أي وقت. الشاشة عبارة عن معالج خطوات (wizard) يظبط كل اللي المعمل محتاجه يبدأ شغل: هوية المعمل + الحسابات + قائمة الأسعار + استيراد التحاليل (الميزة اللي طلبتها — عندنا كتالوج NAFIS فيه 1,666 تحليل قياسي يتحمّل بضغطة، أو رفع ملف Excel/CSV) + طرق الدفع + (اختياري) الأطباء/المعامل الخارجية/التأمين/الأجهزة. اكتشاف مهم: أغلب الـ seeders للبيانات المرجعية مش متسجلة في الـ installer، فأي نسخة جديدة ممكن تطلع بكتالوجات فاضية — الشاشة + إصلاح الـ installer هيحلّوا ده. اقرأ قسم القرارات في الآخر وقوللي رأيك قبل التنفيذ.

1 · Goal

A guided first-run setup screen for the Lab module that (a) appears automatically the first time the program runs, (b) has a permanent link to re-open anytime, and (c) lets the admin configure everything the lab needs to operate — including an optional one-click import of a standard investigations (tests) catalog, plus optional CSV/Excel import. After finishing, the lab can create requests, price them, collect payment, and post to accounting — with no hidden blockers.

2 · What the analysis found — the LIS setup surface

Seven parallel agents mapped catalogs, settings, financial wiring, machines, people, the existing setup infra, and the investigation entity. Summary of what needs setup and how it behaves today:

Area	Seeded today?	Blocks day-1?	Belongs on setup screen
Lab identity (name, logo, contact, license)	No (empty)	name recommended	Yes — step 1
Reference catalogs — sections(13), specimen types(12), units(33), specialties(16), deferral reasons(10), histo templates(16)	Seeders exist but NOT in installer → may be empty on fresh install	Yes (sections/specimen/units)	Yes — verify/seed + light customize
GL accounts — `lis.receivable_account_id`, `revenue`, `tax_payable`	Auto-wired by my `seedDefaultAccountSettings` (detail leaves)	Yes	Yes — confirm step (reuse default-accounts)
Default price list (+ priced items)	No	Yes — invoices need a default list	Yes — create + bulk-price
Investigations (tests) + ranges/panels	NAFIS catalog (1,666) seeded hidden via `NafisCatalogSeeder`	Yes (need tests to order)	★ Yes — the headline: import
Payment methods / treasuries / banks	5 method fallbacks; treasuries user-made	No (fallbacks)	Yes — review (optional)
Doctors · external labs · insurance	No	No (all optional)	Optional quick-add or defer
Analyzers / machines	Device catalog seeded (6 models, 79 tests); machines user-made	No (manual entry works)	Optional "have analyzers? Y/N"

⚠️ Key discovery — the installer seeder gap

Only LabSettingDefinitionSeeder + LabDeviceModelSeeder run in config/moonstack.php → installer.seeders. The catalog seeders (LabSectionSeeder, LabSpecimenTypeSeeder, LabUnitSeeder, LabDoctorSpecialtySeeder, LabDeferralReasonSeeder, LabHistopathTemplateSeeder) are not in the install/update chain — they only run via a manual LISDatabaseSeeder. So a fresh install can land with empty sections/specimen-types/units, which then blocks investigation/request creation. Fix: add them to installer + updater seeders (idempotent), AND let the setup screen verify/seed them on demand. This is the same class as the documented "moonstack-update seeder gap".

3 · Architecture decision

Build a new dedicated Lab Setup wizard at /lab-setup, mirroring the existing /setup wizard pattern (setup-wizard.component.ts — 9-step signal-based stepper). REUSE the components that already exist instead of rebuilding:

reuse LisLabInfoComponent (identity / report / barcode / invoice tabs) → identity step
reuse default-accounts.config.ts + the Default-Accounts accordion logic → accounts step (LIS section already defined)
reuse LisPaymentMethodsComponent + treasuries → payments step
reuse existing POST /lis/investigations/import (CSV) + NafisCatalogSeeder → investigations step
new the wizard shell, the NAFIS one-click endpoint, a setup-status endpoint, first-run detection, the nav link

Why a separate wizard (not cram into /setup): lab setup is LIS-specific, large, and must be (a) offered on first run and (b) re-openable anytime from the Lab menu — independent of the global company/accounting setup.

4 · The wizard — step by step

Lab Identity required: name reuse lab-info
lab_name (+ _ar), logo upload, phone/email/address, license, director. Writes via PUT /lis/lab-info.

Reference Data required new seed endpoint
Detect empty catalogs → one-click "Set up standard sections / specimen types / units" (runs the catalog seeders idempotently). Show counts; allow rename/disable. Closes the installer gap.

Investigations (Tests) Catalog ★ headline new endpoint + UI
Three choices (pick any/skip):

Import standard NAFIS catalog — 1,666 Saudi SBS tests with ranges, one-click, idempotent by sbscs_code (reuses NafisCatalogSeeder via new POST /lis/investigations/import-standard). Shows progress + summary.
Upload CSV/Excel — existing POST /lis/investigations/import (cols: name, code, section_code, specimen_code, result_type, unit, price, loinc…).
Start empty — add tests later in the Investigations page.

After import, imported tests can be left hidden and activated as the lab offers them.

Pricing required for billing new bulk-price
Create a default price list and set prices for active tests (NAFIS rows carry a price column we can pre-fill; or flat/percent bulk-set; or per-test). Without a default price list, invoices can't auto-price.

Accounting required reuse default-accounts
Confirm lis.receivable_account_id / revenue_account_id / tax_payable_account_id — already auto-wired to detail leaves by seedDefaultAccountSettings; the step just surfaces them with the leaf-only guard (avoids the AR-header trap).

Payments optional reuse
Review the 5 default payment methods; create cash boxes/treasuries + link GL accounts (auto-created via AutoAccountService). Has safe fallbacks, so skippable.

People optional
Quick-add primary doctors / external labs / insurance contracts (auto-create partners), or skip — all addable later. Commission rules + per-test pricing deferred.

Analyzers optional reuse instantiate
"Do you have lab analyzers?" → if yes, quick add-from-catalog (device model + connection). Code-mapping + middleware download deferred to the Machines page.

Finish
Summary of what's configured → set lis.setup_completed = 1 → go to the Lab dashboard.

5 · The investigations import (headline feature)

Setup step 3→ choose source→ NAFIS 1,666 one-click or CSV/Excel existing or skip→ progress + summary→ step 4: price them

Source: Modules/LIS/database/data/nafis_catalog.csv (1,666 tests + ranges) via NafisCatalogSeeder. Idempotent by sbscs_code (re-running skips existing — safe). Auto-creates missing sections/categories/specimen types. The CSV path reuses the live ImportInvestigationsJob (skips duplicates by code; no nested ranges/panels — those stay defaults or get set per-test later).

New BE work: extract NafisCatalogSeeder::seedForCompany() into a reusable service + expose POST /lis/investigations/import-standard { source:"nafis", skip_existing:true } returning {created, skipped, sections_created, ranges_created}. For large runs, dispatch a queued job + poll.

6 · First-run detection & the access link

First run

BE install marker = storage/moonstack/installed; FE flag = setup.completed. There is no lab-setup auto-trigger today. Add a lis.setup_completed flag + a GET /lis/setup/status endpoint (returns: has sections? investigations? price list? accounts wired? name set?). On Lab-module entry, if not completed → show a dismissible banner / redirect offering the wizard.

Permanent link

Add a "Lab Setup" item to the Lab module nav (nav-items.config.ts, icon pi pi-compass, route /lab-setup, permission lis.settings.manage) so it's reachable anytime — not just first run.

7 · Work breakdown

Backend

Item	Type	Notes
Add LIS catalog seeders to `installer.seeders` + `updater.seeders`	fix gap	Make idempotent (firstOrCreate/updateOrCreate); backfill existing installs on update
`POST /lis/setup/seed-catalogs`	new	Run catalog seeders for the company on demand (drives step 2)
`POST /lis/investigations/import-standard`	new	Reusable NAFIS service; returns counts; idempotent
`GET /lis/setup/status`	new	Drives wizard checklist + first-run detection
Bulk price-list create + price endpoint	new/extend	Default list + set prices (flat / from NAFIS / per-test)
`lis.setup_completed` definition	new	Add to `LabSettingDefinitionSeeder`

Frontend

Item	Type
`LabSetupWizardComponent` (mirror setup-wizard; signals + stepper/accordion)	new
Route `/lab-setup` (+ permission guard) and nav link	new
i18n keys `LAB_SETUP.*` in `en.json` + `ar.json` (English-first)	new
First-run banner/redirect using `/lis/setup/status`	new
Identity / accounts / payments / import steps	reuse existing components

8 · Suggested phasing

Phase 1 (MVP — get a lab running): installer-gap fix · status endpoint · wizard shell + first-run + nav link · steps 1 Identity, 2 Reference Data, 3 Investigations import (NAFIS + CSV), 4 Pricing, 5 Accounts, 9 Finish.
Phase 2 (polish): step 6 Payments review, 7 People quick-add, 8 Analyzers quick-add, bulk-price refinements, queued import + progress polling.

9 · Open decisions — need your call before I build

1) مصدر استيراد التحاليل: نعتمد كتالوج NAFIS (1,666 تحليل سعودي قياسي) كمصدر "استيراد التحاليل الحقيقية"؟ ولا عايز كمان خيار "انسخ من نسخة/معمل تاني موجود"؟

2) الإجبار: أول تشغيل — المعالج يكون إجباري (يفتح لوحده ولازم يخلّص) ولا عرض اختياري (بانر skippable + لينك دائم)؟ (أرشّح: عرض اختياري + لينك دائم.)

3) الأسعار: في خطوة التسعير — نملأ الأسعار من عمود price بتاع NAFIS تلقائي، ولا تحديد سعر موحّد/نسبة، ولا يدوي لكل تحليل؟ (أرشّح: من NAFIS + إمكانية تعديل جماعي.)

4) نطاق المرحلة الأولى: أبدأ بالـ MVP (الخطوات 1–5 + 9) وأأجّل الأطباء/التأمين/الأجهزة للمرحلة 2؟ (أرشّح: أيوه.)

5) أين نبني؟ أنفّذ على hazemdev (moonui) زي المعتاد، ولا ده موديول مناسب نجرّب بيه الـ moonui2 / hazemdev2 المتوازي؟

Generated from a 7-agent parallel analysis of the LIS module (catalogs · settings · pricing · machines · people · setup-infra · investigations). All file paths verified against /home/moonui/moon-erp-be/Modules/LIS and /home/moonui/public_html/moon-erp. Nothing built yet — this is the plan for review.