---
task_id: task-2313
type: context
scope: task
created: 2026-04-29
updated: 2026-04-29
status: in-progress
---

# 맥락 노트: task-2313

**task**: task-2313

---

## 결정 근거

### 1. 기존 AI 도구 ID 재활용 vs 신규 ID 생성
- **결정**: 기존 `ai-background`/`ai-watermark` 도구 ID 재활용, 내부에서 플랜별 분기
- **이유**: Codex 리뷰에서 신규 ID(`ai-remove-bg-premium`) 추가 시 AIPanel switch에 매칭 안 되는 버그 경고. 기존 구조와 더 자연스럽게 통합됨
- **기각된 대안**: 별도 "고급 AI" 섹션에 새 버튼 추가 → AIPanel/useImageAI 전면 수정 필요, 변경 범위 과다

### 2. IOPaint → simple-lama-inpainting 대체
- **결정**: simple-lama-inpainting 사용
- **이유**: IOPaint 설치가 복잡하고 의존성 무거움. simple-lama-inpainting은 LaMa 모델만 가볍게 래핑
- **기각된 대안**: IOPaint 직접 사용 → GPU/CUDA 의존성 복잡, CPU 환경에서 불안정

### 3. rembg 세션 싱글톤 캐싱
- **결정**: 모듈 수준 lazy singleton으로 rembg 세션 캐시
- **이유**: Codex 리뷰에서 요청마다 new_session() 호출 시 메모리 급증 + 초기화 비용 경고

### 4. 파일 크기/MIME 검증 추가
- **결정**: 10MB 상한 + image/* MIME 타입 검증
- **이유**: Codex 리뷰에서 대용량/악성 입력 취약점 경고

## 3 Step Why

### 1st Why: "왜 이 설계가 필요한가?"
**A**: 현재 브라우저 ONNX 기반 배경 제거/워터마크 삭제 품질이 중급이며, 프로 사용자에게 고품질 AI 처리를 제공해야 유료 플랜 가치 차별화가 가능하다.

### 2nd Why: "왜 서버 측 AI 모델이 최선의 접근인가?"
**B**: BiRefNet(rembg)과 LaMa(simple-lama-inpainting)는 브라우저 ONNX 대비 최신 모델로 품질이 월등히 높다. 서버 측에서만 실행 가능한 모델 크기/연산량이며, 플랜 기반 접근 제어도 서버에서만 안전하게 적용 가능하다.

### 3rd Why: "왜 기존 도구 재활용이 별도 버튼보다 나은가?"
**C**: 사용자 관점에서 같은 기능(배경 제거)이 두 개 버튼으로 존재하면 혼란. 하나의 버튼에서 플랜에 따라 자동 분기하면 UX가 깔끔하고, 코드 변경 범위도 최소화된다. Codex 리뷰도 이 접근을 권장.

→ A-B-C 논리 일관성 확인 완료

## 참조 자료

- Codex 게이트 검증 결과: codex_gate_check 실행 (7 risks, 설계에 반영)
- 기존 코드: `server/main.py:350` PLAN_FEATURE_MAP
- 기존 코드: `src/config/planFeatureMap.ts` FeatureConfig 구조
- 기존 코드: `src/hooks/useImageAI.ts` 브라우저 AI 로직
- 기존 코드: `src/components/image-editor/AIPanel.tsx` AI 도구 패널

## 주의사항

- rembg 첫 실행 시 모델 다운로드 ~170MB → 서버 시작 후 첫 요청 느릴 수 있음
- simple-lama-inpainting도 첫 실행 시 모델 다운로드
- GPU 없는 환경에서는 `rembg` (CPU 전용) 설치
- main.py가 6554줄로 매우 큼 → image_ai.py를 별도 모듈로 분리하여 라우터 등록