HeuJung
6c8381f164
이슈 본연: API 레퍼런스의 미채움 마커 5종(실측 제외/TODO/필드 없음/대표 에러 없음)
1,194건을 코드에서 읽어 전수 채우고(0건), api:docgen 재생성이 사람이 채운 내용을
손실·열화시키던 멱등성 결함 4종(CRLF, 표 파이프 이스케이프, 에러 서술 보존, 중복
라우트명 키)을 근본 수정. --check 를 실측 제외와 드리프트가 구분되도록 재정의.
ParameterDescriber/ResourceFieldDescriber 에 leaf 폴백·SEO 스코프·공통 사전 확장.
파생 결함(문서 실측 중 발견): ResponseHelper 기본 메시지 키 6종이 존재하지 않는
messages.* 를 가리켜 응답 message 가 번역문 대신 키 문자열로 노출되던 문제를 common.*
으로 정정하고, 코어 7 + gdpr/marketing/pay_kginicis/verification/ecommerce 확장의
호출부와 누락 lang 키(게시판 10키 + 이커머스 category_images 4키 포함)를 ko/en/ja
전수 정정. 중복 그룹 키 2건은 기존 키로 호출부 통합.
보안: GET /api/identity/challenges/{id} 는 권한 가드 없는 공개 폴링 엔드포인트인데
Service::getStatus 가 attempts/max_attempts 를 응답에 담아 남은 시도 횟수를 추론할 수
있었다. 두 필드를 제거하고, 챌린지 화면(admin_basic/basic)의 서버 attempts 참조를
제거(남은 횟수 UI 는 query fallback + verify 실패 시 로컬 증가로 유지).
부수 정리(변경셋에 들어온 board 컨트롤러의 audit 사전 결함): FormRequest 4개 신설로
base Request 주입 제거, CommentController 의 Board 직접 호출을 BoardService 위임으로
전환, PHPDoc @return 보강. board 스위트에서 발견한 stale test 3건(seed SSoT 불일치,
admin 계정 user 역할 누락)도 같은 세션에서 정정.
버전 정렬(공개 release 기준): 코어 7.0.3→7.0.4, sirsoft-board 1.0.1→1.0.2,
verification_kginicis 1.0.0→1.0.1, admin_basic 1.0.1→1.0.4.
3.9 KiB
3.9 KiB
Attachment API 레퍼런스
소유: 코어 · 생성:
php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Attachment 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
GET /api/attachment/{hash}
- 라우트명:
api.attachment.download - 컨트롤러:
App\Http\Controllers\Api\Public\PublicAttachmentController@download - 인증/권한: 공개 (인증 불필요)
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| hash | path | string | 예 | — | 다운로드할 첨부파일의 해시 식별자 (attachments.hash) |
요청 예시
GET /api/attachment/{hash} HTTP/1.1
Host: api.example.com
Accept: application/json
응답 필드 (data 내부)
이 엔드포인트는 JSON 봉투(data)를 반환하지 않습니다. 성공 시 파일 바이너리 본문을 그대로 응답합니다 (실패 시에만 JSON 에러 봉투).
| 응답 헤더 | 값 | 용도/설명 |
|---|---|---|
| Content-Type | image/png 등 |
첨부파일의 MIME 타입 (attachments.mime_type) |
| Content-Disposition | attachment; filename="원본파일명.pdf" |
이미지가 아닌 파일에만 부여 — 원본 파일명으로 다운로드 |
| Cache-Control | public, max-age=86400, immutable (프로덕션) / no-cache (그 외) |
이미지 응답의 캐싱 정책. max-age 는 환경설정 cache.layout_ttl (기본 86400초) |
| Expires | Wed, 15 Jul 2026 00:00:00 GMT |
이미지 응답의 만료 시각 (현재 시각 + max-age) |
| ETag | 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d |
이미지 응답의 검증자 (파일 수정시각 + 크기의 MD5). 요청의 If-None-Match 와 일치하면 304 Not Modified |
응답 예시
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=86400, immutable
Expires: Wed, 15 Jul 2026 00:00:00 GMT
ETag: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d
<파일 바이너리>
이미지가 아닌 파일:
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="manual.pdf"
<파일 바이너리>
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 304 | Not Modified | 이미지 응답에서 요청 If-None-Match 헤더가 현재 ETag 와 일치하는 경우 (본문 없음) |
| 403 | Forbidden | 첨부파일 접근 권한 없음 (core.attachment.download 훅 권한 미충족) 또는 스토리지에 실제 파일이 없는 경우 — {"success": false, "message": "이 첨부파일에 대한 접근 권한이 없습니다."} |
| 404 | Not Found | 해당 해시의 첨부파일이 존재하지 않는 경우 — {"success": false, "message": "첨부파일을 찾을 수 없습니다."} |
설명 해시(12자)로 식별되는 첨부파일을 다운로드합니다. 이미지 파일은 캐싱 헤더와 함께 인라인으로 표시하고 그 외 파일은 다운로드 방식으로 제공합니다. 인증이 필요 없는 공개 라우트이지만 접근 권한은 AttachmentService가 로그인/비로그인 사용자 모두를 대상으로 하이브리드 방식으로 검사하며, 파일이 없으면 404, 권한이 없으면 403을 반환합니다. 게시글 첨부·상품 이미지 등 공개 리소스를 URL로 직접 내려받는 시나리오에 사용합니다.