# Human-in-the-loop 의도 학습/리뷰 큐 아키텍처

**작성일**: 2025-11-16  
**수정일**: 2025-11-16 (rb8001 intent 리뷰 큐/피드백 1차 구현 정리)

---

## 1. 목표

1. rb8001에서 **모든 의도 분석 결과를 구조화된 로그로 남기고**, 나중에 재학습/분석에 활용할 수 있게 한다.  
2. 모델이 헷갈리는 케이스·에러·사용자 부정 피드백만 골라 **리뷰 큐(intent_review_queue)** 로 보내서 human-in-the-loop 라벨링을 가능하게 한다.  
3. 프론트/슬랙에서 최소 클릭(좋아요/싫어요)으로 피드백을 수집하고, 이를 **의도 로그/리뷰 큐와 자연스럽게 연결**한다.

---

## 2. 데이터 흐름 개요

### 2.1 대화 저장 (ConversationLog)

- 책임 파일:  
  - `app/state/database.py:44-58: ConversationLog`  
  - `app/state/conversation_repository.py:16-159: save_conversation`

1. `router.route_message()`가 실행계획을 만들고 스킬을 실행한다.  
2. LLM 응답(또는 스킬 응답)이 성공하면 `_save_conversation()` → `save_conversation()` 호출.  
3. `ConversationLog`에 다음 필드 저장:
   - `user_id` (UUID, FK to user)  
   - `channel_id` (frontend/slack 등)  
   - `message` (사용자 발화)  
   - `response` (로빙 응답)  
   - `intent` (DecisionEngine이 판단한 의도 이름)  
   - `confidence` (의도 신뢰도)  
   - `timestamp`

> **원칙**: 의도/신뢰도는 항상 ConversationLog에 남긴다. 리뷰 큐/재학습은 이 로그를 기반으로 한다.

### 2.2 Intent 리뷰 큐 (IntentReviewQueue)

- 책임 파일:  
  - `app/state/database.py:60-88: IntentReviewQueue`  
  - `app/brain/intent_review.py:16-82: should_enqueue_for_review`  
  - `app/state/conversation_repository.py:153-188: 리뷰 큐 저장 로직`

1. `save_conversation()`는 PostgreSQL 저장이 성공하고 `conversation_id`를 얻은 뒤, 의도가 있으면 `should_enqueue_for_review(...)`를 호출한다.
2. `should_enqueue_for_review` 규칙:
   - `error=True` → 무조건 리뷰 큐 진입  
   - `user_feedback`가 부정(wrong/이상해/다시 등) → 무조건 리뷰 큐 진입  
   - 그 외에는 **top-alternatives와의 마진이 작은 케이스**만 리뷰 대상  
     - `margin = predicted_conf - best_alt_score < 0.1`  
     - `predicted_conf >= 0.3` 인 경우에만 고려
3. 리뷰 큐에 들어가는 필드:
   - `conversation_log_id` (nullable, 히스토리와 연결 가능할 때만)  
   - `user_id`  
   - `message`  
   - `predicted_intent`, `predicted_confidence`  
   - `alternatives` (JSON, intent/score 목록)  
   - `user_feedback` (up/down/wrong 등)  
   - `error` (bool)  
   - `status` (`pending`/`confirmed`/`corrected`)  
   - `true_intent` (라벨링 완료 후 사람이 채운 값)

> **원칙**:  
> - 리뷰 큐는 **“라벨링 대상 샘플”만 모아 두는 얇은 테이블**이다.  
> - 실제 원문/컨텍스트는 항상 ConversationLog/ChromaDB에서 조회한다.

---

## 3. 프론트/슬랙 피드백 흐름

### 3.1 프론트엔드 피드백 UI

- 책임 파일:  
  - `frontend-customer/src/components/chat-interface.tsx:646-680, 488-507, 510-751`  
  - `frontend-customer/src/services/robeing-api.ts:4-73, 100-154`

1. 각 로빙 응답 말풍선 아래 타임스탬프 옆에 **좋아요/싫어요 버튼** 추가:
   - 클릭 시 `Message.metadata.feedback = 'up' | 'down'`로 낙관적 UI 업데이트.  
2. 동시에 `sendChatFeedback(message.id, 'up' | 'down')` 호출:
   - `POST { message_id, feedback }` → `gateway/api/feedback/chat`  
   - 게이트웨이는 rb8001의 `/api/feedback/chat`으로 프록시.

### 3.2 rb8001 피드백 API → 리뷰 큐

- 책임 파일:  
  - `rb8001/main.py:66-72, 189-149, 205-236, 522-531, 627-701, 366-404, 532-624, 636-701, 704-708` (중 `/api/feedback/chat`)  
  - `app/router/feedback_handler.py:16-118`

1. 엔드포인트: `/api/feedback/chat`  
   - Request Body: `{"message_id": "...", "feedback": "up" | "down"}`  
   - `get_current_user`로 JWT에서 **UUID** 추출.  
2. `handle_chat_feedback(user_id, message_id, feedback)` 호출:
   - `message_id`에서 `conversation_log_id`를 파싱 (`"123_robeing" → 123`)  
   - `conversation_log_id`로 `ConversationLog`를 찾아서 `message`, `intent`, `confidence`를 가져옴(있으면).  
   - 해당 `(conversation_log_id, user_id)` 조합에 대해 리뷰 큐 행을 생성/업데이트:
     - `feedback='up'` → `status='confirmed'`  
     - `feedback='down'` → `status='corrected'`
3. ConversationLog가 없는 경우(예: 임시 ID)에는 `conversation_log_id=None`으로 리뷰 큐에 최소 정보만 남긴다.

> **원칙**: 피드백 API는 실패하더라도 사용자 경험을 깨지 않기 위해 항상 200을 반환하며, 내부 에러는 로그로만 남긴다.

---

## 4. 의도/리뷰 TDD 상태

### 4.1 Intent 리뷰 규칙 테스트

- 책임 파일:  
  - `rb8001/tests/test_intent_review_queue.py`

검증 내용:
- 캘린더 쿼리 vs 이벤트처럼 **마진이 작은 케이스**는 리뷰 큐로 가야 한다.  
- high-confidence 명확 케이스는 리뷰 큐에 안 들어간다.  
- 사용자 부정 피드백(wrong 등)이나 내부 에러가 있으면, confidence와 무관하게 리뷰 큐로 들어가야 한다.

### 4.2 종합 의도/캘린더 테스트

- 책임 파일:  
  - `rb8001/tests/test_intent_entity_skill_comprehensive.py`

검증 내용:
- 이메일/뉴스/문서/웹검색/액션/인사/캘린더(등록/조회/승인/삭제)까지 전체 intent 분류.  
- 캘린더 조회/등록 문장들은 `calendar_event` vs `calendar_query`로 명시적으로 분리.  
- 캘린더 후속 질문 `"어디서?"`에 대해 최근 `calendar_query` 응답에서 장소를 추출해 답변.

> **교훈**: 의도/캘린더 관련 코드는 “문장 → 기대 intent”를 먼저 테스트에 못 박고, DecisionEngine/threshold를 그에 맞춰 조정하는 TDD 패턴을 유지한다.

---

## 5. 향후 확장 포인트

1. **리뷰 큐 라벨링/조회 API**  
   - `status='pending'` 행만 필터링하는 관리자용 엔드포인트 추가.  
   - 사람이 `true_intent`를 입력하고 `status='confirmed'/'corrected'`로 변경하는 라벨링 플로우 구축.
2. **재학습/재시드 배치 연동**  
   - `IntentReviewQueue`에서 검수 완료된 샘플만 모아서 Ko-SRoBERTa prototype/Naive Bayes 시드 스크립트 입력으로 사용.  
   - “신규 검수 샘플 N개 + 일정 주기” 조건에서만 재시드/배포하도록 가드 추가.
3. **스킬 실행 로그와의 통합**  
   - `log_decision`/intent_runtime 로그에 **실행된 스킬 목록**을 포함하고, 리뷰 큐에서 이 정보를 함께 조회할 수 있게 하면 “어떤 스킬 조합이 실패/성공했는지”를 분석하기 쉬워진다.

---

## 6. 체크리스트

- [x] ConversationLog에 `intent`/`confidence`를 항상 저장하는가  
- [x] 리뷰 큐 규칙이 테스트(`test_intent_review_queue.py`)로 고정되어 있는가  
- [x] 프론트/슬랙에서 피드백을 1~2클릭으로 보낼 수 있는가  
- [x] 피드백 API가 실패해도 사용자 경험이 깨지지 않는가  
- [x] 라벨링/조회용 API 엔드포인트가 준비되어 있는가 (2025-11-17 완료)
  - `GET /api/intent-review/queue`: 리뷰 큐 조회 (필터링/페이지네이션)
  - `PUT /api/intent-review/{id}/label`: 리뷰 항목 라벨링
  - `GET /api/intent-review/stats`: 리뷰 큐 통계
- [ ] 재시드 배치 스크립트가 준비되어 있는가 (다음 단계)
- [ ] 운영에서 리뷰 큐를 모니터링할 대시보드/쿼리가 있는가