전자서명 서비스에서 문제가 잇따릅니다. "대용량 PDF 업로드 시 앱 서버가 OOM으로 죽어요." "서명 완료된 문서의 필드가 수정 가능해 무결성 우려가 있어요." "고객이 올린 파일명·내용 한글이 '占쏙옙'으로 깨져요." "다운로드 링크가 영구 공개돼 보안 우려가 있고요." PM·인프라인 당신은 문서·파일 도메인 용어를 알아야 이 문제들을 판단합니다. 이 사전은 파일·문서·전자서명 도메인 용어를 빠르게 해독합니다.
- 1전자서명 도메인(템플릿·워크플로우·서명 필드) 용어를 이해할 수 있다
- 2PDF 처리(렌더링·평탄화·병합·분할)와 무결성의 관계를 설명할 수 있다
- 3presigned URL·오브젝트 스토리지로 대용량 파일을 안전·효율적으로 다루는 법을 설명할 수 있다
- 4인코딩(UTF-8/EUC-KR)·MIME·Base64로 파일 깨짐·전송 문제를 진단할 수 있다
전자서명 도메인
템플릿·워크플로우·서명 필드
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| Template / Template ID / Document ID | 문서 양식 / 양식·문서 식별 | 재사용 양식 | ★★ |
| Workflow / Recipient / Signer / Approver | 서명 흐름 / 수신자·서명자·승인자 | 순서·역할 | ★★ |
| Form Field / Text·Multiline·Signature·Stamp Field | 입력 필드 종류 | 서명·날인 위치 | ★★ |
| Company Stamp / Embedded Signing | 회사 도장 / 화면 내 서명 | 임베디드 UX | ★★ |
| Document Generation / Bulk Send / Bulk Create / Batch ID | 문서 생성 / 대량 발송·생성 | 대량 처리 → [[glossary-batch-async]] | ★★ |
| Document Status / Completed / Draft Status | 문서 상태 | 진행 추적 | ★★ |
| Webhook Event | 상태 변경 이벤트 알림 | 외부 연동 → [[glossary-api-auth]] | ★★ |
| Audit Trail / Time Stamp / Certificate-based Signature | 감사 추적 / 타임스탬프 / 인증서 기반 서명 | 법적 효력 | ★★ |
핵심: 전자서명은 '누가·언제·무엇에' 서명했는지의 감사 추적(Audit Trail) 과 무결성(서명 후 변경 불가)이 법적 효력의 핵심입니다.
PDF 처리
문서를 만들고 고정하는 작업
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| PDF Rendering | 문서를 PDF로 그림 | 생성 | ★★ |
| PDF Flattening | 폼/레이어를 고정 콘텐츠로 병합 | 서명 후 변경 방지 | ★★ |
| PDF Merge / Split | 병합 / 분할 | 다중 문서 | ★ |
핵심: 서명 완료 후 Flattening(평탄화) 으로 필드를 고정하면 누구도 값을 바꿀 수 없어 무결성이 보장됩니다 — 전자서명의 법적 효력에 직결됩니다.
파일 저장·전송
대용량을 안전·효율적으로 다루기
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| File Upload / Download | 업로드 / 다운로드 | 대용량은 직접전송 | ★★ |
| Presigned URL | 한시적 직접 업/다운 URL | 서버 부하↓ → [[file-sftp-batch]] | ★★★ |
| Object Storage / S3 / MinIO | 오브젝트 스토리지 | 파일 저장 표준 | ★★ |
| Download Token / Access Token | 다운로드 권한 토큰 | 만료·권한 제한 → [[glossary-api-auth]] | ★★ |
| File Size Limit | 업로드 크기 제한 | OOM·악용 방지 | ★★ |
핵심: 대용량 파일을 앱 서버 메모리로 받으면 OOM 위험([[glossary-backend-java-spring]]). Presigned URL로 클라이언트가 스토리지에 직접 올리면 서버는 URL 발급만 하고 전송은 스토리지가 전담합니다. 다운로드도 만료시간이 있는 토큰/URL로 보안을 유지합니다.
인코딩 · 형식
글자 깨짐과 전송 형식
| 용어 | 한 줄 뜻 | 비고 | 중요도 |
|---|---|---|---|
| MIME Type / Content-Type | 파일 형식 표시 | application/pdf 등 | ★★ |
| Base64 / Binary | 텍스트 인코딩 / 이진 | 전송 형식 | ★★ |
| Encoding / UTF-8 / EUC-KR | 문자 인코딩 / 유니코드 / 한글 구형 | 깨짐 원인 | ★★★ |
핵심: 한글 깨짐('占쏙옙'/'???')은 거의 항상 인코딩 불일치입니다 — 저장과 읽기 인코딩을 UTF-8로 통일하는 것이 표준 해법([[mysql-features]]의 utf8mb4와 동일 맥락). 레거시·외부 연동에서 EUC-KR이 섞이면 변환 지점을 명확히 합니다.
파일 문제 진단 — 직접 확인
문서 서비스의 단골 문제 셋을 점검합니다.
1) 대용량 업로드: 앱 서버가 파일을 메모리로 받나, presigned로 직접 올리나?
→ 메모리로 받으면 큰 파일에서 OOM([[glossary-backend-java-spring]])
2) 인코딩: 저장/읽기 인코딩이 UTF-8로 통일됐나?
→ file 명령으로 실제 인코딩 확인: file -i upload.csv
3) 다운로드 URL: 만료시간·권한이 있나, 영구 공개인가?
→ 영구 공개면 링크 유출 시 누구나 접근(보안 위험)
file -i orders.csv → charset=euc-kr ← UTF-8 아님! 깨짐 원인
업로드: MultipartFile로 전체 메모리 적재 → 100MB+ 파일서 OOM
다운로드: /files/abc.pdf 영구 공개 → presigned(만료 10분)로 전환 필요
echo '업로드 경로 + 인코딩 + 다운로드 URL 만료 확인'- 대용량 업로드가 앱 서버 메모리로 들어오면 OOM 위험 → presigned URL로 스토리지 직접 업로드 전환([[file-sftp-batch]])
- 한글 깨짐이면 file -i로 실제 인코딩 확인 → EUC-KR이면 UTF-8로 변환·통일. 저장·읽기·DB([[mysql-features]]) 모두 UTF-8인지
- 다운로드 URL이 영구 공개면 유출 시 누구나 접근 → 만료시간 있는 presigned URL/다운로드 토큰으로([[glossary-api-auth]])
- 서명 완료 문서가 수정 가능하면 무결성 위험 → Flattening(평탄화)으로 필드 고정. 감사 추적(누가·언제 서명)이 남는지 확인
상황: 고객이 수십~수백 MB PDF를 업로드하자 앱 서버가 그 파일을 통째로 메모리에 받다 OutOfMemory로 죽고, 같은 서버의 다른 요청까지 마비됩니다.
원인: 파일을 앱 서버 메모리로 받는 구조입니다(MultipartFile 전체 적재 등). 대용량·동시 업로드가 겹치면 Heap을 초과합니다([[glossary-backend-java-spring]]의 OOM).
진단:
□ 업로드를 앱 서버가 메모리/디스크로 받나, 스토리지로 직접 보내나?
□ 파일 크기 제한(File Size Limit)이 있나?
□ OOM 시각이 대용량 업로드와 겹치나?
해결: (1) Presigned URL로 클라이언트가 오브젝트 스토리지(S3 등)에 직접 업로드하게 해 앱 서버 메모리를 우회. (2) 부득이 서버 경유 시 스트리밍(전체 적재 대신 흘려보내기)과 크기 제한 적용. (3) 다운로드도 presigned URL로 서버 부하·대역폭을 줄입니다. 대용량 파일은 '앱 서버를 거치지 않게' 설계하는 것이 확장성의 핵심입니다([[file-sftp-batch]]).
인프라/플랫폼으로서 문서·파일 서비스는 스토리지 설계가 핵심입니다 — presigned URL로 대용량 전송을 앱 서버에서 분리하고([[file-sftp-batch]]), 다운로드 토큰 만료·접근 제어로 보안을 지키며, 인코딩(UTF-8 통일)으로 깨짐을 예방합니다. PM은 이 용어로 문서 도메인 요구를 정확히 적습니다 — "presigned 업로드", "서명 후 flattening으로 무결성", "감사 추적", "다운로드 링크 만료" 같은 항목을 인수 기준에 넣어 OOM·무결성·유출 사고를 예방합니다.
다음(마지막) 용어사전에서는 환경 차이·설정·운영 이슈 용어를 정리합니다.