DB 스키마 v1

1. 설계 원칙

• DB는 PostgreSQL을 기준으로 설계하고, Prisma 모델로 옮기기 쉬운 테이블 단위 구조를 사용한다.
• 본사관리자 계정과 부동산 사무소 사용자는 인증 영역과 테이블을 분리한다.
• 사무소 업무 데이터는 반드시 officeId를 가진다.
• 일반 업무 사용자의 데이터 범위는 writerUserId, managerUserId, createdByUserId, assigneeUserId 등 담당자 필드로 제한한다.
• 모든 주요 테이블은 id, createdAt, updatedAt을 가진다.
• 업무 데이터는 삭제보다 status, deletedAt 기반 비활성/소프트 삭제를 우선한다.
• 개인정보 접근, 계약 PDF 생성, 과금 계산처럼 민감하거나 감사가 필요한 작업은 별도 로그를 남긴다.

2. 공통 타입

2.1 ID와 시간

• id: UUID, primary key
• createdAt: timestamptz, default now
• updatedAt: timestamptz, default now
• deletedAt: timestamptz nullable

2.2 주요 enum

HeadquartersRole = SUPER_ADMIN | ADMIN | BILLING_MANAGER | SUPPORT
HeadquartersUserStatus = ACTIVE | INACTIVE

OfficeStatus = ACTIVE | SUSPENDED | CLOSED
OfficeUserRole = OWNER_ADMIN | AGENT | ASSISTANT
OfficeUserStatus = INVITED | ACTIVE | INACTIVE | SUSPENDED

PermissionScope = SYSTEM | OFFICE
FeatureCode = EXPIRY_KAKAO_ALERT | CUSTOMER_POPUP | LISTING_EXCHANGE | ADVANCED_PDF | BULK_EXCEL_UPLOAD | EXTERNAL_DOCUMENT_LINK

ContractType = SALE | LEASE | COMMERCIAL | LAND | OTHER
ContractStatus = DRAFT | ACTIVE | COMPLETED | CANCELED | ARCHIVED
ContractPartyType = SELLER | BUYER | LESSOR | LESSEE | AGENT | CO_AGENT | OTHER

CustomerStatus = ACTIVE | LEAD | IN_PROGRESS | CONTRACTED | INACTIVE | ARCHIVED
ListingType = APARTMENT | OFFICETEL | HOUSE | COMMERCIAL | LAND | OTHER
ListingDealType = SALE | JEONSE | MONTHLY_RENT | SHORT_TERM | OTHER
ListingVisibility = PRIVATE | OFFICE | EXCHANGE
ListingStatus = DRAFT | ACTIVE | RESERVED | CONTRACTED | HIDDEN | ARCHIVED
ListingExchangeStatus = REQUESTED | APPROVED | REJECTED | REVOKED | EXPIRED

NotificationStatus = SCHEDULED | SENT | FAILED | CANCELED
PopupCampaignStatus = DRAFT | ACTIVE | PAUSED | ENDED
BillingMonthStatus = DRAFT | CONFIRMED | CANCELED
AuditAction = READ | CREATE | UPDATE | DELETE | EXPORT | PRINT | LOGIN | PERMISSION_CHANGE | BILLING_CHANGE

3. 본사 영역

3.1 headquarters_users

본사관리자 계정이다. 부동산 사무소 사용자인 office_users와 분리한다.

관계:

• headquarters_users.id는 사무소 생성, 과금 정책 변경, 기능 권한 변경, 감사 로그의 행위자 FK로 사용한다.

인덱스:

• unique headquarters_users_email_key(email)
• index idx_headquarters_users_status(status)

4. 사무소와 사용자

4.1 offices

부동산 사무소 tenant의 루트 테이블이다.

관계:

• offices 1:N office_users
• offices 1:N contracts
• offices 1:N customers
• offices 1:N listings
• offices 1:N office_billing_policies
• offices 1:N office_features

인덱스:

• unique partial offices_business_number_key(businessNumber) where businessNumber is not null
• index idx_offices_status(status)
• index idx_offices_name(name)

4.2 office_users

부동산 사무소에 소속된 사용자 계정이다.

제약:

• unique (officeId, email)
• role = OWNER_ADMIN 사용자는 사무소별 최소 1명 유지를 애플리케이션 또는 트랜잭션으로 보장한다.
• billable = false는 비활성/초대 미가입/특별 면제 등 명시 사유가 있어야 한다.

인덱스:

• index idx_office_users_office_role_status(officeId, role, status)
• index idx_office_users_office_billable_status(officeId, billable, status)
• index idx_office_users_permission_group(permissionGroupId)

4.3 permission_groups

사무소별 사용자 권한 그룹이다. MVP에서는 JSON 권한을 사용하고, 기능 확정 후 별도 permission 테이블로 분리할 수 있다.

권장 permissionsJson 예시:

{
  "contracts": { "read": "own", "create": true, "update": "own", "delete": false, "export": false },
  "customers": { "read": "own", "create": true, "update": "own", "delete": false, "export": false },
  "listings": { "read": "own", "create": true, "update": "own", "delete": false, "exchange": false },
  "users": { "read": false, "create": false, "update": false },
  "billing": { "read": false },
  "features": { "manage": false }
}

인덱스:

• unique (officeId, code) where officeId is not null
• unique (code) where officeId is null
• index idx_permission_groups_scope(scope)

5. 기능 권한과 과금

5.1 features

기능 권한 및 추가 과금 기준의 마스터 테이블이다.

인덱스:

• unique features_code_key(code)
• index idx_features_status(status)

5.2 office_features

사무소별 기능 사용 가능 여부와 월 과금액을 저장한다.

제약:

• 같은 officeId + featureId에서 effectiveTo is null인 현재 정책은 1개만 허용한다.

인덱스:

• index idx_office_features_office_enabled(officeId, enabled)
• index idx_office_features_feature(featureId)
• unique partial office_features_current_key(officeId, featureId) where effectiveTo is null

5.3 office_billing_policies

사무소별 기본 과금, 등록 가능 인원, 무료 인원, 초과 인원 단가를 이력형으로 저장한다.

제약:

• maxUserLimit >= includedUserLimit
• baseMonthlyFee >= 0, extraUserFee >= 0
• 같은 사무소의 현재 정책은 1개만 허용한다.

인덱스:

• index idx_office_billing_policies_office_effective(officeId, effectiveFrom desc)
• unique partial office_billing_policies_current_key(officeId) where effectiveTo is null

5.4 billing_monthly_usages

월별 예상 또는 확정 과금 스냅샷이다. 실제 결제 자동화 전에도 본사 화면의 예상 과금 계산에 사용한다.

인덱스:

• unique billing_monthly_usages_office_month_key(officeId, billingMonth)
• index idx_billing_monthly_usages_month_status(billingMonth, status)

6. 계약

6.1 contracts

계약관리 목록의 기준 테이블이다.

제약:

• unique (officeId, contractNo)
• writerUserId, managerUserId, listingId는 같은 officeId에 속해야 한다.

인덱스:

• index idx_contracts_office_status_date(officeId, status, contractDate desc)
• index idx_contracts_office_manager(officeId, managerUserId, updatedAt desc)
• index idx_contracts_office_writer(officeId, writerUserId, updatedAt desc)
• index idx_contracts_office_end_date(officeId, endDate)
• index idx_contracts_office_balance_due_date(officeId, balanceDueDate)
• index idx_contracts_listing(listingId)

6.2 contract_versions

계약 입력값과 특약사항의 버전 이력이다. PDF 재생성은 이 테이블의 특정 버전 데이터를 사용한다.

인덱스:

• unique contract_versions_contract_version_key(contractId, versionNo)
• index idx_contract_versions_contract_created(contractId, createdAt desc)

6.3 contract_parties

계약 당사자와 고객관리 데이터 연결 테이블이다.

제약:

• customerId가 있으면 계약의 officeId와 고객의 officeId가 같아야 한다.

인덱스:

• index idx_contract_parties_contract(contractId, sortOrder)
• index idx_contract_parties_customer(customerId)
• index idx_contract_parties_phone(phone)

7. 고객

7.1 customer_groups

사무소별 고객 그룹이다.

인덱스:

• unique (officeId, name)

7.2 customers

고객관리의 기준 테이블이다.

제약:

• managerUserId, groupId, sourceContractId는 같은 officeId에 속해야 한다.

인덱스:

• index idx_customers_office_manager_status(officeId, managerUserId, status)
• index idx_customers_office_name(officeId, name)
• index idx_customers_office_phone(officeId, phone)
• index idx_customers_group(groupId)

7.3 customer_memos

고객별 상담/업무 메모 이력이다.

인덱스:

• index idx_customer_memos_customer_created(customerId, createdAt desc)
• index idx_customer_memos_office_created(officeId, createdAt desc)

8. 매물

8.1 listings

매물관리의 기준 테이블이다.

제약:

• managerUserId, createdByUserId는 같은 officeId에 속해야 한다.
• visibility = EXCHANGE이면 exchangeEnabled = true여야 한다.

인덱스:

• index idx_listings_office_manager_status(officeId, managerUserId, status)
• index idx_listings_office_visibility_status(officeId, visibility, status)
• index idx_listings_exchange_status(visibility, exchangeEnabled, status)
• index idx_listings_address(officeId, address1)
• GIN index idx_listings_price_json(priceJson) 필요 시 추가

8.2 listing_exchanges

공동중개/매물 교환 공개 범위를 확장하기 위한 준비 테이블이다.

제약:

• ownerOfficeId는 listing.officeId와 같아야 한다.
• sharedToOfficeId가 null이면 전체 공개 정책으로 해석한다.

인덱스:

• index idx_listing_exchanges_listing_status(listingId, status)
• index idx_listing_exchanges_shared_office_status(sharedToOfficeId, status)
• unique partial listing_exchanges_target_key(listingId, sharedToOfficeId) where status in ('REQUESTED', 'APPROVED')

9. 알림과 팝업

9.1 notifications

계약 만료 알림 등 발송 예약/이력이다. 실제 카카오 발송은 2차라도 스키마는 준비한다.

인덱스:

• index idx_notifications_office_status_remind(officeId, status, remindAt)
• index idx_notifications_contract(contractId)
• index idx_notifications_customer(customerId)

9.2 popup_campaigns

고객 예약 팝업 캠페인이다.

인덱스:

• index idx_popup_campaigns_office_status(officeId, status)
• GIN index idx_popup_campaigns_target_rule(targetRuleJson)

9.3 popup_deliveries

사용자별 팝업 노출/확인/닫기 이력이다.

인덱스:

• index idx_popup_deliveries_user_created(userId, createdAt desc)
• index idx_popup_deliveries_campaign(campaignId)
• unique popup_deliveries_campaign_user_customer_key(campaignId, userId, customerId)

10. 감사 로그

10.1 audit_logs

개인정보, 권한, 과금, 데이터 내보내기 작업을 추적한다.

인덱스:

• index idx_audit_logs_office_created(officeId, createdAt desc)
• index idx_audit_logs_actor_created(actorType, headquartersUserId, officeUserId, createdAt desc)
• index idx_audit_logs_resource(resourceType, resourceId)

11. 핵심 관계 요약

headquarters_users
  ├─ offices.createdByHeadquartersUserId
  ├─ office_billing_policies.changedByHeadquartersUserId
  └─ office_features.changedByHeadquartersUserId

offices
  ├─ office_users
  ├─ permission_groups
  ├─ office_billing_policies
  ├─ office_features ─ features
  ├─ contracts ─ contract_versions
  │             └─ contract_parties ─ customers
  ├─ customers ─ customer_groups
  ├─ listings ─ listing_exchanges
  ├─ notifications
  ├─ popup_campaigns ─ popup_deliveries
  └─ billing_monthly_usages

12. Prisma 변환 메모

• PostgreSQL jsonb는 Prisma Json으로 매핑한다.
• PostgreSQL inet은 Prisma에서 String으로 시작하고, 필요 시 raw SQL migration으로 타입을 조정한다.
• partial unique index, GIN index, enum 변경은 Prisma schema만으로 표현이 제한될 수 있으므로 migration SQL에 별도 작성한다.
• 같은 사무소 소속 검증은 DB FK만으로 완전 보장하기 어렵다. 애플리케이션 서비스 레이어에서 officeId 일치 검사를 공통 함수로 강제한다.
• deletedAt is null 조건이 자주 붙는 목록 조회는 향후 partial index를 추가한다.