feat(configuration): 파일 API 공통 응답 규약 및 예외 처리 #26

[tlgms]

스택 PR 3/4 — base: feat(document)-파일-저장소-어댑터-#26
PR 1, 2가 먼저 머지되어야 합니다.

Summary

• 명세의 성공/실패 응답 형식에 맞춘 ApiResponse envelope과 ErrorCode를 정의합니다.
• 도메인 예외를 명세의 HTTP 상태로 변환하는 @RestControllerAdvice를 추가합니다.
• 응답 DTO와 컨트롤러 공용 헬퍼를 추가합니다.

Related Issue

• Ref document 도메인 개발 #26

Scope

• In scope: configuration-adapter-in의 common / document.dto 패키지
• Out of scope: 컨트롤러 구현(PR 4), gRPC 예외 매핑, OpenAPI 어노테이션

Implementation

API 공통 규약 §12가 "서비스마다 다른 응답 형식 사용"과 "에러 메시지만 반환하고 에러 코드 생략"을 금지합니다.

ApiResponse<T>

• 성공 시에도 error 키를 항상 포함합니다. 개별 API 명세가 전부 "error": null을 보여주고 있고, 클라이언트 파싱도 단순해집니다
• timestamp는 실패 시에만 직렬화합니다 (@get:JsonInclude(NON_NULL))

DocumentExceptionHandler

예외	코드	HTTP
InvalidFileFormatException	INVALID_FILE_FORMAT	400
InvalidFileNameException, 파라미터 누락	INVALID_REQUEST_PARAM	400
FileDocumentNotFoundException	FILE_NOT_FOUND	404
FileTooLargeException, MaxUploadSizeExceededException	FILE_TOO_LARGE	413
StorageUploadFailedException	STORAGE_UPLOAD_FAILED	502
PresignFailedException	PRESIGN_FAILED	502

MaxUploadSizeExceededException을 잡지 않으면 용량 초과 시 명세의 413이 아니라 500이 나갑니다. 이것 때문에 핸들러에 포함했습니다.

헬퍼

• FileReferenceId — attachment_1 형태의 참조 ID ↔ files PK 변환
• MultipartFileExtensions — 확장자 검증, 커맨드 변환

Testing

• Unit tests — 이 PR 범위에는 없습니다
• Integration tests
• Manual verification

bazel build //systems/configuration/...

Deployment Notes

• Feature flag: 없음
• Migration required: 없음
• Rollout considerations: @RestControllerAdvice가 configuration 서비스 전역에 적용됩니다. 기존 gRPC 어댑터에는 영향이 없지만, 향후 다른 REST 컨트롤러가 추가되면 이 핸들러를 공유하게 됩니다

Checklist

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

리뷰 시 봐주셨으면 하는 것

1. ApiResponse를 packages/common으로 뺄지 — 다른 서비스도 같은 envelope이 필요합니다. 다만 공유 패키지 신설은 이슈 범위를 넘어 지금은 configuration-adapter-in에 두었습니다. 두 번째 서비스가 필요해지는 시점에 추출을 권합니다.
2. HttpStatus.CONTENT_TOO_LARGE — PAYLOAD_TOO_LARGE가 deprecated라 교체했습니다.
3. 규약 페이지와 개별 명세가 어긋나 있습니다 (목록 키 items vs applicants, page 1-base vs 0-base). Document에는 목록 API가 없어 이 PR에는 영향이 없지만, 명세 정정이 필요합니다.

[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: 55fde766-5763-48a5-8450-b35528eb2606

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)-파일-응답-규약-#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.}