논리 데이터 모델 정책¶

문서 역할¶

역할: 규범
문서 종류: policy
충돌 시 우선 문서: 이 문서
기준 성격: as-is

목적¶

개발자가 데이터의 주인, 연결 관계, 꼭 지켜야 할 규칙을 빠르게 이해하게 한다.
공개 문서와 실제 DB 구현이 서로 달라지지 않게 자동으로 확인한다.

적용 범위¶

공개 docs의 논리 데이터 모델
coupler-api 안의 비공개 DB 구조 연결 정보
DB 구조나 데이터 의미를 변경하는 구현과 리뷰

단일 기준¶

현행 도메인 ID와 소유 문서: 논리 데이터 모델 인덱스
예정 도메인 ID와 소유 문서: 예정 논리 데이터 모델 인덱스
공개 범위와 문서 역할: 문서 거버넌스 정책
데이터 분류와 보관: 데이터 거버넌스 정책
실제 DB 구조와 변경 절차: DB Migration Gate 정책

처음 읽는 방법¶

논리 데이터 모델은 DB 테이블 목록이 아니다. 아래 세 가지만 설명한다.

이 데이터는 어느 업무 영역이 맡는가.
다른 데이터와 어떻게 연결되는가.
어떤 상태에서도 깨지면 안 되는 규칙은 무엇인가.

개발자는 소유 문서의 먼저 보는 그림과 꼭 지킬 규칙을 먼저 읽는다. 실제 구현이나 리뷰에서 정확한 이름, 분류, 연결 수가 필요할 때만 아래 상세 표를 확인한다.

소유권 규칙¶

하나의 논리 엔티티는 정확히 하나의 도메인과 architecture 문서가 소유한다.
다른 문서는 논리 ID를 참조할 수 있지만 엔티티 정의를 다시 작성하지 않는다.
도메인은 다른 업무 데이터와 구분되는 의미와 관리 기간을 기준으로 나눈다.
화면, 사용자 역할, 상태, 행위, API 오류가 생긴 곳을 데이터 소유 도메인과 섞지 않는다.
Cron, 업로드, 테스트 데이터처럼 여러 도메인의 데이터를 처리하는 기능은 독립 엔티티를 소유하지 않으면 데이터 소유 도메인으로 등록하지 않는다.

식별자¶

도메인 ID는 소문자 kebab-case를 사용한다.
논리 엔티티 ID는 <domain-id>.<entity-id> 형식을 사용한다.
표시명이나 물리 테이블명이 바뀌어도 의미가 같으면 논리 ID를 유지한다.
논리 ID를 바꾸면 삭제 후 재생성으로 처리하지 않고 영향받는 관계, 비공개 연결 정보, 사용 문서를 함께 이관한다.

정해진 분류값¶

상세 표에서는 아래 영문값만 사용한다. 먼저 보는 그림은 같은 뜻을 쉬운 한국어로 보여준다.

생명주기 역할¶

값	쉬운 뜻
`root`	다른 데이터 없이도 따로 존재하고 관리되는 데이터
`child`	상위 데이터에 딸려 함께 관리되는 데이터

엔티티 형태¶

값	쉬운 뜻
`entity`	회원, 결제, 메시지처럼 업무에서 다루는 데이터
`association`	두 개 이상의 데이터를 잇고, 그 연결 자체의 상태나 기록을 가진 데이터

기록 역할¶

값	쉬운 뜻
`state`	지금 상태를 나타내며 바뀔 수 있는 값
`ledger`	순서와 변화를 남기기 위해 기존 기록을 고치지 않고 계속 추가하는 기록
`history`	이미 일어난 일이나 메시지를 남긴 기록
`snapshot`	특정 시점의 값을 그대로 보관한 복사본
`reference`	운영자가 관리하는 설정과 기준값
`projection`	다른 데이터를 계산하거나 모아서 만든 읽기 전용 결과

관계 유형¶

값	쉬운 뜻
`owns`	출발 데이터가 도착 데이터를 같이 관리
`references`	도착 데이터를 참고하지만 각자 따로 관리
`associates`	서로 대등한 데이터를 연결
`derives-from`	원본 데이터에서 계산해 만듦

연결 수는 관계 방향을 기준으로 1:1, 1:N, N:1, N:M만 사용한다. 예를 들어 1:N은 출발 데이터 하나가 도착 데이터 여러 개와 연결된다는 뜻이다.
관계 역할은 출발 엔티티에서 도착 엔티티가 맡는 의미를 소문자 kebab-case로 기록한다. 같은 출발·도착 조합이라도 작성자와 대상자처럼 의미가 다르면 관계 행을 분리하고 서로 다른 역할을 사용한다.
child는 정확히 하나의 owns 관계의 도착 엔티티여야 한다. association은 생명주기 소유 관계를 포함해 둘 이상의 관계 끝점을 명시해야 하며, 적어도 하나의 참조·연결 끝점을 가져야 한다.
데이터 분류는 데이터 거버넌스 정책의 일반, 내부, 민감만 사용하고, 엔티티에 포함되는 데이터 중 가장 높은 등급을 기록한다.

소유 문서 형식¶

각 소유 문서는 ## 논리 데이터 모델 절을 정확히 하나만 두고 아래 순서를 유지한다.

도메인 ID
먼저 보는 그림
논리 엔티티 표
관계 표
불변조건 표
먼저 보는 그림과 그 아래 꼭 지킬 규칙은 세 상세 표에서 자동으로 만든다.
작성자는 상세 표만 고치고 yarn generate:logical-data-model을 실행한다. 그림과 catalog를 직접 고치지 않는다.

논리 엔티티 표의 열은 아래 순서로 고정한다.

논리 ID	표시명	생명주기 역할	엔티티 형태	기록 역할	책임	최고 데이터 분류	생명주기

관계 표의 열은 아래 순서로 고정한다.

출발 논리 ID	관계 역할	관계 유형	도착 논리 ID	카디널리티	소유·삭제 규칙

불변조건 표의 열은 아래 순서로 고정한다.

규칙 ID	관련 논리 ID	불변조건	기준 문서

물리 테이블·컬럼·타입·인덱스·FK 이름은 이 절에 작성하지 않는다.
중요한 데이터 속성은 컬럼 사전이 아니라 책임, 관계, 불변조건으로 표현한다.
그림은 처음 읽는 사람을 위한 요약이다. 정확한 이름과 조건은 상세 표가 기준이다.
하나의 소유 문서는 현재 구조(as-is) 또는 예정 구조(to-be) 중 하나만 가진다. 현행과 예정 도메인은 각각의 인덱스에 정확히 한 번 등록한다.
현행·예정 분류는 해당 논리 모델이 실제 운영 서비스의 데이터 계약으로 사용되는지를 설명한다. 릴리스의 모든 부가 smoke나 사전 Gate 증빙이 완전한지를 나타내는 품질 상태로 사용하지 않는다.
구현과 운영 DB 구조가 반영되고 API·Admin·Mobile 중 해당 기능의 운영 소비 표면이 활성화됐다면 현행이다. FCM·WebSocket·scheduler 같은 개별 운영 검증의 누락은 별도 릴리스 기록이나 기술부채로 추적하되 이미 운영 중인 논리 모델을 예정 상태로 유지하는 근거로 사용하지 않는다.
API 계약 cutover 판정과 논리 모델 단계는 독립된 축이다. API 호환성 Gate의 완료·위반 여부로 현행 논리 모델을 예정 인덱스에 남기거나 되돌리지 않는다.
예정 모델을 현행으로 바꿀 때는 소유 문서의 기준 성격, 두 인덱스의 등록 위치, 생성 catalog와 비공개 연결 정보를 같은 작업에서 변경한다.

실제 DB 구조 연결¶

비공개 서비스 저장소는 검증용 DB 구조 목록(schema lock)의 모든 테이블과 뷰를 아래 중 하나로 분류한다.
- 공개 논리 엔티티 구현
- 내부 운영 객체
- 파생 조회 객체
하나의 물리 객체는 여러 논리 엔티티를 구현할 수 있고, 하나의 논리 엔티티도 여러 물리 객체로 구현할 수 있다.
내부 운영 객체는 공개 논리 ID를 만들지 않고 내부로 남기는 이유를 기록한다.
비공개 연결 정보는 공개 catalog의 canonical JSON snapshot과 SHA-256 checksum을 함께 고정한 local lock을 사용한다. 내장 snapshot과 checksum이 다르거나 존재하지 않는 논리 ID와 schema lock에 없는 물리 객체를 참조하면 실패해야 한다.
lock의 source repository와 catalog path는 출처를 설명하는 metadata다. Git commit, PR head, merge commit은 같은 catalog 내용에 여러 값이 생길 수 있고 local 검증에서 도달 가능성도 증명하지 않으므로 lock 불변조건에 포함하지 않는다.
생성 catalog는 현행과 예정 엔티티의 단계를 명시한다. 비공개 연결 정보는 현행 논리 엔티티 전체의 역방향 구현 커버리지를 보장한다. 예정 엔티티는 구현 브랜치 또는 출시 전 main에 선행 매핑할 수 있다.
출시 전 main에 선행 매핑할 때는 소유 문서가 운영 반영 조건을 추적하는 기술부채·flow·릴리스 기록을 링크하고, 구현·migration·소비자 활성화 조건과 비적용 범위의 N/A 근거를 명시한다. 운영 반영 전에는 예정으로 유지한다. 운영 반영 뒤에는 실제 배포 artifact와 대상 DB runtime이 해당 모델을 사용한다는 근거로 현행 승격하고, 남은 개별 smoke·복구·호환성 검증은 별도 상태로 추적한다.
GitHub Actions가 실행될 때마다 다른 저장소의 최신 브랜치를 조회하지 않는다. 공개 catalog를 고정한 local lock으로 검증하고, 논리 모델 변경으로 생성 catalog의 checksum이 달라질 때만 lock을 명시적으로 갱신한다. API·docs의 무관한 commit이나 squash·rebase에 따른 Git SHA 변경만으로는 lock을 갱신하지 않는다.

변경 영향 판정¶

변경	공개 논리 모델	비공개 연결 정보
도메인·엔티티 추가 또는 삭제	필수	필수
소유권·관계·불변조건·분류·생명주기 변경	필수	필요 시
테이블 분할·통합	논리 의미 변경 시	필수
컬럼명·저장 타입·인덱스 변경	논리 의미가 같으면 불필요	schema 검증
파생 뷰 추가·변경	공개 조회 의미 변경 시	필수
내부 backup 객체 변경	불필요	필수

공개 문서 갱신이 불필요하면 PR에 논리 문서 영향 없음 근거를 남긴다.
비공개 catalog lock 갱신 여부는 Git 이력 변경이 아니라 생성 catalog checksum 변경으로 판정한다.
새 물리 객체를 논리 엔티티나 내부/파생 객체로 분류하지 않은 상태에서는 DB 변경을 완료로 판정하지 않는다.

충실도 리뷰 판정¶

리뷰를 시작할 때 공개 논리 모델 충실도, 물리 DB 설계·운영 안전성, 문서 작성 도구 중 판정 대상을 먼저 고정한다. 서로 다른 대상의 문제를 하나로 합치지 않는다.
공개 논리 모델 충실도는 아래를 확인한다.
- 현행·예정 도메인과 소유 문서가 등록 인덱스와 빠짐없이 정확히 일치한다.
- 비공개 schema lock의 모든 물리 객체가 공개 논리 엔티티 구현, 내부 운영 객체, 파생 조회 객체 중 하나로 분류되고 현행 논리 엔티티가 모두 역방향 매핑된다.
- 논리 엔티티의 책임·분류·생명주기와 관계·불변조건이 매핑된 물리 객체의 업무 의미 및 실제 동작과 모순되지 않는다.
공개 논리 모델은 물리 컬럼 사전이나 ERD가 아니다. 물리 컬럼·타입, PK/FK/UNIQUE/CHECK, 인덱스, transaction/lock 구현, 파생 뷰의 전체 SQL 의존성을 공개 표에 나열하지 않은 것은 누락이 아니다.
논리 관계와 불변조건은 FK, UNIQUE, transaction, 애플리케이션 검증, 공통 업무 식별자, 파생 계산 중 하나 이상으로 구현될 수 있다. 특정 물리 제약 하나가 없다는 사실만으로 논리 관계나 불변조건이 틀렸다고 판정하지 않는다.
문서의 논리 의미와 실제 동작이 모순된다는 문제는 소유 문서와 함께 schema lock의 COMMENT, 실행 경로, 쿼리 또는 재현 결과 중 하나 이상의 직접 근거를 제시한다. 실제로 문서화된 불변조건을 위반하는 경로가 확인되면 구현 불변조건 위반으로 기록하고, 단순히 PK/FK/인덱스 누락으로 바꾸어 설명하지 않는다.
물리 DB의 중복 방지, 동시성, 성능, 제약 적절성 문제는 DB Migration Gate 정책과 엔지니어링 가드레일 기준의 별도 문제다. 그 문제가 논리 의미나 매핑 커버리지를 실제로 바꾸지 않으면 공개 논리 모델 충실도 판정에는 합산하지 않는다.
템플릿·검증기가 표준 형식을 만들거나 차단하지 못하는 문제는 문서 작성 도구 문제다. 현재 DB 구조나 논리 모델 내용이 틀렸다는 근거로 사용하지 않는다.

판정 대상	유효한 핵심 근거	단독으로는 무효인 근거
공개 논리 모델 충실도	미분류 물리 객체, 미매핑 현행 엔티티, 책임·관계·불변조건의 직접 모순	공개 컬럼·PK/FK·인덱스 목록 부재, 중간 VIEW 의존성 생략
물리 DB 설계·운영 안전성	재현 가능한 중복·경합·제약·쿼리 문제	공개 논리 표에 물리 구현 정보가 없음
문서 작성 도구	표준과 다른 템플릿, 잘못된 문서를 통과시키는 검증 재현	DB 구조 또는 업무 동작에 대한 추정

검증¶

docs 검증은 현행·예정 목록이 빠짐없이 일치하는지, 도메인·논리 ID가 겹치지 않는지, 소유 문서와 정해진 분류값이 맞는지, 관계 대상과 표 구조가 올바른지 확인한다. 하나라도 맞지 않으면 검증에 실패한다.
상세 표가 바뀌었는데 먼저 보는 그림을 다시 만들지 않으면 검증에 실패한다.
비공개 DB 구조 검증은 schema lock과 연결 정보가 빠짐없이 일치하는지, 객체 종류와 공개 catalog의 논리 ID가 맞는지 확인한다. 하나라도 맞지 않으면 검증에 실패한다.
비공개 catalog lock 검증은 고정된 repository·catalog path, 내장 canonical snapshot과 checksum의 일치, catalog 구조·참조 무결성을 확인한다. Git commit의 형식·도달 가능성·merge 포함 여부는 검증 대상이 아니다.
기존 문서 전체의 일반 분류값 변경은 이 정책의 논리 모델 절 검증과 분리한다. 이번 표준에 등록된 소유 문서만 즉시 필수 검사 대상으로 삼는다.