Skip to content

Shortlink Data Model

wcorn edited this page Oct 16, 2026 · 5 revisions

데이터 모델: 단축 URL (링크)

확정 명세 · 아키텍처 · API 설계

Liquibase 마이그레이션: 055-create-shortlink-tables.yaml(현행 최신은 054-create-travel-move.yaml). 컨벤션: 불리언은 BIT(1)(Hibernate validate와 맞추기 위해 — DB 마이그레이션), 상태값은 VARCHAR enum, 시각은 엔티티 Instant / DB DATETIME(6). 단일 사용자지만 기존 도메인대로 member_id 스코프를 포함한다.

1. ERD

member 1 ──< shortlink 1 ──< shortlink_tag
                        1 ──< shortlink_target_history
                        1 ──< shortlink_visit          (원시, 90일)
                        1 ──< shortlink_visit_daily    (집계, 영구)
  • shortlink — 링크 1건 (SSOT). 슬러그가 불변 키다
  • shortlink_tag — 태그 0..N (denormalized, moment_tag와 같은 방식)
  • shortlink_target_history — 목적지 교체 이력. 최초 발급도 한 줄
  • shortlink_visit — 방문 원시 기록. 90일 후 삭제
  • shortlink_visit_daily — 일별 집계. 영구 보존

방문 시점에 shortlink_visit INSERT와 shortlink_visit_daily UPSERT를 함께 한다. 야간 집계 배치가 없다(아키텍처 §3).

2. 테이블

2.1 shortlink

컬럼 타입 제약 설명
id BIGINT PK, AI
member_id BIGINT NOT NULL 소유 멤버(스코프)
slug VARCHAR(32) NOT NULL, UNIQUE 소문자 정규화 저장. 불변
target_url VARCHAR(2048) NOT NULL 현재 목적지
title VARCHAR(100) NULL 사용자가 붙인 이름(#1424). NULL이면 화면은 짧은 주소를 제목 자리에 둔다. og_title로 채우지 않는다 — 그건 목적지가 말하는 제목이라 목적지를 갈면 바뀌어야 하고, 이 칸은 사용자가 붙인 이름이라 남는다
memo VARCHAR(255) NULL 화면에서는 **「설명」**이다(#1424). 설명 컬럼을 따로 두지 않는다 — 같은 일을 하는 칸이 둘이면 어디에 적을지가 갈린다
status VARCHAR(20) NOT NULL ACTIVE · DISABLED · DELETED
favorite BIT(1) NOT NULL, DEFAULT 0 즐겨찾기
custom_slug BIT(1) NOT NULL, DEFAULT 0 사용자가 슬러그를 직접 지었는지(「커스텀」 배지). 길이로는 판정할 수 없다 — 5자짜리 커스텀 슬러그가 자동 발급과 구분되지 않는다(API의 custom · #1236)
password_hash VARCHAR(72) NULL BCrypt(60자). NULL이면 비밀번호 없음
expires_at DATETIME(6) NULL NULL이면 만료 없음
og_title VARCHAR(255) NULL 프리뷰 결과(있으면)
og_image_url VARCHAR(1024) NULL 〃
og_fetched_at DATETIME(6) NULL 〃 시도 시각. NULL = 아직 시도 안 함
created_at DATETIME(6) NOT NULL @CreatedDate
updated_at DATETIME(6) NOT NULL @LastModifiedDate
deleted_at DATETIME(6) NULL 소프트 삭제 시각

인덱스:

  • uk_shortlink_slug (slug) UNIQUE — 리다이렉트 조회 경로이자 §3.1 영구 점유의 집행 지점
  • idx_shortlink_member_created (member_id, created_at DESC, id DESC) — 목록
  • idx_shortlink_member_favorite (member_id, favorite, created_at DESC) — 즐겨찾기 섹션

UNIQUE(slug)에 deleted_at을 섞지 않는다. 삭제된 행이 슬러그를 계속 물고 있어야 재발급이 막힌다(명세 §3.1). "삭제된 것만 제외한 부분 UNIQUE"는 이 모듈에서 버그다.

검색(SL-012)은 slug · target_url · title · memo에 대한 LIKE %...%다. 전용 인덱스를 두지 않는다 — 단일 사용자 규모에서 풀스캔이 문제되지 않고, 링크가 수천 건이 되면 그때 판단한다.

2.2 shortlink_tag

컬럼 타입 제약 설명
id BIGINT PK, AI
shortlink_id BIGINT FK→shortlink(id), NOT NULL, ON DELETE CASCADE
name VARCHAR(50) NOT NULL 태그명(정규화 안 함, 단순 저장)

인덱스: idx_shortlink_tag_link (shortlink_id) · idx_shortlink_tag_name (name) — 사이드바 태그별 개수 집계

2.3 shortlink_target_history

컬럼 타입 제약 설명
id BIGINT PK, AI
shortlink_id BIGINT FK→shortlink(id), NOT NULL, ON DELETE CASCADE
target_url VARCHAR(2048) NOT NULL 그 시점의 목적지
reason VARCHAR(255) NULL 교체 사유(예: 서명 만료로 재발급)
changed_at DATETIME(6) NOT NULL

인덱스: idx_shortlink_history (shortlink_id, changed_at DESC)

발급 시 최초 1행을 함께 넣는다(reason = 최초 발급). 상세 화면 이력의 마지막 줄이 그것이다.

2.4 shortlink_visit (원시 · 90일)

컬럼 타입 제약 설명
id BIGINT PK, AI
shortlink_id BIGINT FK→shortlink(id), NOT NULL, ON DELETE CASCADE
visited_at DATETIME(6) NOT NULL
referrer_domain VARCHAR(255) NULL 도메인까지만. 저장 시점에 잘라 넣는다
device VARCHAR(20) NULL MOBILE · DESKTOP · TABLET · UNKNOWN
country CHAR(2) NULL ISO 3166-1 alpha-2. 항상 NULL이다 — 국가를 판정하지 않기로 했다(2026-08-24, D-9 뒤집힘). 컬럼은 남겨 둔다: 지우면 나중에 마이그레이션이 한 번 더 필요하고, 값이 비는 것은 화면이 이미 다루고 있다
is_bot BIT(1) NOT NULL, DEFAULT 0 봇·프리뷰 여부

인덱스: idx_visit_link_time (shortlink_id, visited_at DESC) · idx_visit_time (visited_at) — 90일 정리 배치

IP 컬럼이 없다. 없는 것이 설계다(명세 §8.1). 국가 판정을 하지 않기로 한 뒤에는 IP를 읽지도 않는다(D-9). 남는 것은 판정 결과 2자 자리뿐이고 그마저 비어 있다.

〈원문〉 국가는 판정 결과 2자만 남고, User-Agent 원문과 전체 리퍼러 URL도 저장하지 않는다. 나중에 "분석에 필요할지 모르니 원문도 넣자"는 요구가 오면 이 문단을 근거로 거절한다.

2.5 shortlink_visit_daily (집계 · 영구)

컬럼 타입 제약 설명
id BIGINT PK, AI
shortlink_id BIGINT FK→shortlink(id), NOT NULL, ON DELETE CASCADE
visit_date DATE NOT NULL 집계 기준일 (KST)
visit_count INT NOT NULL, DEFAULT 0 사람 방문만
bot_count INT NOT NULL, DEFAULT 0 봇·프리뷰

인덱스: uk_visit_daily (shortlink_id, visit_date) UNIQUE — UPSERT 키

visit_date는 KST 날짜다. 화면의 "최근 30일 일별 막대"·"오늘"이 사용자 기준 하루와 어긋나면 안 된다. (여행 모듈과 달리 이 모듈에는 여러 타임존이 없다 — 발급자는 1인이고 KST에 산다.)

3. 파생값 — 저장하지 않는 것

값 왜 파생인가
총 방문 수 SUM(visit_count). 캐시 컬럼을 두면 갱신 주체가 둘(방문·정리 배치)이 되어 어긋난다
최근 7일 · 마지막 방문 집계·원시에서 계산
만료 여부 expires_at < now(). 저장하면 날짜가 넘어갈 때 갱신할 주체가 없다(여행 모듈 §13.4와 같은 이유)
화면 상태(활성/꺼짐/만료) status + expires_at + deleted_at의 조합
짧은 주소 전체 문자열 s.orino.dev + / + slug. 도메인을 행마다 저장하지 않는다

4. 보존과 삭제

대상 규칙
shortlink 소프트 삭제(status=DELETED, deleted_at). 행은 영구히 남는다 — 슬러그 점유
shortlink_tag · _target_history 링크 행이 남으므로 함께 남는다. CASCADE는 하드 삭제 시의 안전장치일 뿐 평시에 발동하지 않는다
shortlink_visit 90일 초과 삭제(하루 1회 배치)
shortlink_visit_daily 영구

하드 삭제(행을 실제로 지우기)는 API에 없다. 필요하면 DB에서 수동으로 하고, 그때 슬러그가 재사용 가능해진다는 것을 알고 해야 한다.

5. 마이그레이션

055-create-shortlink-tables.yaml 하나로 5테이블을 만든다. 기존 테이블 변경 없음.

구현 시점 정정(#1236): 055는 3테이블(shortlink · shortlink_tag · shortlink_target_history)만 만든다. 방문 2테이블은 통계 단계(#1240)에서 별도 changelog로 붙인다 — 쓰는 코드 없이 테이블만 서 있으면 스키마가 무엇을 약속하는지 흐려진다.

#1240에서 056-create-shortlink-visit-tables.yaml로 shortlink_visit · shortlink_visit_daily를 만들었다. 컬럼 구성은 §2.4·§2.5 그대로이고, 일별 누적은 엔티티가 아니라 INSERT … ON DUPLICATE KEY UPDATE 한 문장이다(ShortlinkVisitDailyRepository.accumulate) — 읽어서 +1 하고 저장하면 동시 방문 두 건이 하나로 뭉개진다.

세 changeSet 모두 rollback: dropTable을 명시한다. 자동 롤백은 인덱스를 먼저 지우려 드는데 FK가 그 인덱스를 쓰고 있어 MySQL이 거부한다(054-create-travel-move.yaml과 같은 이유). TravelMultiCityMigrationTest가 태그 지점까지 되감으므로 이 실패는 테스트에서 바로 드러난다.

체크:

  • favorite · custom_slug · is_bot은 **BIT(1)**로 선언한다. BOOLEAN으로 적으면 Hibernate validate가 깨진다
  • target_url(2048)은 VARCHAR다. TEXT가 아니므로 @JdbcTypeCode 처리가 필요 없다
  • visit_date는 DATE(시각 아님)

Clone this wiki locally