# task-2313 완료 보고서

## SCQA

**S**: InsuRo 이미지 편집기의 배경 제거/워터마크 삭제 기능은 브라우저 ONNX(@imgly/background-removal, PatchMatch 인페인팅)로 동작하며, 중급 수준의 품질을 제공하고 있다.

**C**: 프로 플랜 이상 사용자에게는 서버 측 고품질 AI 모델(rembg BiRefNet, LaMa)을 활용한 프리미엄 버전이 필요하다. 서버 엔드포인트, 플랜 기반 접근 제어, 프론트 분기 로직이 모두 부재한 상태이다.

**Q**: 서버 측 AI 이미지 처리 엔드포인트를 추가하고, 프로 플랜 이상에서만 접근 가능하도록 FeatureGate 연동이 가능한가?

**A**: 서버에 image_ai.py 모듈(2개 엔드포인트)을 신규 생성하고, PLAN_FEATURE_MAP/planFeatureMap.ts에 `ai_image_premium` 키를 등록하여 프로 플랜 이상에서만 사용 가능하도록 구현 완료. 기존 브라우저 AI 기능은 그대로 유지하면서, 프리미엄 사용자는 서버 API를 통해 고품질 처리를 받는 분기 로직을 프론트에 추가했다. pytest 44 passed, npm run build 성공, 서버 재시작 + API 401 응답 확인 완료.

## 수정 파일 목록

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| server/image_ai.py (신규) | 고급 AI 이미지 처리 모듈 (remove-bg, remove-watermark) | ls OK | verified |
| server/main.py:78 | image_ai_router import 추가 | grep "image_ai_router" 2건 OK | verified |
| server/main.py:356 | PLAN_FEATURE_MAP에 ai_image_premium 추가 | grep "ai_image_premium" 1건 OK | verified |
| server/main.py:780 | image_ai 라우터 등록 (dependencies 포함) | grep "image_ai_router" OK | verified |
| server/requirements.txt:25-26 | rembg, simple-lama-inpainting 추가 | grep 2건 OK | verified |
| src/config/planFeatureMap.ts:13 | aiImagePremium 항목 추가 | grep 1건 OK | verified |
| src/components/PlanUpgradeDialog.tsx:41 | ai_image_premium 라벨 추가 | grep 1건 OK | verified |
| src/hooks/useImageAI.ts | isPremium/accessToken 분기 로직 추가 | grep 4건 OK | verified |
| src/components/image-editor/AIPanel.tsx | isPremium 프리미엄 배지 UI | grep 10건 OK | verified |
| server/tests/test_plan_feature_parameterize.py:50 | aiImagePremium 테스트 추가 | grep 2건 OK | verified |

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **순환 import (critical)** — image_ai.py에서 main.py의 require_feature를 직접 import하면 순환 참조 발생. 해결: image_ai.py에서 main.py import 제거, 대신 main.py의 `app.include_router()` 시 `dependencies=[Depends(require_feature("ai_image_premium"))]` 파라미터로 접근 제어 적용
   - 상세: image_ai.py를 독립 모듈로 만들고, 라우터 레벨 dependencies로 접근 제어

2. **PIL.Image.LANCZOS pyright 에러** — Pillow 10+에서 `Image.LANCZOS`가 deprecated되어 `Image.Resampling.LANCZOS`로 변경. Pyright가 동적 속성을 인식하지 못해 `type: ignore[attr-defined]` 추가

3. **require_feature 호출 시점 문제** — `require_feature`와 `verify_jwt`가 main.py 후반부에 정의되어 모듈 초기화 시 include_router에서 사용 불가. 해결: include_router를 verify_jwt 정의 이후(780줄)로 이동

### 범위 외 미해결 (0건)
없음

## L1 스모크테스트 결과
- 서버 재시작: 성공 (포트 10099, uvicorn)
- API 응답 확인:
  - GET /api/status → 200 `{"status":"ok"}`
  - POST /api/insuro/image/remove-bg (인증 없음) → 401 `{"detail":"Missing or invalid authorization"}`
  - POST /api/insuro/image/remove-watermark (인증 없음) → 401 `{"detail":"Missing or invalid authorization"}`
- 스크린샷: 해당없음 (백엔드 API 작업)

## 빌드 결과
- npm run build: 성공 (12.64s, dist/ 생성 2026-04-29 13:45)
- pytest: 44 passed in 0.08s

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-2313-dev4
- **워크트리 경로**: /home/jay/projects/InsuRo/.worktrees/task-2313-dev4
- **머지 의견**: 모든 테스트 통과, 빌드 성공, L1 스모크테스트 통과. 기존 기능 영향 없음 (신규 모듈 + 기존 코드 분기 추가).

## 모델 사용 기록
- 카르티케야(백엔드) / 작업: image_ai.py + main.py + requirements.txt / 사용 모델: sonnet / 정당성: -
- 사라스바티(프론트엔드) / 작업: planFeatureMap + useImageAI + AIPanel / 사용 모델: sonnet / 정당성: -
- 하누만(테스터) / 작업: 테스트 케이스 추가 / 사용 모델: sonnet / 정당성: -
- 비슈누(팀장) / 작업: 설계, 순환 import 해결, 진단 이슈 수정 / 사용 모델: opus / 정당성: 팀장 직접 개입 (순환 import은 Sonnet 팀원이 해결하지 못한 아키텍처 이슈)

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회