feat(configuration): 파일 REST API 11종 구현 #26

[tlgms]

스택 PR 4/4 (마지막) — base: feat(document)-파일-응답-규약-#26
PR 1~3이 먼저 머지되어야 합니다.

Summary

• 명세의 파일관리(document) API 11개 전부를 /api/document/v11/** 경로로 구현합니다.
• 멀티파트 업로드 한도와 S3 접속 설정, files 테이블 DDL을 추가합니다.

Related Issue

• Closes document 도메인 개발 #26

Scope

• In scope: configuration-adapter-in의 document 패키지, configuration-bootstrap 설정
• Out of scope: 인증·인가, gRPC 노출, OpenAPI 어노테이션, 컨트롤러 테스트 (전부 후속 이슈)

Implementation

컨트롤러 6개로 11개 엔드포인트를 구현합니다.

컨트롤러	명세
ApplicationFileController	#1 원서 저장 / #2 조회 / #3 다운
AdmissionTicketController	#4 수험표 저장 / #5 다운
ApplicantListController	#6 엑셀 저장 / #7 다운
PhotoController	#8 증명사진 첨부
AttachmentController	#9 게시글 첨부 저장 / #10 다운
GuidelineController	#11 전형요강 다운

경로 prefix — 명세의 document 경로(/application, /photo 등)에는 /api/{service}/v11/ 이 없어 규약 §2 위반이고 Gateway 라우팅도 불가능합니다. prefix를 붙이되 도메인명(document)을 유지했습니다.

부트스트랩 — 멀티파트 한도를 21MB로 두어 카테고리별 도메인 규칙(최대 20MB)이 먼저 판정하고, 서블릿 컨테이너 한도는 백스톱으로 남깁니다.

Testing

• Unit tests — 컨트롤러 테스트는 후속 이슈
• Integration tests
• Manual verification — 실제 S3 / DB에 대해 실행해 보지 않았습니다

bazel test //systems/configuration/...

빌드와 도메인 테스트 12개 통과만 확인했습니다.

Deployment Notes

• Feature flag: 없음
• Migration required: 예 — configuration-bootstrap/ddl/files.sql을 수기로 적용해야 합니다. ddl-auto: validate라 테이블이 없으면 기동에 실패합니다. 마이그레이션 도구 도입은 후속 이슈
• Rollout considerations: S3_BUCKET, AWS_REGION 환경변수 주입 필요. 버킷과 IAM 권한(s3:PutObject, GetObject, HeadObject, DeleteObject)이 선행되어야 합니다

Checklist

• Matches product/tech requirements
• Backward compatibility considered
• Docs updated if applicable

명세와 의도적으로 다르게 구현한 3곳 — 리뷰 필요

1. 증명사진 url (의존성 등록 과정 문서화 #8) — 평문 S3 URL 대신 presigned URL로 발급합니다. 증명사진은 개인정보인데 공개 버킷이면 키를 아는 누구나 열람할 수 있고, 비공개 버킷이면 명세대로는 아예 동작하지 않습니다. 응답 스키마(url 필드)는 그대로 유지했습니다.
2. 원서 조회 (GitHub 이슈 템플릿을 활성화하기 위해 .gitub 디렉터리 오타 수정 #2) — 파일 부재 시 404가 아니라 200 + exists:false 를 반환합니다. "다운로드가 아닌 조회 목적"이라는 명세 설명상 부재는 예외가 아니라 정상 결과입니다. 명세의 FILE_NOT_FOUND 행은 삭제가 필요합니다.
3. attachmentId (docs(documents): 의존성 관리 구조 문서 추가 (#8) #9) — object_key에는 랜덤 토큰을 쓰고 ID는 files PK로 발급합니다. 명세 예시(attachment/attachment_1_guide.pdf)와 달리 키가 추측 불가능하고, 업로드 전에 ID를 알아야 하는 순서 문제도 없습니다.

알려진 공백

• 전형요강 업로드 API가 명세에 없습니다. guidelineId가 어떻게 생기는지 미정이라 다운로드만 구현했습니다. ID 기반 조회라 어느 prefix로 저장되든 동작합니다.
• 인증이 전혀 없습니다. 명세의 인증 컬럼이 11개 전부 공란이고 소비자가 모두 내부 서비스라 "내부 전용"으로 설계했습니다. 다만 이 전제가 코드로도 인프라로도 강제되어 있지 않고, systems/gateway도 아직 스캐폴딩입니다. 현재는 포트가 닿으면 누구나 파일을 올리고 presigned URL을 받을 수 있습니다. 네트워크 차단 + 서비스 간 공유 시크릿을 별도 이슈로 처리해야 합니다.
• Admin이 쓸 gRPC 어댑터가 없습니다. contracts/proto/configuration.proto에 파일 RPC 추가가 선행되어야 하며, Admin의 파일 연동 전체가 여기에 막혀 있습니다.

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• ready-for-review

🚫 Excluded labels (none allowed) (2)

• wip
• do-not-review

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 444fe240-d55b-423f-962f-dc7442f66e34

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat(document)-파일-rest-api-#26

• 🛠️ cleanup stale imports
• 🛠️ harden error messages
• 🛠️ test clarity pass

---

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.}