From 0807574986639a3292bf60e4330a49076e060e11 Mon Sep 17 00:00:00 2001
From: Hyungi Ahn <hyungiahn@Hyungiui-MacBookPro.local>
Date: Fri, 17 Apr 2026 08:07:24 +0900
Subject: [PATCH] =?UTF-8?q?docs(upload):=20=EC=97=85=EB=A1=9C=EB=93=9C=20?=
 =?UTF-8?q?=ED=95=9C=EB=8F=84=20=EC=A0=95=EC=B1=85=20+=20=EC=B1=85?=
 =?UTF-8?q?=EC=9E=84=20=EA=B2=BD=EA=B3=84=20+=20=EC=A0=95=EC=B1=85?=
 =?UTF-8?q?=EC=8B=9D=20=EB=AC=B8=EC=84=9C=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase B 로 확립된 업로드 size 정책을 deploy.md 에 섹션으로 정리:
- config.yaml `upload` 블록 (단일 진실 공급원)
- 4 레이어 책임 경계 (home-caddy / FastAPI / /config/public / UploadDropzone)
- 정책식: `proxy max_size ≥ upload.max_bytes * content_length_slack_ratio`
- 다른 배수("1.1배" 등) 혼용 금지
- /api/config/public scope 제약 (민감정보 금지 / 프론트 필수 기준)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/deploy.md | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/deploy.md b/docs/deploy.md
index d5bc1ca..09b4b9e 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -139,7 +139,42 @@ Docker 내부에서 APScheduler로 관리 (launchd 대체):
 | */5분 | file_watcher | 상시 |
 | */10분 | processing_queue consumer | 상시 |
 
-## 7. 백업
+## 7. 업로드 한도 정책
+
+업로드 크기 제한의 단일 진실 공급원은 `config.yaml` 의 `upload` 블록.
+
+```yaml
+upload:
+  max_bytes: 100000000              # 100 MB (SI). authoritative policy value.
+  content_length_slack_ratio: 1.05  # multipart 오버헤드 여유.
+  stream_chunk_bytes: 1048576       # 1 MiB 단위 스트리밍 read/write.
+```
+
+### 책임 경계
+
+| 레이어 | 역할 | 값 출처 |
+|---|---|---|
+| home-caddy (edge proxy) | DoS 방어선 | infra config |
+| FastAPI `POST /api/documents/` | **authoritative policy enforcement** (스트리밍 누적 검사, 413) | `upload.max_bytes` |
+| `GET /api/config/public` | 프론트용 공개 값 노출 | `upload.max_bytes` 재사용 |
+| 프론트 `UploadDropzone.svelte` | **pre-check UX** (드롭 시 즉시 차단) | API 응답 구독 (fallback 100MB) |
+
+### 정책식 (단일 기준)
+
+> **proxy `request_body max_size` ≥ `upload.max_bytes * upload.content_length_slack_ratio`**
+
+현재 기본값 기준 → 최소 proxy 한도 **105,000,000 바이트 (≈105MB SI)**. home-caddy 도
+이 식을 만족해야 하며, 다른 배수("1.1배" 등) 를 별도로 관리하지 말 것.
+
+### `GET /api/config/public` 범위 제한
+
+이 엔드포인트는 **민감정보 없는 프론트 필수 설정만** 제공. 임의의 서버 설정을
+프론트에 노출하는 범용 창구로 확장 금지. 필드 추가 시 리뷰 기준:
+
+1. 민감정보 포함 여부 (비밀/내부 정책/경로 등 배제)
+2. 프론트 동작 필수 여부 (UI 가 실제로 소비하지 않으면 불추가)
+
+## 8. 백업
 
 ### 우선순위