Foreign Keys Reference

Diagram Relacji

┌─────────────────────────────────────────────────────────────────────────┐
│                           CORE ENTITIES                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  users ◄─────────────┬────────────────┬─────────────────────────────►  │
│    │                 │                │                                 │
│    │ 1:N             │ 1:N            │ 1:1                             │
│    ▼                 ▼                ▼                                 │
│  visits          user_sessions   user_preferences                       │
│    │                                                                    │
│    │ N:1                                                                │
│    ▼                                                                    │
│  patients ◄──────────────────────────────────────────────────────────► │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                      AUDIO PIPELINE                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  visits ◄────────── recordings ─────────► transcripts (1:1)            │
│    │                    │                                               │
│    │                    │                                               │
│    ▼                    ▼                                               │
│  speaker_segments   patients (optional)                                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                      TASKS & REMINDERS                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  tasks ────────────► visits (optional)                                  │
│    │                                                                    │
│    ├────────────────► patients (optional)                               │
│    │                                                                    │
│    └────────────────► users (assigned_to, created_by)                  │
│                                                                         │
│  reminders ─────────► users (assigned_to - required)                   │
│    │                                                                    │
│    ├────────────────► patients (optional)                               │
│    │                                                                    │
│    └────────────────► visits (optional)                                 │
│                                                                         │
│  ai_task_suggestions ► visits (required) + patients (required)         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                        AI CHAT                                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  chat_sessions ────► users (optional)                                   │
│       │                                                                 │
│       ├────────────► visits (optional)                                  │
│       │                                                                 │
│       └──────────────────────┬──────────────────┐                       │
│                              │                  │                       │
│                              ▼                  ▼                       │
│                       chat_messages      chat_attachments              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

---

Cascade Rules (ON DELETE)

Tabele z kompletnymi FK ON DELETE

Parent	Child	Rule	Uwagi
patients	appointments	CASCADE	Usunięcie pacjenta usuwa jego wizyty
users	appointments.veterinarian_id	CASCADE
visits	appointments.visit_id	SET NULL	Appointment zostaje, tylko visit_id = NULL
patients	ai_task_suggestions	CASCADE
visits	ai_task_suggestions	CASCADE
recordings	transcripts	CASCADE	1:1 - usunięcie nagrania usuwa transkrypt
users	user_sessions	CASCADE
users	user_preferences	CASCADE
users	user_working_hours	CASCADE
users	pin_lockout	CASCADE
users	dashboard_state	CASCADE
users	personal_notes	CASCADE
users	custom_dictionary	CASCADE
chat_sessions	chat_messages	CASCADE	Usunięcie sesji usuwa wiadomości
users	recordings.created_by	SET NULL	Nagranie zostaje, autor = NULL
patients	tasks.patient_id	SET NULL
visits	tasks.visit_id	SET NULL
users	tasks.assigned_to	SET NULL
users	tasks.created_by	SET NULL
users	reminders.created_by	SET NULL
users	reminders.assigned_to	CASCADE	Usunięcie usera usuwa jego przypomnienia
patients	reminders.context_patient_id	SET NULL
visits	reminders.context_visit_id	SET NULL
visits	visit_shares	CASCADE
users	visit_shares.shared_by	CASCADE
users	visit_shares.shared_with	CASCADE

---

Brakujące FK ON DELETE

Krytyczne braki

Poniższe FK nie mają zdefiniowanego ON DELETE - usunięcie parenta spowoduje constraint error!

Parent	Child.Column	Problem	Rekomendacja
patients	visits.patient_id	BRAK	Powinno być CASCADE lub SET NULL
users	visits.user_id	BRAK	Powinno być SET NULL
users	user_sessions.user_id	BRAK	Powinno być CASCADE
patients	clinical_notes.patient_id	BRAK	Powinno być CASCADE
users	clinical_notes.user_id	BRAK	SET NULL
patients	media_files.patient_id	BRAK	SET NULL
visits	media_files.visit_id	BRAK	SET NULL
users	media_files.uploaded_by	BRAK	SET NULL
visits	speaker_segments.visit_id	BRAK	CASCADE
visits	recordings.visit_id	BRAK	SET NULL
patients	recordings.patient_id	BRAK	SET NULL
users	time_blocks.created_by	BRAK	SET NULL
users	time_blocks.updated_by	BRAK	SET NULL
users	appointments.created_by	BRAK	SET NULL
users	appointments.updated_by	BRAK	SET NULL

---

Znany bug: chat_attachments

Błędny FK

Tabela chat_attachments ma FK do user_sessions zamiast chat_sessions:

-- AKTUALNIE (błędnie):
session_id TEXT NOT NULL REFERENCES user_sessions(session_id) ON DELETE CASCADE

-- POWINNO BYĆ:
session_id TEXT NOT NULL REFERENCES chat_sessions(id) ON DELETE CASCADE

---

Priorytet naprawy

ID	Priorytet	Problem	Lokalizacja
DB-001	P0	Hard delete visits	visits - brak soft-delete dla dokumentów medycznych
DB-002	P1	FK bez ON DELETE	visits.patient_id, visits.user_id
DB-003	P1	Błędny FK	chat_attachments.session_id → user_sessions
DB-004	P2	Niespójny soft-delete	Tylko users ma is_deleted + deleted_at
DB-005	P2	FK bez ON DELETE	clinical_notes, media_files, speaker_segments
DB-006	P3	Polska nazwa pola	visits.ai_sugestie → powinno być ai_suggestions

---

Best Practices

Kiedy używać CASCADE vs SET NULL?

Scenariusz	Reguła	Przykład
Child nie ma sensu bez parenta	CASCADE	chat_messages → chat_sessions
Child może istnieć samodzielnie	SET NULL	tasks → visits
Dane medyczne / audit	SET NULL lub NO ACTION	Zachowaj historię
Dane tymczasowe	CASCADE	password_reset_tokens

Sprawdzanie integralności

-- Włącz FK constraints (wymagane przy każdym połączeniu)
PRAGMA foreign_keys = ON;

-- Sprawdź czy są FK violations
PRAGMA foreign_key_check;

-- Sprawdź definicje FK dla tabeli
PRAGMA foreign_key_list(visits);