[WTH-508] V3 파일 마이그레이터 + 첨부 허용 형식 확장

[hyxklee]

배경

V3 → V4 마이그레이션(WTH-508)에서 파일만은 SQL로 처리할 수 없습니다.

	이유
file.file_size	V4에서 NOT NULL인데 V3 DB에 값이 없음 → S3 HeadObject 필요
file.content_type	동일
storage_key	키 형식이 달라 모든 객체를 새 키로 복사해야 함

V3  b2835a47-8728-4570-b584-6c0a39d5dbad.pdf          (버킷 루트 평면)
V4  POST/2025-03/b2835a47-...-dbad_영수증.pdf          ({OWNER_TYPE}/{yyyy-MM}/{uuid}_{fileName})

StorageKey VO가 정규식으로 형식을 강제하므로 예외가 없습니다.

변경 내용

1. 파일 마이그레이터 (src/migration/kotlin)

• 별도 소스셋 — 일회성 도구가 운영 아티팩트(bootJar)에 섞이지 않습니다.
• Spring 컨텍스트 없이 JDBC + AWS SDK v2만 사용합니다.
• 기본이 dry-run입니다. 실제 반영은 --apply를 명시해야 합니다.
• 원본 버킷은 읽기만 합니다. 삭제하지 않으므로 롤백은 V4 쪽 정리로 충분합니다.
• CopyObject는 서버사이드라 객체 바이트가 실행 머신을 거치지 않습니다.
• uuid를 V3 키에서 재사용하므로 같은 입력이면 같은 키가 나옵니다(멱등).
• --offline 모드 — 자격증명 없이 키 생성·소유 매핑만 검토합니다.

2. 첨부 허용 형식에 pptx / docx 추가

V3에 세션 자료(pptx 27건)와 문서(docx 2건)가 있어 현행 목록으로는 이전할 수 없습니다.

PPTX("application/vnd.openxmlformats-officedocument.presentationml.presentation", setOf("pptx")),
DOCX("application/vnd.openxmlformats-officedocument.wordprocessingml.document", setOf("docx")),

svg는 추가하지 않았습니다. XML이라 <script>를 품을 수 있어 인라인 서빙 시 XSS 벡터가 됩니다.
mp4도 제외했습니다(용량·전송비·Range 요청). 두 건은 UNSUPPORTED_TYPE으로 남습니다.

Swagger @Schema 설명과 FileTypeTest도 함께 갱신했습니다.

실행

# 자격증명 없이 키 생성·소유 매핑만 검토
MIG_DB_PASSWORD=... ./gradlew migrateFiles --args="--offline"

# HeadObject로 생존·크기 확인 (복사 없음)
MIG_DB_PASSWORD=... ./gradlew migrateFiles --args="--source-bucket=... --target-bucket=..."

# 실제 반영
MIG_DB_PASSWORD=... ./gradlew migrateFiles --args="--source-bucket=... --target-bucket=... --apply"

검증

로컬 V3 복제본(406건)에 --offline 전수 실행:

	변경 전	변경 후
이전 가능	370	399
UNSUPPORTED_TYPE	31	2 (mp4 1 / svg 1)
FAILED (비표준 키)	5	5

98.3%가 이전 가능해졌습니다. 생성 키 최대 길이 216자(한도 500), 키 생성 실패 0건.

./gradlew ktlintCheck compileMigrationKotlin test --tests "*File*Test" 통과.

남은 확인 사항

• S3 객체 생존율 — 개발 머신에 AWS 자격증명이 없어 실측하지 못했습니다. 자격증명이 있는 환경에서 dry-run을 돌리면 확정됩니다.
• 비표준 키 5건 — 한글 원본 파일명이 URL 인코딩된 채 키에 들어 있어 수동 확인이 필요합니다.

관련

• docs/plan/v3-to-v4-migration-plan.md §5
• docs/migration/v3-to-v4/10_file_prepare.sql (선행 SQL)
• PR [WTH-508] 일정·세션 내용 길이 제한 완화 #106 (일정·세션 content TEXT)

🤖 Generated with Claude Code

https://claude.ai/code/session_01FUfuUw4qjjHWfZKiyqgADJ

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}