diff --git a/300_architecture/sequences/items_sequences.md b/300_architecture/sequences/items_sequences.md new file mode 100644 index 0000000..17d2ad3 --- /dev/null +++ b/300_architecture/sequences/items_sequences.md @@ -0,0 +1,443 @@ +# 아이템 시스템 시퀀스 다이어그램 + +## 작성일: 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[프론트엔드
React] + end + + subgraph Gateway Layer + GW[robeing-gateway
:8100] + end + + subgraph Services + RM[robeing-monitor
:9024] + RB[rb10508_micro
:10508] + AS[auth-server
:9000] + SE[skill-email
:8501] + end + + subgraph Database + PG[(PostgreSQL)] + GT[gmail_tokens] + RS[robing_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
Header: X-User-Id + + Monitor->>DB: SELECT * FROM gmail_tokens
WHERE user_id = ? + DB-->>Monitor: 토큰 데이터 + + Monitor->>Monitor: 아이템 상태 계산 + Note over Monitor: - locked (레벨 미달)
- available (장착 가능)
- equipped (장착됨) + + Monitor-->>Gateway: {equipped: {...}, available: [...]} + Gateway-->>Front: 아이템 목록 + + Front->>Front: UI 렌더링 + Note over Front: 레벨별 색상 표시
- 회색: 잠김
- 파란색: 사용 가능
- 초록색: 장착됨 +``` + +### 2.2 레벨 기반 필터링 + +```mermaid +sequenceDiagram + participant Monitor as robeing-monitor + participant DB as PostgreSQL + + Monitor->>DB: SELECT level FROM robing_stats
WHERE robing_id = ? + DB-->>Monitor: 현재 레벨 (예: 20) + + Monitor->>Monitor: 아이템별 레벨 체크 + Note over Monitor: Gmail (Lv.5): ✅ available
Notion (Lv.10): ✅ available
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
scopes: gmail.send
gmail.readonly
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_tokens + Note over DB: token_data, scopes,
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 robing_stats
WHERE robing_id = ? + DB-->>Monitor: level: 20 + + Monitor->>Monitor: 레벨 요구사항 체크 + Note over Monitor: Gmail 요구 레벨: 5
현재 레벨: 20
✅ 통과 + + Monitor->>DB: 토큰 소유권 확인 + DB-->>Monitor: 토큰 존재 확인 + + Monitor->>DB: UPDATE gmail_tokens
SET is_equipped = true,
equipped_to = 'rb10508_micro' + DB-->>Monitor: 업데이트 완료 + + Monitor->>DB: INSERT INTO gmail_audit_logs + Note over DB: action: 'equip'
user_id, robeing_id, timestamp + + Monitor-->>Gateway: {success: true, message: "장착 완료"} + Gateway-->>Front: 성공 응답 + + Front->>Front: UI 상태 업데이트 + Note over Front: equipped 상태로 변경
초록색 + 체크 아이콘 + + 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 robing_stats + DB-->>Monitor: level: 3 + Monitor-->>Front: {error: "레벨 5 이상 필요"} + else 토큰 없음 + Monitor->>DB: SELECT * FROM gmail_tokens + DB-->>Monitor: null + Monitor-->>Front: {error: "Gmail 연결 필요"} + else 이미 장착됨 + Monitor->>DB: SELECT is_equipped FROM gmail_tokens + 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_tokens
WHERE user_id = ? + DB-->>Monitor: 토큰 데이터 + + Monitor-->>RB: {equipped: {is_equipped: true,
capabilities: {send: true, read: true}}} + + alt 아이템 장착됨 + RB->>SE: POST /process + Note over SE: message: "최근 이메일 확인" + + SE->>DB: SELECT token_data FROM gmail_tokens + 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 확인
- send: true (Lv.7)
- read: true (Lv.5)
- 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_tokens
SET is_equipped = false,
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 상태로 변경
파란색 표시 +``` + +--- + +## 7. 레벨 기반 아이템 해금 + +### 7.1 레벨업 시 아이템 해금 알림 + +```mermaid +sequenceDiagram + participant RB as rb10508_micro + participant DB as PostgreSQL + participant Front as 프론트엔드 + + RB->>DB: 경험치 획득 + DB->>DB: UPDATE robing_stats
SET experience = experience + 100 + + DB->>DB: 레벨 계산 + Note over DB: 레벨 4 → 5 상승! + + RB->>RB: 새 아이템 해금 체크 + Note over RB: Gmail (Lv.5): 해금!
Notion (Lv.10): 대기 + + RB->>Front: WebSocket: level_up 이벤트 + Note over Front: {
new_level: 5,
unlocked_items: ["Gmail"]
} + + 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_tokens + 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_tokens + DB-->>SE: 토큰 (만료됨) + + SE->>Auth: 토큰 갱신 요청 + Auth->>Google: Refresh Token 사용 + Google-->>Auth: 새 Access Token + + Auth->>DB: UPDATE gmail_tokens
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` + +--- + +**문서 끝** \ No newline at end of file