Presigned URL 완전 가이드

텍스트 파일 (hello.txt):
  저장된 형태 → 01101000 01100101 01101100 01101100 01101111
  메모장으로 열면 → "hello" (사람이 읽을 수 있음)
 
바이너리 파일 (photo.png):
  저장된 형태 → 10001001 01010000 01001110 01000111 ...
  메모장으로 열면 → "‰PNG..." (사람이 읽을 수 없음)

1 Byte = 8 bit (0과 1 여덟 개)
1 KB (킬로바이트) = 1,024 Byte        ← 짧은 텍스트 파일
1 MB (메가바이트) = 1,024 KB          ← 일반 사진
1 GB (기가바이트) = 1,024 MB          ← 영상 파일

[헤더] — 메타 정보 (편지 봉투에 적힌 정보)
Content-Type: image/png          ← "이 파일은 PNG 이미지야"
Content-Length: 5242880           ← "크기는 5MB야"
Content-Disposition: attachment   ← "다운로드하게 해줘"
 
[본문(body)] — 실제 데이터 (편지 내용물)
(이미지 바이너리 데이터...)

image/png          → PNG 이미지
image/jpeg         → JPG 이미지
application/pdf    → PDF 문서
application/vnd.ms-excel → 엑셀 파일
text/csv           → CSV 파일
text/plain         → 일반 텍스트
video/mp4          → MP4 영상
audio/mpeg         → MP3 음악

const formData = new FormData()
formData.append('name', '홍길동')        // 텍스트 데이터
formData.append('file', imageFile)       // 파일 데이터 (바이너리)

원본 바이너리:  10001001 01010000 01001110
Base64 변환:   "iVBORw0KGgo..."

"hello" → SHA256 → "2cf24dba5fb0a30e26e83b2ac5b9e29e..."
"hello!" → SHA256 → "ce06092fb948d9ffac7d1a376f7b656d..."  ← 한 글자만 달라도 완전히 다른 결과

HMAC-SHA256("비밀키", "데이터") → "서명값"

백엔드 엔드포인트: https://api.kodeflo.com/presigned_url/
S3 엔드포인트:    https://kodeflo-bucket.s3.ap-northeast-2.amazonaws.com/

kodeflo-bucket/                          ← 버킷
  ├── advertiser_memo/
  │     └── AdvertiserMemoImage/
  │           └── image/
  │                 └── a1b2c3_photo.png  ← 실제 파일
  ├── advertiser/
  │     └── Advertiser/
  │           └── bankbook_copy/
  │                 └── d4e5f6_통장.pdf
  └── cpa/
        └── Cpa/
              └── main_image/
                    └── g7h8i9_banner.jpg

예: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

브라우저 →(파일 전송)→ 백엔드 서버 →(파일 전송)→ AWS S3

브라우저 →(파일명만)→ 백엔드 서버    ← 가벼운 JSON (수백 바이트)
백엔드 서버 →(서명 생성)→ 브라우저   ← 임시 허가증 반환
브라우저 →(파일 전송)→ AWS S3        ← 직접 전송 (백엔드 경유 안 함)

서명 = HMAC-SHA256(Secret Key, policy)

// 클라이언트 → 백엔드
const { fields, url } = await presignedUrlApi.presignedUrlCreate({
  data: {
    fileName: 'receipt.png',                            // 파일명
    fieldChoice: 'advertiser_memo.AdvertiserMemoImage.image',  // 용도 (어디에 쓸 파일인지)
    isDownload: false,                                  // 다운로드용 파일인지 여부
  },
})

{
  "url": "https://kodeflo-bucket.s3.ap-northeast-2.amazonaws.com/",
  "fields": {
    "key": "advertiser_memo/AdvertiserMemoImage/image/a1b2c3d4_receipt.png",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjYtMDMtMjdUMTI6MDA6MDBaIi...",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "AKIA.../20260327/ap-northeast-2/s3/aws4_request",
    "x-amz-date": "20260327T060000Z",
    "x-amz-signature": "a1b2c3d4e5f6..."
  }
}

const formData = new FormData()
 
// 1) 인증 필드들을 먼저 추가
Object.entries(fields).forEach(([k, v]) => formData.append(k, v))
 
// 2) 파일은 반드시 마지막에 추가 (S3 POST 규칙)
formData.append('file', file)

await fetch(url, {
  method: 'POST',
  body: formData,
})

const baseUrl = url.endsWith('/') ? url.slice(0, -1) : url
const fileUrl = `${baseUrl}/${encodeURI(fields.key)}`
// → "https://kodeflo-bucket.s3.../advertiser_memo/AdvertiserMemoImage/image/a1b2c3d4_receipt.png"

const { name, type } = file
const [mime] = type.split('/')   // 'image/png' → 'image'
 
assertItemOf(
  ['image', 'audio', 'text', 'video', 'application'] as const,
  mime,
)

Content-Type: image/png      → 브라우저가 이미지로 렌더링
Content-Type: application/pdf → 브라우저 내장 PDF 뷰어로 표시
Content-Type: text/csv        → 텍스트로 표시하거나 다운로드

// 통장사본 업로드 — 다운로드 용도
await uploadFile({
  file,
  fieldChoice: 'advertiser.Advertiser.bankbook_copy',
  isDownload: true,   // ← 다운로드용
})
 
// 메모 이미지 업로드 — 조회(미리보기) 용도
await uploadFiles([{
  file,
  fieldChoice: 'advertiser_memo.AdvertiserMemoImage.image',
  // isDownload 기본값 false → 조회용
}])

{
  "expiration": "2026-03-27T06:05:00Z",
  "conditions": [
    {"bucket": "kodeflo-bucket"},
    {"key": "advertiser_memo/AdvertiserMemoImage/image/a1b2c3d4.png"},
    {"x-amz-algorithm": "AWS4-HMAC-SHA256"},
    ["content-length-range", 0, 10485760]
  ]
}

// 코멘트 이미지 — 브라우저에서 바로 볼 수 있어야 함
const result = await uploadFiles([
  {
    file: imageFile,
    fieldChoice: 'advertiser_memo.AdvertiserMemoImage.image',
    // isDownload: false (기본값)
  },
])
const imageUrl = result.fulfilled[0].url
// → <img src={imageUrl} /> 로 렌더링 가능

// 통장사본 — 다운로드받아서 확인해야 함
const { url } = await uploadFile({
  file: bankbookPdf,
  fieldChoice: 'advertiser.Advertiser.bankbook_copy',
  isDownload: true,
})
// → 이 URL 클릭 시 브라우저가 파일 다운로드 대화상자를 띄움

// uploadFiles는 내부적으로 Promise.allSettled를 사용
const inputs = files.map((f) => ({
  file: f.file,
  fieldChoice: 'advertiser_memo.AdvertiserMemoImage.image' as const,
}))
const result = await uploadFiles(inputs)
 
result.fulfilled  // 성공한 파일들: { url, name, file }[]
result.rejected   // 실패한 파일들