데이터 모델 개요
목적
Lumie의 주요 데이터 모델은 PostgreSQL에 있으며 lumie-backend가 소유합니다. 백엔드는 모듈형 모놀리스이므로 데이터베이스 소유권도 별도 서비스 DB가 아니라 모듈 경계 기준으로 구성됩니다. 런타임 tenant 격리는 tenant별 스키마 데이터베이스가 아니라 공유 public 스키마와 PostgreSQL Row-Level Security(RLS)로 구현됩니다.
이 페이지는 overview 문서입니다. 테이블, migration, repository, 교차 모듈 데이터 계약을 변경하기 전에 어떤 상세 참고 문서를 봐야 하는지 선택하는 데 사용하세요.
소스 경로
| 경로 | 역할 |
|---|---|
lumie-backend/app/src/main/resources/db/migration/public/ | 백엔드 데이터베이스용 Flyway migration |
V1__create_platform_tables.sql | tenants, tenant_settings 같은 초기 플랫폼 테이블 |
V18__rls_baseline.sql | tenant 범위 도메인 테이블용 공유 public-schema RLS baseline |
V27__langgraph_schema.sql | chatbot 체크포인트 영속화용 전용 langgraph 스키마 |
V28__billing_platform_tables.sql | 플랫폼 범위의 Lumie-to-tenant 구독 billing 테이블 |
V29__tuition_tenant_tables.sql | tenant 범위의 academy-to-guardian 등록금 billing 테이블 |
lumie-backend/modules/**/domain/entity/ | 백엔드 모듈을 테이블에 매핑하는 JPA 엔티티 |
lumie-infra/applications/lumie/**/common-values.yaml | 런타임 데이터베이스, pooler, 서비스 설정 |
스키마 계열
| 계열 | 범위 | RLS | 예시 |
|---|---|---|---|
| Platform core | 교차 tenant Lumie 제어 평면 | No | tenants, tenant_settings, owner_directory, plans |
| Tenant domain | academy 소유 운영 데이터 | Yes | users, students, staff, classes, lectures, exams, attendance_* |
| Platform billing | Lumie가 tenant에 청구 | No | subscriptions, billing_keys, invoices, payment_transactions |
| Tenant tuition | academy가 guardian 또는 학생에게 청구 | Yes | guardians, tuition_invoices, tuition_payments, cash_receipts |
| Worker state | 서비스 소유 기술 상태 | Separate schema | langgraph checkpointer 테이블 |
| Operational support | 횡단 공통 백엔드 지원 | Depends on table | event_publication, shedlock, idempotency_keys |
런타임 격리 모델
tenant 범위 테이블은 non-null tenant_id 컬럼을 가지며 다음의 표준 RLS predicate를 사용합니다.
tenant_id = NULLIF(current_setting('app.tenant_id', true), '')::bigint
런타임 DB role은 의도적으로 RLS를 우회할 수 없도록 되어 있습니다. 백엔드 코드는 tenant 범위 repository나 JDBC 쿼리가 데이터를 건드리기 전에 tenant 컨텍스트를 설정해야 합니다.
소유권 경계
- 백엔드 모듈은 JPA 엔티티와 Flyway migration을 통해 자신의 aggregate 테이블을 소유합니다.
- 교차 모듈 관계가 항상 데이터베이스 수준 foreign key인 것은 아닙니다. hard FK가 두 모듈 경계를 결합시킬 경우 의도적으로 soft reference를 유지하기도 합니다.
- 플랫폼 billing 테이블은 cross-tenant이며 RLS 대신 애플리케이션 수준 권한 부여로 보호됩니다.
- worker 서비스는 tenant 데이터 테이블을 소유하지 않습니다. 백엔드 내부 API를 호출하거나
langgraph같은 전용 기술 스키마를 사용합니다.
변경 규칙
- 모든 스키마 변경은 forward-only Flyway migration으로 추가합니다.
- tenant 범위 테이블에는
tenant_id, RLS 활성화,FORCE ROW LEVEL SECURITY,tenant_isolationpolicy가 반드시 포함되어야 합니다. - tenant 범위 조회 패턴을 위한 인덱스에는 접근 경로의 일부로
tenant_id를 포함합니다. - 소유 모듈이 의도적으로 hard persistence boundary를 공유하지 않는 한 교차 모듈 FK는 피합니다.
- 생성된 문서는 migration, entity 매핑, repository query와 맞춰 둡니다.