chore: Flyway 기반 데이터베이스 스키마 형상관리 활성화 (#109)

* [BOOK-280] fix: infra - userBook 엔티티의 length와 통일

* [BOOK-280] feat: infra - 초기 데이터베이스 스키마 생성(users, books, user_books, reading_records, tags, reading_record_tags 테이블 추가 및 제약조건)

* [BOOK-280] feat: infra - 기본 태그 데이터 삽입 SQL 스크립트 추가

* [BOOK-280] chore: infra - application-persistence.yml 파일 수정 및 Flyway 설정 변경

* [BOOK-280] docs: infra - 데이터베이스 스키마 거버넌스 전략 및 초기 데이터 관리 가이드라인 추가

* [BOOK-280] docs: infra - 데이터 삽입 가이드라인 수정 및 성능 고려 사항 추가

* [BOOK-280] refactor: infra - bookIsbn13 필드 길이 13으로 변경

* [BOOK-280] feat: infra - bookIsbn13 필드 길이 13자로 변경하는 Flyway 마이그레이션 스크립트 추가

Author: move-hoon

infra/README.md

@@ -51,3 +51,60 @@ Batch ────────→ Infra
 - Repository Implementation은 실제 데이터 저장소와의 연동을 담당하며, Repository Interface를 구현하여 JPA, MongoDB 등 구체적인 기술로 데이터를 처리한다.
 - Client Implementation은 외부 시스템과의 실제 통신을 구현하며, Domain Client Interface를 구현하여 REST API, gRPC 등 구체적인 프로토콜로 통신한다.
 - Import Selector는 모듈 간 설정 조합을 관리하며, admin, batch, apis 모듈 내부에서 애플리케이션 요구사항에 따라 필요한 Infrastructure 구성을 동적으로 선택한다.
+
+## **💿Database Schema Governance Strategy**
+- 개발 환경에서는 ddl-auto를 활용해 스키마를 신속히 반영하고, 운영 환경에서는 Flyway 기반 마이그레이션을 통해 데이터베이스 스키마를 형상관리한다.
+- Flyway 스크립트는 스키마 구조를 다루는 migration과 초기 데이터를 다루는 seed로 역할을 분리하여 관리한다.
+
+### 1. 스키마 관리 (migration)
+- 스크립트 위치는 infra 모듈의 resources/db/migration 디렉터리에 저장한다.
+- 스크립트는 `V<YYYYMMDD>_<NNN>__<Action>_<Object>_<Details>.sql` 형식으로 명명한다.
+- 구체적인 네이밍 규칙은 아래와 같다.
+  - `V` (접두사): Versioned Migration을 의미하는 Flyway의 표준 접두사로 이 스크립트는 DB 당 단 한 번만 실행된다.
+      - 예시: V
+  - `<YYYYMMDD>` (버전 - 날짜): 스크립트가 작성된 날짜로, 버전 충돌을 방지하고 시간순으로 마이그레이션을 정렬하는 기준이된다.
+      - 예시: 20250820 
+  - _`<NNN>` (버전 - 일련번호): 같은 날짜에 여러 스크립트가 생성될 경우, 실행 순서를 보장하기 위한 3자리 일련번호로 매일 001부터 시작한다.
+      - 예시: _001, _002
+  - __ (구분자): 버전과 설명을 구분하는 이중 밑줄 표준 구분자이다.
+  - `<Action>` (동작): 스크립트가 수행하는 주요 DDL 동작을 대문자로 명시한다.
+      - 예시: CREATE, ALTER, ADD, DROP, RENAME, INSERT
+  - `<Object>` (객체): 변경이 일어나는 주된 객체의 이름으로, 테이블 이름을 뜻한다.
+      - 예시: USERS, BOOKS, USER_BOOKS 
+  - `<Details>` (상세 설명): 변경 사항을 더 구체적으로 설명한다. 여러 단어는 밑줄(_)로 연결하고, 첫 글자만 대문자로 표기한다.
+      - 예시: mail_Column, Add_Nickname, Fk_To_Users
+
+| 상황                               | 파일 이름 예시                                                      |
+|------------------------------------|---------------------------------------------------------------------|
+| Users 테이블 생성                  | `V20250820_001__Create_Users.sql`                                   |
+| Books 테이블에 nickname 컬럼 추가  | `V20250820_002__Add_Books_Nickname.sql`                             |
+| Users 테이블의 nickname 컬럼 이름 변경 | `V20250821_001__Rename_Users_Nickname_To_Username.sql`              |
+| User_books 테이블에 인덱스 추가    | `V20250821_002__Add_User_books_Index_On_UserId.sql`                 |
+| Books 테이블의 title 컬럼 타입 변경 | `V20250822_001__Alter_Books_Title_To_Varchar500.sql`                 |
+| 기본 Role 데이터 삽입              | `V20250822_002__Insert_Default_Roles.sql`                           |
+
+### 2. 초기 데이터 관리 (seed)
+- 스크립트 위치는 infra 모듈의 resources/db/seed 디렉터리 구조로 관리한다.
+- `db/seed/common/`: 모든 환경(개발, 스테이징, 운영)에 필요한 필수 기본 데이터
+- `db/seed/dev/`: 개발 환경 전용 테스트 데이터 (향후 필요시 적용)
+- 스크립트는 `R__<Object>_<Data_Type>.sql` 형식으로 명명한다.
+- 구체적인 네이밍 규칙은 아래와 같다.
+- `R` (접두사): Repeatable Migration을 의미하는 Flyway의 표준 접두사로, 스크립트 내용이 변경될 때마다 다시 실행된다.
+  - 예시: R
+- __ (구분자): 접두사와 설명을 구분하는 이중 밑줄 표준 구분자이다.
+- `<Object>` (객체): 데이터가 삽입되는 주된 테이블 이름을 소문자로 명시한다.
+  - 예시: tags, roles, categories
+- `<Data_Type>` (데이터 유형): 삽입되는 데이터의 성격을 설명한다. 여러 단어는 밑줄(_)로 연결하고, 소문자로 표기한다.
+  - 예시: default_data, master_data, essential_data
+
+| 데이터 유형                        | 파일 이름 예시                                    | 설명                                             |
+|------------------------------------|---------------------------------------------------|--------------------------------------------------|
+| 기본 태그 데이터                   | `R__tags_default_data.sql`                       | 시스템에서 사용하는 기본 태그들                  |
+| 필수 역할 데이터                   | `R__roles_essential_data.sql`                    | USER, ADMIN 등 필수 사용자 역할                  |
+| 카테고리 마스터 데이터             | `R__categories_master_data.sql`                  | 도서 분류 등 비즈니스 카테고리                   |
+| 시스템 설정 데이터                 | `R__system_config_default_data.sql`              | 애플리케이션 기본 설정값들                       |
+
+#### 데이터 삽입 가이드라인
+- **기본 원칙**: 모든 초기 데이터는 R__ 스크립트를 사용하여 관리한다.
+- **중복 방지**: INSERT IGNORE 또는 ON DUPLICATE KEY UPDATE 구문을 활용하여 중복 삽입을 방지한다.
+- **성능 고려**: 대용량 데이터(만 건 이상)는 R__ 스크립트 사용을 지양하고, 별도 프로세스로 관리한다.

infra/src/main/kotlin/org/yapp/infra/book/entity/BookEntity.kt

@@ -41,7 +41,7 @@ class BookEntity private constructor(
     var author: String = author
         protected set
 
-    @Column(length = 255)
+    @Column(length = 300)
     var publisher: String = publisher
         protected set
 

infra/src/main/kotlin/org/yapp/infra/userbook/entity/UserBookEntity.kt

@@ -34,7 +34,7 @@ class UserBookEntity(
     @JdbcTypeCode(Types.VARCHAR)
     val bookId: UUID,
 
-    @Column(name = "book_isbn13", nullable = false)
+    @Column(name = "book_isbn13", nullable = false, length = 13)
     val bookIsbn13: String,
 
     coverImageUrl: String,

infra/src/main/resources/application-persistence.yml

@@ -17,12 +17,11 @@ spring:
 
   flyway:
     enabled: true
-    baseline-on-migrate: true
-    baseline-version: 0
-    clean-disabled: true
+    baseline-on-migrate: false
+    validate-on-migrate: true
     locations:
-      - classpath:db/migration
-      - classpath:db/reed
+      - classpath:db/migration/mysql
+      - classpath:db/seed/common
 
 ---
 spring:
@@ -32,10 +31,14 @@ spring:
 
   jpa:
     hibernate:
-      ddl-auto: update
+      ddl-auto: validate
 
   flyway:
-    enabled: false
+    enabled: true
+    baseline-on-migrate: false
+    locations:
+      - classpath:db/migration/mysql
+      - classpath:db/seed/common
 
 ---
 spring:

infra/src/main/resources/db/migration/mysql/V1__init.sql

@@ -0,0 +1,94 @@
+CREATE TABLE users
+(
+    id                  VARCHAR(36)   NOT NULL,
+    created_at          datetime(6)   NOT NULL,
+    updated_at          datetime(6)   NOT NULL,
+    deleted_at          datetime(6)      NULL,
+    email               VARCHAR(100)  NOT NULL,
+    provider_type       ENUM ('APPLE', 'KAKAO') NOT NULL,
+    provider_id         VARCHAR(100)  NOT NULL,
+    nickname            VARCHAR(100)  NOT NULL,
+    profile_image_url   VARCHAR(255)  NULL,
+    `role`              ENUM ('ADMIN', 'USER')  NOT NULL,
+    terms_agreed        BIT(1)        NOT NULL,
+    apple_refresh_token VARCHAR(1024) NULL,
+    CONSTRAINT pk_users PRIMARY KEY (id)
+);
+
+CREATE TABLE books
+(
+    id               VARCHAR(36)   NOT NULL,
+    created_at       datetime(6)   NOT NULL,
+    updated_at       datetime(6)   NOT NULL,
+    deleted_at       datetime(6)      NULL,
+    isbn13           VARCHAR(13)   NOT NULL,
+    title            VARCHAR(255)  NOT NULL,
+    author           VARCHAR(255)  NULL,
+    publisher        VARCHAR(300)  NULL,
+    publication_year INT           NULL,
+    cover_image_url  VARCHAR(2048) NULL,
+    `description`    VARCHAR(2000) NULL,
+    CONSTRAINT pk_books PRIMARY KEY (id)
+);
+
+CREATE TABLE user_books
+(
+    id                   VARCHAR(36)   NOT NULL,
+    created_at           datetime(6)   NOT NULL,
+    updated_at           datetime(6)   NOT NULL,
+    deleted_at           datetime(6)     NULL,
+    user_id              VARCHAR(36)   NOT NULL,
+    book_id              VARCHAR(36)   NOT NULL,
+    book_isbn13          VARCHAR(255)  NOT NULL,
+    cover_image_url      VARCHAR(2048) NOT NULL,
+    publisher            VARCHAR(300)  NOT NULL,
+    title                VARCHAR(255)  NOT NULL,
+    author               VARCHAR(255)  NULL,
+    `status`             ENUM ('BEFORE_READING', 'BEFORE_REGISTRATION', 'COMPLETED', 'READING') NOT NULL,
+    reading_record_count INT           NOT NULL,
+    CONSTRAINT pk_user_books PRIMARY KEY (id)
+);
+
+CREATE TABLE reading_records
+(
+    id           VARCHAR(36)       NOT NULL,
+    created_at   datetime(6)   NOT NULL,
+    updated_at   datetime(6)   NOT NULL,
+    deleted_at   datetime(6)      NULL,
+    user_book_id VARCHAR(36)   NOT NULL,
+    page_number  INT           NOT NULL,
+    quote        VARCHAR(1000) NOT NULL,
+    review       VARCHAR(1000) NOT NULL,
+    CONSTRAINT pk_reading_records PRIMARY KEY (id)
+);
+
+CREATE TABLE tags
+(
+    id         VARCHAR(36)     NOT NULL,
+    created_at datetime(6) NOT NULL,
+    updated_at datetime(6) NOT NULL,
+    deleted_at datetime(6)    NULL,
+    name       VARCHAR(10) NOT NULL,
+    CONSTRAINT pk_tags PRIMARY KEY (id)
+);
+
+CREATE TABLE reading_record_tags
+(
+    id                VARCHAR(36)     NOT NULL,
+    created_at        datetime(6) NOT NULL,
+    updated_at        datetime(6) NOT NULL,
+    deleted_at        datetime(6)    NULL,
+    reading_record_id VARCHAR(36) NOT NULL,
+    tag_id            VARCHAR(36) NOT NULL,
+    CONSTRAINT pk_reading_record_tags PRIMARY KEY (id)
+);
+
+ALTER TABLE books
+    ADD CONSTRAINT uc_books_isbn13 UNIQUE (isbn13);
+
+ALTER TABLE tags
+    ADD CONSTRAINT uc_tags_name UNIQUE (name);
+
+CREATE INDEX idx_user_books_title ON user_books (title);
+
+CREATE INDEX idx_user_books_user_id_title ON user_books (user_id, title);

infra/src/main/resources/db/migration/mysql/V20250820_001__ALTER_User_books_Book_isbn13_To_Varchar13.sql

@@ -0,0 +1,2 @@
+ALTER TABLE user_books
+    MODIFY COLUMN book_isbn13 VARCHAR(13) NOT NULL;

infra/src/main/resources/db/seed/common/R__tags_default_data.sql

@@ -0,0 +1,7 @@
+INSERT INTO tags (id, name, created_at, updated_at)
+VALUES ('0198c238-dd86-737c-af79-8875fe2290c1', '깨달음', NOW(6), NOW(6)),
+       ('0198c238-dd86-737c-af79-8875fe2290c2', '슬픔', NOW(6), NOW(6)),
+       ('0198c238-dd86-737c-af79-8875fe2290c3', '즐거움', NOW(6), NOW(6)),
+       ('0198c238-dd86-737c-af79-8875fe2290c4', '따뜻함', NOW(6), NOW(6))
+ON DUPLICATE KEY UPDATE name       = VALUES(name),
+                        updated_at = NOW(6);