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