DOCS/book/300_architecture/sequences/items_sequences.md

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

작성일: 2025-08-20

작성자: Claude (51123 서버 관리자)

상태: 초안

---

목차

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

---

1. 시스템 개요

1.1 아이템 시스템 아키텍처

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 사용자 아이템 조회

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 레벨 기반 필터링

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 인증 플로우

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 장착 프로세스

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 장착 실패 케이스

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 스킬 실행 전 아이템 체크

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 권한별 기능 제한

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 해제 프로세스

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 레벨업 시 아이템 해금 알림

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 상태 동기화

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 토큰 만료 및 재인증

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 아이템 조합 시스템

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

---

문서 끝