מדריך למפתחים

1 · סקירה

HospAI הוא אפליקציית FastAPI עם תבניות Jinja2, מסד SQLite מקומי, וסיבוב AI דרך Ollama. עקרון מרכזי: local-first — PHI לא עוזב את המכשיר כברירת מחדל.

שכבת הטריאז׳ משלבת LLM (שאלות, ניתוח) עם מנוע כללים דטרמיניסטי לדגלים אדומים. ציון התור מחושב ב-QueuePriorityService וניתן לכוונון דרך JSON בפאנל הרופא.

2 · התקנה מהירה

דרישות

• Python 3.9+
• Ollama עם מודל (למשל llama3.2)
• אופציונלי: AWS credentials ל-Polly, מודל Whisper ב-Ollama ל-STT באיכות גבוהה

cd hospai
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
ollama pull llama3.2
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

התקנה ראשונה: אם המערכת לא מוגדרת, middleware מפנה ל-/setup. דפי שיווק (/, /developers) פטורים מהשער רק אחרי setup — לפני כן רק setup/static/health.

ברירת מחדל לצוות: admin / admin123! (החליפו ב-production).

3 · מבנה הפרויקט

app/
├── main.py                 # FastAPI app, routers, lifespan
├── config.py               # Settings מ-.env
├── controllers/
│   ├── pages_controller.py # GET /, GET /developers
│   ├── web_controller.py   # MVC טריאז׳ + dashboard
│   ├── api_controller.py   # REST API
│   ├── admin_controller.py # משתמשים, audit
│   ├── doctor_controller.py# כללים קליניים (/doctor)
│   ├── voice_controller.py # TTS/STT API
│   └── setup_controller.py # אשף התקנה
├── services/               # לוגיקה עסקית
├── triage/                 # rule_engine, validator
├── ai/                     # ollama_service, prompts, bedrock (אופציונלי)
├── security/               # auth, encryption, kiosk, permissions
├── models/                 # SQLAlchemy
├── templates/ + static/
data/
├── hospai.db
├── doctor_clinical_rules.json
tests/

4 · ניתוב ודפים

Router pages נרשם לפני web ב-main.py כדי ש-GET / יגיע לנחיתה ולא ל-dashboard.

5 · קיוסק מטופלים ללא התחברות

מודל גישה

app/security/kiosk_access.py יוצר שחקן אנונימי (resolve_triage_actor) באמצעות cookies, בלי משתמש patient ב-DB. נתיבים תחת /kiosk וזרימת /triage/{session_id}/... משתמשים באותו resolver.

איפוס אוטומטי

• kiosk-idle.js — איפוס אחרי ~5 דקות חוסר פעילות
• איפוס ~20 שניות אחרי דף complete
• POST /kiosk/reset — איפוס ידני

בדיקות

tests/test_kiosk_access.py — cookies, redirects, forbidden staff routes.

6 · זרימת טריאז׳

1. welcome / intake — פרטים, מסמכים (אופציונלי), הפרדת מטופלים במסמך
2. complaint — תלונה + מיקרופון (Web Speech / Whisper)
3. questions — שאלות AI מ-Ollama או fallback
4. analyze — TriageService + rule_engine
5. verify / details / decide — צוות (לא בקיוסק)
6. complete — סיום + איפוס קיוסק

מודל מרכזי: TriageSession (סטטוס, עדיפות, דגלים, requires_human_review). שירות: app/services/triage_service.py.

7 · מנוע כללים היברידי

app/triage/rule_engine.py מריץ כללים לפי מילות מפתח ותסמינים (שבץ, לב, נשימה, אנפילקסיס וכו'). כללים מותאמים נטענים מ-data/doctor_clinical_rules.json דרך doctor_rules_service.py.

app/schemas/doctor_rules.py — סכמת Pydantic לוולידציה לפני שמירה. שינוי בפאנל הרופא משפיע מיד על ניתוח ועל משקלי התור (אם הוגדרו ב-JSON).

8 · תור ועדיפויות

QueuePriorityService בונה רשימה ממוינת: ציון מורכב מרמת חירום, זמן המתנה, דגלים, ומשקלים מהקובץ הקליני. לוח הבקרה (/dashboard) משתמש ב-HTMX/JS לקידום ידני — QueueManagementService + רישום ב-audit.

הרשאה: PERM_QUEUE_PROMOTE לפי תפקיד ב-permissions.py.

9 · פאנל רופא

נתיב נפרד /doctor — לא משתמש ב-JWT של האפליקציה. אימות via DOCTOR_PANEL_SECRET ב-.env (מינימום 8 תווים).

• GET /doctor — טופס / פאנל
• POST /doctor/save — שמירת JSON
• POST /doctor/reset — ברירת מחדל
• POST /doctor/test — הרצת כלל על טקסט לדוגמה

אם הסוד ריק — doctor_disabled.html.

10 · קול ו-STT/TTS

שכבת לקוח

• voice-lang.js — Web Speech API, getUserMedia, בחירת קול מזכירה
• secretary-voice.js — אנימציית אווטאר + TTS
• voice-engine.js — Polly + lip-sync מאודיו
• voice-mic-bind.js — כפתור מיקרופון גלובלי

שרת

GET  /api/voice/capabilities
POST /api/voice/tts          # Amazon Polly (דורש AWS)
POST /api/voice/transcribe   # Ollama Whisper (voice_whisper_enabled)

הגדרות: voice_whisper_enabled, ollama_whisper_model ב-config.py. בדיקות: tests/test_voice_service.py.

מיקרופון: דפדפן Chrome/Edge על localhost — נדרש secure context (HTTPS או 127.0.0.1).

11 · מסמכים ו-PDF

העלאת PDF/תמונות → document_service + pdf_extractor. זיהוי מספר מטופלים: DocumentPatientClusterService — אשכול per-document ו-UI הפרדה (triage_patient_separation.html).

סנכרון לרשומת מטופל: patient_record_sync.py.

12 · בינה מלאכותית

• Ollama — ollama_service.py, prompts ב-ai/prompts.py
• Bedrock — אופציונלי לחילוץ מסמכים (bedrock_service.py)
• Fallback — אם Ollama לא זמין, שאלות וניתוח מוגבלים בכללים/תבניות

ספי ביטחון: ai_confidence_threshold, force_human_review_below, emergency_override_enabled.

13 · אבטחה ו-RBAC

• JWT — security/auth.py, cookie session לדפדפן
• הצפנת PHI — Fernet ב-encryption.py
• תפקידים — admin, doctor, nurse, reception, triage_operator, auditor, patient
• Audit — security/audit.py, צפייה ב-/admin/audit
• Rate limit — slowapi ב-main.py
• Headers — X-Frame-Options, nosniff, וכו'

מטופל בקיוסק: אין גישה ל-/dashboard או נתיבי צוות — require_staff_or_redirect ב-patient_access.py.

14 · API (REST)

תיעוד אינטראקטיבי: /docs (Swagger).

סכמות: app/api/schemas.py. בקר: api_controller.py.

15 · משתני סביבה (.env)

דוגמה מלאה: .env.example בשורש הפרויקט.

16 · בדיקות

pytest
pytest tests/test_triage.py -v
pytest tests/test_kiosk_access.py tests/test_doctor_rules.py -v

tests/conftest.py — DB זמני. כיסוי: טריאז׳, תור, הרשאות, קיוסק, מסמכים, קול, locale RTL.

17 · פריסה

• Docker — docker-compose.yml; Ollama על המארח (host.docker.internal)
• Production — החלפת מפתחות, HTTPS, SQLite → Postgres אם נדרש (שינוי DATABASE_URL)
• גיבוי — data/hospai.db + doctor_clinical_rules.json