---
task_id: task-2273
type: plan
scope: task
created: 2026-04-28
updated: 2026-04-28
status: completed
---

# 계획서: task-2273

**task**: task-2273
**목표**: InsuRo 모든 AI 기능을 통합 큐(ai_queue)로 관리하여 동시 요청 과부하 방지
**승인**: 아누 2026-04-28
**근거**: 콘텐츠 생성만 큐 적용, 나머지 AI 기능은 큐 없이 직접 호출 → 동시 요청 과부하 위험

---

## 목표

- 통합 AI 큐 모듈(ai_queue.py) 신규 생성
- 모든 AI 엔드포인트에서 ai_queue 경유로 subprocess 호출
- 기존 generation_queue.py와의 하위 호환성 유지
- 동시 실행 10건 제한으로 서버 안정성 확보

## 범위

### 포함
- ai_queue.py 신규 모듈 (AIPriority, AIJobStatus, AIJob, UnifiedAIQueue)
- generation_queue.py → ai_queue wrapper 전환
- main.py의 5개 AI 엔드포인트에 큐 적용 (newsletter_chat, premium_chat, copilot_analyze, conversation_summarize, onboarding_ai_generate)
- 테스트 11건 작성

### 제외 (다음 페이즈 이후)
- 프론트엔드 대기 표시 (queue_position UI)
- PriorityQueue dispatcher (우선순위 실제 스케줄링)
- parse_premium_file (동기 subprocess, 별도 구조)
- keywords/analyze (BackgroundTasks 사용 중)

## 위임 계획

- ai_queue.py 신규 생성: **스바로그(백엔드)** — 핵심 큐 로직
- generation_queue.py wrapper: **스바로그(백엔드)** — 하위 호환
- main.py 통합: **스바로그(백엔드)** — 엔드포인트 수정
- 테스트 작성: **벨레스(테스터)** — 11개 테스트 케이스

## 검증 기준

- pytest 전량 통과: `pytest server/tests/test_ai_queue.py -v` → 11 passed
- 기존 테스트 회귀 없음: `pytest server/tests/ -v` → 64+ passed
- npm run build 성공: 빌드 에러 0건
- 서버 기동 확인: main.py 정상 시작 (docs 200 응답)