# 아이템 시스템 시퀀스 다이어그램

## 작성일: 2025-08-20
## 작성자: Claude (51123 서버 관리자)
## 상태: 초안

---

## 목차
1. [시스템 개요](#1-시스템-개요)
2. [아이템 목록 조회](#2-아이템-목록-조회)
3. [Gmail 아이템 획득 (OAuth)](#3-gmail-아이템-획득-oauth)
4. [아이템 장착](#4-아이템-장착)
5. [아이템 사용 권한 확인](#5-아이템-사용-권한-확인)
6. [아이템 해제](#6-아이템-해제)
7. [레벨 기반 아이템 해금](#7-레벨-기반-아이템-해금)
8. [아이템 상태 영구 저장](#8-아이템-상태-영구-저장)

---

## 1. 시스템 개요

### 1.1 아이템 시스템 아키텍처

```mermaid
graph TB
    subgraph Frontend
        UI[프론트엔드<br/>React]
    end
    
    subgraph Gateway Layer
        GW[robeing-gateway<br/>:8100]
    end
    
    subgraph Services
        RM[robeing-monitor<br/>:9024]
        RB[rb10508_micro<br/>:10508]
        AS[auth-server<br/>:9000]
        SE[skill-email<br/>:8501]
    end
    
    subgraph Database
        PG[(PostgreSQL)]
        GT[gmail_token]
        RS[robeing_stats]
    end
    
    UI --> GW
    GW --> RM
    GW --> RB
    GW --> AS
    RB --> RM
    RB --> SE
    SE --> PG
    AS --> PG
    RM --> PG
    
    PG --> GT
    PG --> RS
```

### 1.2 아이템 분류 체계

| 아이템 유형 | 레벨 요구 | 설명 | 예시 |
|------------|----------|------|------|
| API 아이템 | Lv.3+ | 외부 서비스 접근권 | Gmail API, Notion API, OpenAI GPT-4 |
| 도구 아이템 | Lv.6+ | 실행 가능한 외부 프로그램 | Code Executor, Docker Container |
| 데이터 아이템 | Lv.4+ | 특수 지식 베이스 | 도메인 전문 지식, 규제 컴플라이언스 DB |
| 강화 아이템 | Lv.1+ | 임시 능력치 부스트 | 카페인 부스트, 하이퍼 포커스 |

---

## 2. 아이템 목록 조회

### 2.1 사용자 아이템 조회

```mermaid
sequenceDiagram
    participant User as 사용자
    participant Front as 프론트엔드
    participant Gateway as Gateway
    participant Monitor as robeing-monitor
    participant DB as PostgreSQL

    User->>Front: 인벤토리 페이지 접속
    Front->>Gateway: GET /api/items/gmail
    Note over Gateway: JWT 토큰 검증
    Gateway->>Monitor: GET /api/items/gmail<br/>Header: X-User-Id
    
    Monitor->>DB: SELECT * FROM gmail_token<br/>WHERE user_id = ?
    DB-->>Monitor: 토큰 데이터
    
    Monitor->>Monitor: 아이템 상태 계산
    Note over Monitor: - locked (레벨 미달)<br/>- available (장착 가능)<br/>- equipped (장착됨)
    
    Monitor-->>Gateway: {equipped: {...}, available: [...]}
    Gateway-->>Front: 아이템 목록
    
    Front->>Front: UI 렌더링
    Note over Front: 레벨별 색상 표시<br/>- 회색: 잠김<br/>- 파란색: 사용 가능<br/>- 초록색: 장착됨
```

### 2.2 레벨 기반 필터링

```mermaid
sequenceDiagram
    participant Monitor as robeing-monitor
    participant DB as PostgreSQL

    Monitor->>DB: SELECT level FROM robeing_stats<br/>WHERE robeing_id = ?
    DB-->>Monitor: 현재 레벨 (예: 20)
    
    Monitor->>Monitor: 아이템별 레벨 체크
    Note over Monitor: Gmail (Lv.5): ✅ available<br/>Notion (Lv.10): ✅ available<br/>GPT-4 (Lv.25): ❌ locked
    
    Monitor-->>Monitor: 필터링된 목록 반환
```

---

## 3. Gmail 아이템 획득 (OAuth)

### 3.1 OAuth 인증 플로우

```mermaid
sequenceDiagram
    participant User as 사용자
    participant Front as 프론트엔드
    participant Gateway as Gateway
    participant Auth as auth-server
    participant Google as Google OAuth
    participant DB as PostgreSQL

    User->>Front: "Gmail 연결" 버튼 클릭
    Front->>Gateway: POST /api/auth/gmail/passport
    Gateway->>Auth: 패스포트 발급 요청
    
    Auth->>Auth: state 토큰 생성
    Auth->>DB: state 임시 저장
    
    Auth->>Auth: OAuth URL 생성
    Note over Auth: client_id, redirect_uri<br/>scopes: gmail.send<br/>gmail.readonly<br/>gmail.modify
    
    Auth-->>Gateway: {oauth_url: "https://..."}
    Gateway-->>Front: OAuth URL
    Front->>Google: 브라우저 리다이렉트
    
    User->>Google: Google 계정 로그인
    User->>Google: 권한 승인
    
    Google->>Auth: 인증 코드 콜백
    Auth->>Google: 코드 → 토큰 교환
    Google-->>Auth: Access Token + Refresh Token
    
    Auth->>DB: INSERT INTO gmail_token
    Note over DB: token_data, scopes,<br/>metadata (email 등)
    
    Auth->>Front: 리다이렉트 /inventory?success=true
    Front->>User: "Gmail 연결 완료!"
```

---

## 4. 아이템 장착

### 4.1 장착 프로세스

```mermaid
sequenceDiagram
    participant User as 사용자
    participant Front as 프론트엔드
    participant Gateway as Gateway
    participant Monitor as robeing-monitor
    participant DB as PostgreSQL

    User->>Front: "활성화" 버튼 클릭
    Front->>Front: 로딩 상태 표시
    
    Front->>Gateway: POST /api/items/gmail/{userId}/equip
    Note over Gateway: JWT 검증
    
    Gateway->>Monitor: 장착 요청
    Note over Monitor: Body: {robeing_id: "rb10508_micro"}
    
    Monitor->>DB: 레벨 확인
    Note over DB: SELECT level FROM robeing_stats<br/>WHERE robeing_id = ?
    DB-->>Monitor: level: 20
    
    Monitor->>Monitor: 레벨 요구사항 체크
    Note over Monitor: Gmail 요구 레벨: 5<br/>현재 레벨: 20<br/>✅ 통과
    
    Monitor->>DB: 토큰 소유권 확인
    DB-->>Monitor: 토큰 존재 확인
    
    Monitor->>DB: UPDATE gmail_token<br/>SET is_equipped = true,<br/>equipped_to = 'rb10508_micro'
    DB-->>Monitor: 업데이트 완료
    
    Monitor->>DB: INSERT INTO gmail_audit_logs
    Note over DB: action: 'equip'<br/>user_id, robeing_id, timestamp
    
    Monitor-->>Gateway: {success: true, message: "장착 완료"}
    Gateway-->>Front: 성공 응답
    
    Front->>Front: UI 상태 업데이트
    Note over Front: equipped 상태로 변경<br/>초록색 + 체크 아이콘
    
    Front->>User: Toast: "Gmail 패스포트가 활성화되었습니다"
```

### 4.2 장착 실패 케이스

```mermaid
sequenceDiagram
    participant Front as 프론트엔드
    participant Monitor as robeing-monitor
    participant DB as PostgreSQL

    Front->>Monitor: POST /api/items/gmail/{userId}/equip
    
    alt 레벨 부족
        Monitor->>DB: SELECT level FROM robeing_stats
        DB-->>Monitor: level: 3
        Monitor-->>Front: {error: "레벨 5 이상 필요"}
    else 토큰 없음
        Monitor->>DB: SELECT * FROM gmail_token
        DB-->>Monitor: null
        Monitor-->>Front: {error: "Gmail 연결 필요"}
    else 이미 장착됨
        Monitor->>DB: SELECT is_equipped FROM gmail_token
        DB-->>Monitor: is_equipped: true
        Monitor-->>Front: {error: "이미 장착됨"}
    end
```

---

## 5. 아이템 사용 권한 확인

### 5.1 스킬 실행 전 아이템 체크

```mermaid
sequenceDiagram
    participant User as 사용자
    participant RB as rb10508_micro
    participant Monitor as robeing-monitor
    participant SE as skill-email
    participant DB as PostgreSQL

    User->>RB: "최근 이메일 확인해줘"
    
    RB->>RB: 의도 분류
    Note over RB: intent: "email"
    
    RB->>Monitor: GET /api/items/gmail
    Note over Monitor: Header: X-User-Id
    
    Monitor->>DB: SELECT * FROM gmail_token<br/>WHERE user_id = ?
    DB-->>Monitor: 토큰 데이터
    
    Monitor-->>RB: {equipped: {is_equipped: true,<br/>capabilities: {send: true, read: true}}}
    
    alt 아이템 장착됨
        RB->>SE: POST /process
        Note over SE: message: "최근 이메일 확인"
        
        SE->>DB: SELECT token_data FROM gmail_token
        DB-->>SE: OAuth 토큰
        
        SE->>SE: Gmail API 호출
        SE-->>RB: 이메일 목록
        RB-->>User: "받은 메일이 3개 있습니다..."
    else 아이템 미장착
        RB-->>User: "Gmail을 먼저 연결해주세요!"
    end
```

### 5.2 권한별 기능 제한

```mermaid
sequenceDiagram
    participant RB as rb10508_micro
    participant Monitor as robeing-monitor

    RB->>Monitor: GET /api/items/gmail
    Monitor-->>RB: capabilities 반환
    
    Note over RB: capabilities 확인<br/>- send: true (Lv.7)<br/>- read: true (Lv.5)<br/>- modify: true (Lv.11)
    
    alt 이메일 발송 요청 (Lv.7 필요)
        RB->>RB: 현재 레벨 20 ✅
        RB->>RB: 발송 기능 활성화
    else 이메일 추적 요청 (Lv.11 필요)
        RB->>RB: 현재 레벨 20 ✅
        RB->>RB: 추적 기능 활성화
    else 고급 분석 요청 (Lv.25 필요)
        RB->>RB: 현재 레벨 20 ❌
        RB-->>RB: "레벨 25에 해금됩니다"
    end
```

---

## 6. 아이템 해제

### 6.1 해제 프로세스

```mermaid
sequenceDiagram
    participant User as 사용자
    participant Front as 프론트엔드
    participant Monitor as robeing-monitor
    participant DB as PostgreSQL

    User->>Front: "해제" 버튼 클릭
    Front->>Monitor: POST /api/items/gmail/{userId}/unequip
    
    Monitor->>DB: UPDATE gmail_token<br/>SET is_equipped = false,<br/>equipped_to = null
    DB-->>Monitor: 업데이트 완료
    
    Monitor->>DB: INSERT INTO gmail_audit_logs
    Note over DB: action: 'unequip'
    
    Monitor-->>Front: {success: true}
    Front->>Front: UI 상태 업데이트
    Note over Front: available 상태로 변경<br/>파란색 표시
```

---

## 7. 레벨 기반 아이템 해금

### 7.1 레벨업 시 아이템 해금 알림

```mermaid
sequenceDiagram
    participant RB as rb10508_micro
    participant DB as PostgreSQL
    participant Front as 프론트엔드

    RB->>DB: 경험치 획득
    DB->>DB: UPDATE robeing_stats<br/>SET experience = experience + 100
    
    DB->>DB: 레벨 계산
    Note over DB: 레벨 4 → 5 상승!
    
    RB->>RB: 새 아이템 해금 체크
    Note over RB: Gmail (Lv.5): 해금!<br/>Notion (Lv.10): 대기
    
    RB->>Front: WebSocket: level_up 이벤트
    Note over Front: {<br/>  new_level: 5,<br/>  unlocked_items: ["Gmail"]<br/>}
    
    Front->>User: 알림: "레벨 5 달성! Gmail 아이템을 사용할 수 있습니다"
```

---

## 8. 아이템 상태 영구 저장

### 8.1 상태 동기화

```mermaid
sequenceDiagram
    participant Front as 프론트엔드
    participant Monitor as robeing-monitor
    participant DB as PostgreSQL

    Note over Front: 페이지 새로고침
    
    Front->>Monitor: GET /api/items/gmail
    Monitor->>DB: SELECT * FROM gmail_token
    DB-->>Monitor: is_equipped: true
    
    Monitor-->>Front: 장착 상태 반환
    Front->>Front: UI 복원
    Note over Front: 장착 상태 유지됨
```

### 8.2 토큰 만료 및 재인증

```mermaid
sequenceDiagram
    participant SE as skill-email
    participant DB as PostgreSQL
    participant Auth as auth-server
    participant Google as Google OAuth

    SE->>DB: SELECT token_data FROM gmail_token
    DB-->>SE: 토큰 (만료됨)
    
    SE->>Auth: 토큰 갱신 요청
    Auth->>Google: Refresh Token 사용
    Google-->>Auth: 새 Access Token
    
    Auth->>DB: UPDATE gmail_token<br/>SET token_data = ?
    DB-->>Auth: 업데이트 완료
    
    Auth-->>SE: 새 토큰
    SE->>SE: Gmail API 호출 재시도
```

---

## 9. 향후 확장 계획

### 9.1 추가 아이템 타입

- **Notion API** (Lv.10): 문서 관리
- **Slack API** (Lv.8): 메시지 자동화
- **GitHub API** (Lv.12): 코드 리뷰 및 PR 관리
- **OpenAI GPT-4** (Lv.15): 고급 텍스트 생성

### 9.2 아이템 조합 시스템

```mermaid
graph LR
    Gmail[Gmail API] --> Combo1[이메일 자동화]
    Calendar[Calendar API] --> Combo1
    
    Notion[Notion API] --> Combo2[지식 관리 시스템]
    Gmail --> Combo2
    
    GitHub[GitHub API] --> Combo3[개발 워크플로우]
    Slack[Slack API] --> Combo3
```

### 9.3 아이템 거래/양도

- 사용자 간 아이템 공유
- 팀 단위 아이템 라이선스
- NFT 기반 소유권 증명

---

## 관련 문서

- `/200_core_design/260_아이템시스템_외부도구_통합과_권한관리.md`
- `/plans/250819_gmail_item_implementation_plan.md`
- `/troubleshooting/250820_happybell80_Gmail패스포트시스템완성.md`
- `/300_architecture/sequences/email_sequences.md`

---

**문서 끝**