← всі звіти · 02-pseudocode.md

sparc_phase: P project: med-detective created: 2026-05-10 last_updated: 2026-05-10 author: Claude (post-hoc документація існуючої системи) status: approved approved_date: 2026-05-10 legacy_baseline: true spec_link: ./01-specification.md

Pseudocode — Псевдокод: логіка кроків без коду — Med Detective (umbrella)

Post-hoc документація існуючої системи. Описує fluxи реально розгорнутих 4 форм без коду.

High-level flow (game session)

Лікар відкриває URL з конкретним кейсом → бачить картку пацієнта → спілкується з AI-пацієнтом через чат → паралельно замовляє лабораторні обстеження → ставить діагноз і пропонує продукт → Judge оцінює сесію → результат (бал/100 + правильна відповідь + рекомендований SKU).

Основний flow (детально)

1. GET /<form_path>/case/<case_id>
2. Backend завантажує JSON-спеку кейса з cases/<case_id>.json
3. Створює Redis-сесію (DB per форма, TTL 24h, ключ session:<uuid>)
4. Повертає HTML з картою пацієнта + chat-UI

5. Loop (chat):
   5.1. Лікар вводить повідомлення → POST /api/chat
   5.2. Backend паралельно викликає:
        - Patient Agent (рольова симуляція пацієнта згідно patient_<case>.md)
        - Intent Recognition (класифікує: question / examination_request / diagnosis_attempt)
   5.3. Зберігає у Redis історію
   5.4. Повертає відповідь пацієнта

6. Loop (Investigation Panel):
   6.1. Лікар відкриває панель → GET /api/lab_catalog (39 тестів × 6 категорій)
   6.2. Шукає тест через search-bar → клік
   6.3. POST /api/order_tests з list test_ids
   6.4. Backend перевіряє test_id ∈ LAB_CATALOG ∪ extra_tests кейса
   6.5. Повертає результати з cases/<case_id>.json (test_results секція)

7. Закриття сесії:
   7.1. POST /api/finish_case з diagnosis_text + product_choice
   7.2. Backend викликає Judge Agent (system+user prompts)
   7.3. Judge оцінює по rubric: 40 + 30 + 15 + 15 = 100
   7.4. Зберігає результат у Redis
   7.5. Повертає score + правильна відповідь + рекомендація

8. Result-screen → CTA: «Скачати CME» (TODO: Lead Capture модалка → Supabase email confirm → PDF)

Альтернативні flows / scenarios помилок

Replicate API timeout (>30с)

1. Patient/Intent Agent отримує timeout
2. Backend: спробувати Gemini fallback (тільки на Schönen-main)
3. Якщо обидва failed — повертає friendly error «AI поки відпочиває, спробуй ще раз»

Redis unavailable

1. Backend перехоплює connection error
2. Повертає 503 з «session expired, refresh»
3. Лікар починає сесію заново

Тест поза каталогом (рідко через UI, можливо через прямий API call)

1. Backend: test_id ∉ LAB_CATALOG ∪ extra_tests
2. Повертає 400 з «test not available for this case»

Judge повертає неможливий score (regex fail)

1. Backend logs error
2. Fallback: показує bare diagnosis match без rubric breakdown
3. Алерт у Telegram (TODO — наразі тільки в logs)

Ключові структури даних

Кейс (case JSON)

{
  "case_id": "case_07_ibs",
  "title": "Пацієнт N р. зі скаргами на...",  # no-spoiler title
  "patient_persona_md": "patient_case_07.md",
  "correct_diagnosis": "...",
  "differential": ["...", "..."],
  "key_tests_to_order": ["FBC", "CRP", "calprotectin"],
  "extra_tests": ["..."],
  "test_results": { "FBC": {...}, ... },
  "recommended_sku": "Allerveg Atopik",
  "rubric_overrides": { ... }   # optional per-case
}

Сесія (Redis)

session:<uuid> = {
  "case_id": "...",
  "started_at": ts,
  "history": [{"role":"doctor"|"patient", "text":"..."}],
  "ordered_tests": ["..."],
  "diagnosis_attempt": "...",
  "product_choice": "...",
  "judge_result": { "total": 87, "diagnosis": 35, ... }
}

LAB_CATALOG (shared, 39 тестів)

[
  {"id":"FBC", "name":"...", "category":"hematology", "price":180, "turnaround":"1d"},
  ...
]

Псевдо-функції / responsibilities

Інтеграції зі сторонніми системами

Що НЕ робимо у логіці

Sign-off